@toghen/figma 0.0.0-stage → 0.1.1

package/main/utils/designSource.ts

@@ -0,0 +1,122 @@
+/**
+ * The design system, as a component file asks about it (`shared/components/axes.ts`).
+ *
+ * The reader holds no `@toghen/lib`, so what a file may ask (the contexts of a modifier,
+ * the part axes a token group has) is answered here, by lib: in the
+ * repository for the command line, and on the main thread for a template kept in a file. The answers are asked for lazily: a file that takes nothing from the tokens
+ * never builds the sum, so a document the sum cannot be built from (a modifier with no
+ * default) only matters to a file that needs it.
+ */
+
+import { referencePath, type Collection, type Resolver } from '@toghen/lib';
+import type { DesignSource } from '../../shared/components/axes.js';
+import type { GroupInfo } from '../../shared/components/model.js';
+import { foldsOf, unfoldedFor, type Folds } from './folds.js';
+import { figmaContexts, pathsInAnyMode, resolveSumModes, snapshotModes } from './resolverModes.js';
+import type { ModeSnapshot } from './resolverModes.js';
+
+interface Modifier {
+  name: string;
+  /** Every context, the default first: the default member of an axis, as the first mode of a Figma collection. */
+  contexts: string[];
+  /** The contexts Figma gets, in that order (`figmaContexts`). Read when asked: a modifier's bad `figma.include` is only the problem of a file that uses it. */
+  figma(): string[];
+}
+
+export function designSourceOf(resolver: Resolver): DesignSource {
+  let built:
+    | { modifiers: Modifier[]; paths: string[]; collection: string; tokens: Collection; resolution: ReturnType<typeof resolveSumModes> }
+    | undefined;
+  const foldsCache = new Map<string, Folds>();
+  // The values of every token in every context, read only for a group with a composite `border` in it.
+  let snapshots: ModeSnapshot[] | undefined;
+  const design = () => {
+    if (built) return built;
+    // The sum, as variable sync builds it; the modifiers in the document's declared order, with their spelling.
+    const resolution = resolveSumModes(resolver);
+    const { ds, dsCollectionName } = resolution;
+    const collection = ds.getCollection(dsCollectionName);
+    // `resolveSumModes` has refused a modifier with no default.
+    const modifiers = resolver.getModifiers().map(
+      (modifier): Modifier => ({
+        name: modifier.name,
+        contexts: [modifier.default!, ...modifier.contexts.filter((context) => context !== modifier.default)],
+        figma: () => figmaContexts(modifier),
+      }),
+    );
+    built = {
+      modifiers,
+      paths: [...pathsInAnyMode(resolution).keys()],
+      collection: dsCollectionName,
+      tokens: collection as Collection,
+      resolution,
+    };
+    return built;
+  };
+
+  return {
+    // A component file takes the contexts Figma gets: the others have no mode to pin.
+    contexts: (modifier) =>
+      design()
+        .modifiers.find((entry) => entry.name === modifier)
+        ?.figma(),
+    leftOut: (modifier) => {
+      const found = design().modifiers.find((entry) => entry.name === modifier);
+      const gets = found?.figma();
+      return found && gets ? found.contexts.filter((context) => !gets.includes(context)) : undefined;
+    },
+    partsOf: (group, layoutParts) => {
+      const { paths, tokens } = design();
+      if (tokens.getNodeKind(group) === 'missing') return undefined;
+      // This file's own layout decides its component; the others keep what the files checked before it said.
+      const stored = unfoldedFor(resolver).filter((name) => name !== group);
+      const unfold = layoutParts ? [...stored, group] : stored;
+      const key = unfold.join('\n');
+      let folds = foldsCache.get(key);
+      if (!folds) foldsCache.set(key, (folds = foldsOf(tokens, paths, unfold)));
+      return folds.components.find((component) => component.group === group)?.axes ?? [];
+    },
+    children: (path) => {
+      const { tokens } = design();
+      if (tokens.getNodeKind(path) === 'token') return 'token';
+      // One name for each child, tokens and groups alike, in document order (lib's `childrenOf`).
+      const names = tokens.childrenOf(path).map((child) => child.key);
+      return names.length > 0 ? names : undefined;
+    },
+    group: (path, selection = {}) => {
+      const { tokens, collection, resolution } = design();
+      // The token each key is: in the group, or in a part group the member selects (`button.primary.backgroundColor`),
+      // as lib's `applies` rules: more parts wins, then the later axis; the document's key order never matters.
+      const at = tokens.applies(path, selection);
+      const keys = Object.keys(at);
+      const kind = tokens.getNodeKind(path);
+      if (keys.length === 0) return kind === 'group' ? { keys } : kind === 'token' ? 'token' : undefined;
+
+      const info: GroupInfo = { keys };
+      const moved = keys.filter((key) => at[key] !== `${path}.${key}`);
+      if (moved.length > 0) {
+        info.paths = {};
+        for (const key of moved) info.paths[key] = at[key];
+      }
+      snapshots ??= snapshotModes(resolution);
+      const prefix = `${collection}.`;
+      for (const key of keys) {
+        // `background` binds the fill only when its token is a colour in every context.
+        if (key === 'background' && snapshots.every((snapshot) => snapshot.pathToToken.get(`${prefix}${at[key]}`)?.type === 'color'))
+          info.colors = [key];
+        // A composite `border`: its members are what binds. A member that is one whole reference binds the
+        // token it refers to (in the default context); a style that is not solid, in any context, is not bindable.
+        const token = (snapshot: ModeSnapshot) => snapshot.pathToToken.get(`${prefix}${at[key]}`);
+        if (snapshots.every((snapshot) => token(snapshot)?.type !== 'border')) continue;
+        const border: NonNullable<GroupInfo['borders']>[string] = {};
+        const members = token(snapshots[0])?.memberOf ?? {};
+        if (members.color) border.color = referencePath(members.color);
+        if (members.width) border.width = referencePath(members.width);
+        if (snapshots.some((snapshot) => token(snapshot) && (token(snapshot)?.value as { style?: unknown } | undefined)?.style !== 'solid'))
+          border.unsolid = true;
+        (info.borders ??= {})[key] = border;
+      }
+      return info;
+    },
+  };
+}

