@apollion-dsi/tokens 4.1.0 → 4.2.0

package/src/renderers/resolver.ts

@@ -0,0 +1,129 @@
+/**
+ * Resolver renderer (R5) — project the IR slices to a DTCG **Resolver** manifest
+ * plus the reference-closed set documents it points at.
+ *
+ * **Spec:** DTCG Resolver draft (Design Tokens Community Group — Resolver /
+ * "modes" module on the 2025.10 draft track). A resolver names a set of token
+ * files (`sets`) and a set of `modifiers` (enumerated axes with a `default`); a
+ * consumer composes the chosen modifier values into a single resolved token
+ * tree. This replaces the old N-file per-variant JSON explosion with one
+ * manifest + O(brand·mode·surface + dimension + 1) sets.
+ *
+ * **S5 mode caveat:** `mode` is emitted as a real modifier (values + default)
+ * even though palette generation is currently mode-agnostic (dark == light).
+ * The topology is therefore correct ahead of S6 wiring real dark-mode logic.
+ *
+ * Set documents are projected from `IRSlice`s via the shared `dtcg-project`
+ * mapping, so a composed (base + color + spacing) tree is byte-equivalent to the
+ * old full per-variant document (asserted in `resolver.test.ts`).
+ *
+ * @see ../ir.ts (slices) · ./dtcg-project.ts · ../set-plan.ts
+ * @see https://www.designtokens.org/TR/ (Resolver draft)
+ */
+
+import { projectGroup } from './dtcg-project';
+
+import type { ApollionConfig } from '../config-schema';
+import type { IRSlice } from '../ir';
+import type { SetPlan } from '../set-plan';
+
+/** A DTCG modifier: an enumerated axis with a default value. */
+interface ResolverModifier {
+  name: string;
+  values: string[];
+  default: string;
+}
+
+/** A DTCG set reference: a named token document at `source`. */
+interface ResolverSet {
+  name: string;
+  source: string;
+}
+
+interface ResolverManifest {
+  name: string;
+  description: string;
+  sets: ResolverSet[];
+  modifiers: ResolverModifier[];
+  $extensions: Record<string, unknown>;
+}
+
+/** Render one IR slice (base/color/spacing) to a DTCG set JSON document. */
+function renderSet(slice: IRSlice, description: string): string {
+  const doc: Record<string, unknown> = {
+    $description: description,
+    ...projectGroup(slice.groups),
+  };
+  if (Object.keys(slice.extensions).length > 0) doc.$extensions = slice.extensions;
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+/** Axis-invariant base set (border + font). */
+export function renderBaseSet(slice: IRSlice): string {
+  return renderSet(slice, 'Apollion DS — base set (axis-invariant: border + font). DTCG 2025.10.');
+}
+
+/** Colour set for one (brand × mode × surface). */
+export function renderColorSet(slice: IRSlice, brand: string, mode: string, surface: string): string {
+  return renderSet(slice, `Apollion DS — colour set. brand=${brand} mode=${mode} surface=${surface}. DTCG 2025.10.`);
+}
+
+/** Spacing set for one dimension. */
+export function renderSpacingSet(slice: IRSlice, dimension: string): string {
+  return renderSet(slice, `Apollion DS — spacing set. dimension=${dimension}. DTCG 2025.10.`);
+}
+
+/**
+ * Render the Resolver manifest (`resolver.json`).
+ *
+ * Modifiers enumerate the four axes (brand/mode/surface/dimension) with the
+ * first encountered value as `default`. `sets` lists every concrete set file.
+ * The `$extensions['com.apollion.resolver']` block documents the composition
+ * rule — which sets to merge for a chosen modifier tuple — since the draft's
+ * apply-by-modifier binding is still settling; this keeps the manifest
+ * self-describing for our own consumers.
+ */
+export function renderResolver(config: ApollionConfig, plan: SetPlan): string {
+  const { modifiers } = plan;
+
+  const modifierList: ResolverModifier[] = [
+    { name: 'brand', values: [...modifiers.brand], default: modifiers.brand[0] },
+    { name: 'mode', values: [...modifiers.mode], default: modifiers.mode[0] },
+    { name: 'surface', values: [...modifiers.surface], default: modifiers.surface[0] },
+    { name: 'dimension', values: [...modifiers.dimension], default: modifiers.dimension[0] },
+  ];
+
+  const sets: ResolverSet[] = [
+    { name: plan.base.name, source: plan.base.file },
+    ...plan.spacing.map((s) => ({ name: s.name, source: s.file })),
+    ...plan.color.map((c) => ({ name: c.name, source: c.file })),
+  ];
+
+  const manifest: ResolverManifest = {
+    name: 'apollion-tokens',
+    description:
+      'Apollion DS token resolver — DTCG 2025.10. Compose the base set with the ' +
+      'colour set for the chosen brand/mode/surface and the spacing set for the ' +
+      'chosen dimension. NOTE: mode is a topology placeholder in this release ' +
+      '(dark resolves identically to light until S6).',
+    sets,
+    modifiers: modifierList,
+    $extensions: {
+      'com.apollion.resolver': {
+        // How to compose a final token tree for a chosen modifier tuple.
+        composition: {
+          always: [plan.base.name],
+          byModifier: {
+            // colour set name = `<brand>.color.<mode>.<surface>`
+            color: '${brand}.color.${mode}.${surface}',
+            // spacing set name = `spacing.<dimension>`
+            spacing: 'spacing.${dimension}',
+          },
+        },
+        modeIsPlaceholder: true,
+      },
+    },
+  };
+
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/src/set-plan.ts

@@ -0,0 +1,136 @@
+/**
+ * Set topology planner (R5) — the single source of truth for which Resolver
+ * sets exist, their file paths, and the modifier enumerations.
+ *
+ * Both `build.ts` (which writes the set files) and `resolver.ts` (which writes
+ * the manifest pointing at them) derive from this plan, so set names can never
+ * drift between the two. Derived purely from the expanded variants of a config.
+ *
+ * **Set topology** (each set is reference-closed, see `ir.ts` slices):
+ * - `base` — 1 file, axis-invariant (border + font).
+ * - `spacing.<dimension>` — one per dimension.
+ * - `<brand>.color.<mode>.<surface>` — one per (brand × mode × surface).
+ *
+ * @see ir.ts (`buildBaseIR` / `buildColorIR` / `buildSpacingIR`)
+ * @see renderers/resolver.ts (manifest) · build.ts (set emission)
+ */
+
+import type { Dimension } from '@apollion-dsi/core/themes/dimension';
+
+import type { ApollionConfig, Mode, Surface } from './config-schema';
+import { expandVariants } from './config-schema';
+
+/** Directory (relative to dist root) holding the emitted set files. */
+export const SETS_DIR = 'json/sets';
+/** Resolver manifest path (relative to dist root). */
+export const RESOLVER_PATH = 'json/resolver.json';
+
+/** A colour set keyed by its (brand × mode × surface) coordinate. */
+export interface ColorSetPlan {
+  readonly kind: 'color';
+  readonly name: string;
+  readonly file: string;
+  readonly brand: string;
+  readonly mode: Mode;
+  readonly surface: Surface;
+}
+
+/** A spacing set keyed by its dimension. */
+export interface SpacingSetPlan {
+  readonly kind: 'spacing';
+  readonly name: string;
+  readonly file: string;
+  readonly dimension: Dimension;
+}
+
+/** The axis-invariant base set. */
+export interface BaseSetPlan {
+  readonly kind: 'base';
+  readonly name: string;
+  readonly file: string;
+}
+
+export interface SetPlan {
+  readonly base: BaseSetPlan;
+  readonly spacing: readonly SpacingSetPlan[];
+  readonly color: readonly ColorSetPlan[];
+  /** Distinct modifier values (declaration/encounter order), for the manifest. */
+  readonly modifiers: {
+    readonly brand: readonly string[];
+    readonly mode: readonly Mode[];
+    readonly surface: readonly Surface[];
+    readonly dimension: readonly Dimension[];
+  };
+}
+
+/** Set source path relative to the dist root (used by the resolver manifest). */
+function setFile(name: string): string {
+  return `${SETS_DIR}/${name}.json`;
+}
+
+/** Stable colour-set name for a coordinate: `<brand>.color.<mode>.<surface>`. */
+export function colorSetName(brand: string, mode: Mode, surface: Surface): string {
+  return `${brand}.color.${mode}.${surface}`;
+}
+
+/** Stable spacing-set name for a dimension: `spacing.<dimension>`. */
+export function spacingSetName(dimension: Dimension): string {
+  return `spacing.${dimension}`;
+}
+
+/** Push `value` onto `list` if absent — preserves first-encounter order. */
+function pushUnique<T>(list: T[], value: T): void {
+  if (!list.includes(value)) list.push(value);
+}
+
+/**
+ * Derive the full set topology from a config. Deterministic: ordering follows
+ * `expandVariants` (brands alphabetical → declaration order for the rest), so
+ * the emitted manifest + files are byte-stable across runs.
+ */
+export function planSets(config: ApollionConfig): SetPlan {
+  const variants = expandVariants(config);
+
+  const brands: string[] = [];
+  const modes: Mode[] = [];
+  const surfaces: Surface[] = [];
+  const dimensions: Dimension[] = [];
+
+  const colorSeen = new Set<string>();
+  const color: ColorSetPlan[] = [];
+  const spacingSeen = new Set<string>();
+  const spacing: SpacingSetPlan[] = [];
+
+  for (const v of variants) {
+    pushUnique(brands, v.brand);
+    pushUnique(modes, v.mode);
+    pushUnique(surfaces, v.surface);
+    pushUnique(dimensions, v.dimension);
+
+    const cName = colorSetName(v.brand, v.mode, v.surface);
+    if (!colorSeen.has(cName)) {
+      colorSeen.add(cName);
+      color.push({
+        kind: 'color',
+        name: cName,
+        file: setFile(cName),
+        brand: v.brand,
+        mode: v.mode,
+        surface: v.surface,
+      });
+    }
+
+    const sName = spacingSetName(v.dimension);
+    if (!spacingSeen.has(sName)) {
+      spacingSeen.add(sName);
+      spacing.push({ kind: 'spacing', name: sName, file: setFile(sName), dimension: v.dimension });
+    }
+  }
+
+  return {
+    base: { kind: 'base', name: 'base', file: setFile('base') },
+    spacing,
+    color,
+    modifiers: { brand: brands, mode: modes, surface: surfaces, dimension: dimensions },
+  };
+}

package/src/token-meta.ts

@@ -0,0 +1,86 @@
+/**
+ * Token metadata registry — the SSOT for DTCG `$description` / `$deprecated`
+ * annotations (Format Module 2025.10 §"Description" + §"Deprecation").
+ *
+ * **Why a side-table (not inline on each builder):** descriptions and
+ * deprecations are editorial metadata, not derived from the foundation math.
+ * Keeping them in one keyed map lets the IR stay a pure projection of the
+ * resolved theme while `decorateMeta` (see `ir.ts`) stitches the prose on in a
+ * single post-pass — smaller diff than threading copy through every builder.
+ *
+ * **Keying:** each key is a token's dotted IR path **after** kebab-case
+ * normalization (`kebabPath`), i.e. exactly the path the JSON renderer emits in
+ * a `{...}` alias. So `bg.primary`, `border.radius.md`, `space.medium`. A dev
+ * assertion (`assertTokenMetaResolves`) fails the build/tests on any stale key
+ * that no longer maps to an IR node, so this map can never silently rot.
+ *
+ * **Deprecation values:** `true` is a bare DTCG deprecation flag; a string is a
+ * human-readable reason (DTCG allows either). Prefer the string form — it
+ * surfaces the migration path to consumers reading the JSON.
+ *
+ * @see ir.ts (`decorateMeta` post-pass + `assertTokenMetaResolves`)
+ * @see renderers/json.ts (`projectToken` emits `$description` / `$deprecated`)
+ * @see https://www.designtokens.org/TR/drafts/format/ §Description, §Deprecation
+ */
+
+export interface TokenMetaEntry {
+  /** DTCG `$description` — human-readable intent of the token. */
+  readonly description?: string;
+  /** DTCG `$deprecated` — `true` (bare flag) or a string migration reason. */
+  readonly deprecated?: boolean | string;
+}
+
+/**
+ * Editorial metadata keyed by kebab-normalized dotted IR path.
+ *
+ * Starter set covers the well-known foundation roles + a couple of scale
+ * anchors; extend as tokens gain documented intent. Every key MUST resolve to
+ * a live IR node (enforced by `assertTokenMetaResolves`).
+ */
+export const TOKEN_META: Readonly<Record<string, TokenMetaEntry>> = {
+  // ── Foundation backgrounds (semantic surface roles) ──────────────────────
+  'bg.primary': { description: 'Primary action surface — the brand’s dominant call-to-action background.' },
+  'bg.secondary': { description: 'Secondary action surface — supporting actions paired with the primary.' },
+  'bg.danger': { description: 'Destructive / error surface — irreversible or failing actions.' },
+  'bg.success': { description: 'Positive confirmation surface — completed or healthy states.' },
+  'bg.info': {
+    description: 'Informational surface — neutral, non-blocking notices.',
+    deprecated: 'Use bg.information once the foundation role is renamed (tracked for S6).',
+  },
+
+  // ── Foundation text-on roles ─────────────────────────────────────────────
+  'text.on-primary': { description: 'Text/icon colour with guaranteed contrast over bg.primary.' },
+  'text.on-danger': { description: 'Text/icon colour with guaranteed contrast over bg.danger.' },
+
+  // ── Spacing primitives (density-aware dimension scale) ────────────────────
+  'space.medium': { description: 'Base spacing step (1rem at normal density) — the layout rhythm unit.' },
+  'space.large': { description: 'Comfortable spacing step — section padding and card gutters.' },
+
+  // ── Spacing foundation aliases ───────────────────────────────────────────
+  'spacing.md': { description: 'Medium foundation spacing alias — references the space.medium primitive.' },
+  'spacing.lg': { description: 'Large foundation spacing alias — references the space.large primitive.' },
+
+  // ── Border scale ─────────────────────────────────────────────────────────
+  'border.radius.md': { description: 'Default card corner radius.' },
+  'border.width.thin': { description: 'Hairline border — dividers and default input outlines.' },
+  'border.width.regular': { description: 'Standard emphasis border — focused/active controls.' },
+};
+
+/**
+ * Dev assertion: every {@link TOKEN_META} key must map to a live IR node.
+ *
+ * `resolvedPaths` is the set of kebab-normalized dotted paths the IR currently
+ * emits (built by `decorateMeta`'s walk). Throws listing every stale key so a
+ * rename in the foundation can never leave dangling documentation behind.
+ *
+ * @throws if any `TOKEN_META` key is absent from `resolvedPaths`.
+ */
+export function assertTokenMetaResolves(resolvedPaths: ReadonlySet<string>): void {
+  const stale = Object.keys(TOKEN_META).filter((key) => !resolvedPaths.has(key));
+  if (stale.length > 0) {
+    throw new Error(
+      `token-meta: ${stale.length} stale TOKEN_META key(s) resolve to no IR node: ${stale.join(', ')}. ` +
+        `Update src/token-meta.ts to match the current IR paths.`,
+    );
+  }
+}