@toghen/figma 0.0.0-stage → 0.1.0

package/main/handlers/planVariableSync.ts

@@ -0,0 +1,49 @@
+import type { Command, Response } from '../../shared/protocol.js';
+import { VariableSyncEngine } from '../engines/variableSyncEngine.js';
+import { getState, setState } from '../runtimeState.js';
+import { danglingSymbolWarnings } from '../utils/planSymbols.js';
+import { figmaCollectionNameFor } from '../utils/resolverModes.js';
+
+type PlanVariableSyncCommand = Extract<Command, { type: 'PLAN_VARIABLE_SYNC' }>;
+
+export async function PLAN_VARIABLE_SYNC(payload: PlanVariableSyncCommand['payload']): Promise<void> {
+  const state = getState();
+  if (!state.resolver) {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: 'Load a resolver document before planning sync.',
+        code: 'NO_RESOLVER',
+        commandType: 'PLAN_VARIABLE_SYNC',
+      },
+    });
+    return;
+  }
+
+  const collectionName = figmaCollectionNameFor(state.resolver, payload.collectionName);
+  const engine = new VariableSyncEngine();
+  const { operations } = await engine.buildPlan(state.resolver, collectionName, state.conversionMap, {
+    allowBreaking: payload.allowBreaking === true,
+    overwriteDrift: payload.overwriteDrift === true,
+  });
+  operations.push(...danglingSymbolWarnings(operations));
+  const summary = engine.summarizePlan(operations);
+
+  setState({
+    lastPlan: operations,
+    lastPlanType: 'variable_sync',
+  });
+
+  postToUi({
+    type: 'PLAN_READY',
+    payload: {
+      planType: 'variable_sync',
+      operations,
+      summary,
+    },
+  });
+}
+
+function postToUi(response: Response): void {
+  figma.ui.postMessage(response);
+}

package/main/handlers/readSelectionBindings.ts

