@apollion-dsi/tokens 7.9.0 → 7.10.0

package/src/renderers/tokens-studio.ts

@@ -0,0 +1,264 @@
+/**
+ * Tokens Studio renderer (APOLLION-FIGMA-EXPORT) — project the Resolver slices
+ * to a Tokens Studio for Figma multi-file sync tree.
+ *
+ * **Shape** (`dist/tokens-studio/`, point Tokens Studio's folder sync at it):
+ * - one set file per Resolver set: `base.json`, `spacing/<dimension>.json`,
+ *   `font/<textSize>.json`, `color/<brand>/<mode>/<surface>.json`;
+ * - `$themes.json` — one theme **group** per axis (`base`, `color`,
+ *   `dimension`, `textSize`), each theme enabling its one set. Tokens Studio
+ *   PRO turns each group into a Figma variable collection whose modes are the
+ *   group's themes;
+ * - `$metadata.json` — `tokenSetOrder`.
+ *
+ * **Dialect** (measured in the 2026-08-13 spike — every mapping is a pure
+ * projection, no IR change): unprefixed `value`/`type`; colours as hex
+ * (8-digit when translucent); dimensions as `"<n>px|rem"` strings; aliases keep
+ * the shared `{group.path}` form; shadows as `boxShadow` objects. Types follow
+ * the Tokens Studio vocabulary, refined by path (`font.size` → `fontSizes`,
+ * `border.radius` → `borderRadius`, …). Line heights become percentages, the
+ * unit Tokens Studio reads as relative.
+ *
+ * **Carried from `$extensions`:** `com.apollion.font` letter spacing
+ * (`letterSpacing`, `em` → `%`) and text transforms (`textCase`). **Dropped**
+ * (no Tokens Studio type): `fontStyle`, the `circular: 100%` radius, the
+ * breakpoint interval notes. The deprecated `font.<dimension>` alias sets are
+ * not exported — no designer file pins them.
+ *
+ * Every set is reference-closed (see `ir.ts` slices), so a theme never needs a
+ * second set as a source.
+ *
+ * @see ../set-plan.ts · ../ir.ts · ./resolver.ts (the DTCG twin of this surface)
+ * @see packages/tokens/docs/spikes/2026-08-13-tokens-studio-export.md
+ */
+
+import type { IRColorValue, IRDimensionValue, IRGroup, IRShadowValue, IRSlice, IRToken, IRValue } from '../ir';
+import { isToken, kebab, kebabPath } from '../ir';
+import type { ColorSetPlan, SetPlan } from '../set-plan';
+
+/** Directory (relative to dist root) of the Tokens Studio tree. */
+export const TOKENS_STUDIO_DIR = 'tokens-studio';
+
+export interface TokensStudioShadow {
+  x: string;
+  y: string;
+  blur: string;
+  spread: string;
+  color: string;
+  type: 'dropShadow' | 'innerShadow';
+}
+
+export interface TokensStudioToken {
+  value: string | number | TokensStudioShadow;
+  type: string;
+  description?: string;
+}
+
+export interface TokensStudioGroup {
+  [key: string]: TokensStudioToken | TokensStudioGroup;
+}
+
+export type TokenSetStatus = 'enabled' | 'source' | 'disabled';
+
+export interface TokensStudioTheme {
+  id: string;
+  name: string;
+  group: string;
+  selectedTokenSets: Record<string, TokenSetStatus>;
+}
+
+const json = (value: unknown) => `${JSON.stringify(value, null, 2)}\n`;
+
+/** Short decimal form — drops binary-float noise (`0.6000000000000001` → `0.6`). */
+const num = (value: number) => `${Number(value.toFixed(4))}`;
+
+const hexByte = (value: number) =>
+  Math.round(Math.min(1, Math.max(0, value)) * 255)
+    .toString(16)
+    .padStart(2, '0');
+
+function color(value: IRColorValue): string {
+  return value.alpha !== undefined && value.alpha < 1 ? `${value.hex}${hexByte(value.alpha)}` : value.hex;
+}
+
+function dimension(value: IRDimensionValue): string {
+  return `${num(value.value)}${value.unit}`;
+}
+
+/** Shadow offsets are bare numbers in Tokens Studio (px implied). */
+function shadowLength(value: IRDimensionValue): string {
+  return value.unit === 'px' ? num(value.value) : dimension(value);
+}
+
+function shadow(value: IRShadowValue): TokensStudioShadow {
+  const { shadow: layer } = value;
+  return {
+    x: shadowLength(layer.offsetX),
+    y: shadowLength(layer.offsetY),
+    blur: shadowLength(layer.blur),
+    spread: shadowLength(layer.spread),
+    color: color(layer.color),
+    type: layer.inset ? 'innerShadow' : 'dropShadow',
+  };
+}
+
+const startsWith = (path: string, ...prefixes: string[]) =>
+  prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}.`));
+
+/** Tokens Studio type for an IR token at a kebab dotted `path`. */
+export function tokensStudioType(token: IRToken, path: string): string {
+  switch (token.type) {
+    case 'color':
+      return 'color';
+    case 'dimension':
+      if (startsWith(path, 'font.size')) return 'fontSizes';
+      if (startsWith(path, 'border-width', 'border.width')) return 'borderWidth';
+      if (startsWith(path, 'border.radius')) return 'borderRadius';
+      if (startsWith(path, 'space', 'spacing')) return 'spacing';
+      if (startsWith(path, 'breakpoint', 'container-size', 'layout')) return 'sizing';
+      return 'dimension';
+    case 'fontFamily':
+      return 'fontFamilies';
+    case 'fontWeight':
+      return 'fontWeights';
+    case 'number':
+      return startsWith(path, 'font.line-height') ? 'lineHeights' : 'number';
+    case 'shadow':
+      return 'boxShadow';
+    default:
+      return 'other';
+  }
+}
+
+/** Tokens Studio value for an IR value; `type` picks the line-height form. */
+export function tokensStudioValue(value: IRValue, type: string): TokensStudioToken['value'] {
+  switch (value.kind) {
+    case 'ref':
+      return `{${kebabPath(value.path)}}`;
+    case 'color':
+      return color(value);
+    case 'dimension':
+      return dimension(value);
+    case 'fontFamily':
+      return value.family;
+    case 'fontWeight':
+      return value.weight;
+    case 'number':
+      return type === 'lineHeights' ? `${num(value.number * 100)}%` : value.number;
+    case 'shadow':
+      return shadow(value);
+    case 'strokeStyle':
+      return value.style;
+    default:
+      return value.raw;
+  }
+}
+
+function description(token: IRToken): string | undefined {
+  if (token.deprecated === undefined || token.deprecated === false) return token.description;
+  const note = typeof token.deprecated === 'string' ? `Deprecated: ${token.deprecated}` : 'Deprecated.';
+  return token.description ? `${token.description} ${note}` : note;
+}
+
+function projectToken(token: IRToken, path: string): TokensStudioToken {
+  const type = tokensStudioType(token, path);
+  const out: TokensStudioToken = { value: tokensStudioValue(token.value, type), type };
+  const text = description(token);
+  if (text !== undefined) out.description = text;
+  return out;
+}
+
+/** Project an IR group to a Tokens Studio group (kebab keys, like the DTCG surface). */
+export function projectTokensStudioGroup(group: IRGroup, prefix = ''): TokensStudioGroup {
+  const out: TokensStudioGroup = {};
+  for (const [key, node] of Object.entries(group)) {
+    const name = kebab(key);
+    const path = prefix ? `${prefix}.${name}` : name;
+    out[name] = isToken(node) ? projectToken(node, path) : projectTokensStudioGroup(node, path);
+  }
+  return out;
+}
+
+interface FontExtensions {
+  letterSpacing?: Record<string, string | number>;
+  textTransform?: Record<string, string>;
+}
+
+/** `-0.045em` → `-4.5%` (Tokens Studio's relative letter spacing); other units pass through. */
+function letterSpacing(value: string | number): string {
+  if (typeof value === 'number') return `${num(value * 100)}%`;
+  const em = /^(-?[\d.]+)em$/.exec(value.trim());
+  return em ? `${num(Number(em[1]) * 100)}%` : value;
+}
+
+/** First-class tokens for the font extensions Tokens Studio can type. */
+function fontExtensionTokens(extensions: FontExtensions): TokensStudioGroup {
+  const out: TokensStudioGroup = {};
+  if (extensions.letterSpacing) {
+    out['letter-spacing'] = Object.fromEntries(
+      Object.entries(extensions.letterSpacing).map(([key, value]) => [
+        kebab(key),
+        { value: letterSpacing(value), type: 'letterSpacing' },
+      ]),
+    );
+  }
+  if (extensions.textTransform) {
+    out['text-case'] = Object.fromEntries(
+      Object.entries(extensions.textTransform).map(([key, value]) => [kebab(key), { value, type: 'textCase' }]),
+    );
+  }
+  return out;
+}
+
+/** Render one Resolver slice as a Tokens Studio set document. */
+export function renderTokensStudioSet(slice: IRSlice): string {
+  const doc = projectTokensStudioGroup(slice.groups);
+  const font = slice.extensions['com.apollion.font'] as FontExtensions | undefined;
+  if (font && doc.font) doc.font = { ...(doc.font as TokensStudioGroup), ...fontExtensionTokens(font) };
+  return json(doc);
+}
+
+/** Tokens Studio set name (and file stem) of a colour coordinate. */
+export function tokensStudioColorSetName(set: Pick<ColorSetPlan, 'brand' | 'mode' | 'surface'>): string {
+  return `color/${set.brand}/${set.mode}/${set.surface}`;
+}
+
+/** Every set the Tokens Studio tree carries, in `tokenSetOrder` (deprecated font aliases excluded). */
+export function planTokensStudioSets(plan: SetPlan): { name: string; group: string; theme: string }[] {
+  return [
+    { name: 'base', group: 'base', theme: 'base' },
+    ...plan.spacing.map((set) => ({ name: `spacing/${set.dimension}`, group: 'dimension', theme: set.dimension })),
+    ...plan.font
+      .filter((set) => !set.deprecatedDimension)
+      .map((set) => ({ name: `font/${set.textSize}`, group: 'textSize', theme: set.textSize })),
+    ...plan.color.map((set) => ({
+      name: tokensStudioColorSetName(set),
+      group: 'color',
+      theme: `${set.brand} / ${set.mode} / ${set.surface}`,
+    })),
+  ];
+}
+
+/** File path (relative to dist root) of a Tokens Studio set. */
+export function tokensStudioSetFile(name: string): string {
+  return `${TOKENS_STUDIO_DIR}/${name}.json`;
+}
+
+/**
+ * `$themes.json` — one theme per set, grouped by axis. Theme ids are the set
+ * names with `/` → `-`, so they stay stable across builds.
+ */
+export function renderTokensStudioThemes(plan: SetPlan): string {
+  const themes: TokensStudioTheme[] = planTokensStudioSets(plan).map((set) => ({
+    id: set.name.replace(/\//g, '-'),
+    name: set.theme,
+    group: set.group,
+    selectedTokenSets: { [set.name]: 'enabled' },
+  }));
+  return json(themes);
+}
+
+/** `$metadata.json` — the set order Tokens Studio loads. */
+export function renderTokensStudioMetadata(plan: SetPlan): string {
+  return json({ tokenSetOrder: planTokensStudioSets(plan).map((set) => set.name) });
+}