@vectoriox/iox-ui 5.21.0 → 5.23.0

package/package.json

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

package/src/design-core/adopt.ts

@@ -0,0 +1,250 @@
+import {
+    BUTTON_VARIANT_TO_STYLE, ElementStyle, ElementStyleTarget, OwnedTrait, defaultElementStyleFor,
+    elementStyleById, ownedTraitsOf, readOwnedTrait, writeOwnedTrait,
+} from './element-styles';
+
+/**
+ * ADOPT (design-system DS7, decision D5): link the nodes of a page saved before element styles to
+ * the style a NEW node of their type is born wearing, so the page follows the look from then on.
+ * Opt-in per page, one click, one undo step — this module is only the pure tree pass; the builder
+ * owns the click, the history step and the save.
+ *
+ * The rule that keeps the author's work: a trait the style owns is rewritten to the style's
+ * reference ONLY when the node still holds what an untouched node of its type was saved with — the
+ * type's BASELINE (the unstyled constructor default the caller supplies), or a value a machine wrote
+ * into every new node before element styles existed (`PRE_DS2_FLAVOR_DEFAULTS`). Anything else is an
+ * author edit and is KEPT, and reported.
+ *
+ * A node that already wears a style is UPGRADED where it holds a value that style wrote in an OLDER
+ * contract (`SUPERSEDED_STYLE_VALUES`) — the same untouched-means-machine-written rule, one version on.
+ *
+ * Works on both node shapes element-styles.ts does: a builder node (values in `styleTraits`) or a
+ * serialized node (`styleProps`), so the server-side site build can run it too.
+ */
+
+/**
+ * What a NEW node holds before its element style is written (C1.1): running text inherits, so a
+ * literal colour on any container would override the section's text. The factory
+ * (`ComponentRegistryService.createConfig`) writes it; adopt releases a baseline colour to it, so an
+ * adopted node is exactly what a new node of its type is.
+ */
+export const NEW_NODE_STYLE_DEFAULTS: Readonly<Record<string, string>> = { color: 'inherit' };
+
+/**
+ * Values a machine wrote into every NEW node of a type before element styles: the F1 Swiss pack's
+ * element defaults (`SWISS_FLAVOR.defaults`, iox-ui 5.3.0 `0a00761` + iox-builder 4.24.0 `85109eb`,
+ * `createConfig → applyFlavorDefaults`, resolved by `resolveFlavorDefaults` to
+ * `var(--iox-<token>, <pack value>)`; deleted in DS2). An untouched node created between F1 and DS2
+ * holds exactly these, so they count as untouched.
+ */
+export const PRE_DS2_FLAVOR_DEFAULTS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+    Button: { borderRadius: 'var(--iox-radius-control, 4px)', padding: 'var(--iox-space-control, 10px 18px)' },
+    ButtonBlock: { borderRadius: 'var(--iox-radius-control, 4px)', padding: 'var(--iox-space-control, 10px 18px)' },
+    Card: { borderRadius: 'var(--iox-radius-surface, 4px)' },
+};
+
+/** One owned trait whose value an element style CHANGED in the contract's history. */
+export interface SupersededStyleValue extends OwnedTrait {
+    readonly style: string;
+    /** What the style wrote before. */
+    readonly values: ReadonlyArray<string>;
+    /** The style did not own the trait before, so an untouched node held its type's baseline. */
+    readonly wasUnowned?: boolean;
+    /** The iox-ai-guidance contract commit that changed it. */
+    readonly contract: string;
+}
+
+/**
+ * Every element-style value the contract has superseded since element styles shipped (a diff of
+ * `flavor-spec.v1.json`'s `elementStyles` across its history — nothing else changed a value):
+ * - `b86c54f` (C1): body / lead `color: var(--iox-text)` → `inherit`;
+ * - `602d96e` (C1.1): box / card / panel / nav gained `color: inherit` — before, they owned no colour.
+ * A spec pins this list against the generated contract. Add an entry with every contract change.
+ */
+export const SUPERSEDED_STYLE_VALUES: ReadonlyArray<SupersededStyleValue> = [
+    { style: 'body', trait: 'color', values: ['var(--iox-text)'], contract: 'b86c54f' },
+    { style: 'lead', trait: 'color', values: ['var(--iox-text)'], contract: 'b86c54f' },
+    { style: 'box', trait: 'color', values: [], wasUnowned: true, contract: '602d96e' },
+    { style: 'card', trait: 'color', values: [], wasUnowned: true, contract: '602d96e' },
+    { style: 'panel', trait: 'color', values: [], wasUnowned: true, contract: '602d96e' },
+    { style: 'nav', trait: 'color', values: [], wasUnowned: true, contract: '602d96e' },
+];
+
+export enum AdoptOutcome {
+    /** The node wore no style; it now wears its type's default (or its legacy Button variant's). */
+    Linked = 'linked',
+    /** The node wore a style; values that style wrote in an older contract were brought current. */
+    Upgraded = 'upgraded',
+}
+
+export enum AdoptSkipReason {
+    /** The type is born wearing no style (Gallery, SliderContainer, Spacer, …). */
+    NoStyle = 'no-style',
+    /** The node takes its look from a style preset — the author's own class. */
+    Preset = 'preset',
+    /** The node is (inside) a linked symbol instance: its look is the symbol's, shared across pages. */
+    Symbol = 'symbol',
+}
+
+export interface AdoptContext {
+    /** Per type, the style map an untouched SAVED node of it holds — its unstyled constructor
+     *  defaults (the builder's `ComponentRegistryService.adoptionBaseline`). */
+    baseline(type: string): Readonly<Record<string, unknown>>;
+}
+
+/** The shapes this pass reads: an element-style target plus the fields that decide skips and styles. */
+export interface AdoptableNode extends ElementStyleTarget {
+    id?: string;
+    props?: Readonly<Record<string, unknown>> | null;
+    traits?: ReadonlyArray<{ name: string; default?: unknown }> | null;
+    stylePresetId?: string | null;
+    symbolId?: string | null;
+    children?: AdoptableNode[] | null;
+}
+
+/** An owned trait the author had changed — kept, with the value kept. */
+export interface KeptEdit extends OwnedTrait {
+    value: unknown;
+}
+
+export interface AdoptedNode {
+    id?: string;
+    type: string;
+    style: string;
+    outcome: AdoptOutcome;
+    /** Traits rewritten (the style's references, a current value, or a released colour). */
+    written: OwnedTrait[];
+    kept: KeptEdit[];
+}
+
+export interface SkippedNode {
+    id?: string;
+    type: string;
+    reason: AdoptSkipReason;
+}
+
+export interface AdoptReport {
+    adopted: AdoptedNode[];
+    skipped: SkippedNode[];
+    /** Author edits kept across every adopted node. */
+    kept: number;
+}
+
+const sameValue = (a: unknown, b: unknown): boolean =>
+    a === b || (a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b));
+
+function propOf(node: AdoptableNode, name: string): unknown {
+    const fromProps = node.props?.[name];
+    if (fromProps !== undefined) return fromProps;
+    return node.traits?.find(t => t?.name === name)?.default;
+}
+
+/** The style an unstyled node adopts: a legacy Button by its `variant` (spec `buttonVariantToStyle`),
+ *  every other type by its default (a Heading by its level), or null. */
+export function adoptionStyleFor(node: AdoptableNode): string | null {
+    if (node.type === 'Button') {
+        const byVariant = BUTTON_VARIANT_TO_STYLE[String(propOf(node, 'variant') ?? '')];
+        if (byVariant) return byVariant;
+    }
+    const traits: Record<string, unknown> = { ...(node.props ?? {}) };
+    for (const t of node.traits ?? []) if (t?.name && !(t.name in traits)) traits[t.name] = t.default;
+    return defaultElementStyleFor(node.type, traits);
+}
+
+const owns = (style: ElementStyle, trait: string) => trait in style.base;
+
+/** Release each new-node default the style does not own, where the node still holds its baseline. */
+function releaseNewNodeDefaults(node: AdoptableNode, style: ElementStyle | null, baseline: Readonly<Record<string, unknown>>, written: OwnedTrait[]): void {
+    for (const [trait, value] of Object.entries(NEW_NODE_STYLE_DEFAULTS)) {
+        if (style && owns(style, trait)) continue;
+        const ref = { trait };
+        const current = readOwnedTrait(node, ref);
+        if (current === undefined || sameValue(current, value) || !sameValue(current, baseline[trait])) continue;
+        if (writeOwnedTrait(node, ref, value)) written.push(ref);
+    }
+}
+
+function untouched(node: AdoptableNode, trait: string, value: unknown, baseline: Readonly<Record<string, unknown>>): boolean {
+    return value === undefined || sameValue(value, baseline[trait]) || sameValue(value, PRE_DS2_FLAVOR_DEFAULTS[node.type]?.[trait]);
+}
+
+function link(node: AdoptableNode, style: ElementStyle, baseline: Readonly<Record<string, unknown>>): AdoptedNode {
+    const written: OwnedTrait[] = [];
+    const kept: KeptEdit[] = [];
+    for (const { value, ...ref } of ownedTraitsOf(style)) {
+        const current = readOwnedTrait(node, ref);
+        if (sameValue(current, value)) continue;
+        // A pseudo-state map has no baseline: a state value is always the author's.
+        const free = ref.state ? current === undefined : untouched(node, ref.trait, current, baseline);
+        if (!free) { kept.push({ ...ref, value: current }); continue; }
+        if (writeOwnedTrait(node, ref, value)) written.push(ref);
+    }
+    releaseNewNodeDefaults(node, style, baseline, written);
+    node.elementStyle = style.id;
+    return { id: node.id, type: node.type, style: style.id, outcome: AdoptOutcome.Linked, written, kept };
+}
+
+function upgrade(node: AdoptableNode, style: ElementStyle, baseline: Readonly<Record<string, unknown>>): AdoptedNode | null {
+    const written: OwnedTrait[] = [];
+    for (const old of SUPERSEDED_STYLE_VALUES) {
+        if (old.style !== style.id) continue;
+        const ref: OwnedTrait = old.state ? { trait: old.trait, state: old.state } : { trait: old.trait };
+        const now = old.state ? style[old.state]?.[old.trait] : style.base[old.trait];
+        if (now === undefined) continue;
+        const current = readOwnedTrait(node, ref);
+        const before = old.wasUnowned ? [...old.values, baseline[old.trait]] : old.values;
+        if (!before.some(v => sameValue(current, v))) continue;
+        if (writeOwnedTrait(node, ref, now)) written.push(ref);
+    }
+    releaseNewNodeDefaults(node, style, baseline, written);
+    return written.length ? { id: node.id, type: node.type, style: style.id, outcome: AdoptOutcome.Upgraded, written, kept: [] } : null;
+}
+
+/**
+ * Adopt every node of `tree` in place (children included) and report what happened. Skipped, never
+ * touched: a node with a style preset, and every node of a linked symbol instance. A node whose type
+ * has no default style is not linked, but an untouched baseline colour on it is released to the
+ * new-node default all the same, so adopted text inside it is not painted the old literal.
+ */
+export function adoptElementStyles(tree: AdoptableNode[] | null | undefined, ctx: AdoptContext): AdoptReport {
+    const report: AdoptReport = { adopted: [], skipped: [], kept: 0 };
+    const visit = (nodes: AdoptableNode[] | null | undefined, inSymbol: boolean) => {
+        for (const node of nodes ?? []) {
+            if (!node?.type) continue;
+            const symbol = inSymbol || !!node.symbolId;
+            adoptNode(node, symbol, ctx, report);
+            visit(node.children, symbol);
+        }
+    };
+    visit(tree, false);
+    report.kept = report.adopted.reduce((n, a) => n + a.kept.length, 0);
+    return report;
+}
+
+function adoptNode(node: AdoptableNode, inSymbol: boolean, ctx: AdoptContext, report: AdoptReport): void {
+    const worn = elementStyleById(node.elementStyle);
+    const target = worn ? null : elementStyleById(adoptionStyleFor(node));
+    const reason = inSymbol ? AdoptSkipReason.Symbol : node.stylePresetId ? AdoptSkipReason.Preset : null;
+    if (reason) {
+        if (target) report.skipped.push({ id: node.id, type: node.type, reason });
+        return;
+    }
+    const baseline = ctx.baseline(node.type) ?? {};
+    if (worn) {
+        const upgraded = upgrade(node, worn, baseline);
+        if (upgraded) report.adopted.push(upgraded);
+        return;
+    }
+    if (node.elementStyle) return;
+    if (!target) {
+        releaseNewNodeDefaults(node, null, baseline, []);
+        report.skipped.push({ id: node.id, type: node.type, reason: AdoptSkipReason.NoStyle });
+        return;
+    }
+    report.adopted.push(link(node, target, baseline));
+}
+
+/** What adopting `tree` WOULD do, without touching it (the banner's count). */
+export function previewElementStyleAdoption(tree: AdoptableNode[] | null | undefined, ctx: AdoptContext): AdoptReport {
+    return adoptElementStyles(JSON.parse(JSON.stringify(tree ?? [])), ctx);
+}

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