package/main/utils/figmaCollectionIndex.ts

@@ -0,0 +1,120 @@
+import { getStamp, sortOut, type Stamp } from '../components/stamp.js';
+
+export interface IndexedMode {
+  modeId: string;
+  name: string;
+}
+
+export interface IndexedCollection {
+  id: string;
+  name: string;
+  modes: IndexedMode[];
+}
+
+export interface IndexedVariable {
+  id: string;
+  name: string;
+  variableCollectionId: string;
+  resolvedType: VariableResolvedDataType;
+  /**
+   * What Figma currently holds, per mode id.
+   *
+   * The plugin used to index a variable's identity and never its contents, so
+   * it could not see a value a designer had changed by hand: every difference
+   * it detected was a difference in the *document*. This is the other half of
+   * the comparison.
+   */
+  valuesByMode: Record<string, VariableValue>;
+  /** The code syntax Figma holds for the web, when it holds one. */
+  codeSyntaxWeb?: string;
+  /** What the variable may be bound to, in Figma's own order. */
+  scopes: VariableScope[];
+  /** What Toghen keeps on the variable: the token it holds and a receipt of what it wrote. Absent on one Toghen did not write. */
+  stamp?: Stamp;
+  /** Toghen's variable, moved: its stamp names another id, which the next write replaces with its own (`sortOut`). */
+  moved?: true;
+}
+
+export interface FigmaCollectionIndex {
+  byName: Record<string, IndexedCollection>;
+  byId: Record<string, IndexedCollection>;
+  variableById: Record<string, IndexedVariable>;
+  variableByCollectionAndName: Record<string, IndexedVariable>;
+  /** The variables stamped for each token, by the key the sync gives it: one, or more where a token moved collection and the old one is still there. A copy is not among them. */
+  variablesByToken: Record<string, IndexedVariable[]>;
+  /** The copies a person made of a variable Toghen wrote, each with the original: never written, never removed, never counted as Toghen's. */
+  copies: Array<{ copy: IndexedVariable; of: IndexedVariable }>;
+}
+
+function pairKey(collectionId: string, variableName: string): string {
+  return `${collectionId}::${variableName}`;
+}
+
+export async function indexFigmaCollections(): Promise<FigmaCollectionIndex> {
+  const byName: Record<string, IndexedCollection> = {};
+  const byId: Record<string, IndexedCollection> = {};
+  const variableById: Record<string, IndexedVariable> = {};
+  const variableByCollectionAndName: Record<string, IndexedVariable> = {};
+  const variablesByToken: Record<string, IndexedVariable[]> = {};
+
+  const collections = await figma.variables.getLocalVariableCollectionsAsync();
+  for (const collection of collections) {
+    const indexedCollection: IndexedCollection = {
+      id: collection.id,
+      name: collection.name,
+      modes: collection.modes.map((mode) => ({ modeId: mode.modeId, name: mode.name })),
+    };
+
+    byName[indexedCollection.name] = indexedCollection;
+    byId[indexedCollection.id] = indexedCollection;
+  }
+
+  const variables = await figma.variables.getLocalVariablesAsync();
+  const indexed: IndexedVariable[] = [];
+  for (const variable of variables) {
+    const stamp = getStamp(variable);
+    const indexedVariable: IndexedVariable = {
+      id: variable.id,
+      name: variable.name,
+      variableCollectionId: variable.variableCollectionId,
+      resolvedType: variable.resolvedType,
+      valuesByMode: { ...variable.valuesByMode },
+      scopes: [...(variable.scopes ?? ['ALL_SCOPES'])],
+      // measured 2026-10-08 (measured behaviour §10): `codeSyntax` reads back what `setVariableCodeSyntax` wrote, under the key 'WEB'
+      ...(variable.codeSyntax?.WEB !== undefined ? { codeSyntaxWeb: variable.codeSyntax.WEB } : {}),
+      ...(stamp ? { stamp } : {}),
+    };
+
+    variableById[indexedVariable.id] = indexedVariable;
+    variableByCollectionAndName[pairKey(indexedVariable.variableCollectionId, indexedVariable.name)] = indexedVariable;
+    indexed.push(indexedVariable);
+  }
+
+  const sorted = await sortOut(
+    indexed,
+    (variable) => variable.stamp,
+    (id) => variableById[id],
+  );
+  for (const variable of sorted.ours) {
+    if (sorted.moved.has(variable)) variable.moved = true;
+    const token = variable.stamp?.is.token;
+    if (token !== undefined) (variablesByToken[token] ??= []).push(variable);
+  }
+
+  return {
+    byName,
+    byId,
+    variableById,
+    variableByCollectionAndName,
+    variablesByToken,
+    copies: sorted.copies,
+  };
+}
+
+export function getIndexedVariableByCollectionAndName(
+  index: FigmaCollectionIndex,
+  collectionId: string,
+  variableName: string,
+): IndexedVariable | undefined {
+  return index.variableByCollectionAndName[pairKey(collectionId, variableName)];
+}

