@vectoriox/iox-ui 5.21.0 → 5.23.0

package/design-core/index.d.ts

@@ -8390,6 +8390,14 @@ interface SwitchElementStyleResult {
     /** Traits the old style owned whose value the author had changed — kept, never overwritten. */
     kept: OwnedTrait[];
 }
+/** Every trait the style owns with the value it writes — base first, then hover/active/focus. */
+declare function ownedTraitsOf(style: ElementStyle): Array<OwnedTrait & {
+    value: string;
+}>;
+/** The node's value of one owned trait (a base trait, or a trait inside a pseudo-state map). */
+declare function readOwnedTrait(target: ElementStyleTarget, owned: OwnedTrait): unknown;
+/** Write one owned trait. False when a builder node has no slot for a base trait (dropped). */
+declare function writeOwnedTrait(target: ElementStyleTarget, owned: OwnedTrait, value: string): boolean;
 /** Write the style's exact base map and its hover/active/focus maps into the target. */
 declare function applyElementStyle(target: ElementStyleTarget, id: string): ApplyElementStyleResult;
 /**
@@ -8427,6 +8435,125 @@ declare function elementStyleClass(id: string | null | undefined): string | null
  */
 declare function applyHeadingLevelRule(target: ElementStyleTarget, oldLevel: string | null | undefined, newLevel: string | null | undefined, baseline?: Readonly<Record<string, unknown>>): SwitchElementStyleResult | null;
 
+/**
+ * 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.
+ */
+declare const NEW_NODE_STYLE_DEFAULTS: Readonly<Record<string, string>>;
+/**
+ * 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.
+ */
+declare const PRE_DS2_FLAVOR_DEFAULTS: Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** One owned trait whose value an element style CHANGED in the contract's history. */
+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.
+ */
+declare const SUPERSEDED_STYLE_VALUES: ReadonlyArray<SupersededStyleValue>;
+declare 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"
+}
+declare 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"
+}
+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. */
+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. */
+interface KeptEdit extends OwnedTrait {
+    value: unknown;
+}
+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[];
+}
+interface SkippedNode {
+    id?: string;
+    type: string;
+    reason: AdoptSkipReason;
+}
+interface AdoptReport {
+    adopted: AdoptedNode[];
+    skipped: SkippedNode[];
+    /** Author edits kept across every adopted node. */
+    kept: number;
+}
+/** 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. */
+declare function adoptionStyleFor(node: AdoptableNode): string | 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.
+ */
+declare function adoptElementStyles(tree: AdoptableNode[] | null | undefined, ctx: AdoptContext): AdoptReport;
+/** What adopting `tree` WOULD do, without touching it (the banner's count). */
+declare function previewElementStyleAdoption(tree: AdoptableNode[] | null | undefined, ctx: AdoptContext): AdoptReport;
+
 /**
  * The design-system classes a node renders, in BOTH renderers (builder canvas, engine component
  * path, engine string path) — ONE helper, so the three can never disagree about which class a node
@@ -8631,7 +8758,12 @@ interface FlavorRevertSnapshot {
         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. */
