@vectoriox/iox-ui 5.11.0 → 5.12.0

package/index.d.ts

@@ -374,12 +374,21 @@ declare class SectionComponent {
     static ɵcmp: i0.ɵɵComponentDeclaration<SectionComponent, "section[iox-section]", never, { "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
 }
 
-/** Directive-host container: the `<div>` IS the host — no wrapper, no inner/outer split. */
+/**
+ * The tags a Container may render as (its `htmlTag` trait) — the builder canvas's list. The engine's
+ * string renderer and component path both pick from THIS list, so a Navigation bar is a `<nav>` on
+ * the live site exactly as on the canvas.
+ */
+declare const CONTAINER_HTML_TAGS: ReadonlyArray<string>;
+/** `htmlTag` when it is an allowed Container tag, else `div`. */
+declare function containerHtmlTag(htmlTag: unknown): string;
+/** Directive-host container: the host element IS the container — no wrapper, no inner/outer split.
+ *  Variable tag: the engine creates it on an explicit `hostElement` of `containerHtmlTag(htmlTag)`. */
 declare class ContainerComponent {
     nodeId: string;
     childrenHost: ViewContainerRef;
     static ɵfac: i0.ɵɵFactoryDeclaration<ContainerComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ContainerComponent, "div[iox-container]", never, { "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ContainerComponent, "div[iox-container],section[iox-container],article[iox-container],header[iox-container],footer[iox-container],main[iox-container],nav[iox-container],ul[iox-container],ol[iox-container],li[iox-container]", never, { "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
 }
 
 /** Directive-host linked container: the `<a>` IS the host — no wrapper, no inner/outer split. */
@@ -1265,9 +1274,32 @@ declare class IoxFormErrorComponent {
     static ɵcmp: i0.ɵɵComponentDeclaration<IoxFormErrorComponent, "div[iox-form-error]", never, { "nodeId": { "alias": "nodeId"; "required": false; }; "message": { "alias": "message"; "required": false; }; }, {}, never, never, false, never>;
 }
 
+/**
+ * The Dialog's LIVE twin on the engine's component path (actions plan A1b; design-system DS2).
+ * Directive-host: the `<dialog>` IS the host, carrying exactly the markup the string renderer
+ * writes (`data-iox-dialog`, the opt-in backdrop-close / consent-role / placement attributes and
+ * the close X), so the runtime's dialog actions, the consent prompt and `styles.scss` treat both
+ * paths alike. Ships CLOSED — only the dialog actions open it. Before this existed, a page holding
+ * a Dialog fell back to the string renderer wholesale.
+ */
+declare class IoxDialogComponent {
+    nodeId: string;
+    placement: string;
+    closeOnBackdrop: boolean | string;
+    showCloseButton: boolean | string;
+    consentRole: boolean | string;
+    childrenHost: ViewContainerRef;
+    get backdropCloses(): boolean;
+    get closeButtonShown(): boolean;
+    get consentRoleOn(): boolean;
+    get placementAttr(): string | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<IoxDialogComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<IoxDialogComponent, "dialog[iox-dialog]", never, { "nodeId": { "alias": "nodeId"; "required": false; }; "placement": { "alias": "placement"; "required": false; }; "closeOnBackdrop": { "alias": "closeOnBackdrop"; "required": false; }; "showCloseButton": { "alias": "showCloseButton"; "required": false; }; "consentRole": { "alias": "consentRole"; "required": false; }; }, {}, never, never, false, never>;
+}
+
 declare class IoxBuilderComponentsModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<IoxBuilderComponentsModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<IoxBuilderComponentsModule, [typeof BuilderImageComponent, typeof BuilderSpacerComponent, typeof CardComponent, typeof BuilderDividerComponent, typeof BuilderIconComponent, typeof BuilderLinkComponent, typeof BuilderButtonComponent, typeof BuilderHeadingComponent, typeof TextBlockComponent, typeof SectionComponent, typeof ContainerComponent, typeof LinkedContainerComponent, typeof ClientRepeaterComponent, typeof ButtonBlockComponent, typeof ClientSliderContainerComponent, typeof ClientSliderSlideComponent, typeof ClientListComponent, typeof ClientListItemComponent, typeof ClientGalleryComponent, typeof IoxFormComponent, typeof IoxFieldComponent, typeof IoxSubmitButtonComponent, typeof IoxFormSuccessComponent, typeof IoxFormErrorComponent], [typeof i2.CommonModule], [typeof BuilderImageComponent, typeof BuilderSpacerComponent, typeof CardComponent, typeof BuilderDividerComponent, typeof BuilderIconComponent, typeof BuilderLinkComponent, typeof BuilderButtonComponent, typeof BuilderHeadingComponent, typeof TextBlockComponent, typeof SectionComponent, typeof ContainerComponent, typeof LinkedContainerComponent, typeof ClientRepeaterComponent, typeof ButtonBlockComponent, typeof ClientSliderContainerComponent, typeof ClientSliderSlideComponent, typeof ClientListComponent, typeof ClientListItemComponent, typeof ClientGalleryComponent, typeof IoxFormComponent, typeof IoxFieldComponent, typeof IoxSubmitButtonComponent, typeof IoxFormSuccessComponent, typeof IoxFormErrorComponent]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<IoxBuilderComponentsModule, [typeof BuilderImageComponent, typeof BuilderSpacerComponent, typeof CardComponent, typeof BuilderDividerComponent, typeof BuilderIconComponent, typeof BuilderLinkComponent, typeof BuilderButtonComponent, typeof BuilderHeadingComponent, typeof TextBlockComponent, typeof SectionComponent, typeof ContainerComponent, typeof LinkedContainerComponent, typeof ClientRepeaterComponent, typeof ButtonBlockComponent, typeof ClientSliderContainerComponent, typeof ClientSliderSlideComponent, typeof ClientListComponent, typeof ClientListItemComponent, typeof ClientGalleryComponent, typeof IoxFormComponent, typeof IoxFieldComponent, typeof IoxSubmitButtonComponent, typeof IoxFormSuccessComponent, typeof IoxFormErrorComponent, typeof IoxDialogComponent], [typeof i2.CommonModule], [typeof BuilderImageComponent, typeof BuilderSpacerComponent, typeof CardComponent, typeof BuilderDividerComponent, typeof BuilderIconComponent, typeof BuilderLinkComponent, typeof BuilderButtonComponent, typeof BuilderHeadingComponent, typeof TextBlockComponent, typeof SectionComponent, typeof ContainerComponent, typeof LinkedContainerComponent, typeof ClientRepeaterComponent, typeof ButtonBlockComponent, typeof ClientSliderContainerComponent, typeof ClientSliderSlideComponent, typeof ClientListComponent, typeof ClientListItemComponent, typeof ClientGalleryComponent, typeof IoxFormComponent, typeof IoxFieldComponent, typeof IoxSubmitButtonComponent, typeof IoxFormSuccessComponent, typeof IoxFormErrorComponent, typeof IoxDialogComponent]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<IoxBuilderComponentsModule>;
 }
 
@@ -1351,6 +1383,32 @@ declare enum DeclarationContext {
  *                       initial values are kept, because there they reset rather than no-op.
  */
 declare function compileDeclarations(props: Record<string, any>, importantProps?: ReadonlySet<string>, context?: DeclarationContext): string[];
+/**
+ * The state names whose rule compiles to a DIFFERENT pseudo-class than their own name. `focus`
+ * compiles to `:focus-visible` (design-system DS2): an element style's focus ring must appear for
+ * keyboard users, not stick to a button after a mouse click. Stored states keep the name `focus` —
+ * no migration — and a text field still matches, since browsers treat a focused text input as
+ * focus-visible. Shared by the builder canvas and both engine paths.
+ */
+declare const STATE_PSEUDO_CLASS: Readonly<Record<string, string>>;
+/** The pseudo-class a stored state compiles to (`focus` → `focus-visible`, everything else itself). */
+declare function statePseudoClass(state: string): string;
+/** The states driven by a pointer hovering something — each earns the default hover transition. */
+declare const HOVER_STATES: ReadonlyArray<string>;
+/** True when the node restyles on hover (its own, its parent's or a chosen trigger's). */
+declare function hasHoverState(stateStyles: Record<string, Record<string, any> | undefined> | null | undefined): boolean;
+/**
+ * The base-rule transition a hovering node gets when it declares none of its own, so a hover
+ * animates instead of snapping. Token-driven with today's literal as the fallback (T6), so an
+ * unseeded org renders `all 0.2s ease` byte-identically. ONE copy for the builder canvas, the style
+ * panel and the engine — it was hand-written in three places.
+ */
+declare const HOVER_DEFAULT_TRANSITION = "all var(--iox-dur-fast, 0.2s) var(--iox-ease-standard, ease)";
+/** True when the RAW style map already yields a transition (an explicit one, or the composed
+ *  transitionDuration/TimingFunction an element style writes). */
+declare function hasOwnTransition(styleProps: Record<string, any> | null | undefined): boolean;
+/** `styleProps` plus the default hover transition when the node hovers and sets none itself. */
+declare function withDefaultHoverTransition(styleProps: Record<string, any>, stateStyles: Record<string, Record<string, any> | undefined> | null | undefined): Record<string, any>;
 /**
  * Per-type default `width` that the builder applies from each component's config
  * (NOT persisted in styleProps — see render-parity.md "saved node is not
@@ -1391,6 +1449,11 @@ interface VirtualTraitGroup {
      *  (`::marker` styles are a nested map, not a single cancellable property). */
     readonly reset: string | null;
 }
+/** The whole-value backdrop trait (DS2). A plain key — it is copied, not stripped — but it feeds
+ *  the backdrop group's output, so a breakpoint layer that sets it must count as touching it. */
+declare const BACKDROP_WHOLE_KEY = "backdropFilter";
+/** The prefixed twin emitted beside every composed `backdropFilter` (Safari). */
+declare const BACKDROP_TWIN_KEY = "WebkitBackdropFilter";
 declare const VIRTUAL_TRAIT_GROUPS: readonly VirtualTraitGroup[];
 /** Every virtual trait key — derived from the groups so there is one list to maintain. */
 declare const VIRTUAL_TRAIT_KEYS: Set<string>;
@@ -2690,5 +2753,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, getByPath, getSeoValue, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, stripSuppressedProps, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
+export { AOSService, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, composeVirtualTraits, computeRelative, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, getByPath, getSeoValue, hasHoverState, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, statePseudoClass, stripSuppressedProps, variableAliases, variableItemsFrom, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
 export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };

package/package.json

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

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

@@ -0,0 +1,271 @@
+import {
+    SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_PALETTE_PRESETS,
+} from './flavor-spec.generated';
+
+/**
+ * Element styles — the author's "classes" (design-system plan §3b). A named look is an EXACT trait
+ * map written into a node; every value is a `var(--iox-…)` reference or a flavor-independent
+ * keyword, so a re-theme rewrites token rows and every node wearing the style follows. No renderer
+ * reads `elementStyle`: it records which look a node wears, for the panel row, Reset, adopt and AI.
+ *
+ * Works on two node shapes through one minimal interface, so the builder (a ComponentNode whose
+ * values live in `styleTraits[].traits[].default`) and the server-side composer (a plain serialized
+ * layout node with `styleProps`) share every function here.
+ */
+
+export enum ElementStyleState {
+    Hover = 'hover',
+    Active = 'active',
+    Focus = 'focus',
+}
+
+export const ELEMENT_STYLE_STATES: ReadonlyArray<ElementStyleState> =
+    [ElementStyleState.Hover, ElementStyleState.Active, ElementStyleState.Focus];
+
+export interface ElementStyle {
+    readonly id: string;
+    readonly label: string;
+    readonly group: string;
+    readonly appliesTo: ReadonlyArray<string>;
+    readonly base: Readonly<Record<string, string>>;
+    readonly hover?: Readonly<Record<string, string>>;
+    readonly active?: Readonly<Record<string, string>>;
+    readonly focus?: Readonly<Record<string, string>>;
+}
+
+export const ELEMENT_STYLES: ReadonlyArray<ElementStyle> = SPEC_ELEMENT_STYLES;
+
+/** Legacy `Button.variant` → the element style it maps to (adopt, DS7). */
+export const BUTTON_VARIANT_TO_STYLE: Readonly<Record<string, string>> = SPEC_BUTTON_VARIANT_TO_STYLE;
+
+export interface PalettePreset {
+    readonly label: string;
+    readonly type: string;
+    readonly elementStyle: string;
+    readonly traits?: Readonly<Record<string, string>>;
+    readonly styleProps: Readonly<Record<string, string>>;
+}
+
+/** Palette entries that are a Container wearing an element style (Card · Panel · Navigation bar). */
+export const PALETTE_PRESETS: ReadonlyArray<PalettePreset> = SPEC_PALETTE_PRESETS;
+
+const BY_ID = new Map(ELEMENT_STYLES.map(s => [s.id, s]));
+
+export function elementStyleById(id: string | null | undefined): ElementStyle | undefined {
+    return id ? BY_ID.get(id) : undefined;
+}
+
+/** The styles a node of `type` may wear — the Style panel's select. */
+export function elementStylesFor(type: string): ElementStyle[] {
+    return ELEMENT_STYLES.filter(s => s.appliesTo.includes(type));
+}
+
+/** The minimal shape both a builder node and a serialized layout node satisfy. */
+export interface ElementStyleTraitLike {
+    name: string;
+    default?: unknown;
+}
+
+export interface ElementStyleTarget {
+    type: string;
+    elementStyle?: string;
+    /** Builder shape: values live in `trait.default`. Wins when present. */
+    styleTraits?: ReadonlyArray<{ traits: ElementStyleTraitLike[] }>;
+    /** Serialized shape: a flat map. Created on first write when the target has no `styleTraits`. */
+    styleProps?: Record<string, unknown>;
+    stateStyles?: Partial<Record<string, Record<string, unknown>>>;
+}
+
+/** One trait an element style owns: a base trait, or a trait inside a pseudo-state. */
+export interface OwnedTrait {
+    trait: string;
+    state?: ElementStyleState;
+}
+
+export enum OwnedTraitLink {
+    /** The node still holds the style's value. */
+    Linked = 'linked',
+    /** The author replaced it on this node. */
+    Changed = 'changed',
+}
+
+export interface OwnedTraitStatus extends OwnedTrait {
+    expected: string;
+    actual: unknown;
+    status: OwnedTraitLink;
+}
+
+export interface ApplyElementStyleResult {
+    applied: boolean;
+    /** Base traits the target has no slot for — a builder node silently drops these, so a spec
+     *  asserts this list is empty for every style × every type it applies to. */
+    unknownTraits: string[];
+}
+
+export interface SwitchElementStyleResult {
+    applied: boolean;
+    /** Traits the old style owned whose value the author had changed — kept, never overwritten. */
+    kept: OwnedTrait[];
+}
+
+const usesTraits = (t: ElementStyleTarget): boolean => Array.isArray(t.styleTraits);
+
+function findTrait(target: ElementStyleTarget, name: string): ElementStyleTraitLike | undefined {
+    for (const group of target.styleTraits ?? []) {
+        const hit = group.traits.find(tr => tr.name === name);
+        if (hit) return hit;
+    }
+    return undefined;
+}
+
+function readBase(target: ElementStyleTarget, name: string): unknown {
+    return usesTraits(target) ? findTrait(target, name)?.default : target.styleProps?.[name];
+}
+
+/** False when a builder node has no such trait — the value would be dropped. */
+function writeBase(target: ElementStyleTarget, name: string, value: unknown): boolean {
+    if (usesTraits(target)) {
+        const trait = findTrait(target, name);
+        if (!trait) return false;
+        trait.default = value;
+        return true;
+    }
+    target.styleProps = target.styleProps ?? {};
+    if (value === undefined) delete target.styleProps[name];
+    else target.styleProps[name] = value;
+    return true;
+}
+
+function readState(target: ElementStyleTarget, state: ElementStyleState, name: string): unknown {
+    return target.stateStyles?.[state]?.[name];
+}
+
+function writeState(target: ElementStyleTarget, state: ElementStyleState, name: string, value: string): void {
+    target.stateStyles = target.stateStyles ?? {};
+    target.stateStyles[state] = { ...(target.stateStyles[state] ?? {}), [name]: value };
+}
+
+function deleteState(target: ElementStyleTarget, state: ElementStyleState, name: string): void {
+    const map = target.stateStyles?.[state];
+    if (!map) return;
+    const { [name]: _drop, ...rest } = map;
+    if (Object.keys(rest).length) target.stateStyles![state] = rest;
+    else delete target.stateStyles![state];
+}
+
+/** Every (state, trait, value) a style owns, base first. */
+function ownedEntries(style: ElementStyle): Array<OwnedTrait & { value: string }> {
+    const out: Array<OwnedTrait & { value: string }> = [];
+    for (const [trait, value] of Object.entries(style.base)) out.push({ trait, value });
+    for (const state of ELEMENT_STYLE_STATES) {
+        for (const [trait, value] of Object.entries(style[state] ?? {})) out.push({ trait, state, value });
+    }
+    return out;
+}
+
+const sameOwned = (a: OwnedTrait, b: OwnedTrait) => a.trait === b.trait && a.state === b.state;
+
+function writeEntries(target: ElementStyleTarget, style: ElementStyle, skip: OwnedTrait[] = []): string[] {
+    const unknown: string[] = [];
+    for (const entry of ownedEntries(style)) {
+        if (skip.some(s => sameOwned(s, entry))) continue;
+        if (entry.state) writeState(target, entry.state, entry.trait, entry.value);
+        else if (!writeBase(target, entry.trait, entry.value)) unknown.push(entry.trait);
+    }
+    target.elementStyle = style.id;
+    return unknown;
+}
+
+/** Write the style's exact base map and its hover/active/focus maps into the target. */
+export function applyElementStyle(target: ElementStyleTarget, id: string): ApplyElementStyleResult {
+    const style = elementStyleById(id);
+    if (!style) return { applied: false, unknownTraits: [] };
+    return { applied: true, unknownTraits: writeEntries(target, style) };
+}
+
+/** `Heading[level=h3..h6]` → { type: 'Heading', prop: 'level', values: ['h3','h4','h5','h6'] }. */
+interface DefaultRule {
+    type: string;
+    prop?: string;
+    values?: string[];
+    style: string;
+}
+
+const RULE_KEY = /^(\w+)(?:\[(\w+)=([^\]]+)\])?$/;
+const RANGE = /^([a-z]*)(\d+)\.\.\1(\d+)$/;
+
+function expandValues(raw: string): string[] {
+    const range = RANGE.exec(raw);
+    if (!range) return [raw];
+    const [, prefix, from, to] = range;
+    const out: string[] = [];
+    for (let n = Number(from); n <= Number(to); n++) out.push(`${prefix}${n}`);
+    return out;
+}
+
+const DEFAULT_RULES: ReadonlyArray<DefaultRule> = Object.entries(SPEC_DEFAULT_ELEMENT_STYLE).map(([key, style]) => {
+    const m = RULE_KEY.exec(key);
+    if (!m) throw new Error(`defaultElementStyle: unreadable key "${key}"`);
+    const [, type, prop, raw] = m;
+    return prop ? { type, prop, values: expandValues(raw), style } : { type, style };
+});
+
+/**
+ * The element style a NEW node of `type` is born wearing (the spec's `defaultElementStyle`), or null
+ * when the type has none. `traits` is the node's own trait values (props) — a Heading's default
+ * follows its `level`; a Heading with no level matches no rule.
+ */
+export function defaultElementStyleFor(type: string, traits: Readonly<Record<string, unknown>> = {}): string | null {
+    for (const rule of DEFAULT_RULES) {
+        if (rule.type !== type) continue;
+        if (!rule.prop) return rule.style;
+        if (rule.values!.includes(String(traits[rule.prop]))) return rule.style;
+    }
+    return null;
+}
+
+/** Per owned trait: does the node still hold the style's value (linked) or the author's (changed)? */
+export function ownedTraitStatus(target: ElementStyleTarget, id: string): OwnedTraitStatus[] {
+    const style = elementStyleById(id);
+    if (!style) return [];
+    return ownedEntries(style).map(({ trait, state, value }) => {
+        const actual = state ? readState(target, state, trait) : readBase(target, trait);
+        return {
+            trait, ...(state ? { state } : {}), expected: value, actual,
+            status: actual === value ? OwnedTraitLink.Linked : OwnedTraitLink.Changed,
+        };
+    });
+}
+
+/**
+ * Move a node from one style to another, rewriting ONLY what the old style owned:
+ * - an owned trait still holding the old style's value is released — a base trait goes back to
+ *   `baseline[trait]` (the type's unstyled value; deleted when the baseline has none), a state trait
+ *   is removed from its state map;
+ * - an owned trait the author changed is KEPT, and the new style does not overwrite it.
+ * Then the new style is written. Traits neither style owns are never touched.
+ */
+export function switchElementStyle(
+    target: ElementStyleTarget,
+    fromId: string | null | undefined,
+    toId: string,
+    baseline: Readonly<Record<string, unknown>> = {},
+): SwitchElementStyleResult {
+    const to = elementStyleById(toId);
+    if (!to) return { applied: false, kept: [] };
+    const kept: OwnedTrait[] = [];
+    const from = elementStyleById(fromId);
+    if (from) {
+        for (const status of ownedTraitStatus(target, from.id)) {
+            const ref: OwnedTrait = status.state ? { trait: status.trait, state: status.state } : { trait: status.trait };
+            if (status.status === OwnedTraitLink.Changed) {
+                if (status.actual !== undefined) kept.push(ref);
+                continue;
+            }
+            if (ref.state) deleteState(target, ref.state, ref.trait);
+            else writeBase(target, ref.trait, baseline[ref.trait]);
+        }
+    }
+    writeEntries(target, to, kept);
+    return { applied: true, kept };
+}

