@toghen/figma 0.0.0-stage → 0.1.0

package/main/utils/shardedData.ts

@@ -0,0 +1,142 @@
+/**
+ * One JSON value kept in the Figma file's shared plugin data, split across
+ * numbered shards with an index saying how many there are.
+ *
+ * ```
+ * toghen/<key>      {"v":1,"shards":2}
+ * toghen/<key>.0    {"first part…
+ * toghen/<key>.1    …the rest"}
+ * ```
+ *
+ * Figma caps one entry at 100 kB counting namespace and key, so anything that
+ * can grow is sharded. The payload is escaped to pure ASCII first, so its
+ * character count is its byte count and no surrogate pair is split across a
+ * shard boundary. The index is cleared first, the shards written, then the
+ * index: a write interrupted part-way leaves no index, which reads as nothing
+ * stored, never as a mixture of old and new shards.
+ *
+ * The kept templates (`templateStore.ts`) and the lock (`lockStore.ts`) are kept this way. So was the sync
+ * record of older builds, which `rootRecord.ts` reads once and deletes.
+ */
+
+/** Figma requires a namespace of at least three alphanumeric characters. */
+export const NAMESPACE = 'toghen';
+
+/** Figma's documented cap on one entry, counting namespace + key + value. */
+const ENTRY_LIMIT_BYTES = 100 * 1024;
+/** Generous allowance for the namespace plus the longest shard key. */
+const KEY_OVERHEAD_BYTES = 64;
+export const SHARD_CAPACITY = ENTRY_LIMIT_BYTES - KEY_OVERHEAD_BYTES;
+
+const FORMAT_VERSION = 1;
+
+export interface ShardedWrite {
+  ok: boolean;
+  /** Set when the payload needed more shards than allowed; nothing was kept. */
+  tooBig?: boolean;
+  /** Set when Figma refused a write. */
+  reason?: string;
+  bytes: number;
+  shards: number;
+}
+
+/**
+ * The stored payload, or `''` when there is none.
+ *
+ * Throws only when the index itself is not JSON; a missing index, a future
+ * version, or a count that is not a whole number read as nothing stored.
+ */
+export function readSharded(key: string): string {
+  const index = read(key);
+  if (!index) return '';
+
+  const parsed: unknown = JSON.parse(index);
+  if (!isPlainObject(parsed)) return '';
+  if (parsed.v !== FORMAT_VERSION) return '';
+
+  const count = parsed.shards;
+  if (typeof count !== 'number' || !Number.isInteger(count) || count < 0) return '';
+
+  let payload = '';
+  for (let i = 0; i < count; i += 1) {
+    payload += read(`${key}.${i}`);
+  }
+  return payload;
+}
+
+/**
+ * Writes `payload` (already ASCII, see `toAsciiJson`) under `key`. Returns rather
+ * than throws: a caller that has just written to Figma must not have that work
+ * reported as failed because its record could not be kept.
+ */
+export function writeSharded(key: string, payload: string, maxShards: number): ShardedWrite {
+  const shards = chunk(payload, SHARD_CAPACITY);
+  try {
+    // Clearing the index first is the commit protocol: see the note at the top.
+    write(key, '');
+
+    if (shards.length > maxShards) {
+      clearShardsFrom(key, 0);
+      return { ok: false, tooBig: true, bytes: payload.length, shards: 0 };
+    }
+
+    shards.forEach((shard, index) => {
+      write(`${key}.${index}`, shard);
+    });
+    clearShardsFrom(key, shards.length);
+    write(key, toAsciiJson({ v: FORMAT_VERSION, shards: shards.length }));
+    return { ok: true, bytes: payload.length, shards: shards.length };
+  } catch (error) {
+    return { ok: false, bytes: payload.length, shards: 0, reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Removes the value kept under `key`: the index first, then every shard. */
+export function clearSharded(key: string): void {
+  write(key, '');
+  clearShardsFrom(key, 0);
+}
+
+/**
+ * Serializes to JSON containing only ASCII. `JSON.stringify` already escapes
+ * control characters, so what remains above U+007F is escaped here; the result
+ * parses back identically, astral characters included.
+ */
+export function toAsciiJson(value: unknown): string {
+  return JSON.stringify(value).replace(/[\u0080-￿]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function read(key: string): string {
+  return figma.root.getSharedPluginData(NAMESPACE, key);
+}
+
+/** Figma removes the key when the value is the empty string. */
+function write(key: string, value: string): void {
+  figma.root.setSharedPluginData(NAMESPACE, key, value);
+}
+
+/**
+ * Removes every shard of `key` from `first` upward. A value that shrinks leaves
+ * shards behind; enumerating the namespace rather than trusting the previous
+ * index also cleans up after an interrupted write.
+ */
+function clearShardsFrom(key: string, first: number): void {
+  const prefix = `${key}.`;
+  for (const stored of figma.root.getSharedPluginDataKeys(NAMESPACE)) {
+    if (!stored.startsWith(prefix)) continue;
+    const rest = stored.slice(prefix.length);
+    if (/^\d+$/.test(rest) && Number(rest) >= first) write(stored, '');
+  }
+}
+
+function chunk(text: string, size: number): string[] {
+  const chunks: string[] = [];
+  for (let i = 0; i < text.length; i += size) {
+    chunks.push(text.slice(i, i + size));
+  }
+  return chunks;
+}

package/main/utils/standing.ts

@@ -0,0 +1,106 @@
+/**
+ * Where each collection of the sum stands in the Figma file.
+ *
+ * The plan and the Inspector both ask it, so a collection's id, the id of each of
+ * its modes and whether it may be written to are decided once.
+ *
+ * ### Collections built by an earlier sync
+ *
+ * The earlier sync built the product: one collection named for the document, a
+ * mode per combination of every modifier's contexts. So only the base collection,
+ * the one with the document's name, can have been built by it: when it holds any
+ * mode other than `default` it is reported as built by an earlier sync and left
+ * alone, and the run stops before its first write. A collection named after one
+ * of the document's modifiers is the sum's own, whatever modes it holds.
+ *
+ * ### A modifier's collection that no longer matches its modifier
+ *
+ * - A mode the modifier no longer has (`goneModes`) is a mode to delete, which
+ *   the plan lists as breaking and deletes only when it is allowed to.
+ * - Figma's default mode is the first one and is fixed at creation. When the
+ *   modifier no longer has that context (`defaultGone`), the collection can
+ *   never match the document again: it is reported and nothing is written to it.
+ *
+ * Moving a file from the product to the sum is a migration, designed when a
+ * consumer needs one.
+ */
+
+import type { FigmaCollectionIndex, IndexedCollection, IndexedMode } from './figmaCollectionIndex.js';
+import type { Sum, SumCollection } from './sum.js';
+
+export function symbolicCollectionId(collectionName: string): string {
+  return `$col:${collectionName}`;
+}
+
+export function symbolicModeId(collectionName: string, modeName: string): string {
+  return `$mode:${collectionName}/${modeName}`;
+}
+
+export interface CollectionStanding {
+  spec: SumCollection;
+  /** The collection of that name in the file, when there is one. */
+  existing?: IndexedCollection;
+  /**
+   * Base collection only: the modes it holds besides `default`. Set means built
+   * by an earlier sync: it is reported and never written to.
+   */
+  strangeModes: string[];
+  /** A modifier's collection: the modes it holds that the modifier no longer has. */
+  goneModes: IndexedMode[];
+  /** A modifier's collection: Figma's default mode, when the modifier no longer has that context. */
+  defaultGone?: string;
+  /** The real id, or the symbolic one of the collection this plan creates. */
+  id: string;
+  /** The real mode id, or the symbolic one of a mode this plan creates. */
+  modeId(mode: string): string;
+}
+
+export function standingOf(sum: Sum, figmaIndex: FigmaCollectionIndex): Map<string, CollectionStanding> {
+  const standing = new Map<string, CollectionStanding>();
+  for (const spec of sum.collections) {
+    const existing = figmaIndex.byName[spec.name];
+    const isBase = spec.modifier === undefined && !spec.axis;
+    const unknown = existing ? existing.modes.filter((mode) => !spec.modes.includes(mode.name)) : [];
+    const figmaDefault = existing?.modes[0]?.name;
+    standing.set(spec.name, {
+      spec,
+      ...(existing ? { existing } : {}),
+      strangeModes: isBase ? unknown.map((mode) => mode.name) : [],
+      goneModes: isBase ? [] : unknown,
+      ...(!isBase && figmaDefault !== undefined && !spec.modes.includes(figmaDefault) ? { defaultGone: figmaDefault } : {}),
+      id: existing?.id ?? symbolicCollectionId(spec.name),
+      modeId: (mode) => existing?.modes.find((m) => m.name === mode)?.modeId ?? symbolicModeId(spec.name, mode),
+    });
+  }
+  return standing;
+}
+
+/** Whether the base collection exists and was built by an earlier sync. */
+export const builtEarlier = (standing: CollectionStanding): boolean => standing.strangeModes.length > 0;
+
+/**
+ * Why nothing may be written to the collection, when that is so: the short reason a skipped token
+ * carries, and the sentence that says it in full.
+ */
+export function closedBecause(standing: CollectionStanding): { skip: string; message: string } | undefined {
+  const name = standing.spec.name;
+  if (builtEarlier(standing)) {
+    return {
+      skip: 'built by an earlier sync',
+      message:
+        `Collection "${name}" was built by an earlier sync: it holds mode(s) ` +
+        `${standing.strangeModes.join(', ')} besides "default". The base collection takes that name, so ` +
+        `nothing is written to it. Rename or delete the old collection, or sync under another collection name.`,
+    };
+  }
+  if (standing.defaultGone !== undefined) {
+    return {
+      skip: 'default mode removed',
+      message:
+        `Collection "${name}" has "${standing.defaultGone}" as its default mode, which the modifier no longer ` +
+        `has. Figma fixes a collection's default mode when the collection is created and cannot reassign it, so ` +
+        `nothing is written to this collection; recreating it is a migration.`,
+    };
+  }
+  return undefined;
+}

package/main/utils/styleTarget.ts

@@ -0,0 +1,51 @@
+/**
+ * The token a style name is spelled from, when a file names a style through references.
+ *
+ * `effectStyle="{kbd.boxShadow}"` where `kbd.boxShadow` is only `{elevation.raised}` binds the style the target
+ * becomes, as a reference to a token Figma holds is an alias of it. The chain of whole-value references is followed
+ * to the first token that is not one, in the default context (styles have no modes). If that token is not a style of
+ * the kind asked for, or the path is not in the document, the path asked about is returned unchanged and names what
+ * it named before.
+ */
+
+import type { Resolver } from '@toghen/lib';
+import type { TokenTypeConversionMap } from '../../shared/tokenTypeMap.js';
+import { resolveSumModes, snapshotModes, type SnapshotToken } from './resolverModes.js';
+import { referencePath } from '@toghen/lib';
+
+export function styleTargetOf(
+  resolver: Resolver | null | undefined,
+  conversionMap: TokenTypeConversionMap,
+): (path: string, styleType: 'TEXT' | 'EFFECT') => string {
+  let read: { tokens: Map<string, SnapshotToken>; prefix: string } | null | undefined;
+  const tokens = () => {
+    if (read === undefined) {
+      read = null;
+      if (resolver) {
+        try {
+          const resolution = resolveSumModes(resolver);
+          const snapshot = snapshotModes(resolution).find((s) => s.modeName === resolution.defaultMode);
+          if (snapshot) read = { tokens: snapshot.pathToToken, prefix: `${resolution.dsCollectionName}.` };
+        } catch {
+          // a document the sum cannot be built from names no style through a reference
+        }
+      }
+    }
+    return read;
+  };
+
+  return (path, styleType) => {
+    const found = tokens();
+    if (!found) return path;
+    const seen = new Set<string>();
+    for (let at = path; !seen.has(at); ) {
+      seen.add(at);
+      const token = found.tokens.get(`${found.prefix}${at}`);
+      if (!token) return path;
+      if (!token.aliasOf)
+        return conversionMap[token.type]?.target === 'style' && conversionMap[token.type]?.styleType === styleType ? at : path;
+      at = referencePath(token.aliasOf);
+    }
+    return path;
+  };
+}