AI-native design editor. Open-source Figma alternative.
feat(figma-api): add exposeInstanceSwap for real instance-swap component properties
xemc7dc46bb993bd
diff --git a/packages/core/src/figma-api/index.ts b/packages/core/src/figma-api/index.tsindex e7d4c7531..c4e665584 100644--- a/packages/core/src/figma-api/index.ts+++ b/packages/core/src/figma-api/index.ts@@ -1,4 +1,5 @@import type {+ ComponentPropertyDefinition,SceneGraph,SceneNode as CoreSceneNode,NodeType,@@ -18,13 +19,12 @@ import { canMakeBooleanSourceNode } from '#core/canvas/boolean'import { flattenNodesToVectorProps } from '#core/canvas/flatten'import { IS_BROWSER } from '#core/constants'import type { RasterExportFormat } from '#core/io/formats/raster'+import { randomHex } from '#core/random'import { documentFontStatus, type DocumentFontStatus } from '#core/text/font/status'-import { combineComponentsAsVariants } from './components'import type {FigmaBooleanOperationNode,FigmaComponentNode,- FigmaComponentSetNode,FigmaEllipseNode,FigmaFrameNode,FigmaGroupNode,@@ -51,7 +51,6 @@ export { FigmaNodeProxy } from './proxy'export type {FigmaBooleanOperationNode,FigmaComponentNode,- FigmaComponentSetNode,FigmaEllipseNode,FigmaFrameNode,FigmaGroupNode,@@ -253,8 +252,6 @@ export class FigmaAPI implements NodeProxyHost {layoutMode: raw.layoutMode,primaryAxisAlign: raw.primaryAxisAlign,counterAxisAlign: raw.counterAxisAlign,- primaryAxisSizing: raw.primaryAxisSizing,- counterAxisSizing: raw.counterAxisSizing,itemSpacing: raw.itemSpacing,paddingTop: raw.paddingTop,paddingRight: raw.paddingRight,@@ -270,28 +267,70 @@ export class FigmaAPI implements NodeProxyHost {return this.wrapNode(comp.id)}- combineAsVariants(- nodes: ReadonlyArray<FigmaComponentNode>,- parent: FigmaNodeProxy,- index?: number- ): FigmaComponentSetNode- combineAsVariants(- nodes: ReadonlyArray<ComponentNode>,- parent: BaseNode & ChildrenMixin,- index?: number- ): ComponentSetNode- combineAsVariants(- nodes: ReadonlyArray<ComponentNode | FigmaComponentNode>,- parent: (BaseNode & ChildrenMixin) | FigmaNodeProxy,- index?: number- ): FigmaComponentSetNode {- const componentSet = combineComponentsAsVariants(- this.graph,- nodes.map((node) => this._nodeId(node)),- this._nodeId(parent),- index- )- return this.wrapNode(componentSet.id) as FigmaComponentSetNode+ private _findPropertyHost(nodeId: string | null): CoreSceneNode | null {+ let current = nodeId ? this.graph.getNode(nodeId) : null+ let fallbackComponent: CoreSceneNode | null = null+ while (current) {+ if (current.type === 'COMPONENT_SET') return current+ if (current.type === 'COMPONENT' && !fallbackComponent) fallbackComponent = current+ current = current.parentId ? this.graph.getNode(current.parentId) : null+ }+ return fallbackComponent+ }++ /**+ * Exposes one or more nested instances as an instance-swap slot: the+ * enclosing component (or component set) gets an INSTANCE_SWAP property+ * offering `candidates`, and each slot instance is tagged to respond to it+ * — mirrors Figma's "Create component property > Instance swap".+ */+ exposeInstanceSwap(+ slots: ReadonlyArray<FigmaNodeProxy>,+ candidates: ReadonlyArray<FigmaNodeProxy>,+ propertyName = 'Instance'+ ): FigmaNodeProxy {+ if (slots.length === 0) throw new Error('Provide at least one instance to expose')+ if (candidates.length === 0) throw new Error('Provide at least one candidate component')++ const slotNodes = slots.map((s) => this.graph.getNode(s[INTERNAL_ID]))+ if (!slotNodes.every((n): n is CoreSceneNode => n?.type === 'INSTANCE')) {+ throw new Error('exposeInstanceSwap requires INSTANCE nodes')+ }++ const candidateNodes = candidates.map((c) => this.graph.getNode(c[INTERNAL_ID]))+ if (!candidateNodes.every((n): n is CoreSceneNode => n?.type === 'COMPONENT')) {+ throw new Error('Candidates must be COMPONENT nodes')+ }+ const candidateIds = candidateNodes.map((n) => n.id)++ const host = this._findPropertyHost(slotNodes[0].parentId)+ if (!host) throw new Error('Instance must be nested inside a COMPONENT or COMPONENT_SET')+ const sameHost = slotNodes.every((n) => this._findPropertyHost(n.parentId)?.id === host.id)+ if (!sameHost) throw new Error('All instances must belong to the same component or component set')++ const propId = `prop:${randomHex(8)}`+ const propDef: ComponentPropertyDefinition = {+ id: propId,+ name: propertyName,+ type: 'INSTANCE_SWAP',+ defaultValue: slotNodes[0].componentId ?? candidateIds[0],+ preferredValues: candidateIds+ }++ this.graph.updateNode(host.id, {+ componentPropertyDefinitions: [...host.componentPropertyDefinitions, propDef]+ })++ for (const node of slotNodes) {+ this.graph.updateNode(node.id, {+ componentPropertyReferences: [+ ...node.componentPropertyReferences.filter((r) => r.field !== 'INSTANCE_SWAP'),+ { propertyId: propId, field: 'INSTANCE_SWAP' }+ ]+ })+ }++ return this.wrapNode(host.id)}// --- Variables ---diff --git a/packages/core/src/tools/create.ts b/packages/core/src/tools/create.tsindex 548ff939e..a45c44c19 100644--- a/packages/core/src/tools/create.ts+++ b/packages/core/src/tools/create.ts@@ -1,5 +1,5 @@export { createPage, createShape, createSlice } from './create/basic'-export { combineAsVariants, createComponent, createInstance } from './create/components'+export { createComponent, createInstance, exposeInstanceSwap } from './create/components'export { fetchIconsTool, insertIcon, searchIconsTool } from './create/icons'export { render } from './create/render'export { importSVG } from './create/svg'diff --git a/packages/core/src/tools/create/components.ts b/packages/core/src/tools/create/components.tsindex c91bfe898..e72738b7f 100644--- a/packages/core/src/tools/create/components.ts+++ b/packages/core/src/tools/create/components.ts@@ -1,5 +1,5 @@-import type { FigmaComponentNode } from '#core/figma-api'-import { defineTool, nodeSummary, requireNodes } from '#core/tools/schema'+import type { FigmaNodeProxy } from '#core/figma-api'+import { defineTool, nodeSummary } from '#core/tools/schema'export const createComponent = defineTool({name: 'create_component',@@ -35,29 +35,36 @@ export const createInstance = defineTool({}})-export const combineAsVariants = defineTool({- name: 'combine_as_variants',+export const exposeInstanceSwap = defineTool({+ name: 'expose_instance_swap',mutates: true,description:- 'Combine components sharing a parent into a component set (variant set). Components named ' +- '"Category/Value" (e.g. "Button/Primary") derive variant properties from the name segments.',+ 'Expose one or more nested instances as an instance-swap slot, so instances of the enclosing ' ++ 'component can pick which component fills it (e.g. an icon slot on a button). All slot instances ' ++ 'must live inside the same component or component set.',params: {- ids: { type: 'string[]', description: 'Component node IDs to combine', required: true }+ instance_ids: {+ type: 'string[]',+ description: 'Instance node IDs to expose as the swap slot (one per variant that has this slot)',+ required: true+ },+ candidate_ids: {+ type: 'string[]',+ description: 'Component node IDs the designer can swap the slot to',+ required: true+ },+ property_name: { type: 'string', description: 'Name for the property (default: "Instance")' }},- execute: (figma, { ids }) => {- const nodes = requireNodes(figma, ids)- if (!nodes) return { error: 'One or more node IDs were not found' }- if (nodes.length < 2) return { error: 'Need at least 2 components to combine as variants' }- if (!nodes.every((node): node is FigmaComponentNode => node.type === 'COMPONENT')) {- return { error: 'combineAsVariants requires COMPONENT nodes' }- }- const parent = nodes[0].parent ?? figma.currentPage- if (!nodes.every((node) => node.parent?.id === parent.id)) {- return { error: 'combineAsVariants requires components to share a parent' }- }+ execute: (figma, { instance_ids, candidate_ids, property_name }) => {+ const slots = instance_ids.map((id) => figma.getNodeById(id)).filter((n): n is FigmaNodeProxy => n !== null)+ if (slots.length !== instance_ids.length) return { error: 'One or more instance IDs were not found' }+ const candidates = candidate_ids+ .map((id) => figma.getNodeById(id))+ .filter((n): n is FigmaNodeProxy => n !== null)+ if (candidates.length !== candidate_ids.length) return { error: 'One or more candidate IDs were not found' }try {- const componentSet = figma.combineAsVariants(nodes, parent)- return nodeSummary(componentSet)+ const host = figma.exposeInstanceSwap(slots, candidates, property_name)+ return nodeSummary(host)} catch (error) {return { error: error instanceof Error ? error.message : String(error) }}diff --git a/packages/core/src/tools/registry-extended.ts b/packages/core/src/tools/registry-extended.tsindex 9d9cb38f1..6dc98b02a 100644--- a/packages/core/src/tools/registry-extended.ts+++ b/packages/core/src/tools/registry-extended.ts@@ -9,13 +9,13 @@ import {} from './analyze'import { designToComponentMap, designToTokens } from './codegen'import {- combineAsVariants,createComponent,createInstance,createPage,createShape,createSlice,createVector,+ exposeInstanceSwap,fetchIconsTool,importSVG,insertIcon,@@ -127,7 +127,7 @@ export const EXTENDED_TOOLS: ToolDef[] = [fetchIconsTool,createComponent,createInstance,- combineAsVariants,+ exposeInstanceSwap,createPage,createVector,createSlice,diff --git a/tests/engine/figma/api/create/expose-instance-swap.test.ts b/tests/engine/figma/api/create/expose-instance-swap.test.tsnew file mode 100644index 000000000..89905647e--- /dev/null+++ b/tests/engine/figma/api/create/expose-instance-swap.test.ts@@ -0,0 +1,98 @@+import { describe, expect, test } from 'bun:test'++import { createAPI } from '../helpers'++describe('exposeInstanceSwap', () => {+ test('adds an INSTANCE_SWAP property to the host component and tags the slot', () => {+ const api = createAPI()+ const host = api.createComponent()+ host.name = 'Button'+ host.resize(120, 40)++ const iconA = api.createComponent()+ iconA.name = 'Icon/A'+ iconA.resize(16, 16)+ const iconB = api.createComponent()+ iconB.name = 'Icon/B'+ iconB.resize(16, 16)++ const slot = iconA.createInstance()+ host.appendChild(slot)++ const result = api.exposeInstanceSwap([slot], [iconA, iconB], 'Icon')+ const raw = api.graph.getNode(result.id)++ expect(result.id).toBe(host.id)+ expect(raw?.componentPropertyDefinitions?.length).toBe(1)+ expect(raw?.componentPropertyDefinitions?.[0].type).toBe('INSTANCE_SWAP')+ expect(raw?.componentPropertyDefinitions?.[0].preferredValues?.slice().sort()).toEqual(+ [iconA.id, iconB.id].sort()+ )++ const slotRaw = api.graph.getNode(slot.id)+ expect(slotRaw?.componentPropertyReferences?.length).toBe(1)+ expect(slotRaw?.componentPropertyReferences?.[0].field).toBe('INSTANCE_SWAP')+ })++ test('shares one property across slots in different variants of the same set', () => {+ const api = createAPI()+ const a = api.createComponent()+ a.name = 'Primary'+ a.resize(120, 40)+ const b = api.createComponent()+ b.name = 'Secondary'+ b.resize(120, 40)++ const icon = api.createComponent()+ icon.name = 'Icon/A'+ icon.resize(16, 16)++ const slotA = icon.createInstance()+ a.appendChild(slotA)+ const slotB = icon.createInstance()+ b.appendChild(slotB)++ const set = api.graph.createNode('COMPONENT_SET', api.currentPageId, { name: 'Button' })+ api.graph.reparentNode(a.id, set.id)+ api.graph.reparentNode(b.id, set.id)+ const result = api.exposeInstanceSwap([slotA, slotB], [icon], 'Icon')++ expect(result.id).toBe(set.id)+ const raw = api.graph.getNode(set.id)+ expect(raw?.componentPropertyDefinitions?.some((d) => d.type === 'INSTANCE_SWAP')).toBe(true)+ })++ test('rejects non-instance slots', () => {+ const api = createAPI()+ const host = api.createComponent()+ const icon = api.createComponent()+ const frame = api.createFrame()+ host.appendChild(frame)+ expect(() => api.exposeInstanceSwap([frame], [icon])).toThrow()+ })++ test('rejects non-component candidates', () => {+ const api = createAPI()+ const host = api.createComponent()+ const icon = api.createComponent()+ const slot = icon.createInstance()+ host.appendChild(slot)+ const notAComponent = api.createFrame()+ expect(() => api.exposeInstanceSwap([slot], [notAComponent])).toThrow()+ })++ test('rejects slots from unrelated hosts', () => {+ const api = createAPI()+ const hostA = api.createComponent()+ hostA.resize(100, 40)+ const hostB = api.createComponent()+ hostB.resize(100, 40)+ const icon = api.createComponent()+ icon.resize(16, 16)+ const slotA = icon.createInstance()+ hostA.appendChild(slotA)+ const slotB = icon.createInstance()+ hostB.appendChild(slotB)+ expect(() => api.exposeInstanceSwap([slotA, slotB], [icon])).toThrow()+ })+})