@@ -0,0 +1,160 @@
+/**
+ * What the selected layers are bound to, property by property, for the
+ * Selection pane. See `reference.md`, *What the selection is bound to*.
+ *
+ * The page and file scopes walk every layer `QueryEngine` reaches; the answer
+ * is capped, and says how many it left out rather than drawing a list nobody
+ * reads to the end.
+ */
+
+import type { Command, FieldBinding, PropertyBinding, Response, SelectionBindingsPayload } from '../../shared/protocol.js';
+import { FIELDS, namesStyle } from '../../shared/components/fields.js';
+import { applyKindOf, reportField } from '../components/fieldWriter.js';
+import { PropertyMapper, type ExpectedBinding } from '../engines/propertyMapper.js';
+import { QueryEngine } from '../engines/queryEngine.js';
+import { getStamp, stampOn } from '../components/stamp.js';
+import { getState } from '../runtimeState.js';
+import { PAINT_PROPERTIES, boundVariablesOf } from '../utils/boundVariables.js';
+import { loadTemplates } from '../utils/templateStore.js';
+
+type ReadCommand = Extract<Command, { type: 'READ_SELECTION_BINDINGS' }>;
+
+/** The most layers one answer carries. */
+export const MAX_NODES = 200;
+
+export async function READ_SELECTION_BINDINGS(payload: ReadCommand['payload']): Promise<void> {
+  const state = getState();
+  const all = payload.scope === 'selection' ? [...figma.currentPage.selection] : await new QueryEngine().resolve('**', payload.scope);
+  const nodes = all.slice(0, MAX_NODES);
+
+  // A variable's stamp says which token it was written for.
+  const tokenOf = new Map<string, string>();
+  const variableName = new Map<string, string>();
+  for (const variable of await figma.variables.getLocalVariablesAsync()) {
+    variableName.set(variable.id, variable.name);
+    const token = getStamp(variable)?.is.token;
+    if (token !== undefined) tokenOf.set(variable.id, token);
+  }
+
+  const mapper = state.conventions.length > 0 ? new PropertyMapper(state.conventions) : null;
+  const kept = new Map(loadTemplates().map((template) => [template.name, template]));
+
+  const out: SelectionBindingsPayload['nodes'] = [];
+  for (const node of nodes) {
+    const bound = boundVariablesOf(node);
+    const expected = new Map<string, ExpectedBinding>();
+    for (const binding of mapper ? await mapper.inferExpectedBindings(node) : []) expected.set(binding.property, binding);
+
+    const template = templateOf(node, kept);
+    const fields = new Set(template ? Object.keys(stampOn(node)?.receipt ?? {}) : []);
+
+    const names = new Set<string>([...bound.keys(), ...expected.keys()]);
+    for (const [key, property] of Object.entries(PAINT_PROPERTIES)) if (solidColor(node, key) !== null) names.add(property);
+
+    const properties: PropertyBinding[] = [...names].map((property) => {
+      const id = bound.get(property);
+      const suggestion = expected.get(property);
+      return {
+        property,
+        bound: id ? { variableName: variableName.get(id) ?? id, tokenPath: tokenOf.get(id) ?? null } : null,
+        literal: id ? null : literalOf(node, property),
+        suggestion: !id && suggestion?.exists && suggestion.variableId ? (tokenOf.get(suggestion.variableId) ?? null) : null,
+        declaredBy: template && fields.has(fieldOf(property)) ? template.name : null,
+      };
+    });
+
+    out.push({
+      id: node.id,
+      name: node.name,
+      kind: node.type,
+      builtFrom: template ? { template: template.name, fileName: template.fileName, kept: template.kept } : null,
+      properties,
+      fields: await fieldRows(node, variableName, tokenOf),
+    });
+  }
+
+  postToUi({
+    type: 'SELECTION_BINDINGS',
+    payload: {
+      scope: payload.scope,
+      readAt: new Date().toISOString(),
+      nodes: out,
+      ...(all.length > nodes.length ? { more: all.length - nodes.length } : {}),
+    },
+  });
+}
+
+/**
+ * A row for every field the field table lists, with a token column, for the layer's kind, read as the receipt reads
+ * it (`reportField`): bound to a variable, or to a style, or plain, with what it holds where that reads as one value.
+ * A layer of no kind the table has gets none.
+ */
+async function fieldRows(node: SceneNode, variableName: Map<string, string>, tokenOf: Map<string, string>): Promise<FieldBinding[]> {
+  if (!['FRAME', 'COMPONENT', 'INSTANCE', 'SLOT', 'TEXT', 'LINE'].includes(node.type)) return [];
+  const kind = applyKindOf(node);
+  const rows: FieldBinding[] = [];
+  for (const [field, spec] of Object.entries(FIELDS)) {
+    if (!spec.token || !spec.nodes.includes(kind)) continue;
+    const report = reportField(node, field);
+    if (namesStyle(spec)) {
+      const style = typeof report === 'string' && report !== '' ? await figma.getStyleByIdAsync(report) : null;
+      rows.push({ field, bound: style ? { name: style.name, tokenPath: getStamp(style)?.is.token ?? null } : null });
+      continue;
+    }
+    const reports = (Array.isArray(report) ? report : [report]) as Array<{ variable?: string | null } | null>;
+    const id = reports.find((each) => typeof each?.variable === 'string')?.variable ?? undefined;
+    rows.push(
+      id
+        ? { field, bound: { name: variableName.get(id) ?? id, tokenPath: tokenOf.get(id) ?? null } }
+        : { field, bound: null, holds: literalOf(node, PAINT_PROPERTIES[field] ?? field) },
+    );
+  }
+  return rows;
+}
+
+/** The kept template whose set this node is in, by the set's stamp. */
+function templateOf<T>(node: SceneNode, kept: Map<string, T>): T | undefined {
+  let current: BaseNode | null = node;
+  while (current && current.type !== 'PAGE') {
+    if (current.type === 'COMPONENT_SET') {
+      const name = stampOn(current)?.is.component;
+      return name !== undefined ? kept.get(name) : undefined;
+    }
+    current = current.parent;
+  }
+  return undefined;
+}
+
+/** The layer field a property is written by, in a component file's vocabulary. */
+function fieldOf(property: string): string {
+  if (property === PAINT_PROPERTIES.fills) return 'fills';
+  if (property === PAINT_PROPERTIES.strokes) return 'strokes';
+  return property;
+}
+
+/** The first paint's colour as hex, when it is a solid paint. */
+function solidColor(node: SceneNode, key: string): string | null {
+  const paints = (node as unknown as Record<string, unknown>)[key];
+  if (!Array.isArray(paints) || paints.length === 0) return null;
+  const paint = paints[0] as { type?: string; color?: { r: number; g: number; b: number }; opacity?: number };
+  if (paint.type !== 'SOLID' || !paint.color) return null;
+  const byte = (channel: number) =>
+    Math.round(channel * 255)
+      .toString(16)
+      .padStart(2, '0');
+  return `#${byte(paint.color.r)}${byte(paint.color.g)}${byte(paint.color.b)}`;
+}
+
+/** What an unbound property holds, written for reading. */
+function literalOf(node: SceneNode, property: string): string | null {
+  if (property === PAINT_PROPERTIES.fills) return solidColor(node, 'fills');
+  if (property === PAINT_PROPERTIES.strokes) return solidColor(node, 'strokes');
+  const value = (node as unknown as Record<string, unknown>)[property];
+  if (typeof value === 'number') return String(Math.round(value * 100) / 100);
+  if (typeof value === 'string') return value;
+  return null;
+}
+
+function postToUi(response: Response): void {
+  figma.ui.postMessage(response);
+}