package/src/design-core/flavor.ts

@@ -1,18 +1,11 @@
-import { styleKeyToKebab } from './css-names';
 import { DesignTokenGroup, DesignTokenTier, DesignTokenType } from './design-token.model';
 
 /**
- * Flavors (flavors-and-theming-plan.md, F1): the design language a studio launches with,
- * expressed as data. THE invariant — a flavor never writes a literal into a node; it writes
- * tokens, and element defaults that REFERENCE tokens. To that end a pack's `defaults` map
- * holds TOKEN NAMES, not CSS values: the resolver builds `var(--iox-<name>, <packValue>)`,
- * so smuggling a literal in is impossible by construction, and the validator only has to
- * check that every referenced token exists.
- *
- * The fallback is the bootstrap: until F2 seeds the org's `designtokens` rows, no `--iox-*`
- * var is defined anywhere, and `var(--iox-radius-control, 4px)` must still paint identically
- * in the builder canvas and the SSR page. Once tokens ARE seeded (or re-themed), the var wins
- * over the fallback everywhere — which is exactly the §3 propagation story.
+ * Flavors v1 (flavors-and-theming-plan.md, F1–F2): a pack is its TOKENS plus the accent hue
+ * opinion the brand derivation reads. The per-type `defaults` map and its resolvers are gone
+ * (design-system plan §3e, DS2): a new element is born wearing an ELEMENT STYLE
+ * (`element-styles.ts`), which references tokens and is flavor-independent. Swiss survives only
+ * until DS4 migrates orgs to Crisp.
  */
 
 export interface FlavorTokenDef {
@@ -32,82 +25,24 @@ export interface FlavorPack {
     label: string;
     blurb: string;
     tokens: FlavorTokenDef[];
-    /** type → styleTrait → TOKEN NAME (never a CSS value — see the module header). */
-    defaults: Record<string, Record<string, string>>;
     /** F2: the accent's hue rotation (degrees in OKLab) from the brand seed — a pack opinion. */
     accentHueDeg?: number;
 }
 
-/** trait → `var(--iox-<token>, <packValue>)` for one node type. Unknown type → {}. */
-export function resolveFlavorDefaults(
-    type: string,
-    pack: FlavorPack | null | undefined,
-): Record<string, string> {
-    const map = pack?.defaults?.[type];
-    if (!map) return {};
-    const byName = new Map((pack!.tokens ?? []).map(t => [t.name, t.value]));
-    const out: Record<string, string> = {};
-    for (const [trait, tokenName] of Object.entries(map)) {
-        const fallback = byName.get(tokenName);
-        if (fallback === undefined) continue;   // validator fails the build; runtime stays safe
-        out[trait] = `var(--iox-${tokenName}, ${fallback})`;
-    }
-    return out;
-}
-
-/**
- * The ENGINE's half of the cascade: kebab `prop: var(…)` declarations for every pack default
- * the node's persisted styleProps does NOT set. Appended beside renderDefaultDeclarations —
- * same guard-on-undefined discipline, so a node saved post-F1 (var already serialised via the
- * builder's trait defaults) is untouched, and a legacy node picks the pack default up at
- * render time. Node styleProps always wins.
- */
-export function flavorDefaultDeclarations(
-    type: string,
-    styleProps: Record<string, any> | null | undefined,
-    pack: FlavorPack | null | undefined,
-): string[] {
-    const sp = styleProps ?? {};
-    const out: string[] = [];
-    for (const [trait, value] of Object.entries(resolveFlavorDefaults(type, pack))) {
-        if (sp[trait] === undefined) out.push(`${styleKeyToKebab(trait)}: ${value}`);
-    }
-    return out;
-}
-
-/**
- * The CI gate (flavors plan §10 C4): a pack may only name types and traits that exist in the
- * live component registry, and tokens it defines itself. Returns human-readable errors; a
- * consumer spec feeds it the REAL registry and asserts [].
- */
-export function validateFlavorPack(
-    pack: FlavorPack,
-    knownTraitsByType: Record<string, ReadonlySet<string> | string[]>,
-): string[] {
+/** A pack's own sanity: every token row names itself and carries a value. Returns errors. */
+export function validateFlavorPack(pack: FlavorPack): string[] {
     const errors: string[] = [];
-    const tokenNames = new Set((pack.tokens ?? []).map(t => t.name));
     for (const t of pack.tokens ?? []) {
         if (!t.name) errors.push(`${pack.id}: token with empty name`);
         if (!t.value) errors.push(`${pack.id}: token "${t.name}" has no value`);
     }
-    for (const [type, traits] of Object.entries(pack.defaults ?? {})) {
-        const known = knownTraitsByType[type];
-        if (!known) { errors.push(`${pack.id}: unknown component type "${type}"`); continue; }
-        const knownSet = known instanceof Set ? known : new Set(known);
-        for (const [trait, tokenName] of Object.entries(traits)) {
-            if (!knownSet.has(trait)) errors.push(`${pack.id}: "${type}" has no style trait "${trait}"`);
-            if (!tokenNames.has(tokenName)) errors.push(`${pack.id}: "${type}.${trait}" references undefined token "${tokenName}"`);
-            if (/[:(]|^#|\d/.test(tokenName)) errors.push(`${pack.id}: "${type}.${trait}" must name a token, not a value ("${tokenName}")`);
-        }
-    }
     return errors;
 }
 
 /**
- * Swiss — the default pack (flavors plan §8: "the flavor that can never embarrass anyone").
- * Deliberately SMALL at F1: radius + control padding on the clickables, surface radius on Card.
- * Colour, type and motion arrive with the brand step (F2) — a colour default here would repaint
- * legacy pages before anyone chose anything.
+ * Swiss — the F1 pack: four tokens (control/surface radius, control/stack spacing) and the hue
+ * opinion F2's brand step reads. Kept until DS4 migrates `flavorId: swiss` orgs to Crisp; its four
+ * rows are the spec's `legacyAliases`.
  */
 export const SWISS_FLAVOR: FlavorPack = {
     id: 'swiss',
@@ -120,18 +55,6 @@ export const SWISS_FLAVOR: FlavorPack = {
         { name: 'space-control', value: '10px 18px', type: 'spacing', group: 'space' },
         { name: 'space-stack', value: '12px', type: 'spacing', group: 'space' },
     ],
-    defaults: {
-        Button: { borderRadius: 'radius-control', padding: 'space-control' },
-        ButtonBlock: { borderRadius: 'radius-control', padding: 'space-control' },
-        Card: { borderRadius: 'radius-surface' },
-    },
-    // F2: Swiss turns the seed toward a cool counterpoint. NOTE deliberately: the brand tokens
-    // deriveBrandTokens() emits are SEEDED per org — they do not join `defaults` here, because a
-    // colour default repaints legacy nodes whose saved styleProps lack the key (the engine fills
-    // missing keys from config defaults). Coloured element defaults are a Swiss v2 upgrade
-    // decision (§10 C2), taken with the picker in front of the author — never a side effect.
+    // F2: Swiss turns the seed toward a cool counterpoint.
     accentHueDeg: 150,
 };
-
-/** What both renderers use until F2 lets an org choose. */
-export const DEFAULT_FLAVOR: FlavorPack = SWISS_FLAVOR;

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

@@ -13,6 +13,7 @@ export * from './design-token.model';
 export * from './css-names';
 export * from './token-css';
 export * from './flavor';
+export * from './element-styles';
 export * from './brand';
 export * from './flavor-tokens';
 export * from './flavor-seed';

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

@@ -1,3 +1,4 @@
+import { DesignMode } from './design-token.model';
 import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
 
 /**
@@ -106,15 +107,18 @@ export function tokensToDarkVarMap(tokens: ReadonlyArray<DesignTokenLike> | null
 const TOKEN_REF = /var\(\s*--iox-([\w-]+)\s*(?:,([^()]*))?\)/g;
 const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g;
 
-type Mode = 'light' | 'dark';
+/** A compiled colour mode — the contract's modes minus `auto`, which is a compile CHOICE, not values. */
+export type ResolvedMode = Exclude<DesignMode, 'auto'>;
+const LIGHT: ResolvedMode = 'light';
+const DARK: ResolvedMode = 'dark';
 
-const modeValue = (t: DesignTokenLike, mode: Mode): string => (mode === 'dark' ? darkOf(t) ?? t.value : t.value);
+const modeValue = (t: DesignTokenLike, mode: ResolvedMode): string => (mode === DARK ? darkOf(t) ?? t.value : t.value);
 
 /** Every token's ROOT value in one mode, with `var(--iox-…)` references resolved against the same
  *  set (recursively; a reference cycle or an unknown token is left as written). */
 export function resolveTokenValues(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
-    mode: Mode = 'light',
+    mode: ResolvedMode = LIGHT,
 ): Record<string, string> {
     const raw = new Map(usableTokens(tokens).map(t => [t.name, modeValue(t, mode)]));
     const out: Record<string, string> = {};
@@ -133,6 +137,21 @@ export function resolveTokenValues(
     return out;
 }
 
+/**
+ * `value` with every `var(--iox-…)` replaced by that token's resolved root value in `mode` — what
+ * the Style panel's Detach writes, so the node keeps exactly what it showed as a literal. An unknown
+ * token falls back to its declared fallback, else stays as written.
+ */
+export function resolveTokenReferences(
+    value: string,
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    mode: ResolvedMode = LIGHT,
+): string {
+    const resolved = resolveTokenValues(tokens, mode);
+    return value.replace(TOKEN_REF, (ref, name: string, fallback?: string) =>
+        resolved[name] ?? (fallback !== undefined ? fallback.trim() : ref));
+}
+
 /** A scheme value with its `{{token}}` placeholders replaced by resolved root values — or null
  *  when a placeholder names a token the set does not have (the declaration is then omitted). */
 function substitute(template: string, resolved: Readonly<Record<string, string>>): string | null {
@@ -167,7 +186,7 @@ const hasPlaceholder = (value: string) => value.includes('{{');
 export function compileSchemeCss(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, scope?: string): string {
     const rows = usableTokens(tokens);
     if (!rows.length) return '';
-    const resolved = resolveTokenValues(rows, 'light');
+    const resolved = resolveTokenValues(rows, LIGHT);
     return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
         ...schemeEntries(set, resolved),
         ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
@@ -178,8 +197,8 @@ export function compileSchemeCss(tokens: ReadonlyArray<DesignTokenLike> | null |
 /** The dark twin of both scheme rules: a re-declared token with a dark value would otherwise pin
  *  the LIGHT value inside the section, and a `{{token}}` swap was resolved from LIGHT values. */
 function darkSchemeRules(rows: ReadonlyArray<DesignTokenLike>, scope: string | undefined): string[] {
-    const light = resolveTokenValues(rows, 'light');
-    const dark = resolveTokenValues(rows, 'dark');
+    const light = resolveTokenValues(rows, LIGHT);
+    const dark = resolveTokenValues(rows, DARK);
     const redeclared = rows.filter(t => {
         const d = darkOf(t);
         return d !== null && (t.value.includes(REFERENCE) || d.includes(REFERENCE));