@toghen/figma 0.0.0-stage → 0.1.1

package/main/utils/boundVariables.ts

@@ -0,0 +1,84 @@
+/**
+ * Which variables a layer is bound to, property by property, the first fill's
+ * and stroke's paints included (those are bound on the paint, not the node).
+ */
+
+import { FIELDS, type FieldSpec } from '../../shared/components/fields.js';
+
+/** Field to what `pick` reads from its row of the field table, for the fields it reads something from. */
+function fromTable<T>(pick: (name: string, spec: FieldSpec) => T | undefined): Record<string, T> {
+  const out: Record<string, T> = {};
+  for (const [name, spec] of Object.entries(FIELDS)) {
+    const value = pick(name, spec);
+    if (value !== undefined) out[name] = value;
+  }
+  return out;
+}
+
+/** The property names a paint binding is reported under, as conventions name them: `fills[0].color`, read from the field table. */
+export const PAINT_PROPERTIES: Readonly<Record<string, string>> = fromTable((name, spec) =>
+  spec.token?.bind?.call === 'paint' ? `${name}[0].${spec.token.bind.field}` : undefined,
+);
+
+/**
+ * Fields whose binding Figma reports on their parts, read from the field table. Bound to a variable, `cornerRadius` is
+ * reported as its four corners bound to it, with no `cornerRadius` key (measured 20 October 2026), and `strokeWeight`
+ * as its four sides.
+ */
+export const BOUND_BY_PARTS: Readonly<Record<string, readonly string[]>> = fromTable((_name, spec) => spec.token?.bind?.parts);
+
+/**
+ * The id of the variable a field is bound to, in a node's `boundVariables`. A field Figma binds by its parts is bound
+ * when every part is bound to one variable; `null` when only some are, or to different variables, and `undefined`
+ * when the field is not bound at all.
+ */
+export function boundIdOf(bound: Record<string, unknown>, field: string): string | null | undefined {
+  // A text field is reported as an array of aliases, one per bound range: bound when they all name one variable.
+  // ponytail: a field bound on one range only reads as bound too (measured §14: one alias); `getRangeBoundVariable`
+  // over the whole text would tell, should a person's partial binding need catching.
+  const ranges = bound[field];
+  if (Array.isArray(ranges) && FIELDS[field]?.token?.bind?.call === 'text') {
+    const ids = new Set(ranges.map(idOf));
+    return ids.size === 0 ? undefined : ids.size === 1 ? ([...ids][0] ?? null) : null;
+  }
+  const own = idOf(bound[field]);
+  const parts = BOUND_BY_PARTS[field];
+  if (own !== undefined || !parts) return own;
+  const ids = new Set(parts.map((part) => idOf(bound[part])));
+  return ids.size === 1 ? [...ids][0] : null;
+}
+
+/** Property → bound variable id. */
+export function boundVariablesOf(node: SceneNode): Map<string, string> {
+  const found = new Map<string, string>();
+  const bound = (node as { boundVariables?: Record<string, unknown> }).boundVariables ?? {};
+  for (const [property, value] of Object.entries(bound)) {
+    const id = idOf(Array.isArray(value) ? value[0] : value);
+    if (id && !(property in PAINT_PROPERTIES)) found.set(property, id);
+  }
+  // A field bound by its parts is named once, as the file and the conventions name it.
+  for (const [field, parts] of Object.entries(BOUND_BY_PARTS)) {
+    const id = boundIdOf(bound, field);
+    if (!id) continue;
+    for (const part of parts) found.delete(part);
+    found.set(field, id);
+  }
+  for (const [key, property] of Object.entries(PAINT_PROPERTIES)) {
+    const paints = (node as unknown as Record<string, unknown>)[key];
+    if (!Array.isArray(paints) || paints.length === 0) continue;
+    const id = idOf((paints[0] as { boundVariables?: { color?: unknown } }).boundVariables?.color);
+    if (id) found.set(property, id);
+  }
+  return found;
+}
+
+export function boundVariableIds(node: SceneNode): string[] {
+  return [...boundVariablesOf(node).values()];
+}
+
+function idOf(alias: unknown): string | undefined {
+  if (typeof alias === 'string') return alias;
+  if (typeof alias === 'object' && alias !== null && typeof (alias as { id?: unknown }).id === 'string')
+    return (alias as { id: string }).id;
+  return undefined;
+}

