@toghen/figma 0.0.0-stage → 0.1.0

package/shared/components/groups.ts

@@ -0,0 +1,306 @@
+/**
+ * The token groups a component file names, read from the design system.
+ *
+ * `tokens="{group}"` on a layer, and on the component line for the root, infers bindings
+ * from the keys of the group's tokens (`bindings.ts`). That needs what the group holds, and
+ * only the reader has the design system: the answer is stored on the component
+ * (`Component.groups`), so the engine infers the same bindings without one. Like
+ * `resolveAxes`, this is the reader's step.
+ */
+
+import { referenceTarget } from '@toghen/lib';
+import type { OutNode } from 'kdlet';
+import { planKey, viaAxes } from './axes.js';
+import type { DesignSource, Expanded } from './axes.js';
+import { FIELDS } from './fields.js';
+import type { Component, GroupInfo, GroupPlan, Laid, Layer, Loc, Problem } from './model.js';
+
+// ---------------------------------------------------------------------------
+// The table: which Figma fields a CSS key fills. DTCG does not know; this adapter does.
+// ---------------------------------------------------------------------------
+
+/** A Figma field and how specific the key that offers it is: the higher rank wins, whatever the document's order. */
+type Target = [field: string, rank: number];
+
+const SIDES = ['Top', 'Right', 'Bottom', 'Left'] as const;
+
+/** Keys whose Figma field has the same name, on every kind of layer. */
+const SAME = ['opacity', 'width', 'height', 'minWidth', 'maxWidth', 'minHeight', 'maxHeight'];
+
+/** The keys whose field depends on the layer's layout. */
+const GAPS = ['gap', 'rowGap', 'columnGap'];
+
+/**
+ * The fields a key writes on a `TEXT` or on a `FRAME` or `SLOT`, or `undefined` when it writes none.
+ *
+ * Figma has only horizontal writing, so `paddingBlock` is top and bottom and `paddingInline` left and
+ * right. A more specific key outranks a general one for the same field: `paddingTop` over `paddingBlock`
+ * over `padding`, `borderColor` and `borderWidth` over a composite `border`.
+ */
+function targets(key: string, text: boolean, color: boolean): Target[] | undefined {
+  if (SAME.includes(key)) return [[key, 1]];
+  if (text) return key === 'color' ? [['fills', 1]] : key === 'font' ? [['textStyle', 1]] : undefined;
+  const padding = /^padding(Top|Right|Bottom|Left)$/.exec(key);
+  if (padding) return [[key, 3]];
+  const stroke = /^border(Top|Right|Bottom|Left)Width$/.exec(key);
+  if (stroke) return [[`stroke${stroke[1]}Weight`, 3]];
+  const corner = /^border(Top|Bottom)(Left|Right)Radius$/.exec(key);
+  if (corner) return [[`${corner[1].toLowerCase()}${corner[2]}Radius`, 3]];
+  switch (key) {
+    case 'backgroundColor':
+      return [['fills', 1]];
+    // The shorthand, when the token holds one colour: a gradient or an image has no fill to bind. `backgroundColor` outranks it.
+    case 'background':
+      return color ? [['fills', 0]] : undefined;
+    case 'borderColor':
+      return [['strokes', 2]];
+    case 'borderWidth':
+      return [['strokeWeight', 2]];
+    case 'borderRadius':
+      return [['cornerRadius', 1]];
+    case 'padding':
+      return SIDES.map((side): Target => [`padding${side}`, 1]);
+    case 'paddingBlock':
+      return [
+        ['paddingTop', 2],
+        ['paddingBottom', 2],
+      ];
+    case 'paddingInline':
+      return [
+        ['paddingLeft', 2],
+        ['paddingRight', 2],
+      ];
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * The Figma scope a field belongs to, as the field table holds it: the pickers a variable bound to it should be offered in. The field is one
+ * `targets()` gives; a fill is a frame's or a text's. Variable sync reads the same table, so a variable is
+ * scoped to the fields the component files will bind it to.
+ */
+export function scopesOfField(field: string, text: boolean): VariableScope[] {
+  const scope = FIELDS[field]?.token?.bind?.scope ?? [];
+  return [...('text' in scope ? (text ? scope.text : scope.other) : scope)];
+}
+
+/**
+ * The scopes a token whose last key is `key` is for, on a text layer and on a frame, or `undefined` when the
+ * key fills no field. A key is read as a variable holds one colour, as `background` does.
+ */
+export function scopesOfKey(key: string): VariableScope[] | undefined {
+  const scopes = new Set<VariableScope>();
+  for (const text of [true, false]) {
+    for (const [field] of targets(key, text, true) ?? []) for (const scope of scopesOfField(field, text)) scopes.add(scope);
+  }
+  if (GAPS.includes(key)) scopes.add('GAP');
+  return scopes.size > 0 ? [...scopes] : undefined;
+}
+
+/** Works out what a group binds on each kind of layer, from the keys of its tokens. */
+export function planOf(group: string, info: GroupInfo): GroupPlan {
+  const path = (key: string): string => info.paths?.[key] ?? `${group}.${key}`;
+  const has = (key: string): boolean => info.keys.includes(key);
+  const needs = (key: string, what: string): string => `"${key}" needs ${what}, skipped`;
+  const laid = (): Laid => ({ set: {} });
+
+  /** What the keys that do not depend on the layout bind on a `TEXT`, or on a `FRAME` or `SLOT`. */
+  const laidOver = (text: boolean): Laid => {
+    const offers = new Map<string, { rank: number; path: string }>();
+    const offer = (field: string, rank: number, to: string): void => {
+      const held = offers.get(field);
+      if (!held || rank > held.rank) offers.set(field, { rank, path: to });
+    };
+    const out = laid();
+    for (const key of info.keys) {
+      // Only the key `border` is the composite the table knows. Variable sync makes no variable for it: its
+      // members are what bind. A member that is a literal has no variable, and a literal written in its place
+      // would stop following the tokens, so it is left out and said.
+      const border = key === 'border' && !text ? info.borders?.[key] : undefined;
+      if (border) {
+        for (const [member, field, to] of [
+          ['color', 'strokes', border.color],
+          ['width', 'strokeWeight', border.width],
+        ] as const) {
+          if (to !== undefined) offer(field, 1, to);
+          else (out.warnings ??= []).push(`the ${member} of "${key}" is a literal, which has no variable to bind, so it was left out`);
+        }
+        continue;
+      }
+      if (!text && GAPS.includes(key)) continue;
+      const to = targets(key, text, info.colors?.includes(key) ?? false);
+      if (to) for (const [field, rank] of to) offer(field, rank, path(key));
+      else (out.notes ??= []).push(`"${key}" has no field on this layer in Figma, skipped`);
+    }
+    for (const [field, { path: to }] of offers) out.set[field] = to;
+    return out;
+  };
+
+  /**
+   * What the gaps bind on a `FRAME` or `SLOT` of this layout. A gap spaces children: `itemSpacing` in a flow, the
+   * two grid gaps in a grid, nothing in a layer with no layout. `rowGap` and `columnGap` outrank `gap`, in a grid only.
+   */
+  const gapsOver = (layout: 'NONE' | 'HORIZONTAL' | 'VERTICAL' | 'GRID'): Laid | undefined => {
+    const out = laid();
+    const note = (line: string): void => void (out.notes ??= []).push(line);
+    if (layout === 'GRID') {
+      const row = has('rowGap') ? 'rowGap' : has('gap') ? 'gap' : undefined;
+      const column = has('columnGap') ? 'columnGap' : has('gap') ? 'gap' : undefined;
+      if (row) out.set.gridRowGap = path(row);
+      if (column) out.set.gridColumnGap = path(column);
+    } else {
+      if (has('gap')) {
+        if (layout === 'NONE') note(needs('gap', 'a layer whose layoutMode is HORIZONTAL, VERTICAL or GRID'));
+        else out.set.itemSpacing = path('gap');
+      }
+      for (const key of ['rowGap', 'columnGap']) if (has(key)) note(needs(key, 'a GRID layer'));
+    }
+    return Object.keys(out.set).length > 0 || out.notes ? out : undefined;
+  };
+
+  const plan: GroupPlan = { TEXT: laidOver(true), box: laidOver(false) };
+  for (const layout of ['NONE', 'HORIZONTAL', 'VERTICAL', 'GRID'] as const) {
+    const over = gapsOver(layout);
+    if (over) plan[layout] = over;
+  }
+  return plan;
+}
+
+/** A group a layer names, and where. */
+export interface GroupUse {
+  path: string;
+  loc?: Loc;
+  /** The axis values the path was expanded from (`hue=rose`), for a message; absent when it took none. */
+  via?: string;
+}
+
+/** Every `tokens=` in one member's evaluated tree, as the group path and the line it was written at. */
+export function groupsUsed(roots: OutNode[], combination: Record<string, string> = {}): GroupUse[] {
+  const used: GroupUse[] = [];
+  const visit = (node: OutNode): void => {
+    const group = node.kind === 'element' ? node.fields.tokens : undefined;
+    const axes = (node as Expanded).fromAxes?.tokens;
+    // The form was checked (`check.ts`): a whole reference in quotes.
+    if (typeof group === 'string')
+      used.push({
+        path: referenceTarget(group)!,
+        loc: node.fieldLocs.tokens ?? node.loc,
+        ...(axes ? { via: viaAxes(axes, combination) } : {}),
+      });
+    for (const child of node.children) visit(child);
+  };
+  for (const root of roots) visit(root);
+  return used;
+}
+
+function lookup(
+  source: DesignSource | undefined,
+  path: string,
+  loc: Loc | undefined,
+  problems: Problem[],
+  selection?: Record<string, string>,
+): GroupInfo | 'token' | undefined | 'failed' {
+  const fail = (message: string): 'failed' => {
+    problems.push({ severity: 'error', message, ...(loc ?? {}) });
+    return 'failed';
+  };
+  if (!source?.group)
+    return fail(
+      `tokens="{${path}}" takes its bindings from the tokens it names, and no design system is loaded; load its resolver document in the plugin, or pass it to the command line`,
+    );
+  try {
+    return source.group(path, selection);
+  } catch (error) {
+    return fail(`tokens="{${path}}": the design system could not be read: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/** A border whose style is not solid cannot be bound: Figma's dash pattern is not in this design. */
+function unsolid(info: GroupInfo, path: string, loc: Loc | undefined, problems: Problem[]): void {
+  for (const [key, border] of Object.entries(info.borders ?? {})) {
+    if (border.unsolid) {
+      problems.push({
+        severity: 'error',
+        message: `tokens="{${path}}": the border "${path}.${key}" has a style other than solid, and Figma's dash pattern is not in this design; it cannot be bound`,
+        ...(loc ?? {}),
+      });
+    }
+  }
+}
+
+/**
+ * Stores what each group a member's layers name holds, on the component, and refuses a group
+ * that is a token or names nothing (an `INSTANCE` is refused where the field is checked).
+ */
+export function resolveGroups(
+  component: Component,
+  used: GroupUse[],
+  source: DesignSource | undefined,
+  selection: Record<string, string> = {},
+): Problem[] {
+  const problems: Problem[] = [];
+  for (const { path, loc, via } of used) {
+    const found = lookup(source, path, loc, problems, selection);
+    if (found === 'failed') continue;
+    const from = via ? ` (taken from ${via})` : '';
+    if (found === undefined)
+      problems.push({
+        severity: 'error',
+        message: `tokens="{${path}}"${from} names no token and no group of the design system`,
+        ...(loc ?? {}),
+      });
+    else if (found === 'token')
+      problems.push({
+        severity: 'error',
+        message: `tokens="{${path}}"${from} names a token, not a group: a layer takes its bindings from the tokens inside a group`,
+        ...(loc ?? {}),
+      });
+    else {
+      unsolid(found, path, loc, problems);
+      (component.groups ??= {})[planKey(path, selection)] = planOf(path, found);
+    }
+  }
+  return problems;
+}
+
+/**
+ * The group the component line names, for the root layer. Whether it names anything was asked of
+ * the design system already (it gives the axes); a group the source cannot describe, or a path
+ * that is a token, binds nothing.
+ */
+export function resolveComponentGroup(
+  component: Component,
+  source: DesignSource | undefined,
+  loc: Loc | undefined,
+  selection: Record<string, string> = {},
+): Problem[] {
+  const problems: Problem[] = [];
+  const path = component.tokens;
+  if (path === undefined || !source?.group) return problems;
+  let found: GroupInfo | 'token' | undefined;
+  try {
+    found = source.group(path, selection);
+  } catch {
+    return problems; // said by resolveAxes
+  }
+  if (found === undefined || found === 'token') return problems;
+  unsolid(found, path, loc, problems);
+  (component.groups ??= {})[planKey(path, selection)] = planOf(path, found);
+  return problems;
+}
+
+/**
+ * Collects what inference says about each layer, once per key and layer, however many members repeat it:
+ * pass `seen` to `toMember`. Run in the reader, where the plans are made, and not in the engine.
+ */
+export function sayings(): { notes: Set<string>; warnings: Set<string>; seen: (layer: Layer, group: string, laid: Laid) => void } {
+  const notes = new Set<string>();
+  const warnings = new Set<string>();
+  const seen = (layer: Layer, group: string, laid: Laid): void => {
+    const where = `${layer.kind} "${layer.address}" tokens="{${group}}": `;
+    for (const line of laid.notes ?? []) notes.add(where + line);
+    for (const line of laid.warnings ?? []) warnings.add(where + line);
+  };
+  return { notes, warnings, seen };
+}

