AI-native design editor. Open-source Figma alternative.
feat(figma-api): add getNodeByIdAsync() and getMainComponentAsync() (#779)
mrhard9090bb86d2ad7f4d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 77d3317bd..986f8ef90 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,7 @@### Added+- Run scripts written for Figma's dynamic-page mode that call `figma.getNodeByIdAsync()` or `getMainComponentAsync()`; both resolve to the same nodes as their synchronous forms.- Export components to Storybook with `openpencil export -f storybook`: one CSF3 story file per component set or component for React, Vue, or HTML, with a story and `select` controls per variant, a design image per variant, and an `openpencil://` link that opens the variant in OpenPencil. `--watch` re-exports on every save and removes stories of deleted components (#727).- Export HTML and Tailwind JSX from the app's export options and through the IO registry, and export Tailwind JSX from the CLI with `-f tailwind-jsx` (`-f jsx --style tailwind` still works). HTML export of a single layer now includes the layer itself, as other formats do.- Choose PPTX in the Export panel's format list, alongside PNG, JPG, WEBP, SVG, and PDF.diff --git a/packages/core/src/figma-api/compatibility.ts b/packages/core/src/figma-api/compatibility.tsindex e1cfb3545..dd6a8e356 100644--- a/packages/core/src/figma-api/compatibility.ts+++ b/packages/core/src/figma-api/compatibility.ts@@ -70,6 +70,7 @@ type InstancePropertySurfaceMatch = Expect<| 'setProperties'| 'isExposedInstance'| 'exposedInstances'+ | 'getMainComponentAsync'>,Pick<InstanceNode,@@ -78,6 +79,7 @@ type InstancePropertySurfaceMatch = Expect<| 'setProperties'| 'isExposedInstance'| 'exposedInstances'+ | 'getMainComponentAsync'>>>diff --git a/packages/core/src/figma-api/index.ts b/packages/core/src/figma-api/index.tsindex a9a8987f8..3706dd110 100644--- a/packages/core/src/figma-api/index.ts+++ b/packages/core/src/figma-api/index.ts@@ -137,6 +137,11 @@ export class FigmaAPI implements NodeProxyHost {return node ? this.wrapNode(id) : null}+ /** The async lookup that Figma requires in dynamic-page mode; same result as getNodeById. */+ async getNodeByIdAsync(id: string): Promise<FigmaNodeProxy | null> {+ return this.getNodeById(id)+ }+// --- Node Creation ---private _createNode(type: NodeType): FigmaNodeProxy {diff --git a/packages/core/src/figma-api/proxy.ts b/packages/core/src/figma-api/proxy.tsindex 26813c9f1..641760c65 100644--- a/packages/core/src/figma-api/proxy.ts+++ b/packages/core/src/figma-api/proxy.ts@@ -222,6 +222,11 @@ export class FigmaNodeProxy {setPageBackgrounds(this[INTERNAL_GRAPH], this._raw(), value)}+ /** The async form Figma requires in dynamic-page mode; same result as mainComponent. */+ async getMainComponentAsync(): Promise<FigmaNodeProxy | null> {+ return this.mainComponent+ }+get mainComponent(): FigmaNodeProxy | null {const n = this._raw()if (!n.componentId) return nulldiff --git a/packages/docs/programmable/cli/scripting.md b/packages/docs/programmable/cli/scripting.mdindex 40d6802fc..e3c0f0478 100644--- a/packages/docs/programmable/cli/scripting.md+++ b/packages/docs/programmable/cli/scripting.md@@ -162,6 +162,7 @@ Common node properties are readable/writable through the proxy, including:- `figma.createImage(data)`- `figma.loadFontAsync(fontName)` no-ops because OpenPencil does not gate text edits on plugin font loading- `figma.listAvailableFontsAsync()` returns host-provided fonts when available+- `figma.getNodeByIdAsync(id)` and `instance.getMainComponentAsync()` resolve to the same nodes as `figma.getNodeById(id)` and `instance.mainComponent`, for scripts written for Figma's dynamic-page mode- `figma.notify(message)` logs a warning in headless mode- `figma.viewport`diff --git a/tests/engine/figma/api/components.test.ts b/tests/engine/figma/api/components.test.tsindex 038a8a03f..4b22235ac 100644--- a/tests/engine/figma/api/components.test.ts+++ b/tests/engine/figma/api/components.test.ts@@ -61,4 +61,15 @@ describe('components', () => {expect(instance.type).toBe('INSTANCE')expect(expectDefined(instance.mainComponent, 'instance main component').id).toBe(comp.id)})++ test('async lookups resolve like their synchronous forms', async () => {+ const api = createAPI()+ const component = api.createComponent()+ const instance = component.createInstance()++ expect((await api.getNodeByIdAsync(instance.id))?.id).toBe(instance.id)+ expect(await api.getNodeByIdAsync('0:404')).toBeNull()+ expect((await instance.getMainComponentAsync())?.id).toBe(component.id)+ expect(await component.getMainComponentAsync()).toBeNull()+ })})