@vectoriox/iox-ui 5.22.0 → 5.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.22.0",
+  "version": "5.24.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/design-core/design-apply.ts

@@ -2,7 +2,9 @@ import { deriveBrandTokens } from './brand';
 import { SPEC_LEGACY_ALIASES } from './flavor-spec.generated';
 import { SWISS_FLAVOR } from './flavor';
 import { buildFlavorTokens } from './flavor-tokens';
-import { FlavorSeedPlan, planFlavorSeed, SeedBaseline, SeedExpectation } from './flavor-seed';
+import {
+    FlavorRevertPlan, FlavorSeedOptions, FlavorSeedPlan, planFlavorRevert, planFlavorSeed, SeedBaseline, SeedExpectation, untouchedSeedRow,
+} from './flavor-seed';
 import { DesignChoices, DesignTokenRow, flavorSourceStamp, StoredDesignTokenRow } from './design-token.model';
 import { fontFamilyKey, FontFamilyToken, fontRoleReferences, parseFontFamilies } from './fonts';
 import { flavorPackById, isRetiredFlavorId, packDesignChoices, StoredDesign } from './design-settings';
@@ -37,32 +39,77 @@ function swissExpectations(seed: string | null): Map<string, SeedExpectation> {
     return expectations(rows);
 }
 
+/** What a v2 pack writes at its OWN defaults, by pack id — computed once per id per caller. */
+function packDefaultsLookup(): (packId: string) => Map<string, SeedExpectation> | undefined {
+    const cache = new Map<string, Map<string, SeedExpectation> | undefined>();
+    return packId => {
+        if (!cache.has(packId)) {
+            const pack = isRetiredFlavorId(packId) ? undefined : flavorPackById(packId);
+            cache.set(packId, pack && pack.id === packId ? expectations(designTokenRows(packDesignChoices(pack.id))) : undefined);
+        }
+        return cache.get(packId);
+    };
+}
+
 /**
  * What the PREVIOUS design wrote, as a baseline keyed by the row's own stamp: a row Swiss stamped is
  * judged against what Swiss wrote, every other row against `buildFlavorTokens` of the stored choices
  * (for an org with no design row, Crisp's defaults — exactly what DS2's interim seed wrote). In a
  * Swiss org the only v2 rows are that interim seed's, so they are judged against Crisp's DEFAULTS,
  * never against the brand-seeded Crisp the migration is about to write.
+ *
+ * A row a v2 pack stamped is ALSO untouched while it holds what that pack writes at its own defaults —
+ * what DS2's interim seed, a first run and every pack card at its defaults wrote. Without it, one row
+ * kept for any reason (a dark half iox-cms dropped, `untouchedSeedRow`) was judged against a design that
+ * had moved on, apply after apply, and stayed on the old value for good: the studio's brand colour
+ * reached the design row and never its accent.
  */
 export function designBaseline(previous: StoredDesign): SeedBaseline {
     const retired = isRetiredFlavorId(previous.storedFlavorId);
     const current = expectations(designTokenRows(retired ? packDesignChoices(previous.choices.flavorId) : previous.choices));
     const swiss = swissExpectations(retired ? previous.storedSeed : null);
+    const packDefaults = packDefaultsLookup();
     return (row: StoredDesignTokenRow) => {
         const stampedBy = SEED_STAMP.exec(row.source ?? '')?.[1];
-        return stampedBy === SWISS_FLAVOR.id ? swiss.get(row.name) : current.get(row.name);
+        if (stampedBy === SWISS_FLAVOR.id) return swiss.get(row.name);
+        const ownDefault = stampedBy ? packDefaults(stampedBy)?.get(row.name) : undefined;
+        return [current.get(row.name), ownDefault].filter((e): e is SeedExpectation => !!e);
     };
 }
 
