@vectoriox/iox-ui 5.10.0 → 5.11.0

package/src/design-core/flavor-tokens.ts

@@ -1,6 +1,6 @@
 import { deriveAccentTokens } from './brand';
 import { cssString } from './fonts';
-import { FLAVOR_SPEC } from './flavor-spec.generated';
+import { SPEC_AXES } from './flavor-spec.generated';
 import {
     DesignChoices, DesignTokenRow, FlavorPackV2, FlavorSpecToken, flavorSourceStamp, USER_TOKEN_SOURCE,
 } from './design-token.model';
@@ -70,7 +70,7 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
     const pair = pack.pairs.find(p => p.id === choices.pairId) ?? pack.pairs[0];
     for (const [name, value] of Object.entries(pair?.tokens ?? {})) set(name, value);
 
-    const axes = FLAVOR_SPEC.axes;
+    const axes = SPEC_AXES;
     for (const [name, value] of [
         ...axisValues(axes.shapes, choices.shape),
         ...axisValues(axes.densities, choices.density),
@@ -86,7 +86,11 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
 
     if (choices.seed && choices.seed.toLowerCase() !== pack.seed.toLowerCase()) {
         const bg = byName.get('bg');
-        for (const accent of deriveAccentTokens(choices.seed, { bg: bg?.value ?? '', bgDark: bg?.values?.dark })) {
+        const inverseBg = byName.get('inverse-bg');
+        for (const accent of deriveAccentTokens(choices.seed, {
+            bg: bg?.value ?? '', bgDark: bg?.values?.dark,
+            inverseBg: inverseBg?.value, inverseBgDark: inverseBg?.values?.dark,
+        })) {
             const row = byName.get(accent.name);
             if (!row) continue;
             row.value = accent.value;

package/src/design-core/fonts.ts

@@ -1,4 +1,4 @@
-import { FLAVOR_SPEC } from './flavor-spec.generated';
+import { SPEC_FONTS } from './flavor-spec.generated';
 import { DesignTokenLike } from './token-css';
 
 /**
@@ -7,7 +7,7 @@ import { DesignTokenLike } from './token-css';
  */
 
 /** Family name → Google Fonts css2 `family=` id. Replaces the engine's private GOOGLE_FONTS map. */
-export const FONT_CATALOG: Readonly<Record<string, string>> = FLAVOR_SPEC.fonts;
+export const FONT_CATALOG: Readonly<Record<string, string>> = SPEC_FONTS;
 
 export type FontFormat = 'woff2' | 'woff' | 'truetype' | 'opentype';
 export type FontStyle = 'normal' | 'italic';
@@ -30,9 +30,19 @@ const MIN_WEIGHT = 100;
 const MAX_WEIGHT = 900;
 const FONT_FORMATS: ReadonlyArray<FontFormat> = ['woff2', 'woff', 'truetype', 'opentype'];
 
-/** A CSS string literal, single-quoted, with `\` and `'` escaped and line breaks dropped. */
+/**
+ * A CSS string literal, single-quoted: `\` and `'` escaped, line breaks and NUL dropped, and `<` /
+ * `>` hex-escaped (`\3c `) — the face CSS is inlined into a `<style>` by the SSR engine, where an
+ * uploaded family named `</style><script>` would otherwise close the element.
+ */
 export function cssString(value: string): string {
-    return `'${String(value).replace(/[\r\n\f]/g, '').replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+    const body = String(value)
+        .replace(/[\r\n\f\0]/g, '')
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/</g, '\\3c ')
+        .replace(/>/g, '\\3e ');
+    return `'${body}'`;
 }
 
 const clampWeight = (w: unknown): number => {

package/src/design-core/spring.ts

@@ -3,7 +3,8 @@
  * generator (`build-spec.mjs` `spring()`) uses to write `springs.lively`, so a spring computed at
  * runtime is byte-identical to the one in the contract.
  *
- * `stiffness` is k (ω₀ = √k), `damping` the ratio ζ (< 1 under-damped, ≥ 1 critically damped).
+ * `stiffness` is k (ω₀ = √k), `damping` the ratio ζ: < 1 under-damped, = 1 critically damped,
+ * > 1 over-damped. Both must be positive and finite — a zero or negative spring never settles.
  * Duration = the last instant the curve is more than 0.1% away from rest, rounded up to 10ms.
  */
 const SETTLE_TOLERANCE = 0.001;
@@ -13,20 +14,31 @@ const SAMPLES = 40;
 const DECIMALS = 4;
 const ROUND_TO_MS = 10;
 
+/** Displacement from rest → target (0 → 1) of a unit-mass spring released at rest. */
+function springPosition(w0: number, damping: number): (t: number) => number {
+    if (damping < 1) {
+        const wd = w0 * Math.sqrt(1 - damping * damping);
+        return t => 1 - Math.exp(-damping * w0 * t) * (Math.cos(wd * t) + ((damping * w0) / wd) * Math.sin(wd * t));
+    }
+    if (damping === 1) return t => 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+    // Over-damped: two real, negative roots. Written with exponentials of the roots, not cosh/sinh,
+    // which overflow for a stiff, heavily damped spring well inside the settle horizon.
+    const root = w0 * Math.sqrt(damping * damping - 1);
+    const r1 = -damping * w0 + root;
+    const r2 = -damping * w0 - root;
+    return t => 1 - (r2 * Math.exp(r1 * t) - r1 * Math.exp(r2 * t)) / (r2 - r1);
+}
+
 export interface LinearSpring {
     easing: string;
     duration: string;
 }
 
 export function springToLinear(stiffness: number, damping: number): LinearSpring {
-    const w0 = Math.sqrt(stiffness);
-    const x = (t: number): number => {
-        if (damping < 1) {
-            const wd = w0 * Math.sqrt(1 - damping * damping);
-            return 1 - Math.exp(-damping * w0 * t) * (Math.cos(wd * t) + ((damping * w0) / wd) * Math.sin(wd * t));
-        }
-        return 1 - Math.exp(-w0 * t) * (1 + w0 * t);
-    };
+    if (!(Number.isFinite(stiffness) && stiffness > 0) || !(Number.isFinite(damping) && damping > 0)) {
+        throw new RangeError(`springToLinear: stiffness and damping must be > 0 (got ${stiffness}, ${damping})`);
+    }
+    const x = springPosition(Math.sqrt(stiffness), damping);
     let settle = 0;
     for (let t = 0; t < SETTLE_HORIZON_S; t += SETTLE_STEP_S) if (Math.abs(1 - x(t)) > SETTLE_TOLERANCE) settle = t;
     const durationMs = Math.ceil((settle * 1000) / ROUND_TO_MS) * ROUND_TO_MS;

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

@@ -1,4 +1,4 @@
-import { FLAVOR_SPEC } from './flavor-spec.generated';
+import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
 
 /**
  * Design-token → CSS compilation, shared by BOTH renderers (flavors F0, design-system DS1).
@@ -40,24 +40,11 @@ export interface TokenCssBlocks {
     dark: string;
 }
 
-/** What `prefers-reduced-motion: reduce` collapses — movement and duration, never colour. */
-export const REDUCED_MOTION_OVERRIDES: Readonly<Record<string, string>> = {
-    'dur-fast': '0ms',
-    'dur-base': '0ms',
-    'dur-slow': '0ms',
-    'hover-lift': '0px',
-    'button-hover-x': '0px',
-    'button-hover-y': '0px',
-    'card-hover-x': '0px',
-    'card-lift': '0px',
-};
+/** What `prefers-reduced-motion: reduce` collapses — the contract's complete list (`a11y.reducedMotion`). */
+export const REDUCED_MOTION_OVERRIDES: Readonly<Record<string, string>> = SPEC_A11Y.reducedMotion;
 
-/** What `prefers-reduced-transparency: reduce` makes solid — every glass surface, in one block. */
-export const REDUCED_TRANSPARENCY_OVERRIDES: Readonly<Record<string, string>> = {
-    'surface-glass': 'var(--iox-surface)',
-    'surface-glass-strong': 'var(--iox-surface)',
-    'blur-surface': 'none',
-};
+/** What `prefers-reduced-transparency: reduce` makes solid — the contract's `a11y.reducedTransparency`. */
+export const REDUCED_TRANSPARENCY_OVERRIDES: Readonly<Record<string, string>> = SPEC_A11Y.reducedTransparency;
 
 const ROOT = ':root';
 const DEFAULT_SCHEME = 'default';
@@ -95,7 +82,7 @@ const schemeSelector = (id: string, scope?: string) =>
     scope ? `${scope} .iox-scheme-${id}` : `.iox-scheme-${id}`;
 
 const nonDefaultSchemes = (): ReadonlyArray<[string, Readonly<Record<string, string>>]> =>
-    Object.entries(FLAVOR_SPEC.schemes)
+    Object.entries(SPEC_SCHEMES)
         .filter(([id]) => id !== DEFAULT_SCHEME)
         .map(([id, scheme]) => [id, scheme.set as Readonly<Record<string, string>>]);
 
@@ -116,32 +103,95 @@ export function tokensToDarkVarMap(tokens: ReadonlyArray<DesignTokenLike> | null
     return map;
 }
 
+const TOKEN_REF = /var\(\s*--iox-([\w-]+)\s*(?:,([^()]*))?\)/g;
+const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g;
+
+type Mode = 'light' | 'dark';
+
+const modeValue = (t: DesignTokenLike, mode: Mode): 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',
+): Record<string, string> {
+    const raw = new Map(usableTokens(tokens).map(t => [t.name, modeValue(t, mode)]));
+    const out: Record<string, string> = {};
+    const resolve = (name: string, trail: ReadonlySet<string>): string | null => {
+        if (name in out) return out[name];
+        const value = raw.get(name);
+        if (value === undefined || trail.has(name)) return null;
+        const next = new Set(trail).add(name);
+        return value.replace(TOKEN_REF, (ref, inner: string, fallback?: string) =>
+            resolve(inner, next) ?? (fallback !== undefined ? fallback.trim() : ref));
+    };
+    for (const name of raw.keys()) {
+        const value = resolve(name, new Set());
+        if (value !== null) out[name] = value;
+    }
+    return out;
+}
+
+/** 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 {
+    let missing = false;
+    const value = template.replace(PLACEHOLDER, (_, name: string) => {
+        if (!(name in resolved)) missing = true;
+        return resolved[name] ?? '';
+    });
+    return missing ? null : value;
+}
+
+const schemeEntries = (set: Readonly<Record<string, string>>, resolved: Readonly<Record<string, string>>) =>
+    Object.entries(set)
+        .map(([name, template]): [string, string | null] => [name, substitute(template, resolved)])
+        .filter((e): e is [string, string] => e[1] !== null);
+
+const hasPlaceholder = (value: string) => value.includes('{{');
+
 /**
- * Section colour schemes (design-system plan §3c). ⚠️ Custom properties resolve where they are
- * DECLARED: `--iox-card-bg: var(--iox-surface)` declared on `:root` keeps `:root`'s surface
- * inside `.iox-scheme-inverse`. So each scheme block carries the spec's overrides PLUS every other
- * token whose value references a token, re-declared verbatim — re-resolving it in the section.
+ * Section colour schemes (design-system plan §3c). Two rules, both about WHERE a custom property
+ * resolves:
+ *
+ * - ⚠️ Custom properties resolve where they are DECLARED: `--iox-card-bg: var(--iox-surface)`
+ *   declared on `:root` keeps `:root`'s surface inside `.iox-scheme-inverse`. So each scheme block
+ *   carries the spec's overrides PLUS every other token whose value references a token,
+ *   re-declared verbatim — re-resolving it in the section.
+ * - ⚠️ A scheme that SWAPS two tokens (Brand: accent ⇄ accent-ink) cannot write them as `var()`:
+ *   on one element `accent: var(--iox-accent-ink)` + `accent-ink: var(--iox-accent)` is a cycle,
+ *   and CSS makes both invalid. The contract writes `{{accent}}` instead — the token's ROOT value,
+ *   resolved here at compile time (and again from dark values for the dark twin).
  */
 export function compileSchemeCss(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, scope?: string): string {
     const rows = usableTokens(tokens);
     if (!rows.length) return '';
+    const resolved = resolveTokenValues(rows, 'light');
     return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
-        ...Object.entries(set),
+        ...schemeEntries(set, resolved),
         ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
             .map((t): [string, string] => [t.name, t.value]),
     ])).filter(Boolean).join('\n');
 }
 
-/** The dark twin of the re-declaration rule: a re-declared token with a dark value would
- *  otherwise pin the LIGHT value inside the section once the visitor is in dark mode. */
+/** 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 redeclared = rows.filter(t => {
-        const dark = darkOf(t);
-        return dark !== null && (t.value.includes(REFERENCE) || dark.includes(REFERENCE));
+        const d = darkOf(t);
+        return d !== null && (t.value.includes(REFERENCE) || d.includes(REFERENCE));
+    });
+    return nonDefaultSchemes().map(([id, set]) => {
+        const swapped = Object.fromEntries(Object.entries(set).filter(([, v]) => hasPlaceholder(v)));
+        const lightSwap = new Map(schemeEntries(swapped, light));
+        return rule(schemeSelector(id, scope), [
+            ...schemeEntries(swapped, dark).filter(([name, value]) => lightSwap.get(name) !== value),
+            ...redeclared.filter(t => !(t.name in set)).map((t): [string, string] => [t.name, darkOf(t) as string]),
+        ], '  ');
     });
-    return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), redeclared
-        .filter(t => !(t.name in set))
-        .map((t): [string, string] => [t.name, darkOf(t) as string]), '  '));
 }
 
 function presentOverrides(rows: ReadonlyArray<DesignTokenLike>, overrides: Readonly<Record<string, string>>,