package/main/handlers/resizeUi.ts

@@ -0,0 +1,105 @@
+import type { Command, Response, WindowMode } from '../../shared/protocol.js';
+
+type ResizeUiCommand = Extract<Command, { type: 'RESIZE_UI' }>;
+
+/** Key in `figma.clientStorage`, which is per user rather than per file. */
+export const WINDOW_SIZES_KEY = 'windowSizes';
+/** Where a size was kept before the window had two; read once, as the narrow size. */
+export const LEGACY_WINDOW_SIZE_KEY = 'windowSize';
+
+export interface WindowSize {
+  width: number;
+  height: number;
+}
+
+export interface WindowSizes {
+  mode: WindowMode;
+  narrow: WindowSize;
+  wide: WindowSize;
+}
+
+/**
+ * Below this the tab strip wraps and the result surface has no room to be
+ * anything but a header.
+ */
+export const MIN_WINDOW_SIZE: WindowSize = { width: 320, height: 320 };
+
+/** The size a window that has never been resized opens at: the narrow one, which the design is drawn at. */
+export const DEFAULT_WINDOW_SIZE: WindowSize = { width: 460, height: 720 };
+
+/** The wide size until someone drags it: room for the Tokens browser's columns and a detail panel. */
+export const DEFAULT_WIDE_SIZE: WindowSize = { width: 980, height: 620 };
+
+const DEFAULT_SIZES: WindowSizes = { mode: 'narrow', narrow: DEFAULT_WINDOW_SIZE, wide: DEFAULT_WIDE_SIZE };
+
+function clamp(size: WindowSize): WindowSize {
+  return {
+    width: Math.max(MIN_WINDOW_SIZE.width, Math.round(size.width)),
+    height: Math.max(MIN_WINDOW_SIZE.height, Math.round(size.height)),
+  };
+}
+
+const isSize = (value: unknown): value is WindowSize =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as WindowSize).width === 'number' &&
+  typeof (value as WindowSize).height === 'number';
+
+export async function RESIZE_UI(payload: ResizeUiCommand['payload']): Promise<void> {
+  if ('mode' in payload) {
+    // The switch: the other remembered size, and the mode stored with it.
+    const sizes = { ...(await loadWindowSizes()), mode: payload.mode };
+    const size = sizes[payload.mode];
+    figma.ui.resize(size.width, size.height);
+    await store(sizes);
+    postToUi({ type: 'WINDOW_MODE', payload: { mode: payload.mode } });
+    return;
+  }
+
+  const size = clamp(payload);
+  figma.ui.resize(size.width, size.height);
+
+  // Only at the end of a drag, and under the mode the window is in. Persisting
+  // every frame would write to storage dozens of times for one gesture.
+  if (payload.remember) {
+    const sizes = await loadWindowSizes();
+    await store({ ...sizes, [sizes.mode]: size });
+  }
+}
+
+/**
+ * The two sizes and the mode to open in, from a previous session.
+ *
+ * Stored per user rather than in the file: a window size is a property of the
+ * screen someone is sitting at, not of the design system.
+ */
+export async function loadWindowSizes(): Promise<WindowSizes> {
+  try {
+    const stored: unknown = await figma.clientStorage.getAsync(WINDOW_SIZES_KEY);
+    if (typeof stored === 'object' && stored !== null) {
+      const sizes = stored as Partial<WindowSizes>;
+      return {
+        mode: sizes.mode === 'wide' ? 'wide' : 'narrow',
+        narrow: isSize(sizes.narrow) ? clamp(sizes.narrow) : DEFAULT_WINDOW_SIZE,
+        wide: isSize(sizes.wide) ? clamp(sizes.wide) : DEFAULT_WIDE_SIZE,
+      };
+    }
+    const legacy: unknown = await figma.clientStorage.getAsync(LEGACY_WINDOW_SIZE_KEY);
+    if (isSize(legacy)) return { ...DEFAULT_SIZES, narrow: clamp(legacy) };
+  } catch {
+    // A window size is never worth failing to open over.
+  }
+  return DEFAULT_SIZES;
+}
+
+async function store(sizes: WindowSizes): Promise<void> {
+  try {
+    await figma.clientStorage.setAsync(WINDOW_SIZES_KEY, sizes);
+  } catch {
+    // The window still resized; only the memory of it is lost.
+  }
+}
+
+function postToUi(response: Response): void {
+  figma.ui.postMessage(response);
+}

