@vectoriox/iox-ui 5.9.0 → 5.11.0

package/src/design-core/design-token.model.ts

@@ -0,0 +1,121 @@
+import {
+    FLAVOR_SPEC_VERSION, SPEC_AXES, SPEC_FLAVOR_PACKS, SPEC_FONT_ROLES, SPEC_SCHEMES, SPEC_TIER_IDS, SPEC_TOKEN_TYPES,
+} from './flavor-spec.generated';
+
+/**
+ * The design-token vocabulary (design-system plan §3a/§3f). Every list here is READ from the
+ * generated spec, so the contract has one source: iox-ai-guidance `flavor-spec.v1.json`.
+ */
+
+export type DesignTokenType = (typeof SPEC_TOKEN_TYPES)[number];
+export const DESIGN_TOKEN_TYPES: ReadonlyArray<DesignTokenType> = SPEC_TOKEN_TYPES;
+
+export type DesignTokenTier = (typeof SPEC_TIER_IDS)[number];
+export const DESIGN_TOKEN_TIERS: ReadonlyArray<DesignTokenTier> = SPEC_TIER_IDS;
+
+/** The spec carries groups per row, not as a list — `design-token.model.spec` pins this list
+ *  to exactly the set of groups the spec's rows use. */
+export type DesignTokenGroup = 'colour' | 'type' | 'shape' | 'depth' | 'space' | 'motion' | 'components';
+export const DESIGN_TOKEN_GROUPS: ReadonlyArray<DesignTokenGroup> =
+    ['colour', 'type', 'shape', 'depth', 'space', 'motion', 'components'];
+
+/** One `designtokens` row, transport-agnostic (stored rows add `_id`/`organization`). */
+export interface DesignTokenRow {
+    name: string;
+    type: DesignTokenType;
+    value: string;
+    /** Per-scheme overrides. Only `dark` exists; absent means the base value everywhere. */
+    values?: { dark?: string };
+    /** Machine stamp: `flavor:<id>@<version>` on seeded rows, `user` on a font the author chose. */
+    source?: string;
+    group?: DesignTokenGroup;
+    tier?: DesignTokenTier;
+}
+
+/** A row as the planners see it: a stored row may carry its id. */
+export interface StoredDesignTokenRow extends DesignTokenRow {
+    _id?: string;
+}
+
+export type ShapeId = keyof typeof SPEC_AXES.shapes;
+export type DensityId = keyof typeof SPEC_AXES.densities;
+export type MotionId = keyof typeof SPEC_AXES.motions;
+export type DesignMode = (typeof SPEC_AXES.modes)[number];
+export type SchemeId = keyof typeof SPEC_SCHEMES;
+export type FontRoleToken = (typeof SPEC_FONT_ROLES)[number]['token'];
+
+/** Everything a studio chose about its look — the `settings.design` row, typed. */
+export interface DesignChoices {
+    flavorId: string;
+    seed: string;
+    pairId: string;
+    shape: ShapeId;
+    density: DensityId;
+    motion: MotionId;
+    pillButtons: boolean;
+    mode: DesignMode;
+    fonts?: Partial<Record<FontRoleToken, string>>;
+}
+
+export interface FlavorSpecToken {
+    readonly name: string;
+    readonly tier: DesignTokenTier;
+    readonly type: DesignTokenType;
+    readonly group: DesignTokenGroup;
+    readonly value: string;
+    readonly dark?: string;
+    /** The flavor departs from the component token's semantic default. */
+    readonly overridden?: boolean;
+}
+
+export interface FontPair {
+    readonly id: string;
+    readonly label: string;
+    readonly tokens: Readonly<Record<string, string>>;
+    readonly families: ReadonlyArray<string>;
+}
+
+/** A flavor exactly as the spec writes it. */
+export interface FlavorPackV2 {
+    readonly id: string;
+    readonly name: string;
+    readonly personality: string;
+    readonly inspiredBy: string;
+    readonly blurb: string;
+    readonly popularFor: ReadonlyArray<string>;
+    readonly replaces?: string;
+    readonly defaults: {
+        readonly shape: ShapeId;
+        readonly density: DensityId;
+        readonly motion: MotionId;
+        readonly pillButtons: boolean;
+        readonly mode: DesignMode;
+    };
+    readonly seed: string;
+    readonly seeds: ReadonlyArray<string>;
+    readonly pairs: ReadonlyArray<FontPair>;
+    readonly tokens: ReadonlyArray<FlavorSpecToken>;
+}
+
+/** The spec's flavors, typed. Assignment here is the compile-time proof that the generated
+ *  data fits `FlavorPackV2`. */
+export const SPEC_FLAVORS: ReadonlyArray<FlavorPackV2> = SPEC_FLAVOR_PACKS;
+
+/** The stamp seeded rows carry, so an upgrade can tell the machine's rows from the author's. */
+export function flavorSourceStamp(flavorId: string, version: number = FLAVOR_SPEC_VERSION): string {
+    return `flavor:${flavorId}@${version}`;
+}
+
+export const USER_TOKEN_SOURCE = 'user';
+
+export function isDesignTokenType(v: unknown): v is DesignTokenType {
+    return typeof v === 'string' && (DESIGN_TOKEN_TYPES as ReadonlyArray<string>).includes(v);
+}
+
+export function isDesignTokenGroup(v: unknown): v is DesignTokenGroup {
+    return typeof v === 'string' && (DESIGN_TOKEN_GROUPS as ReadonlyArray<string>).includes(v);
+}
+
+export function isDesignTokenTier(v: unknown): v is DesignTokenTier {
+    return typeof v === 'string' && (DESIGN_TOKEN_TIERS as ReadonlyArray<string>).includes(v);
+}

