@wildo-ai/saas-frontend-lib 1.1.9 → 1.1.11

package/dist/esm/core/ui/design-token.utils.js

@@ -5,7 +5,7 @@
  * Types/schemas: import from @wildo-ai/presets-components-models
  * Utilities: import from this file via @wildo-ai/saas-frontend-lib
  */
-import { DesignTokenValueType, getDesignTokenValue, isDesignTokenLightDarkValueConfiguration, mergeDesignSystemConfiguration as mergeDesignSystemConfigurationShared, TypographyRole, FontAxis, GoogleVariableFont, DEFAULT_CHART_COLOR_PALETTE, } from '@wildo-ai/presets-components-models';
+import { DesignTokenValueType, getDesignTokenValue, isDesignTokenLightDarkValueConfiguration, mergeDesignSystemConfiguration as mergeDesignSystemConfigurationShared, TypographyRole, FontAxis, GoogleVariableFont, DEFAULT_CHART_COLOR_PALETTE, DesignSystemColorError, normalizeDesignSystemColor, } from '@wildo-ai/presets-components-models';
 import { UserTheme, describeCaughtError } from '@wildo-ai/saas-models';
 /*
  * The storage key is NOT declared here. It is shared with the document-head bootstrap
@@ -32,42 +32,29 @@ export const mergeDesignSystemConfiguration = mergeDesignSystemConfigurationShar
  */
 const enumToCssVar = (token) => `--${token}`;
 /**
- * Validate OKLCH color format
- * L: 0-1 (lightness), C: 0+ (chroma), H: 0-360 (hue)
- */
-function validateOklchValue(value) {
-    // Remove oklch() wrapper if present
-    const cleanValue = value.replace(/^oklch\(|\)$/g, '').trim();
-    // Match OKLCH format: L C H (with optional decimal places)
-    const oklchRegex = /^(0(?:\.\d+)?|1(?:\.0+)?)\s+(0|\d*\.?\d+)\s+(0|[1-9]\d{0,2}(?:\.\d+)?|360(?:\.0+)?)$/;
-    if (!oklchRegex.test(cleanValue)) {
-        return false;
-    }
-    // Additional range validation
-    const [l, c, h] = cleanValue.split(/\s+/).map(Number);
-    return l >= 0 && l <= 1 && c >= 0 && h >= 0 && h <= 360;
-}
-/**
- * Ensure OKLCH color values are stored as full `oklch(L C H)` — a valid CSS color.
- * This allows `var(--token)` to work directly as a color in any CSS property,
- * and Tailwind v4's `color-mix()` opacity modifiers to compose correctly.
+ * The CSS value a design-token colour is applied as, read by the SAME design-system colour reader the
+ * stylesheet generator uses (#2354), so the page after mount and the stylesheet before it cannot disagree.
+ *
+ * Before this, the runtime and the generator each guessed: a hex brand colour became mid grey here and the
+ * invalid `oklch(#635BFF)` there, and an `rgb()` value rendered differently in the two. Now hex, `rgb()` and
+ * `hsl()` are converted to OKLCH in both places. A value that is not a design-system colour is REFUSED: it is
+ * reported with its token and not applied, so the stylesheet's value stays on the page. The old code painted
+ * mid grey instead, which replaced a correct colour with a wrong one and hid that anything had happened.
  */