package/shared/components/index.ts

@@ -0,0 +1,140 @@
+/**
+ * A component file, read, validated and expanded.
+ *
+ * Pure: no Figma API and no Node API, so the plugin runs it on the text of a file
+ * whichever way the text came. The file format is owned by
+ * `reference.md`, *Component files*; the design is `specs.md`, *Components from
+ * files*.
+ *
+ * The file is a kdlet file. kdlet reads it; this reads the five words that are
+ * Toghen's; kdlet evaluates the document once per combination of the variant axes;
+ * and Toghen checks each tree it gets back.
+ */
+
+import type { Document } from 'kdlet';
+import { checkLeftOutModes, resolveAxes, selectionOf } from './axes.js';
+import type { DesignSource } from './axes.js';
+import { checkPins, checkRoots } from './check.js';
+import { groupsUsed, resolveComponentGroup, resolveGroups, sayings } from './groups.js';
+import { evaluateMembers, toMember } from './members.js';
+import { isArtboardText, readArtboardFile } from './artboard.js';
+import { readFile } from './read.js';
+import { validateComponent, validateMember, validateMembers } from './validate.js';
+import type { Component, Member, Problem } from './model.js';
+
+export type * from './model.js';
+export { FIELDS, LAYER_KINDS, PROPERTY_TYPES } from './fields.js';
+export type { FieldSpec, PropertyType, ValueKind } from './fields.js';
+export { combinations, evaluateMembers, toArtboardLayer, toLayer, toMember } from './members.js';
+export { ARTBOARD_WORD, isArtboardText, readArtboardFile } from './artboard.js';
+export { BLUEPRINT_WORDS, blueprintNeeds, isBlueprintFile, readBlueprint } from './blueprint.js';
+export type { Blueprint, BlueprintNeeds, BlueprintTokens, ComponentNeed } from './blueprint.js';
+export { expandSegments, INPUT_SEGMENT, pinsOf, resolveAxes, viaAxes } from './axes.js';
+export type { DesignSource } from './axes.js';
+export { applyBindings } from './bindings.js';
+export type { Evaluated } from './members.js';
+export type * from './steps.js';
+export { diff, memberBoard, MEMBER_GAP } from './diff.js';
+export { SET_GAP, describeStack, restack } from './stack.js';
+export type { Plan, TopLevel } from './stack.js';
+export type { Board, LayerSnapshot, MemberCell, MemberSnapshot, PropertySnapshot, SetSnapshot, Snapshot, UnstampedNode } from './diff.js';
+
+export interface ComponentFile {
+  /** True for an artboard file: `component` then holds only its name, and `members` its one frame. */
+  artboard?: true;
+  /** Absent only when the file holds no usable `component` node (or `artboard` node). */
+  component?: Component;
+  /** What kdlet evaluates, once per combination: the file without the words that are Toghen's, as plain JSON. */
+  document?: Document;
+  /** Empty when the component has errors: a file that is wrong is not expanded. */
+  members: Member[];
+  /** Errors and warnings, in file order. Nothing is built while any is an error. */
+  problems: Problem[];
+}
+
+const position = (problem: Problem): number => (problem.line === undefined ? Infinity : problem.line * 100000 + (problem.column ?? 0));
+
+/**
+ * Problems found member by member, as the file's: one found in every member is one
+ * problem, and a member is named only when it is found in some and not all.
+ */
+function perMember(found: { member: string; problems: Problem[] }[]): Problem[] {
+  const groups = new Map<string, { problem: Problem; members: string[] }>();
+  for (const { member, problems } of found) {
+    for (const problem of problems) {
+      const key = `${problem.severity}:${problem.line}:${problem.column}:${problem.message}`;
+      const group = groups.get(key) ?? { problem, members: [] };
+      group.members.push(member);
+      groups.set(key, group);
+    }
+  }
+  const out: Problem[] = [];
+  for (const { problem, members } of groups.values()) {
+    const { member: _member, ...bare } = problem;
+    if (members.length === found.length) out.push(bare);
+    else for (const member of members) out.push({ ...bare, member });
+  }
+  return out;
+}
+
+/**
+ * Reads, validates and expands one component file, in one pass.
+ *
+ * Every problem in the file is reported, not the first. The members are evaluated
+ * and checked only when the component itself has no errors, since a member of a
+ * broken component would repeat the same errors once per combination.
+ *
+ * A file with an `artboard` node at the top is an artboard file and is read as one (`artboard.ts`), against the
+ * `inputs` given; a component file ignores them.
+ */
+export function readComponentFile(text: string, source?: DesignSource, inputs?: Record<string, unknown>): ComponentFile {
+  if (isArtboardText(text)) return readArtboardFile(text, inputs);
+  const read = readFile(text);
+  if (!read.component) return { members: [], problems: read.problems };
+  const { component, document } = read;
+
+  // An axis that takes its values from a modifier, and the axes `tokens=` brings in, need the
+  // design system. Until they are known the axes are not, so a file whose axes cannot be filled
+  // is not checked against them: it would be told about guards and exclusions that are not wrong.
+  const axes = resolveAxes(component, source, read.componentLoc);
+  // The same goes for the token groups: what `tokens=` infers from is stored on the component, for the script and the plugin, which have no design system.
+  const problems = [
+    ...read.problems,
+    ...axes,
+    ...(axes.length > 0 ? [] : [...validateComponent(component, document), ...resolveComponentGroup(component, source, read.componentLoc)]),
+  ];
+  let members: Member[] = [];
+  if (!problems.some((problem) => problem.severity === 'error')) {
+    const evaluated = evaluateMembers(component, document);
+    const at = read.componentLoc ?? { line: 1, column: 1 };
+    const said = sayings();
+    // A tree kdlet had problems with is not checked further: what is wrong in it would be said twice.
+    const found = evaluated.map((e) => {
+      const own = [...e.problems];
+      if (own.length === 0) own.push(...checkRoots(e.roots, component.name, at), ...checkPins(e.roots, component));
+      if (own.length === 0) {
+        // A member that selects part groups binds their tokens: its plans are made for that selection.
+        const selection = selectionOf(component, e.combination);
+        own.push(...resolveGroups(component, groupsUsed(e.roots, e.combination), source, selection));
+        if (Object.keys(selection).length > 0) own.push(...resolveComponentGroup(component, source, read.componentLoc, selection));
+      }
+      const member = own.length === 0 ? toMember(e, component, said.seen) : undefined;
+      if (member) own.push(...checkLeftOutModes(member.tree, source));
+      if (member) own.push(...validateMember(component, member));
+      return { name: e.name, problems: own, member };
+    });
+    problems.push(...perMember(found.map((f) => ({ member: f.name, problems: f.problems }))));
+    members = [];
+    for (const f of found) if (f.member) members.push(f.member);
+    if (members.length === evaluated.length) problems.push(...validateMembers(component, members));
+    if (problems.some((problem) => problem.severity === 'error')) members = [];
+    // What inference skipped or could not bind travels with the component: the run's report says it, and the engine has no design system to work it out from.
+    if (said.notes.size > 0) component.notes = [...said.notes];
+    if (said.warnings.size > 0) component.warnings = [...said.warnings];
+  }
+
+  // A stable sort: problems on one line keep the order they were found in.
+  const ordered = problems.map((problem, index) => ({ problem, index }));
+  ordered.sort((a, b) => position(a.problem) - position(b.problem) || a.index - b.index);
+  return { component, document, members, problems: ordered.map((entry) => entry.problem) };
+}