package/src/design-core/flavor-seed.ts

@@ -0,0 +1,126 @@
+import { FlavorTokenDef } from './flavor';
+import { DesignTokenRow, StoredDesignTokenRow } from './design-token.model';
+
+/**
+ * Seeding and reverting a look, as pure plans (flavors F2, moved here from iox-cms-client in
+ * design-system DS1 so the builder, the wizard and the server-side site build share ONE merge).
+ * Each caller applies a plan with its own transport.
+ */
+
+const FLAVOR_SOURCE_PREFIX = 'flavor:';
+const DEFAULT_TOKEN_TYPE = 'other';
+
+/** One row's fate in a seed/re-seed pass (the §10 C2 merge semantics). */
+export interface FlavorSeedPlan {
+    create: DesignTokenRow[];
+    update: { id: string; data: Partial<DesignTokenRow> }[];
+    /** Names deliberately left alone: hand-made rows, and seeded rows the author edited. */
+    kept: string[];
+}
+
+/** What Apply stores so the 7-day revert is honest: the WHOLE pre-apply token set plus the
+ *  design identity it belonged to. */
+export interface FlavorRevertSnapshot {
+    appliedAt: number;
+    /** The design row's identity BEFORE the apply, restored with the tokens. */
+    from: { flavorId: string | null; flavorVersion: string | null; brandSeed: string | null };
+    tokens: Array<Pick<DesignTokenRow, 'name' | 'type' | 'value' | 'values' | 'source' | 'group' | 'tier'>>;
+}
+
+export interface FlavorRevertPlan {
+    create: DesignTokenRow[];
+    update: Array<{ id: string; data: Partial<DesignTokenRow> }>;
+    /** Rows the apply created (flavor-stamped, absent from the snapshot) — removed on revert. */
+    remove: string[];
+}
+
+export const REVERT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+const isSeeded = (row: { source?: string } | null | undefined) => (row?.source ?? '').startsWith(FLAVOR_SOURCE_PREFIX);
+
+const classification = (def: Pick<DesignTokenRow, 'group' | 'tier'>): Pick<DesignTokenRow, 'group' | 'tier'> => ({
+    ...(def.group ? { group: def.group } : {}),
+    ...(def.tier ? { tier: def.tier } : {}),
+});
+
+/** Board F7's footer promise, as a boundary: available through the 7th day, not beyond. */
+export function revertAvailable(appliedAt: number | null | undefined, now: number): boolean {
+    return typeof appliedAt === 'number' && appliedAt > 0 && now - appliedAt <= REVERT_WINDOW_MS;
+}
+
+/**
+ * Restore the snapshot EXACTLY: snapshot rows come back to their stored value/dark/source
+ * (update when present, recreate when deleted); rows the apply CREATED (flavor-stamped and
+ * absent from the snapshot) are removed. Hand-made rows born after the apply are not ours
+ * to touch — a revert undoes the FLAVOR, not the author's week.
+ */
+export function planFlavorRevert(
+    current: ReadonlyArray<StoredDesignTokenRow>,
+    snapshot: FlavorRevertSnapshot['tokens'],
+): FlavorRevertPlan {
+    const byName = new Map<string, StoredDesignTokenRow>();
+    for (const row of current ?? []) byName.set(row.name, row);
+    const snapNames = new Set<string>();
+    const plan: FlavorRevertPlan = { create: [], update: [], remove: [] };
+    for (const snap of snapshot ?? []) {
+        snapNames.add(snap.name);
+        const live = byName.get(snap.name);
+        if (!live) {
+            plan.create.push({ name: snap.name, type: snap.type, value: snap.value, values: snap.values, source: snap.source, ...classification(snap) });
+            continue;
+        }
+        const differs = live.value !== snap.value
+            || (live.values?.dark ?? null) !== (snap.values?.dark ?? null)
+            || (live.source ?? null) !== (snap.source ?? null);
+        if (differs && live._id) {
+            plan.update.push({ id: live._id, data: { value: snap.value, values: snap.values, source: snap.source } });
+        }
+    }
+    for (const row of current ?? []) {
+        if (!snapNames.has(row.name) && row._id && isSeeded(row)) plan.remove.push(row._id);
+    }
+    return plan;
+}
+
+/**
+ * The seeding MERGE: desired tokens vs existing rows, deciding create / update / keep. The §10 C2
+ * rule — "an upgrade only rewrites untouched rows" — is a comparison against what the PREVIOUS
+ * seed wrote (`oldExpected`): a seeded row whose value still equals it is the machine's and may be
+ * rewritten; any drift means the author took it over, and their hand wins. A row without a
+ * `flavor:` stamp is never touched at all. `group`/`tier` ride every write.
+ */
+export function planFlavorSeed(
+    desired: ReadonlyArray<FlavorTokenDef>,
+    existing: ReadonlyArray<StoredDesignTokenRow>,
+    stamp: string,
+    oldExpected: Map<string, { value: string; dark?: string }> | null,
+): FlavorSeedPlan {
+    const byName = new Map((existing ?? []).map(r => [r.name, r]));
+    const plan: FlavorSeedPlan = { create: [], update: [], kept: [] };
+    for (const def of desired ?? []) {
+        if (!def?.name) continue;
+        const row = byName.get(def.name);
+        if (!row) {
+            plan.create.push({
+                name: def.name,
+                type: def.type ?? DEFAULT_TOKEN_TYPE,
+                value: def.value,
+                ...(def.values ? { values: def.values } : {}),
+                source: stamp,
+                ...classification(def),
+            });
+            continue;
+        }
+        if (!isSeeded(row)) { plan.kept.push(def.name); continue; }
+        const sameAsDesired = row.value === def.value && (row.values?.dark ?? '') === (def.values?.dark ?? '');
+        if (sameAsDesired) continue; // already exactly this — nothing to write, nothing kept-against
+        const old = oldExpected?.get(def.name);
+        const untouched = !!old && row.value === old.value && (row.values?.dark ?? '') === (old.dark ?? '');
+        if (untouched && row._id) {
+            plan.update.push({ id: row._id, data: { value: def.value, values: def.values ?? {}, source: stamp, ...classification(def) } });
+        } else {
+            plan.kept.push(def.name); // edited since seeding (or unverifiable) — the author's hand wins
+        }
+    }
+    return plan;
+}