Add support for cross-real communication

Author: LosYear

figma.d.ts

@@ -1,14 +1,17 @@
+// Figma Plugin API version 1, update 5
+
 // Global variable with Figma's plugin API.
 declare const figma: PluginAPI
 declare const __html__: string
 
 interface PluginAPI {
   readonly apiVersion: "1.0.0"
   readonly command: string
-  readonly root: DocumentNode
   readonly viewport: ViewportAPI
   closePlugin(message?: string): void
 
+  notify(message: string, options?: NotificationOptions): NotificationHandler
+
   showUI(html: string, options?: ShowUIOptions): void
   readonly ui: UIAPI
 
@@ -17,8 +20,13 @@ interface PluginAPI {
   getNodeById(id: string): BaseNode | null
   getStyleById(id: string): BaseStyle | null
 
+  readonly root: DocumentNode
   currentPage: PageNode
 
+  on(type: "selectionchange" | "currentpagechange" | "close", callback: () => void)
+  once(type: "selectionchange" | "currentpagechange" | "close", callback: () => void)
+  off(type: "selectionchange" | "currentpagechange" | "close", callback: () => void)
+
   readonly mixed: symbol
 
   createRectangle(): RectangleNode
@@ -28,17 +36,27 @@ interface PluginAPI {
   createStar(): StarNode
   createVector(): VectorNode
   createText(): TextNode
-  createBooleanOperation(): BooleanOperationNode
   createFrame(): FrameNode
   createComponent(): ComponentNode
   createPage(): PageNode
   createSlice(): SliceNode
+  /**
+   * [DEPRECATED]: This API often fails to create a valid boolean operation. Use figma.union, figma.subtract, figma.intersect and figma.exclude instead.
+   */
+  createBooleanOperation(): BooleanOperationNode
 
   createPaintStyle(): PaintStyle
   createTextStyle(): TextStyle
   createEffectStyle(): EffectStyle
   createGridStyle(): GridStyle
 
+  // The styles are returned in the same order as displayed in the UI. Only
+  // local styles are returned. Never styles from team library.
+  getLocalPaintStyles(): PaintStyle[]
+  getLocalTextStyles(): TextStyle[]
+  getLocalEffectStyles(): EffectStyle[]
+  getLocalGridStyles(): GridStyle[]
+
   importComponentByKeyAsync(key: string): Promise<ComponentNode>
   importStyleByKeyAsync(key: string): Promise<BaseStyle>
 
@@ -53,35 +71,54 @@ interface PluginAPI {
 
   group(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): FrameNode
   flatten(nodes: ReadonlyArray<BaseNode>, parent?: BaseNode & ChildrenMixin, index?: number): VectorNode
+
+  union(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode
+  subtract(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode
+  intersect(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode
+  exclude(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode
 }
 
 interface ClientStorageAPI {
   getAsync(key: string): Promise<any | undefined>
   setAsync(key: string, value: any): Promise<void>
 }
 
-type ShowUIOptions = {
+interface NotificationOptions {
+  timeout?: number,
+}
+
+interface NotificationHandler {
+  cancel: () => void,
+}
+
+interface ShowUIOptions {
   visible?: boolean,
   width?: number,
   height?: number,
+  position?: 'default' | 'last' | 'auto' // PROPOSED API ONLY
 }
 
-type UIPostMessageOptions = {
-  targetOrigin?: string,
+interface UIPostMessageOptions {
+  origin?: string,
 }
 
-type OnMessageProperties = {
-  sourceOrigin: string,
+interface OnMessageProperties {
+  origin: string,
 }
 
+type MessageEventHandler = (pluginMessage: any, props: OnMessageProperties) => void
+
 interface UIAPI {
   show(): void
   hide(): void
   resize(width: number, height: number): void
   close(): void
 
   postMessage(pluginMessage: any, options?: UIPostMessageOptions): void
-  onmessage: ((pluginMessage: any, props: OnMessageProperties) => void) | undefined
+  onmessage: MessageEventHandler | undefined
+  on(type: "message", callback: MessageEventHandler)
+  once(type: "message", callback: MessageEventHandler)
+  off(type: "message", callback: MessageEventHandler)
 }
 
 interface ViewportAPI {
@@ -161,13 +198,13 @@ interface ColorStop {
 }
 
 interface ImageFilters {
-  exposure?: number
-  contrast?: number
-  saturation?: number
-  temperature?: number
-  tint?: number
-  highlights?: number
-  shadows?: number
+  readonly exposure?: number
+  readonly contrast?: number
+  readonly saturation?: number
+  readonly temperature?: number
+  readonly tint?: number
+  readonly highlights?: number
+  readonly shadows?: number
 }
 
 interface SolidPaint {
@@ -297,7 +334,7 @@ interface VectorPath {
 
 type VectorPaths = ReadonlyArray<VectorPath>
 
-type LetterSpacing = {
+interface LetterSpacing {
   readonly value: number
   readonly unit: "PIXELS" | "PERCENT"
 }
@@ -340,7 +377,7 @@ interface Font {
 interface BaseNodeMixin {
   readonly id: string
   readonly parent: (BaseNode & ChildrenMixin) | null
-  name: string // Note: setting this also sets `autoRename` to false on TextNodes
+  name: string // Note: setting this also sets \`autoRename\` to false on TextNodes
   readonly removed: boolean
   toString(): string
   remove(): void
@@ -360,13 +397,13 @@ interface SceneNodeMixin {
 }
 
 interface ChildrenMixin {
-  readonly children: ReadonlyArray<BaseNode>
+  readonly children: ReadonlyArray<SceneNode>
 
-  appendChild(child: BaseNode): void
-  insertChild(index: number, child: BaseNode): void
+  appendChild(child: SceneNode): void
+  insertChild(index: number, child: SceneNode): void
 
-  findAll(callback?: (node: BaseNode) => boolean): ReadonlyArray<BaseNode>
-  findOne(callback: (node: BaseNode) => boolean): BaseNode | null
+  findAll(callback?: (node: SceneNode) => boolean): SceneNode[]
+  findOne(callback: (node: SceneNode) => boolean): SceneNode | null
 }
 
 interface ConstraintMixin {
@@ -426,7 +463,7 @@ interface CornerMixin {
 }
 
 interface ExportMixin {
-  exportSettings: ExportSettings[]
+  exportSettings: ReadonlyArray<ExportSettings>
   exportAsync(settings?: ExportSettings): Promise<Uint8Array> // Defaults to PNG format
 }
 
@@ -444,8 +481,16 @@ interface DefaultContainerMixin extends
 ////////////////////////////////////////////////////////////////////////////////
 // Nodes
 
-interface DocumentNode extends BaseNodeMixin, ChildrenMixin {
+interface DocumentNode extends BaseNodeMixin {
   readonly type: "DOCUMENT"
+
+  readonly children: ReadonlyArray<PageNode>
+
+  appendChild(child: PageNode): void
+  insertChild(index: number, child: PageNode): void
+
+  findAll(callback?: (node: (PageNode | SceneNode)) => boolean): Array<PageNode | SceneNode>
+  findOne(callback: (node: (PageNode | SceneNode)) => boolean): PageNode | SceneNode | null
 }
 
 interface PageNode extends BaseNodeMixin, ChildrenMixin, ExportMixin {
@@ -454,6 +499,8 @@ interface PageNode extends BaseNodeMixin, ChildrenMixin, ExportMixin {
 
   guides: ReadonlyArray<Guide>
   selection: ReadonlyArray<SceneNode>
+
+  backgrounds: ReadonlyArray<Paint>
 }
 
 interface FrameNode extends DefaultContainerMixin {
@@ -652,4 +699,4 @@ interface GridStyle extends BaseStyle {
 interface Image {
   readonly hash: string
   getBytesAsync(): Promise<Uint8Array>
-}
+}

package.json

@@ -9,11 +9,16 @@
     "build": "npm run build:clean && npm run build:lib",
     "build:clean": "rimraf dist",
     "build:lib": "cross-env BABEL_ENV=production tsc -p tsconfig.json",
-    "prepublish": "npm run build"
+    "prepublish": "npm run build",
+    "test": "jest"
+  },
+  "jest": {
+    "preset": "ts-jest/presets/js-with-babel"
   },
   "pre-commit": [
     "prettify",
-    "tsc"
+    "tsc",
+    "test"
   ],
   "repository": {
     "type": "git",
@@ -30,10 +35,13 @@
   },
   "homepage": "https://github.com/react-figma/figma-api-stub#readme",
   "devDependencies": {
+    "@types/jest": "^24.0.23",
     "cross-env": "^6.0.3",
+    "jest": "^24.9.0",
     "pre-commit": "^1.2.2",
     "prettier": "^1.18.2",
     "rimraf": "^3.0.0",
+    "ts-jest": "^24.2.0",
     "typescript": "3.5.3"
   }
 }

src/__tests__/postmessage.test.ts

@@ -0,0 +1,26 @@
+import { createParentPostMessage, createFigma } from "../stubs";
+
+describe("postMessage", () => {
+  beforeEach(() => {
+    // @ts-ignore
+    global.figma = createFigma({});
+    // @ts-ignore
+    global.parent.postMessage = createParentPostMessage(global.figma);
+  });
+
+  it("UI sends message and plugin receives it", () => {
+    figma.ui.onmessage = jest.fn();
+    parent.postMessage({ pluginMessage: "abc" }, "*");
+
+    expect(figma.ui.onmessage).toHaveBeenCalledTimes(1);
+    expect(figma.ui.onmessage).toHaveBeenCalledWith("abc", expect.any(Object));
+  });
+
+  it("Plugin sends message and UI receives it", () => {
+    //@ts-ignore
+    global.onmessage = jest.fn();
+    figma.ui.postMessage("abc");
+    //@ts-ignore
+    expect(global.onmessage).toHaveBeenCalledTimes(1);
+  });
+});

src/index.ts

@@ -1 +1 @@
-export { createFigma } from "./stubs";
+export { createFigma, createParentPostMessage } from "./stubs";