@vectoriox/iox-ui 5.14.0 → 5.16.0

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

@@ -1,5 +1,6 @@
 import { DesignMode } from './design-token.model';
 import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
+import { specTokenNames } from './token-names';
 
 /**
  * Design-token → CSS compilation, shared by BOTH renderers (flavors F0, design-system DS1).
@@ -14,6 +15,11 @@ import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
  *   4. reduced transparency `@media (prefers-reduced-transparency: reduce)`
  *   5. dark — LAST     `@media (prefers-color-scheme: dark)`
  *
+ * MODE (design-system D6) is a compile choice, never a row change: `auto` is the visitor-following
+ * order above; `light` compiles the base from light values and emits no dark block; `dark` compiles
+ * the base from DARK values (schemes and placeholders resolved from them too) and emits no dark block —
+ * so a Midnight site is dark for a light-OS visitor.
+ *
  * ⚠️ The appended-last contract: the dark block REDEFINES custom properties, so every consumer
  * appends it AFTER all of its base rules — the engine pushes it after the page's css blocks, the
  * builder registry keeps it as its last token rule (responsive A3 lesson).
@@ -32,6 +38,16 @@ export interface DesignTokenLike {
 export interface TokenCssOptions {
     /** Selector that carries the variables instead of `:root` — a preview wrapper, a specimen. */
     scope?: string;
+    /** The studio's colour mode (`settings.design.mode`). Absent = `auto`. */
+    mode?: DesignMode;
+    /**
+     * Declare every SPEC token the rows lack as `initial` on the scope (the guaranteed-invalid value),
+     * so a `var()` inside the scope cannot inherit a same-named property from an ANCESTOR. The builder
+     * needs it: the admin's `:root` chrome tokens share names with org tokens (`accent`, `surface-2`…),
+     * and a missing org row would silently paint the canvas in admin chrome. With it, the canvas
+     * computes exactly what the live site computes for that row — unset.
+     */
+    isolate?: boolean;
 }
 
 export interface TokenCssBlocks {
@@ -114,6 +130,16 @@ const DARK: ResolvedMode = 'dark';
 
 const modeValue = (t: DesignTokenLike, mode: ResolvedMode): string => (mode === DARK ? darkOf(t) ?? t.value : t.value);
 
+/** The rows as ONE mode: each row's value in that mode, no dark override left. `auto` (or none) →
+ *  the rows unchanged. */
+function rowsForMode(rows: ReadonlyArray<DesignTokenLike>, mode: DesignMode | undefined): DesignTokenLike[] {
+    if (mode !== LIGHT && mode !== DARK) return [...rows];
+    return rows.map(t => {
+        const { values: _dropped, ...rest } = t;
+        return { ...rest, value: modeValue(t, mode) };
+    });
+}
+
 /** 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(
@@ -223,10 +249,14 @@ export function compileTokenCssBlocks(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
     opts: TokenCssOptions = {},
 ): TokenCssBlocks {
-    const rows = usableTokens(tokens);
+    const rows = rowsForMode(usableTokens(tokens), opts.mode);
     const root = opts.scope ?? ROOT;
+    const present = new Set(rows.map(t => t.name));
+    const unset: Array<[string, string]> = opts.isolate
+        ? [...specTokenNames()].filter(name => !present.has(name)).map((name): [string, string] => [name, 'initial'])
+        : [];
     const base = [
-        rule(root, rows.map((t): [string, string] => [t.name, t.value])),
+        rule(root, [...unset, ...rows.map((t): [string, string] => [t.name, t.value])]),
         compileSchemeCss(rows, opts.scope),
         ...ACCESSIBILITY_MEDIA.map(({ query, overrides }) =>
             media(query, [rule(root, presentOverrides(rows, overrides, false), '  ')])),

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

@@ -30,3 +30,24 @@ export function unknownTokenReferences(css: string, alsoAllowed: Iterable<string
     const extra = new Set(alsoAllowed);
     return tokenReferences(css).filter(name => !spec.has(name) && !extra.has(name));
 }
+
+const LEGACY_SCOPE = /:not\(\s*\.iox-es\s*\)/;
+const RULE = /([^{}]+)\{([^{}]*)\}/g;
+
+/**
+ * Tokens read by a LEGACY rule — any rule whose selector is scoped `:not(.iox-es)` (the pre-DS2 look
+ * of a node that wears no element style, design-system §3b-bis). Such a rule must read NO token at
+ * all: a token it reads repaints a pre-DS2 page the moment the org's rows are seeded or a flavor is
+ * applied (D5). Returns `selector → names` for each offending rule; comments are ignored.
+ */
+export function legacyRuleTokenReferences(css: string): Array<{ selector: string; tokens: string[] }> {
+    const text = String(css ?? '').replace(/\/\*[\s\S]*?\*\//g, '');
+    const out: Array<{ selector: string; tokens: string[] }> = [];
+    for (const m of text.matchAll(RULE)) {
+        const selector = m[1].trim().replace(/\s+/g, ' ');
+        if (!LEGACY_SCOPE.test(selector)) continue;
+        const tokens = tokenReferences(m[2]);
+        if (tokens.length) out.push({ selector, tokens });
+    }
+    return out;
+}