+type FlavorRevertWrite = Pick<DesignTokenRow, 'name' | 'value' | 'values'>;
 interface FlavorRevertPlan {
     create: DesignTokenRow[];
     update: Array<{
@@ -8640,17 +8772,25 @@ interface FlavorRevertPlan {
     }>;
     /** 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[];
 }
 declare const REVERT_WINDOW_MS: number;
 /** Board F7's footer promise, as a boundary: available through the 7th day, not beyond. */
 declare function revertAvailable(appliedAt: number | null | undefined, now: number): boolean;
 /**
- * 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.
  */
-declare function planFlavorRevert(current: ReadonlyArray<StoredDesignTokenRow>, snapshot: FlavorRevertSnapshot['tokens']): FlavorRevertPlan;
+declare function planFlavorRevert(current: ReadonlyArray<StoredDesignTokenRow>, snapshot: FlavorRevertSnapshot['tokens'], wrote?: ReadonlyArray<FlavorRevertWrite> | null): FlavorRevertPlan;
+/** What a seed plan leaves in each row it writes, by name — the snapshot's `wrote`. */
+declare function flavorSeedWrites(plan: FlavorSeedPlan, existing: ReadonlyArray<StoredDesignTokenRow>): FlavorRevertWrite[];
 /** What a previous seed wrote for one row — the "untouched" comparison base. */
 interface SeedExpectation {
     value: string;
@@ -8990,6 +9130,14 @@ declare function designTokenRows(choices: DesignChoices): DesignTokenRow[];
 declare function designBaseline(previous: StoredDesign): SeedBaseline;
 /** Apply `next` over the org's rows, judged against `previous` — the plan FlavorApplyService runs. */
 declare function planDesignApply(existing: ReadonlyArray<StoredDesignTokenRow>, previous: StoredDesign, next: DesignChoices): FlavorSeedPlan;
+/**
+ * "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.
+ */
+declare function planDesignRevert(current: ReadonlyArray<StoredDesignTokenRow>, design: StoredDesign): FlavorRevertPlan | null;
 /** The rows a design is missing by name — the builder-load top-up (never touches an existing row). */
 declare function missingDesignRows(existing: ReadonlyArray<{
     name: string;
@@ -9045,5 +9193,5 @@ interface FontFamilyRemoval {
  */
 declare function planFontFamilyRemoval(existing: ReadonlyArray<StoredDesignTokenRow>, previous: StoredDesign, family: string): FontFamilyRemoval;
 
-export { ACCENT_TOKEN_NAMES, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, FontUploadError, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, MAX_FONT_FILE_BYTES, OwnedTraitLink, PALETTE_PRESETS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, checkFontWeight, choicesForPack, colorSchemeClass, colorSchemeOf, compareFontWeights, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontStackWithout, fontWeightCovers, fontWeightRange, fontWeightValue, fontsForTokens, formatFontFamilies, formatFontFamily, formatFontWeight, googleFontHref, groupFontFamilies, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isFontWeightRange, isRetiredFlavorId, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, missingFontRoles, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, normalizeFontWeightValue, oklabToRgb, ownedTraitStatus, packDesignChoices, parseFontFamilies, parseFontWeight, parseHexColor, planDesignApply, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, previewFontWeight, readDesignConfig, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio };
-export type { AccentBackgrounds, AccentTokenName, ApplyElementStyleResult, DensityId, DesignChoices, DesignClassSource, DesignConfigEntry, DesignMode, DesignTokenGroup, DesignTokenLike, DesignTokenRow, DesignTokenTier, DesignTokenType, ElementStyle, ElementStyleTarget, ElementStyleTraitLike, FlavorPack, FlavorPackV2, FlavorRevertPlan, FlavorRevertSnapshot, FlavorSeedPlan, FlavorSpecToken, FlavorTokenDef, FontDescriptor, FontFamilyGroup, FontFamilyRemoval, FontFamilyToken, FontFormat, FontPair, FontRoleToken, FontStyle, FontWeight, FontWeightRange, FontsForTokensOptions, LinearSpring, MissingFontRole, MotionId, OkLab, OwnedTrait, OwnedTraitStatus, PalettePreset, ResolvedMode, Rgb, SchemeId, SeedBaseline, SeedExpectation, ShapeId, StoredDesign, StoredDesignTokenRow, SwissMigration, SwitchElementStyleResult, TokenCssBlocks, TokenCssOptions };
+export { ACCENT_TOKEN_NAMES, AdoptOutcome, AdoptSkipReason, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, FontUploadError, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, MAX_FONT_FILE_BYTES, NEW_NODE_STYLE_DEFAULTS, OwnedTraitLink, PALETTE_PRESETS, PRE_DS2_FLAVOR_DEFAULTS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SUPERSEDED_STYLE_VALUES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, adoptElementStyles, adoptionStyleFor, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, checkFontWeight, choicesForPack, colorSchemeClass, colorSchemeOf, compareFontWeights, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSeedWrites, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontStackWithout, fontWeightCovers, fontWeightRange, fontWeightValue, fontsForTokens, formatFontFamilies, formatFontFamily, formatFontWeight, googleFontHref, groupFontFamilies, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isFontWeightRange, isRetiredFlavorId, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, missingFontRoles, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, normalizeFontWeightValue, oklabToRgb, ownedTraitStatus, ownedTraitsOf, packDesignChoices, parseFontFamilies, parseFontWeight, parseHexColor, planDesignApply, planDesignRevert, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, previewElementStyleAdoption, previewFontWeight, readDesignConfig, readOwnedTrait, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio, writeOwnedTrait };
+export type { AccentBackgrounds, AccentTokenName, AdoptContext, AdoptReport, AdoptableNode, AdoptedNode, ApplyElementStyleResult, DensityId, DesignChoices, DesignClassSource, DesignConfigEntry, DesignMode, DesignTokenGroup, DesignTokenLike, DesignTokenRow, DesignTokenTier, DesignTokenType, ElementStyle, ElementStyleTarget, ElementStyleTraitLike, FlavorPack, FlavorPackV2, FlavorRevertPlan, FlavorRevertSnapshot, FlavorRevertWrite, FlavorSeedPlan, FlavorSpecToken, FlavorTokenDef, FontDescriptor, FontFamilyGroup, FontFamilyRemoval, FontFamilyToken, FontFormat, FontPair, FontRoleToken, FontStyle, FontWeight, FontWeightRange, FontsForTokensOptions, KeptEdit, LinearSpring, MissingFontRole, MotionId, OkLab, OwnedTrait, OwnedTraitStatus, PalettePreset, ResolvedMode, Rgb, SchemeId, SeedBaseline, SeedExpectation, ShapeId, SkippedNode, StoredDesign, StoredDesignTokenRow, SupersededStyleValue, SwissMigration, SwitchElementStyleResult, TokenCssBlocks, TokenCssOptions };

package/fesm2022/vectoriox-iox-ui-design-core.mjs

@@ -9914,6 +9914,21 @@ function ownedEntries(style) {
     }
     return out;
 }
+/** Every trait the style owns with the value it writes — base first, then hover/active/focus. */
+function ownedTraitsOf(style) {
+    return ownedEntries(style);
+}
+/** The node's value of one owned trait (a base trait, or a trait inside a pseudo-state map). */
+function readOwnedTrait(target, owned) {
+    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). */
+function writeOwnedTrait(target, owned, value) {
+    if (!owned.state)
+        return writeBase(target, owned.trait, value);
+    writeState(target, owned.state, owned.trait, value);
+    return true;
+}
 const sameOwned = (a, b) => a.trait === b.trait && a.state === b.state;
 function writeEntries(target, style, skip = []) {
     const unknown = [];
@@ -10043,6 +10058,202 @@ function applyHeadingLevelRule(target, oldLevel, newLevel, baseline = {}) {
     return switchElementStyle(target, from, to, baseline);
 }
 
+/**
+ * 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.
+ */
+const NEW_NODE_STYLE_DEFAULTS = { 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.
+ */
+const PRE_DS2_FLAVOR_DEFAULTS = {
+    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)' },
+};
+/**
+ * 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.
+ */
+const SUPERSEDED_STYLE_VALUES = [
+    { 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' },
+];
+var AdoptOutcome;
+(function (AdoptOutcome) {
+    /** The node wore no style; it now wears its type's default (or its legacy Button variant's). */
+    AdoptOutcome["Linked"] = "linked";
+    /** The node wore a style; values that style wrote in an older contract were brought current. */
+    AdoptOutcome["Upgraded"] = "upgraded";
+})(AdoptOutcome || (AdoptOutcome = {}));
+var AdoptSkipReason;
+(function (AdoptSkipReason) {
+    /** The type is born wearing no style (Gallery, SliderContainer, Spacer, …). */
+    AdoptSkipReason["NoStyle"] = "no-style";
+    /** The node takes its look from a style preset — the author's own class. */
+    AdoptSkipReason["Preset"] = "preset";
+    /** The node is (inside) a linked symbol instance: its look is the symbol's, shared across pages. */
+    AdoptSkipReason["Symbol"] = "symbol";
+})(AdoptSkipReason || (AdoptSkipReason = {}));
+const sameValue$1 = (a, b) => a === b || (a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b));
+function propOf(node, name) {
+    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. */
+function adoptionStyleFor(node) {
+    if (node.type === 'Button') {
+        const byVariant = BUTTON_VARIANT_TO_STYLE[String(propOf(node, 'variant') ?? '')];
+        if (byVariant)
+            return byVariant;
+    }
+    const traits = { ...(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, trait) => trait in style.base;
+/** Release each new-node default the style does not own, where the node still holds its baseline. */
+function releaseNewNodeDefaults(node, style, baseline, written) {
+    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$1(current, value) || !sameValue$1(current, baseline[trait]))
+            continue;
+        if (writeOwnedTrait(node, ref, value))
+            written.push(ref);
+    }
+}
+function untouched(node, trait, value, baseline) {
+    return value === undefined || sameValue$1(value, baseline[trait]) || sameValue$1(value, PRE_DS2_FLAVOR_DEFAULTS[node.type]?.[trait]);
+}
+function link(node, style, baseline) {
+    const written = [];
+    const kept = [];
+    for (const { value, ...ref } of ownedTraitsOf(style)) {
+        const current = readOwnedTrait(node, ref);
+        if (sameValue$1(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, style, baseline) {
+    const written = [];
+    for (const old of SUPERSEDED_STYLE_VALUES) {
+        if (old.style !== style.id)
+            continue;
+        const ref = 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$1(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.
+ */
+function adoptElementStyles(tree, ctx) {
+    const report = { adopted: [], skipped: [], kept: 0 };
+    const visit = (nodes, inSymbol) => {
+        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, inSymbol, ctx, report) {
+    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). */
+function previewElementStyleAdoption(tree, ctx) {
+    return adoptElementStyles(JSON.parse(JSON.stringify(tree ?? [])), ctx);
+}
+
 /**
  * The design-system classes a node renders, in BOTH renderers (builder canvas, engine component
  * path, engine string path) — ONE helper, so the three can never disagree about which class a node
@@ -11058,17 +11269,28 @@ function revertAvailable(appliedAt, now) {
     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.
+ * 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.
  */
-function planFlavorRevert(current, snapshot) {
+function planFlavorRevert(current, snapshot, wrote) {
     const byName = new Map();
     for (const row of current ?? [])
         byName.set(row.name, row);
+    const written = new Map((wrote ?? []).map(w => [w.name, w]));
+    const editedAfter = (live) => {
+        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();
-    const plan = { create: [], update: [], remove: [] };
+    const plan = { create: [], update: [], remove: [], kept: [] };
     for (const snap of snapshot ?? []) {
         snapNames.add(snap.name);
         const live = byName.get(snap.name);
@@ -11079,18 +11301,39 @@ function planFlavorRevert(current, snapshot) {
         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))
+        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`. */
+function flavorSeedWrites(plan, existing) {
+    const byId = new Map((existing ?? []).filter(r => r._id).map(r => [r._id, r]));
+    const out = (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;
+}
 const expectationFor = (baseline, row) => !baseline ? undefined : typeof baseline === 'function' ? baseline(row) : baseline.get(row.name);
 const sameValue = (row, e) => row.value === e.value && (row.values?.dark ?? '') === (e.dark ?? '');
 /**
@@ -11409,6 +11652,19 @@ function planDesignApply(existing, previous, next) {
         return { create: [], update: [], kept: [] };
     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.
+ */
+function planDesignRevert(current, design) {
+    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). */
 function missingDesignRows(existing, choices) {
     const have = new Set((existing ?? []).map(r => r.name));
@@ -11523,5 +11779,5 @@ function planFontFamilyRemoval(existing, previous, family) {
  * Generated bundle index. Do not edit.
  */
 
-export { ACCENT_TOKEN_NAMES, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, FontUploadError, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, MAX_FONT_FILE_BYTES, OwnedTraitLink, PALETTE_PRESETS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, checkFontWeight, choicesForPack, colorSchemeClass, colorSchemeOf, compareFontWeights, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontStackWithout, fontWeightCovers, fontWeightRange, fontWeightValue, fontsForTokens, formatFontFamilies, formatFontFamily, formatFontWeight, googleFontHref, groupFontFamilies, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isFontWeightRange, isRetiredFlavorId, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, missingFontRoles, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, normalizeFontWeightValue, oklabToRgb, ownedTraitStatus, packDesignChoices, parseFontFamilies, parseFontWeight, parseHexColor, planDesignApply, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, previewFontWeight, readDesignConfig, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio };
+export { ACCENT_TOKEN_NAMES, AdoptOutcome, AdoptSkipReason, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, FontUploadError, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, MAX_FONT_FILE_BYTES, NEW_NODE_STYLE_DEFAULTS, OwnedTraitLink, PALETTE_PRESETS, PRE_DS2_FLAVOR_DEFAULTS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SUPERSEDED_STYLE_VALUES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, adoptElementStyles, adoptionStyleFor, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, checkFontWeight, choicesForPack, colorSchemeClass, colorSchemeOf, compareFontWeights, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSeedWrites, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontStackWithout, fontWeightCovers, fontWeightRange, fontWeightValue, fontsForTokens, formatFontFamilies, formatFontFamily, formatFontWeight, googleFontHref, groupFontFamilies, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isFontWeightRange, isRetiredFlavorId, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, missingFontRoles, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, normalizeFontWeightValue, oklabToRgb, ownedTraitStatus, ownedTraitsOf, packDesignChoices, parseFontFamilies, parseFontWeight, parseHexColor, planDesignApply, planDesignRevert, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, previewElementStyleAdoption, previewFontWeight, readDesignConfig, readOwnedTrait, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio, writeOwnedTrait };
 //# sourceMappingURL=vectoriox-iox-ui-design-core.mjs.map