-/** Apply `next` over the org's rows, judged against `previous` — the plan FlavorApplyService runs. */
+/** Options of an apply. */
+export interface DesignApplyOptions {
+    /** The kept rows the author asked to take the look's values too (`FlavorSeedOptions.reclaim`). */
+    reclaim?: FlavorSeedOptions['reclaim'];
+}
+
+/**
+ * Apply `next` over the org's rows, judged against `previous` — the plan FlavorApplyService runs. The
+ * plan's `kept` names the author's rows the look leaves alone; the Design card lists them before Apply,
+ * and `options.reclaim` writes the look's value into the ones the author hands back.
+ */
 export function planDesignApply(
     existing: ReadonlyArray<StoredDesignTokenRow>,
     previous: StoredDesign,
     next: DesignChoices,
+    options: DesignApplyOptions = {},
 ): FlavorSeedPlan {
     const pack = flavorPackById(next.flavorId);
     if (!pack) return { create: [], update: [], kept: [] };
-    return planFlavorSeed(designTokenRows(next), existing, flavorSourceStamp(pack.id), designBaseline(previous));
+    return planFlavorSeed(designTokenRows(next), existing, flavorSourceStamp(pack.id), designBaseline(previous), { reclaim: options.reclaim });
+}
+
+/**
+ * "Revert to previous look" over the org's rows — the ONE plan the Revert executes and its hint counts
+ * (`kept`: the author's edits since the apply, left as they are). The apply's record of what it wrote
+ * decides what an edit since is; a snapshot stored before that record existed (DS8.1) is judged against
+ * the rows the applied design writes — the look's own author rows (a chosen font) still go back.
+ * `null` when the design holds no snapshot.
+ */
+export function planDesignRevert(current: ReadonlyArray<StoredDesignTokenRow>, design: StoredDesign): FlavorRevertPlan | null {
+    const snapshot = design?.revert;
+    if (!snapshot) return null;
+    return planFlavorRevert(current, snapshot.tokens, snapshot.wrote ?? designTokenRows(design.choices));
 }
 
 /** The rows a design is missing by name — the builder-load top-up (never touches an existing row). */
@@ -72,23 +119,34 @@ export function missingDesignRows(existing: ReadonlyArray<{ name: string }>, cho
 }
 
 /**
- * The builder-load REPAIR (DS4.1): rows the design owns and nobody touched — stamped by the current
- * pack, light value exactly the pack's — whose dark override differs from the pack's are rewritten.
- * iox-cms dropped `values.dark` on every write from F0 to DS4 (`values` was an implicit relation),
- * and a revert could leave the previous apply's dark behind; both leave a row whose light half is the
- * design's and whose dark half is not. No author edit can produce that shape — the Tokens panel edits
- * the light value only — so rewriting it heals existing orgs without the author doing anything.
+ * The builder-load REPAIR (DS4.1): rows the design writes that are the machine's and nobody touched,
+ * yet hold something other than the design's value, are rewritten — so an org heals on its next load
+ * with no author action. Two shapes:
+ * - stamped by the current pack, light value exactly the pack's, dark half not: iox-cms dropped
+ *   `values.dark` on every write from F0 to DS4 (`values` was an implicit relation), and a revert could
+ *   leave the previous apply's dark behind;
+ * - stamped by a v2 pack and still holding what THAT pack writes at its own defaults (its dark half
+ *   possibly lost the same way) while the stored design says otherwise: an apply that judged the row
+ *   edited (before 5.24.0, a lost dark half did) left it on the default — the six brand rows of a studio
+ *   whose brand colour never reached its accent.
+ * No author edit produces either shape — the Tokens panel edited the light value only, and since DS8 an
+ * edit makes the row `source: user`, which this never touches.
  */
 export function designTokenRepairs(existing: ReadonlyArray<StoredDesignTokenRow>, choices: DesignChoices): FlavorSeedPlan['update'] {
     const pack = flavorPackById(choices.flavorId);
     if (!pack) return [];
     const stamp = flavorSourceStamp(pack.id);
     const desired = new Map(designTokenRows(choices).map(r => [r.name, r]));
+    const packDefaults = packDefaultsLookup();
     const out: FlavorSeedPlan['update'] = [];
     for (const row of existing ?? []) {
         const want = desired.get(row.name);
-        if (!want || !row._id || row.source !== stamp || want.source !== stamp || row.value !== want.value) continue;
-        if ((row.values?.dark ?? '') === (want.values?.dark ?? '')) continue;
+        if (!want || !row._id || want.source !== stamp) continue;
+        if (row.value === want.value && (row.values?.dark ?? '') === (want.values?.dark ?? '') && row.source === stamp) continue;
+        const stampedBy = SEED_STAMP.exec(row.source ?? '')?.[1];
+        const darkOnly = row.source === stamp && row.value === want.value;
+        const ownDefault = stampedBy ? packDefaults(stampedBy)?.get(row.name) : undefined;
+        if (!darkOnly && !(ownDefault && untouchedSeedRow(row, [ownDefault]))) continue;
         out.push({ id: row._id, data: { value: want.value, values: want.values ?? {}, source: stamp, ...(want.group ? { group: want.group } : {}), ...(want.tier ? { tier: want.tier } : {}) } });
     }
     return out;

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

@@ -25,13 +25,21 @@ export interface FlavorRevertSnapshot {
     /** 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'>>;
+    /** What the apply left in every row it wrote (`flavorSeedWrites`). A row holding something else
+     *  since, as the author's (`source: user`), was edited AFTER the apply — the revert keeps it. */
+    wrote?: FlavorRevertWrite[];
 }
 
+/** One row as an apply left it — the value and dark half the revert compares a live row against. */
+export type FlavorRevertWrite = Pick<DesignTokenRow, 'name' | 'value' | 'values'>;
+
 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[];
+    /** The author's edits made after the apply, left as they are (names) — what the Revert hint counts. */
+    kept: string[];
 }
 
 export const REVERT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