package/main/utils/buildPayloads.ts

@@ -0,0 +1,85 @@
+import type { Resolver } from '@toghen/lib';
+import { figmaCollectionNameFor, pathsInAnyMode, readToken, resolveSumModes } from './resolverModes.js';
+import { buildSum } from './sum.js';
+import { defaultTokenTypeMap, type TokenTypeConversionMap } from '../../shared/tokenTypeMap.js';
+import type { DocumentCollectionSummary, DocumentStatePayload, SelectionPayload } from '../../shared/protocol.js';
+
+export function buildDocumentStatePayload(
+  resolver: Resolver,
+  conversionMap: TokenTypeConversionMap = defaultTokenTypeMap,
+  fileName: string | null = null,
+): DocumentStatePayload {
+  const modifiers: Record<string, string[]> = {};
+  const modifierDefaults: Record<string, string> = {};
+  for (const modifier of resolver.getModifiers()) {
+    modifiers[modifier.name] = modifier.contexts;
+    if (modifier.default !== undefined) modifierDefaults[modifier.name] = modifier.default;
+  }
+  // The sum, as `LOAD_DOCUMENT` builds it; never the product, which a large
+  // document cannot finish. The count is of distinct token paths: a token is
+  // one token however many modes give it a value.
+  const resolution = resolveSumModes(resolver);
+  const { ds, dsCollectionName, defaultMode, modeNames } = resolution;
+  const paths = pathsInAnyMode(resolution);
+  const tokenCount = paths.size;
+  let styleCount = 0;
+  for (const [path, [mode]] of paths) {
+    const type = readToken(ds, `${dsCollectionName}.${path}`, mode)?.$type;
+    if (type !== undefined && conversionMap[type]?.target === 'style') styleCount += 1;
+  }
+
+  const version = resolver.getDeclaredVersion();
+  const collections = sumCollections(resolver, conversionMap);
+
+  return {
+    loaded: true,
+    name: resolver.name ?? 'Untitled',
+    description: resolver.description,
+    tokenCount,
+    modifiers,
+    modes: modeNames,
+    modifierDefaults,
+    defaultMode,
+    ...(version ? { version } : {}),
+    ...(fileName ? { fileName } : {}),
+    styleCount,
+    ...(collections ? { collections } : {}),
+  };
+}
+
+/**
+ * The collections a variable sync would build, with how many variables each
+ * would hold, from the same sum the plan builds from.
+ *
+ * Undefined when the sum cannot be built: the plan says why, and a table drawn
+ * from a guess would contradict it.
+ */
+function sumCollections(resolver: Resolver, conversionMap: TokenTypeConversionMap): DocumentCollectionSummary[] | undefined {
+  try {
+    const sum = buildSum(resolver, figmaCollectionNameFor(resolver), conversionMap);
+    const counts = new Map<string, number>();
+    for (const token of sum.tokens) {
+      for (const variable of token.variables) {
+        counts.set(variable.collection, (counts.get(variable.collection) ?? 0) + 1);
+      }
+    }
+    return sum.collections.map((collection) => ({
+      name: collection.name,
+      ...(collection.modifier ? { modifier: collection.modifier } : {}),
+      // A folded part axis's collection says so, or the screen draws it like the base collection (smell #44).
+      ...(collection.axis ? { axis: true as const } : {}),
+      modes: [...collection.modes],
+      variableCount: counts.get(collection.name) ?? 0,
+    }));
+  } catch {
+    return undefined;
+  }
+}
+
+export function buildSelectionPayload(selection: readonly SceneNode[]): SelectionPayload {
+  return {
+    ids: selection.map((node) => node.id),
+    names: selection.map((node) => node.name),
+    count: selection.length,
+  };
+}