package/main/utils/figmaStyleAdapter.ts

@@ -0,0 +1,268 @@
+import {
+  normalizeColorToSRGB01,
+  normalizeDimensionToPx,
+  normalizeGradient,
+  normalizeLineHeight,
+  type DimensionValue,
+  type GradientKind,
+  type GradientValue,
+  type ShadowValue,
+  type TypographyValue,
+} from '@toghen/lib';
+import { toFigmaFontFamily } from './figmaTokenAdapter.js';
+
+export interface TextStyleProps {
+  fontFamily: string;
+  fontStyle: string;
+  fontSize: number;
+  lineHeight: LineHeight;
+  letterSpacing: LetterSpacing;
+  textCase: TextCase;
+  textDecoration: TextDecoration;
+}
+
+export interface EffectStyleProps {
+  effects: Effect[];
+}
+
+export interface PaintStyleProps {
+  paints: Paint[];
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * A length in pixels. The unit arithmetic is the library's, and so is the
+ * check: `normalizeDimensionToPx()` throws on anything that is not a dimension,
+ * which is why the cast below claims nothing it cannot back.
+ */
+function toPx(value: unknown): number {
+  return normalizeDimensionToPx(value as DimensionValue);
+}
+
+/**
+ * Converts a W3C `lineHeight` to Figma's `LineHeight`.
+ *
+ * The library reads the value; this only reshapes it. The case that matters is
+ * the **unitless multiplier** — `1.5`, the W3C form and the one the demo uses.
+ * It is a ratio of the font size, which Figma expresses as PERCENT. Sending it
+ * down the PIXELS branch, as this once did, sets a 1.5 *pixel* line height and
+ * collapses the text. A length, `'24px'` or `{value, unit}`, stays in PIXELS.
+ *
+ * `'normal'` is not a W3C value and the library rejects it, but it has an exact
+ * Figma counterpart — AUTO, the font's own leading — so it is mapped here.
+ */
+export function toFigmaLineHeight(value: unknown): LineHeight {
+  if (typeof value === 'string' && value.trim().toLowerCase() === 'normal') {
+    return { unit: 'AUTO' };
+  }
+
+  const lineHeight = normalizeLineHeight(value as TypographyValue['lineHeight']);
+  switch (lineHeight.unit) {
+    case 'ratio':
+      return { unit: 'PERCENT', value: lineHeight.value * 100 };
+    case 'percent':
+      return { unit: 'PERCENT', value: lineHeight.value };
+    case 'px':
+      return { unit: 'PIXELS', value: lineHeight.value };
+  }
+}
+
+/**
+ * Converts a W3C `letterSpacing` to Figma's `LetterSpacing`.
+ *
+ * A W3C letterSpacing is a dimension, and goes to PIXELS through the library.
+ * `em` and `%` are not W3C units, but they are how letter spacing is usually
+ * written, and both are proportional to the font size — which Figma expresses
+ * as PERCENT, `1em` being 100%. This once hardcoded PIXELS, so `'0.05em'`
+ * became 0.05px (imperceptible, when 0.8px was meant) and `'5%'` became 5px.
+ *
+ * An absent letterSpacing is 0, as the library's `getLetterSpacingPx()` has it.
+ */
+export function toFigmaLetterSpacing(value: unknown): LetterSpacing {
+  if (value === undefined) {
+    return { unit: 'PIXELS', value: 0 };
+  }
+
+  // `{ value, unit: 'em' }`, the structured form of the string below.
+  if (isObject(value) && value.unit === 'em' && typeof value.value === 'number' && Number.isFinite(value.value)) {
+    return { unit: 'PERCENT', value: value.value * 100 };
+  }
+
+  if (typeof value === 'string') {
+    const text = value.trim().toLowerCase();
+    const suffix = text.endsWith('%') ? '%' : text.endsWith('em') && !text.endsWith('rem') ? 'em' : '';
+    if (suffix) {
+      const amount = Number(text.slice(0, -suffix.length) || NaN);
+      if (!Number.isFinite(amount)) {
+        throw new Error(`Invalid letterSpacing '${value}'.`);
+      }
+      return { unit: 'PERCENT', value: suffix === 'em' ? amount * 100 : amount };
+    }
+  }
+
+  return { unit: 'PIXELS', value: toPx(value) };
+}
+
+function normalizeTextCase(value: unknown): TextCase {
+  if (typeof value !== 'string') return 'ORIGINAL';
+  switch (value.trim().toLowerCase()) {
+    case 'uppercase':
+      return 'UPPER';
+    case 'lowercase':
+      return 'LOWER';
+    case 'capitalize':
+      return 'TITLE';
+    default:
+      return 'ORIGINAL';
+  }
+}
+
+function normalizeTextDecoration(value: unknown): TextDecoration {
+  if (typeof value !== 'string') return 'NONE';
+  switch (value.trim().toLowerCase()) {
+    case 'underline':
+      return 'UNDERLINE';
+    case 'line-through':
+    case 'strikethrough':
+      return 'STRIKETHROUGH';
+    default:
+      return 'NONE';
+  }
+}
+
+/**
+ * Positions a linear gradient within a layer, rotated by `angleDeg`.
+ *
+ * A rotation about the layer's centre — `translate(½,½) ∘ rotate(θ) ∘
+ * translate(−½,−½)` — and nothing else:
+ *
+ * ```
+ * ⎡ cosθ  −sinθ   ½ − ½cosθ + ½sinθ ⎤
+ * ⎣ sinθ   cosθ   ½ − ½sinθ − ½cosθ ⎦
+ * ```
+ *
+ * At 0° that is exactly `[[1,0,0],[0,1,0]]`, the transform measured against a
+ * real file for a full-width left-to-right gradient — see
+ * `.reference/figma/measured_behaviour.md` §6. That identity is the anchor, and
+ * the test asserts it.
+ *
+ * This used to scale by ½ as well, so the layer sampled only the ramp's second
+ * half: a `#0066cc → #004d99` gradient rendered entirely between `#0059b2` and
+ * `#004d99`, with its first stop appearing nowhere on the shape. It went
+ * unnoticed because nothing tested the function and the probe only ever
+ * round-tripped a hand-written transform.
+ *
+ * ### Unmeasured
+ *
+ * At angles that are not multiples of 90° the gradient's extent along the
+ * diagonal exceeds the unit square, so a 45° gradient does not span corner to
+ * corner the way a CSS `linear-gradient` does. Correcting that needs a
+ * measurement of Figma's convention rather than more arithmetic. The W3C array
+ * form is always 0°, so no spec-conformant gradient is affected today.
+ */
+function angleToLinearTransform(angleDeg: number): Transform {
+  const radians = (angleDeg * Math.PI) / 180;
+  const cos = Math.cos(radians);
+  const sin = Math.sin(radians);
+
+  return [
+    [cos, -sin, 0.5 - 0.5 * cos + 0.5 * sin],
+    [sin, cos, 0.5 - 0.5 * sin - 0.5 * cos],
+  ];
+}
+
+export function toTextStyleProps(value: unknown): TextStyleProps {
+  if (!isObject(value)) {
+    throw new Error('Typography token value must be an object.');
+  }
+
+  // No cast: every reader below accepts `unknown` and narrows for itself — the
+  // dimensions through the library, which throws on a value it cannot read — so
+  // asserting the shape here would only be a claim we cannot back.
+  return {
+    fontFamily: toFigmaFontFamily(value.fontFamily),
+    fontStyle: String(value.fontStyle ?? 'Regular'),
+    fontSize: toPx(value.fontSize),
+    lineHeight: toFigmaLineHeight(value.lineHeight),
+    letterSpacing: toFigmaLetterSpacing(value.letterSpacing),
+    textCase: normalizeTextCase(value.textTransform),
+    textDecoration: normalizeTextDecoration(value.textDecoration),
+  };
+}
+
+/**
+ * `currentColor` has no value until an element uses it, and Figma has no equivalent, so a style holding it
+ * (a shadow's colour, a gradient stop) cannot be built. Said in words rather than as the colour
+ * parser's complaint about a string that is not hex.
+ */
+function refuseCurrentColor(value: unknown): void {
+  if (typeof value === 'string' && value.trim().toLowerCase() === 'currentcolor') {
+    throw new Error('it holds currentColor, which Figma cannot hold.');
+  }
+  if (isObject(value) || Array.isArray(value)) {
+    Object.values(value).forEach(refuseCurrentColor);
+  }
+}
+
+export function toEffectStyleProps(value: unknown): EffectStyleProps {
+  refuseCurrentColor(value);
+  const list = Array.isArray(value) ? value : [value];
+
+  const effects: Effect[] = list.map((raw) => {
+    if (!isObject(raw)) {
+      throw new Error('Shadow token value must be an object or array of objects.');
+    }
+
+    const color = normalizeColorToSRGB01(raw.color as ShadowValue['color']);
+
+    return {
+      type: raw.inset ? 'INNER_SHADOW' : 'DROP_SHADOW',
+      color,
+      offset: {
+        x: toPx(raw.offsetX),
+        y: toPx(raw.offsetY),
+      },
+      radius: toPx(raw.blur),
+      spread: raw.spread === undefined ? 0 : toPx(raw.spread),
+      visible: true,
+      blendMode: 'NORMAL',
+    };
+  });
+
+  return { effects };
+}
+
+const GRADIENT_PAINT_TYPE: Record<GradientKind, GradientPaint['type']> = {
+  linear: 'GRADIENT_LINEAR',
+  radial: 'GRADIENT_RADIAL',
+  angular: 'GRADIENT_ANGULAR',
+  conic: 'GRADIENT_ANGULAR',
+};
+
+export function toPaintStyleProps(value: unknown): PaintStyleProps {
+  refuseCurrentColor(value);
+  // `normalizeGradient` accepts both gradient forms — the W3C array of stops
+  // (§9.7) and Toghen's object form. This used to require the object form and
+  // reject arrays outright, which made every spec-conformant gradient token
+  // throw before a single operation was planned.
+  const gradient = normalizeGradient(value as GradientValue);
+
+  const paint: GradientPaint = {
+    type: GRADIENT_PAINT_TYPE[gradient.type],
+    gradientStops: gradient.stops.map((stop) => ({
+      position: stop.position,
+      color: stop.color,
+    })),
+    gradientTransform: angleToLinearTransform(gradient.angleDeg),
+    visible: true,
+    opacity: 1,
+    blendMode: 'NORMAL',
+  };
+
+  return {
+    paints: [paint],
+  };
+}