@@ -49,19 +57,30 @@ export function revertAvailable(appliedAt: number | null | undefined, now: numbe
 }
 
 /**
- * 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.
+ * Restore the snapshot: 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. A revert undoes the FLAVOR, not the author's week: hand-made rows born after
+ * the apply are not touched, and a row the author EDITED after the apply is kept (DS8: an edit makes
+ * the row the author's, and a pack switch keeps it — so does going back). Edited-after = `source: user`,
+ * differing from the snapshot, and holding something other than what the apply wrote (`wrote` — the
+ * apply's own author rows, a chosen font or an Element-styles edit, still go back with it). With no
+ * `wrote` at all, every author row that differs from the snapshot is judged edited after.
  */
 export function planFlavorRevert(
     current: ReadonlyArray<StoredDesignTokenRow>,
     snapshot: FlavorRevertSnapshot['tokens'],
+    wrote?: ReadonlyArray<FlavorRevertWrite> | null,
 ): FlavorRevertPlan {
     const byName = new Map<string, StoredDesignTokenRow>();
     for (const row of current ?? []) byName.set(row.name, row);
+    const written = new Map((wrote ?? []).map(w => [w.name, w]));
+    const editedAfter = (live: StoredDesignTokenRow) => {
+        if (live.source !== USER_TOKEN_SOURCE) return false;
+        const w = written.get(live.name);
+        return !w || !sameValue(live, { value: w.value, dark: w.values?.dark });
+    };
     const snapNames = new Set<string>();
-    const plan: FlavorRevertPlan = { create: [], update: [], remove: [] };
+    const plan: FlavorRevertPlan = { create: [], update: [], remove: [], kept: [] };
     for (const snap of snapshot ?? []) {
         snapNames.add(snap.name);
         const live = byName.get(snap.name);
@@ -72,18 +91,33 @@ export function planFlavorRevert(
         const differs = live.value !== snap.value
             || (live.values?.dark ?? null) !== (snap.values?.dark ?? null)
             || (live.source ?? null) !== (snap.source ?? null);
+        if (!differs || !live._id) continue;
+        if (editedAfter(live)) { plan.kept.push(live.name); continue; }
         // `values` is ALWAYS sent: an absent key is dropped by JSON and a `$set` then keeps the
         // apply's dark override — a snapshot row with no dark must clear it, so it sends `{}`.
-        if (differs && live._id) {
-            plan.update.push({ id: live._id, data: { value: snap.value, values: snap.values ?? {}, source: snap.source } });
-        }
+        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);
+        if (snapNames.has(row.name) || !row._id) continue;
+        if (isSeeded(row)) plan.remove.push(row._id);
+        else if (written.has(row.name) && editedAfter(row)) plan.kept.push(row.name);
     }
     return plan;
 }
 