@@ -2,7 +2,7 @@ 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, FlavorSeedPlan, planFlavorRevert, planFlavorSeed, SeedBaseline, SeedExpectation } 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';
@@ -65,6 +65,19 @@ export function planDesignApply(
     return planFlavorSeed(designTokenRows(next), existing, flavorSourceStamp(pack.id), designBaseline(previous));
 }
 
+/**
+ * "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). */
 export function missingDesignRows(existing: ReadonlyArray<{ name: string }>, choices: DesignChoices): DesignTokenRow[] {
     const have = new Set((existing ?? []).map(r => r.name));

package/src/design-core/element-styles.ts

@@ -163,6 +163,23 @@ function ownedEntries(style: ElementStyle): Array<OwnedTrait & { value: string }
     return out;
 }
 
+/** Every trait the style owns with the value it writes — base first, then hover/active/focus. */
+export function ownedTraitsOf(style: ElementStyle): Array<OwnedTrait & { value: string }> {
+    return ownedEntries(style);
+}
+
+/** The node's value of one owned trait (a base trait, or a trait inside a pseudo-state map). */
+export function readOwnedTrait(target: ElementStyleTarget, owned: OwnedTrait): unknown {
+    return owned.state ? readState(target, owned.state, owned.trait) : readBase(target, owned.trait);
+}
+
+/** Write one owned trait. False when a builder node has no slot for a base trait (dropped). */
+export function writeOwnedTrait(target: ElementStyleTarget, owned: OwnedTrait, value: string): boolean {
+    if (!owned.state) return writeBase(target, owned.trait, value);
+    writeState(target, owned.state, owned.trait, value);
+    return true;
+}
+
 const sameOwned = (a: OwnedTrait, b: OwnedTrait) => a.trait === b.trait && a.state === b.state;
 
 function writeEntries(target: ElementStyleTarget, style: ElementStyle, skip: OwnedTrait[] = []): string[] {

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;

package/src/design-core/public-api.ts

@@ -14,6 +14,7 @@ export * from './css-names';
 export * from './token-css';
 export * from './flavor';
 export * from './element-styles';
+export * from './adopt';
 export * from './node-classes';
 export * from './empty-image';
 export * from './brand';