@vectoriox/iox-ui 5.20.0 → 5.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.20.0",
+  "version": "5.22.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/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/fonts.ts

@@ -422,6 +422,13 @@ export interface FontsForTokensOptions {
      * would otherwise download a monospace face for a site with no code on it.
      */
     usedCss?: string;
+    /**
+     * The families the org UPLOADED. An uploaded family renders from the org's own files, so it is
+     * never fetched from Google — even when the catalog has a family of that name (an org that uploads
+     * Inter's variable file means THAT Inter: linking Google's too put its static cuts beside the
+     * upload, and the browser picked Google's — DS5.1).
+     */
+    uploaded?: ReadonlyArray<string>;
 }
 
 /**
@@ -437,14 +444,21 @@ export function fontsForTokens(
     const monoRead = MONO_REFERENCE.test(opts.usedCss ?? '')
         || rows.some(t => t.name !== MONO_ROLE && MONO_REFERENCE.test(`${t.value ?? ''} ${t.values?.dark ?? ''}`));
     const roles = monoRead ? FONT_FAMILY_TOKENS : ALWAYS_LOADED_ROLES;
+    const uploaded = new Set((opts.uploaded ?? []).map(fontFamilyKey));
     const seen = new Set<string>();
     const ids: string[] = [];
     for (const role of roles) {
         const row = rows.find(t => t.name === role);
-        // The role's FIRST catalog family is the one that renders (or stands in for an uploaded
-        // family that is missing — `userFontStack` puts the look's font right after the author's);
-        // a catalog family further down is never reached, so it is never loaded.
-        const id = parseFontFamilies(row?.value ?? '').map(catalogFontId).find((x): x is string => !!x);
+        // The role's FIRST family that renders decides: an uploaded one needs nothing from Google; the
+        // first catalog one is linked (it renders, or stands in for an uploaded family that is missing
+        // — `userFontStack` puts the look's font right after the author's). Nothing further down is
+        // ever reached, so nothing further down is loaded.
+        let id: string | null = null;
+        for (const family of parseFontFamilies(row?.value ?? '')) {
+            if (uploaded.has(fontFamilyKey(family))) break;
+            id = catalogFontId(family);
+            if (id) break;
+        }
         if (id && !seen.has(id)) {
             seen.add(id);
             ids.push(id);

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';