@vectoriox/iox-ui 5.10.0 → 5.12.0

package/package.json

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

package/src/design-core/brand.ts

@@ -226,13 +226,18 @@ export function deriveBrandTokens(seed: string, pack: Pick<FlavorPack, 'accentHu
 /** WCAG 2 AA for body text — the gate every quartet pair is held to. */
 export const WCAG_AA_TEXT = 4.5;
 
-export const ACCENT_TOKEN_NAMES = ['accent', 'accent-ink', 'accent-hover', 'accent-text'] as const;
+export const ACCENT_TOKEN_NAMES = [
+    'accent', 'accent-ink', 'accent-hover', 'accent-text', 'inverse-accent', 'inverse-accent-ink',
+] as const;
 export type AccentTokenName = (typeof ACCENT_TOKEN_NAMES)[number];
 
-/** The page backgrounds the accent must read on, light and (optionally) dark. */
+/** The backgrounds the accent must read on, light and (optionally) dark. Without an inverse
+ *  background the inverse pair is not derived — the pack's own stays. */
 export interface AccentBackgrounds {
     bg: string;
     bgDark?: string;
+    inverseBg?: string;
+    inverseBgDark?: string;
 }
 
 const RAMP_ORDER = RAMP_STEPS.map(s => s.step);
@@ -252,7 +257,13 @@ const bestInkHex = (bg: string) =>
  * - dark: the first of brand-300/200/400 an ink clears 4.5:1 on, the same hover rule, and
  *   `accent-text` = the first light step that clears 4.5:1 on `bgDark`
  *
- * Every pair (ink/accent, ink/hover, text/bg) is asserted ≥ 4.5:1 in `brand.spec.ts`.
+ * - `inverse-accent` = the first step from 500 toward the end that reads on `inverseBg` clearing
+ *   4.5:1 on it; `inverse-accent-ink` = the higher-contrast of `brandInk` and the OPPOSITE ramp end
+ *   (the spec's `brandSeed` rule). A step whose best ink still misses 4.5:1 is passed over, so the
+ *   pair is a guarantee rather than a hope. Dark: the same against `inverseBgDark`.
+ *
+ * Every pair (ink/accent, ink/hover, text/bg, inverse ink/inverse accent, inverse accent/inverse
+ * bg) is asserted ≥ 4.5:1 across packs and seeds in `flavor-tokens.spec.ts`.
  */
 export function deriveAccentTokens(
     seed: string,
@@ -289,6 +300,24 @@ export function deriveAccentTokens(
         };
     })() : null;
 
+    const inverseOn = (inverseBg: string) => {
+        const toward = wcagContrastRatio(step(RAMP_ORDER[0]), inverseBg) >= wcagContrastRatio(step(RAMP_ORDER[RAMP_ORDER.length - 1]), inverseBg)
+            ? -1 : 1;
+        const walk = RAMP_ORDER.filter(n => (toward < 0 ? n <= 500 : n >= 500));
+        if (toward < 0) walk.reverse();
+        const rampEnd = step(toward < 0 ? RAMP_ORDER[RAMP_ORDER.length - 1] : RAMP_ORDER[0]);
+        const inkOn = (fill: string) =>
+            (wcagContrastRatio(ink, fill) >= wcagContrastRatio(rampEnd, fill) ? ink : rampEnd);
+        for (const n of walk) {
+            const fill = step(n);
+            if (passesText(fill, inverseBg) && passesText(inkOn(fill), fill)) return { accent: fill, ink: inkOn(fill) };
+        }
+        const fill = step(walk[walk.length - 1]);
+        return { accent: fill, ink: passesText(inkOn(fill), fill) ? inkOn(fill) : bestInkHex(fill) };
+    };
+    const inverse = against.inverseBg ? inverseOn(against.inverseBg) : null;
+    const inverseDark = against.inverseBg && against.inverseBgDark ? inverseOn(against.inverseBgDark) : null;
+
     const row = (name: AccentTokenName, value: string, darkValue?: string): FlavorTokenDef => ({
         name, value, type: 'color', group: 'colour', tier: 'semantic',
         ...(darkValue ? { values: { dark: darkValue } } : {}),
@@ -298,5 +327,9 @@ export function deriveAccentTokens(
         row('accent-ink', light.ink, dark?.ink),
         row('accent-hover', light.hover, dark?.hover),
         row('accent-text', light.text, dark?.text),
+        ...(inverse ? [
+            row('inverse-accent', inverse.accent, inverseDark?.accent),
+            row('inverse-accent-ink', inverse.ink, inverseDark?.ink),
+        ] : []),
     ];
 }

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

@@ -1,15 +1,17 @@
-import { FLAVOR_SPEC } from './flavor-spec.generated';
+import {
+    FLAVOR_SPEC_VERSION, SPEC_AXES, SPEC_FLAVOR_PACKS, SPEC_FONT_ROLES, SPEC_SCHEMES, SPEC_TIER_IDS, SPEC_TOKEN_TYPES,
+} from './flavor-spec.generated';
 
 /**
  * The design-token vocabulary (design-system plan §3a/§3f). Every list here is READ from the
  * generated spec, so the contract has one source: iox-ai-guidance `flavor-spec.v1.json`.
  */
 
-export type DesignTokenType = (typeof FLAVOR_SPEC.tokenTypes)[number];
-export const DESIGN_TOKEN_TYPES: ReadonlyArray<DesignTokenType> = FLAVOR_SPEC.tokenTypes;
+export type DesignTokenType = (typeof SPEC_TOKEN_TYPES)[number];
+export const DESIGN_TOKEN_TYPES: ReadonlyArray<DesignTokenType> = SPEC_TOKEN_TYPES;
 
-export type DesignTokenTier = keyof typeof FLAVOR_SPEC.tiers;
-export const DESIGN_TOKEN_TIERS = Object.keys(FLAVOR_SPEC.tiers) as ReadonlyArray<DesignTokenTier>;
+export type DesignTokenTier = (typeof SPEC_TIER_IDS)[number];
+export const DESIGN_TOKEN_TIERS: ReadonlyArray<DesignTokenTier> = SPEC_TIER_IDS;
 
 /** The spec carries groups per row, not as a list — `design-token.model.spec` pins this list
  *  to exactly the set of groups the spec's rows use. */
@@ -35,12 +37,12 @@ export interface StoredDesignTokenRow extends DesignTokenRow {
     _id?: string;
 }
 
-export type ShapeId = keyof typeof FLAVOR_SPEC.axes.shapes;
-export type DensityId = keyof typeof FLAVOR_SPEC.axes.densities;
-export type MotionId = keyof typeof FLAVOR_SPEC.axes.motions;
-export type DesignMode = (typeof FLAVOR_SPEC.axes.modes)[number];
-export type SchemeId = keyof typeof FLAVOR_SPEC.schemes;
-export type FontRoleToken = (typeof FLAVOR_SPEC.fontRoles)[number]['token'];
+export type ShapeId = keyof typeof SPEC_AXES.shapes;
+export type DensityId = keyof typeof SPEC_AXES.densities;
+export type MotionId = keyof typeof SPEC_AXES.motions;
+export type DesignMode = (typeof SPEC_AXES.modes)[number];
+export type SchemeId = keyof typeof SPEC_SCHEMES;
+export type FontRoleToken = (typeof SPEC_FONT_ROLES)[number]['token'];
 
 /** Everything a studio chose about its look — the `settings.design` row, typed. */
 export interface DesignChoices {
@@ -97,9 +99,7 @@ export interface FlavorPackV2 {
 
 /** The spec's flavors, typed. Assignment here is the compile-time proof that the generated
  *  data fits `FlavorPackV2`. */
-export const SPEC_FLAVORS: ReadonlyArray<FlavorPackV2> = FLAVOR_SPEC.flavors;
-
-export const FLAVOR_SPEC_VERSION: number = FLAVOR_SPEC.version;
+export const SPEC_FLAVORS: ReadonlyArray<FlavorPackV2> = SPEC_FLAVOR_PACKS;
 
 /** The stamp seeded rows carry, so an upgrade can tell the machine's rows from the author's. */
 export function flavorSourceStamp(flavorId: string, version: number = FLAVOR_SPEC_VERSION): string {

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 };
+}