-function ensureOklchWrapped(oklchValue, logger) {
-    const trimmed = oklchValue.trim();
-    // Already a complete CSS colour / expression — pass through untouched. Design
-    // tokens are not always raw OKLCH triples: the tonal SUBTLE status tokens (T1b)
-    // are palette-adaptive `color-mix()` formulas, and tokens may also be authored
-    // as `var(...)` references or other CSS colour functions. These are valid
-    // colours (just not `L C H` triples), so they must NOT be flagged as "invalid
-    // OKLCH" nor mangled to the grey fallback.
-    if (/^(oklch|color-mix|rgba?|hsla?|lab|lch|color|var)\(/.test(trimmed)) {
-        return trimmed;
+function resolveRuntimeColor(value, token, logger) {
+    try {
+        return normalizeDesignSystemColor(value);
     }
-    if (!validateOklchValue(trimmed)) {
-        logger?.warn('[DesignTokens] Invalid OKLCH format detected', { value: oklchValue });
-        return 'oklch(0.5 0 0)';
+    catch (error) {
+        if (!(error instanceof DesignSystemColorError))
+            throw error;
+        logger?.warn('[DesignTokens] Refused a value that is not a design-system colour; the stylesheet value stays', {
+            token,
+            value,
+            refusal: error.refusal,
+        });
+        return null;
     }
-    return `oklch(${trimmed})`;
 }
 /**
  * Convert size values to ensure proper CSS format
@@ -208,13 +195,17 @@ export function applyDesignTokens(tokens, options = {}) {
         const rawValue = getDesignTokenValue(config, dark ? 'dark' : 'light');
         // Convert value based on type with validation
         let finalValue;
-        let isValid = true;
         try {
             switch (config.type) {
-                case DesignTokenValueType.COLOR:
-                    finalValue = ensureOklchWrapped(rawValue, logger);
-                    isValid = finalValue !== 'oklch(0.5 0 0)' || rawValue === '0.5 0 0' || rawValue === 'oklch(0.5 0 0)';
+                case DesignTokenValueType.COLOR: {
+                    const color = resolveRuntimeColor(rawValue, varName, logger);
+                    if (color === null) {
+                        appliedCount.invalid++;
+                        continue;
+                    }
+                    finalValue = color;
                     break;
+                }
                 case DesignTokenValueType.SIZE:
                     finalValue = ensureProperSizeFormat(rawValue);
                     break;
@@ -227,10 +218,7 @@ export function applyDesignTokens(tokens, options = {}) {
             // Add to batch
             cssProperties.push({ name: varName, value: finalValue });
             // Track what was applied
-            if (!isValid) {
-                appliedCount.invalid++;
-            }
-            else if (dark && isDesignTokenLightDarkValueConfiguration(config)) {
+            if (dark && isDesignTokenLightDarkValueConfiguration(config)) {
                 appliedCount.dark++;
             }
             else {
@@ -272,14 +260,18 @@ export function applyCustomTokens(customTokens, options = {}) {
         const varName = `--${tokenName}`;
         const rawValue = getDesignTokenValue(config, dark ? 'dark' : 'light');
         let finalValue;
-        let isValid = true;
         try {
             // Format value based on type with validation
             switch (config.type) {
-                case DesignTokenValueType.COLOR:
-                    finalValue = ensureOklchWrapped(rawValue, logger);
-                    isValid = finalValue !== 'oklch(0.5 0 0)' || rawValue === '0.5 0 0' || rawValue === 'oklch(0.5 0 0)';
+                case DesignTokenValueType.COLOR: {
+                    const color = resolveRuntimeColor(rawValue, varName, logger);
+                    if (color === null) {
+                        appliedCount.invalid++;
+                        continue;
+                    }
+                    finalValue = color;
                     break;
+                }
                 case DesignTokenValueType.SIZE:
                     finalValue = ensureProperSizeFormat(rawValue);
                     break;
@@ -291,12 +283,7 @@ export function applyCustomTokens(customTokens, options = {}) {
             }
             // Add to batch
             cssProperties.push({ name: varName, value: finalValue });
-            if (isValid) {
-                appliedCount.valid++;
-            }
-            else {
-                appliedCount.invalid++;
-            }
+            appliedCount.valid++;
         }
         catch (error) {
             logger?.error('[DesignTokens] Error processing custom token', {
@@ -342,7 +329,7 @@ export function applyCustomTokens(customTokens, options = {}) {
  * mutual exclusion at the call-site (e.g. queue/await previous apply).
  */
 export function applyDesignSystemConfiguration(designSystem, options = {}) {
-    const { logger, target = document.documentElement, themeRuntimeVariables } = options;
+    const { target = document.documentElement } = options;
     // Snapshot the keys applied during *this* configuration so we can
     // diff against any prior application on the same target. Each apply* helper
     // adds to the per-target bucket; we capture-and-replace before they run so
@@ -352,25 +339,11 @@ export function applyDesignSystemConfiguration(designSystem, options = {}) {
     // guarantees no other call mutates the bucket between these two lines.
     const previousKeys = new Set(getAppliedKeys(target));
     appliedTokenKeys.set(target, new Set());
-    // Apply order is intentional and acts as a precedence ladder (last write
-    // wins on `style.setProperty`). The orchestrator owns this order so
-    // individual apply* helpers stay agnostic.
-    //
-    //   1. applyDesignTokens          — baseline palette (--primary, etc.)
-    //   2. applyTypographyConfiguration — host font config (--font-body,
-    //                                     --font-heading, --type-size-*)
-    //   3. applyCustomTokens          — theme `requiredCustomTokens` and
-    //                                     app-level customTokens MUST run last
-    //                                     so a theme can fully re-paint the
-    //                                     brand (palette + fonts) when its
-    //                                     `requiredCustomTokens` declares them.
-    //   4. themeRuntimeVariables      — the theme's explicit spacing/radius
-    //                                     overrides are the final authority for
-    //                                     those variables.
-    //
-    // Reordering is a behavior change; if you swap these, every consumer that
-    // relies on theme-level palette/font overrides via `requiredCustomTokens`
-    // will silently revert to host palette/fonts.
+    // The three branches write disjoint variables, so their order decides nothing. Precedence between a theme
+    // and the application is decided BEFORE this call, by `resolveThemedDesignSystemConfiguration` (#2355): the
+    // configuration handed in already holds the theme's values wherever the application declared none, and the
+    // application's own values everywhere else. The order used to BE the precedence — theme custom tokens last, so a
+    // theme repainted the brand over the application's declaration, and only after mount.
     if (designSystem.tokens) {
         applyDesignTokens(designSystem.tokens, options);
     }
@@ -380,13 +353,6 @@ export function applyDesignSystemConfiguration(designSystem, options = {}) {
     if (designSystem.customTokens) {
         applyCustomTokens(designSystem.customTokens, options);
     }
-    if (themeRuntimeVariables) {
-        const currentKeys = getAppliedKeys(target);
-        for (const [name, value] of themeRuntimeVariables) {
-            target.style.setProperty(name, value);
-            currentKeys.add(name);
-        }
-    }
     // Now reconcile: anything that *was* applied previously but is NOT in the
     // newly-collected set gets removed, eliminating stale CSS variables when a
     // theme/preset shrinks the token surface (e.g. neo-brutalist → glass).
@@ -611,9 +577,10 @@ export function generateTokensCSS(designSystem, options = {}) {
             if (config) {
                 const rawValue = getDesignTokenValue(config, 'light');
                 const value = config.type === DesignTokenValueType.COLOR
-                    ? ensureOklchWrapped(rawValue)
+                    ? resolveRuntimeColor(rawValue, token)
                     : rawValue;
-                css += `  --${token}: ${value};\n`;
+                if (value !== null)
+                    css += `  --${token}: ${value};\n`;
             }
         }
     }
@@ -629,9 +596,10 @@ export function generateTokensCSS(designSystem, options = {}) {
             if (config && isDesignTokenLightDarkValueConfiguration(config)) {
                 const rawValue = getDesignTokenValue(config, 'dark');
                 const value = config.type === DesignTokenValueType.COLOR
-                    ? ensureOklchWrapped(rawValue)
+                    ? resolveRuntimeColor(rawValue, token)
                     : rawValue;
-                css += `  --${token}: ${value};\n`;
+                if (value !== null)
+                    css += `  --${token}: ${value};\n`;
             }
         }
         css += '}\n';