+/** What a seed plan leaves in each row it writes, by name — the snapshot's `wrote`. */
+export function flavorSeedWrites(plan: FlavorSeedPlan, existing: ReadonlyArray<StoredDesignTokenRow>): FlavorRevertWrite[] {
+    const byId = new Map((existing ?? []).filter(r => r._id).map(r => [r._id as string, r]));
+    const out: FlavorRevertWrite[] = (plan?.create ?? []).map(r => ({ name: r.name, value: r.value, ...(r.values ? { values: r.values } : {}) }));
+    for (const u of plan?.update ?? []) {
+        const row = byId.get(u.id);
+        if (!row) continue;
+        const values = u.data.values ?? row.values;
+        out.push({ name: row.name, value: u.data.value ?? row.value, ...(values ? { values } : {}) });
+    }
+    return out;
+}
+
 /** What a previous seed wrote for one row — the "untouched" comparison base. */
 export interface SeedExpectation {
     value: string;
@@ -91,19 +125,44 @@ export interface SeedExpectation {
 }
 
 /**
- * What the PREVIOUS seed wrote, per row: a map by name, or a function of the stored row (a baseline
- * that depends on WHICH seed stamped the row — the Swiss → Crisp migration's case).
+ * What a previous seed wrote, per row: a map by name, or a function of the stored row (a baseline that
+ * depends on WHICH seed stamped the row — the Swiss → Crisp migration's case). The function may name
+ * several values: a machine row is untouched when it holds ANY of them (`designBaseline`: what the
+ * previous design wrote, and what the row's own pack writes at its defaults).
  */
 export type SeedBaseline =
     | ReadonlyMap<string, SeedExpectation>
-    | ((row: StoredDesignTokenRow) => SeedExpectation | undefined);
+    | ((row: StoredDesignTokenRow) => SeedExpectation | ReadonlyArray<SeedExpectation> | undefined);
 
-const expectationFor = (baseline: SeedBaseline | null | undefined, row: StoredDesignTokenRow): SeedExpectation | undefined =>
-    !baseline ? undefined : typeof baseline === 'function' ? baseline(row) : baseline.get(row.name);
+/** Options of a seed pass. */
+export interface FlavorSeedOptions {
+    /** Rows the author asked to take the look's values too ("Use the look's values for these too"):
+     *  written like an untouched row instead of being kept. */
+    reclaim?: Iterable<string> | null;
+}
+
+function expectationsFor(baseline: SeedBaseline | null | undefined, row: StoredDesignTokenRow): SeedExpectation[] {
+    if (!baseline) return [];
+    const found = typeof baseline === 'function' ? baseline(row) : baseline.get(row.name);
+    if (!found) return [];
+    return (Array.isArray(found) ? found : [found]).filter(Boolean) as SeedExpectation[];
+}
 
 const sameValue = (row: { value: string; values?: { dark?: string } }, e: SeedExpectation) =>
     row.value === e.value && (row.values?.dark ?? '') === (e.dark ?? '');
 
+/**
+ * A machine-stamped row is untouched when it holds what a seed wrote — or that seed's LIGHT value with no
+ * dark half at all: iox-cms dropped every `values.dark` from F0 to DS4.1, and no author edit produces that
+ * shape (the Tokens panel edited the light value only, and since DS8 an edit makes the row `source: user`).
+ * Judging it edited kept the six brand rows of every studio seeded before DS4.1 on the default blue for
+ * good — a later brand never reached them.
+ */
+export function untouchedSeedRow(row: StoredDesignTokenRow, expected: ReadonlyArray<SeedExpectation>): boolean {
+    const darkLost = isSeeded(row) && !row.values?.dark;
+    return expected.some(e => sameValue(row, e) || (darkLost && row.value === e.value));
+}
+
 /**
  * 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
@@ -114,15 +173,18 @@ const sameValue = (row: { value: string; values?: { dark?: string } }, e: SeedEx
  * choice, so a new choice may replace it. `group`/`tier` ride every write; a desired row's own
  * `source` (a chosen font's `user`) wins over the pack stamp. A machine-owned row that already holds
  * the desired value but another pack's stamp is RE-STAMPED (§10 C2 provenance: the stamp names the
- * design that owns the row, so the next switch judges it against the right baseline).
+ * design that owns the row, so the next switch judges it against the right baseline). A row named in
+ * `options.reclaim` is written whatever it holds — the author chose the look's value over their own.
  */
 export function planFlavorSeed(
     desired: ReadonlyArray<FlavorTokenDef & { source?: string }>,
     existing: ReadonlyArray<StoredDesignTokenRow>,
     stamp: string,
     baseline: SeedBaseline | null,
+    options: FlavorSeedOptions = {},
 ): FlavorSeedPlan {
     const byName = new Map((existing ?? []).map(r => [r.name, r]));
+    const reclaim = new Set(options.reclaim ?? []);
     const plan: FlavorSeedPlan = { create: [], update: [], kept: [] };
     for (const def of desired ?? []) {
         if (!def?.name) continue;
@@ -139,13 +201,14 @@ export function planFlavorSeed(
             });
             continue;
         }
-        const old = expectationFor(baseline, row);
-        const designOwned = isSeeded(row) || (row.source === USER_TOKEN_SOURCE && !!old && sameValue(row, old));
-        if (!designOwned) { plan.kept.push(def.name); continue; }
+        const olds = expectationsFor(baseline, row);
+        const reclaimed = reclaim.has(def.name);
+        const designOwned = isSeeded(row) || (row.source === USER_TOKEN_SOURCE && olds.some(o => sameValue(row, o)));
+        if (!designOwned && !reclaimed) { plan.kept.push(def.name); continue; }
         const sameAsDesired = row.value === def.value && (row.values?.dark ?? '') === (def.values?.dark ?? '');
         if (sameAsDesired && (row.source ?? '') === source) continue; // already exactly this
-        const untouched = !!old && sameValue(row, old);
-        if ((untouched || sameAsDesired) && row._id) {
+        const untouched = untouchedSeedRow(row, olds);
+        if ((untouched || sameAsDesired || reclaimed) && row._id) {
             plan.update.push({ id: row._id, data: { value: def.value, values: def.values ?? {}, source, ...classification(def) } });
         } else {
             plan.kept.push(def.name); // edited since seeding (or unverifiable) — the author's hand wins