package/main/handlers/runComponent.ts

@@ -0,0 +1,65 @@
+import type { Command, Response } from '../../shared/protocol.js';
+import { ComponentRunError } from '../components/errors.js';
+import { beginRun, findStrays, finishRun, strayLine } from '../components/endOfRun.js';
+import { checkComponents, runComponentFile } from '../components/file.js';
+import { brokenSetProblems } from '../components/snapshot.js';
+import { getState } from '../runtimeState.js';
+
+type RunComponentCommand = Extract<Command, { type: 'RUN_COMPONENT' }>;
+type CheckComponentsCommand = Extract<Command, { type: 'CHECK_COMPONENTS' }>;
+type FinishComponentsCommand = Extract<Command, { type: 'FINISH_COMPONENTS' }>;
+
+/**
+ * Runs one component file, given as text and a name: the entry the Templates pane's build uses too (`components/file.ts`).
+ *
+ * The engine stops with a `ComponentRunError` before its first write for everything it can foresee
+ * (a file that does not read, a name that does not resolve, a set that is not ours, a step that breaks
+ * instances), so those come back as an `ERROR` carrying every reason. Anything else is Figma's, and
+ * the dispatcher reports it. A plugin does not roll back: a failure in the middle of the writes leaves
+ * what was written, and the next run reconciles it.
+ */
+export async function RUN_COMPONENT(payload: RunComponentCommand['payload']): Promise<void> {
+  try {
+    postToUi({ type: 'COMPONENT_RUN', payload: await runComponentFile(payload.text, payload.fileName, payload.options, payload.inputs) });
+  } catch (error) {
+    if (!(error instanceof ComponentRunError)) throw error;
+    postToUi({
+      type: 'ERROR',
+      payload: { message: error.message, code: 'COMPONENT_RUN_FAILED', commandType: 'RUN_COMPONENT', problems: error.problems },
+    });
+  }
+}
+
+/** Reads every file and says every problem of every file, and which of their sets Figma already reports as broken, writing nothing. */
+export async function CHECK_COMPONENTS(payload: CheckComponentsCommand['payload']): Promise<void> {
+  const { errors, components } = checkComponents(
+    payload.files,
+    { names: payload.names === true, ...(payload.inputs ? { inputs: payload.inputs } : {}) },
+    getState().resolver,
+  );
+  const problems = [...errors, ...(await brokenSetProblems(components))];
+  // The start of a run. Strays are found once, here, before anything is written: they are breaking, so a real run without the flag stops on them.
+  beginRun();
+  const strays = payload.files.length > 0 ? (await findStrays()).map(strayLine) : [];
+  if (strays.length > 0 && !payload.dryRun && !payload.allowBreaking) problems.push(...strays);
+  if (problems.length === 0)
+    return postToUi({ type: 'COMPONENTS_CHECKED', payload: { files: payload.files.length, ...(strays.length > 0 ? { strays } : {}) } });
+  postToUi({
+    type: 'ERROR',
+    payload: {
+      message: `${problems.length === 1 ? 'one problem' : `${problems.length} problems`} in the component files, and nothing was sent on`,
+      code: 'COMPONENT_RUN_FAILED',
+      commandType: 'CHECK_COMPONENTS',
+      problems,
+    },
+  });
+}
+
+/** The end of a run: the strays removed when allowed, and each page's sets and artboards stacked again. */
+export async function FINISH_COMPONENTS(payload: FinishComponentsCommand['payload']): Promise<void> {
+  postToUi({ type: 'COMPONENTS_FINISHED', payload: await finishRun(payload) });
+}
+
+function postToUi(response: Response): void {
+  figma.ui.postMessage(response);
+}