@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

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

@@ -5,49 +5,9 @@
  * Types/schemas: import from @wildo-ai/presets-components-models
  * Utilities: import from this file via @wildo-ai/saas-frontend-lib
  */
-import { DesignTokenValueType, getDesignTokenValue, isDesignTokenLightDarkValueConfiguration, mergeDesignTokenConfiguration, 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, } from '@wildo-ai/presets-components-models';
 import { UserTheme } from '@wildo-ai/saas-models';
-const DARK_MODE_STORAGE_KEY = 'theme.dark';
 const DARK_MODE_PREFERENCE_STORAGE_KEY = 'theme.preference';
-/**
- * Deep merge two FontConfiguration objects
- */
-function mergeFontConfiguration(base, override) {
-    if (!override)
-        return base;
-    return {
-        ...base,
-        ...override,
-        fallbacks: override.fallbacks ?? base.fallbacks,
-        axisRanges: override.axisRanges
-            ? { ...base.axisRanges, ...override.axisRanges }
-            : base.axisRanges,
-        defaults: override.defaults
-            ? { ...base.defaults, ...override.defaults }
-            : base.defaults,
-    };
-}
-/**
- * Deep merge two TypographyConfiguration objects
- */
-function mergeTypographyConfiguration(base, override) {
-    if (!override)
-        return base;
-    const mergedFonts = { ...base.fonts };
-    if (override.fonts) {
-        for (const role of Object.values(TypographyRole)) {
-            if (override.fonts[role]) {
-                mergedFonts[role] = mergeFontConfiguration(base.fonts[role], override.fonts[role]);
-            }
-        }
-    }
-    return {
-        fonts: mergedFonts,
-        scale: override.scale
-            ? { ...base.scale, ...override.scale }
-            : base.scale,
-    };
-}
 /**
  * Deep merge two DesignSystemConfiguration objects.
  * Override only replaces tokens that are explicitly provided.
@@ -57,55 +17,10 @@ function mergeTypographyConfiguration(base, override) {
  * - Merge with apps-custom overrides
  * - Partial token customization (only override primary color, keep rest)
  *
- * @param base - Base configuration (typically engine defaults)
- * @param override - Override configuration (backend/custom, can be partial)
- * @returns Merged configuration
+ * Re-exported from `@wildo-ai/presets-components-models` so generated CSS and
+ * frontend runtime use the same merge semantics.
  */
-export function mergeDesignSystemConfiguration(base, override) {
-    if (!override) {
-        return base;
-    }
-    const result = {
-        ...base,
-    };
-    // Merge standard tokens (deep merge per token)
-    if (override.tokens) {
-        const baseTokens = (base.tokens || {});
-        result.tokens = { ...baseTokens };
-        for (const [tokenKey, tokenConfig] of Object.entries(override.tokens)) {
-            if (tokenConfig) {
-                const baseToken = baseTokens[tokenKey];
-                result.tokens[tokenKey] = baseToken
-                    ? mergeDesignTokenConfiguration(baseToken, tokenConfig)
-                    : tokenConfig;
-            }
-        }
-    }
-    // Merge custom tokens (deep merge per token)
-    if (override.customTokens) {
-        const baseCustomTokens = (base.customTokens || {});
-        result.customTokens = { ...baseCustomTokens };
-        for (const [tokenKey, tokenConfig] of Object.entries(override.customTokens)) {
-            if (tokenConfig) {
-                const baseToken = baseCustomTokens[tokenKey];
-                result.customTokens[tokenKey] = baseToken
-                    ? mergeDesignTokenConfiguration(baseToken, tokenConfig)
-                    : tokenConfig;
-            }
-        }
-    }
-    // Merge typography configuration
-    if (override.typography && base.typography) {
-        result.typography = mergeTypographyConfiguration(base.typography, override.typography);
-    }
-    else if (override.typography) {
-        result.typography = override.typography;
-    }
-    if (override.theme !== undefined) {
-        result.theme = override.theme;
-    }
-    return result;
-}
+export const mergeDesignSystemConfiguration = mergeDesignSystemConfigurationShared;
 /**
  * Convert enum to CSS variable name
  * DesignSystemToken enum values already match kebab-case CSS variable names
@@ -133,14 +48,21 @@ function validateOklchValue(value) {
  * and Tailwind v4's `color-mix()` opacity modifiers to compose correctly.
  */
 function ensureOklchWrapped(oklchValue, logger) {
-    if (!validateOklchValue(oklchValue)) {
+    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;
+    }
+    if (!validateOklchValue(trimmed)) {
         logger?.warn('[DesignTokens] Invalid OKLCH format detected', { value: oklchValue });
         return 'oklch(0.5 0 0)';
     }
-    if (oklchValue.startsWith('oklch(') && oklchValue.endsWith(')')) {
-        return oklchValue;
-    }
-    return `oklch(${oklchValue.trim()})`;
+    return `oklch(${trimmed})`;
 }
 /**
  * Convert size values to ensure proper CSS format
@@ -180,8 +102,18 @@ function resolveSystemDarkMode() {
     return window.matchMedia('(prefers-color-scheme: dark)').matches;
 }
 function resolveStoredDarkModePreference() {
-    const savedPreference = localStorage.getItem(DARK_MODE_PREFERENCE_STORAGE_KEY);
-    return isUserThemePreference(savedPreference) ? savedPreference : null;
+    try {
+        const savedPreference = localStorage.getItem(DARK_MODE_PREFERENCE_STORAGE_KEY);
+        return isUserThemePreference(savedPreference) ? savedPreference : null;
+    }
+    catch {
+        /**
+         * Storage is an optional persistence mechanism, not the source of the
+         * browser's current color scheme. Privacy modes and browser policies may
+         * deny it; in that case a missing preference semantically means AUTO.
+         */
+        return null;
+    }
 }
 function applyDarkModeState(enabled) {
     const element = document.documentElement;
@@ -190,14 +122,13 @@ function applyDarkModeState(enabled) {
     // Also set .dark class for compatibility
     element.classList.toggle('dark', enabled);
 }
-function persistDarkModePreference(context, preference, enabled) {
+function persistDarkModePreference(context, preference) {
     if (context._debounceTimeout) {
         clearTimeout(context._debounceTimeout);
     }
     context._debounceTimeout = window.setTimeout(() => {
         try {
             localStorage.setItem(DARK_MODE_PREFERENCE_STORAGE_KEY, preference);
-            localStorage.setItem(DARK_MODE_STORAGE_KEY, enabled ? '1' : '0');
         }
         catch (error) {
             console.warn('[DarkMode] Failed to persist theme preference:', error);
@@ -209,22 +140,54 @@ function resolvePreferredDarkMode() {
     if (typeof window === 'undefined') {
         return false;
     }
-    try {
-        const savedPreference = resolveStoredDarkModePreference();
-        if (savedPreference === UserTheme.DARK)
-            return true;
-        if (savedPreference === UserTheme.LIGHT)
-            return false;
-        if (savedPreference === UserTheme.AUTO)
-            return resolveSystemDarkMode();
-        const saved = localStorage.getItem(DARK_MODE_STORAGE_KEY);
-        const prefers = resolveSystemDarkMode();
-        return saved ? saved === '1' : prefers;
-    }
-    catch (error) {
-        console.error('[DarkMode] Failed to resolve preferred dark mode:', error);
+    const savedPreference = resolveStoredDarkModePreference();
+    if (savedPreference === UserTheme.DARK)
+        return true;
+    if (savedPreference === UserTheme.LIGHT)
         return false;
+    /**
+     * AUTO and a missing/invalid/unavailable stored preference all mean the same
+     * thing: follow the browser's live system color-scheme. A derived Boolean
+     * must never be persisted as a second source of truth because it becomes
+     * stale as soon as the operating-system appearance changes.
+     */
+    return resolveSystemDarkMode();
+}
+// ============================================================================
+// Applied-property tracking
+// ============================================================================
+// Track which CSS custom properties we've set per target element so we can:
+//  1. Remove tokens that disappear when the design system is swapped at runtime
+//     (e.g. theme change, tenant switch) instead of leaving stale variables on
+//     the root and letting old colors leak through.
+//  2. Cleanly reset everything we own from `UIContext` unmount, which avoids
+//     polluting the document for the next mount during HMR / SPA navigation.
+//
+// The map is keyed by HTMLElement so multiple roots (document.documentElement,
+// shadow roots, preview iframes) can be managed independently.
+// ============================================================================
+const appliedTokenKeys = new WeakMap();
+function getAppliedKeys(target) {
+    let bucket = appliedTokenKeys.get(target);
+    if (!bucket) {
+        bucket = new Set();
+        appliedTokenKeys.set(target, bucket);
+    }
+    return bucket;
+}
+/**
+ * Remove every CSS custom property that this module has applied to `target`.
+ * Call from `UIProvider` unmount (or an HMR boundary) to leave the document
+ * in a clean state. No-op when nothing has been applied to the given target.
+ */
+export function clearAppliedDesignTokens(target = document.documentElement) {
+    const previous = appliedTokenKeys.get(target);
+    if (!previous)
+        return;
+    for (const key of previous) {
+        target.style.removeProperty(key);
     }
+    appliedTokenKeys.delete(target);
 }
 /**
  * Apply design tokens as CSS variables to the document root or specified target
@@ -280,9 +243,17 @@ export function applyDesignTokens(tokens, options = {}) {
     }
     // Batch apply all CSS properties in single DOM operation
     const style = target.style;
+    const appliedNames = [];
     cssProperties.forEach(({ name, value }) => {
         style.setProperty(name, value);
+        appliedNames.push(name);
     });
+    // Merge into the per-target tracking bucket so subsequent calls can
+    // diff. We don't reconcile here (would prematurely drop custom-token /
+    // typography keys); reconciliation happens in
+    // `applyDesignSystemConfiguration` once all three branches have run.
+    const bucket = getAppliedKeys(target);
+    appliedNames.forEach(n => bucket.add(n));
 }
 /**
  * Apply custom tokens (non-shadcn/ui tokens) with validation and batching
@@ -333,9 +304,15 @@ export function applyCustomTokens(customTokens, options = {}) {
     }
     // Batch apply all CSS properties
     const style = target.style;
+    const appliedNames = [];
     cssProperties.forEach(({ name, value }) => {
         style.setProperty(name, value);
+        appliedNames.push(name);
     });
+    // Merge into the per-target tracking bucket; reconciliation happens at
+    // the orchestrator level (`applyDesignSystemConfiguration`).
+    const bucket = getAppliedKeys(target);
+    appliedNames.forEach(n => bucket.add(n));
     logger?.debug('[DesignTokens] Applied custom OKLCH CSS variables with validation', {
         totalCustomTokens: Object.keys(customTokens).length,
         darkMode: dark,
@@ -346,21 +323,73 @@ export function applyCustomTokens(customTokens, options = {}) {
     });
 }
 /**
- * Apply complete design system configuration
+ * Apply complete design system configuration.
+ *
+ * **Concurrency contract (single-flight)**: this function is **not** safe to
+ * invoke concurrently against the same `target`. The reconcile step uses a
+ * snapshot-then-replace pattern on a single shared `WeakMap` bucket;
+ * two overlapping calls would race on the bucket and could either drop
+ * legitimate keys or leave stale ones behind.
+ *
+ * In practice the only caller is `UIContext`'s mount/update effect, which is
+ * already single-flight by virtue of React's effect serialization on a single
+ * `target`. If you ever need to call this from outside `UIContext`, ensure
+ * mutual exclusion at the call-site (e.g. queue/await previous apply).
  */
 export function applyDesignSystemConfiguration(designSystem, options = {}) {
-    const { logger } = options;
-    // Apply standard tokens
+    const { logger, target = document.documentElement, themeRuntimeVariables } = 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
+    // the reconcile step at the end has both old + new sets to compare.
+    //
+    // NOTE: snapshot-replace is non-atomic. The single-flight contract above
+    // 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.
     if (designSystem.tokens) {
         applyDesignTokens(designSystem.tokens, options);
     }
-    // Apply custom tokens
+    if (designSystem.typography) {
+        applyTypographyConfiguration(designSystem.typography, options);
+    }
     if (designSystem.customTokens) {
         applyCustomTokens(designSystem.customTokens, options);
     }
-    // Apply typography configuration
-    if (designSystem.typography) {
-        applyTypographyConfiguration(designSystem.typography, 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).
+    const currentKeys = getAppliedKeys(target);
+    for (const oldKey of previousKeys) {
+        if (!currentKeys.has(oldKey)) {
+            target.style.removeProperty(oldKey);
+        }
     }
     // logger?.debug('[DesignTokens] Complete design system applied', {
     //   hasStandardTokens: !!designSystem.tokens,
@@ -463,9 +492,15 @@ export function applyTypographyConfiguration(typography, options = {}) {
     }
     // Batch apply all CSS properties
     const style = target.style;
+    const appliedNames = [];
     cssProperties.forEach(({ name, value }) => {
         style.setProperty(name, value);
+        appliedNames.push(name);
     });
+    // Merge into the per-target tracking bucket; reconciliation happens at
+    // the orchestrator level (`applyDesignSystemConfiguration`).
+    const bucket = getAppliedKeys(target);
+    appliedNames.forEach(n => bucket.add(n));
     // logger?.debug('[Typography] Applied typography CSS variables', {
     //   rolesConfigured: Object.keys(typography.fonts).length,
     //   scaleEntries: typography.scale ? Object.keys(typography.scale).length : 0,
@@ -487,7 +522,7 @@ export const darkModeUtils = {
             return;
         try {
             applyDarkModeState(enabled);
-            persistDarkModePreference(this, enabled ? UserTheme.DARK : UserTheme.LIGHT, enabled);
+            persistDarkModePreference(this, enabled ? UserTheme.DARK : UserTheme.LIGHT);
         }
         catch (error) {
             console.error('[DarkMode] Failed to set dark mode:', error);
@@ -502,7 +537,7 @@ export const darkModeUtils = {
         try {
             const enabled = resolveSystemDarkMode();
             applyDarkModeState(enabled);
-            persistDarkModePreference(this, UserTheme.AUTO, enabled);
+            persistDarkModePreference(this, UserTheme.AUTO);
             return enabled;
         }
         catch (error) {
@@ -533,16 +568,7 @@ export const darkModeUtils = {
         if (typeof window === 'undefined') {
             return null;
         }
-        try {
-            return resolveStoredDarkModePreference();
-        }
-        catch (error) {
-            console.warn('[DarkMode] Failed to read stored theme preference:', error);
-            return null;
-        }
-    },
-    isAuto() {
-        return this.getStoredPreference() === UserTheme.AUTO;
+        return resolveStoredDarkModePreference();
     },
     /**
      * Toggle dark mode with debouncing
@@ -1418,11 +1444,20 @@ export function applyChartColorPalette(palette = DEFAULT_CHART_COLOR_PALETTE, op
     if (!target)
         return;
     const colorsToApply = Math.min(palette.length, maxColors);
+    // Track applied chart-* keys in the per-target bucket so
+    // `clearAppliedDesignTokens` can clean them up too. Note this helper is
+    // currently called outside `applyDesignSystemConfiguration` (no reconcile
+    // sweep), so a previous larger palette won't auto-prune from a later
+    // smaller one — pass `maxColors` consistently if that matters.
+    const bucket = getAppliedKeys(target);
     for (let i = 0; i < colorsToApply; i++) {
         const color = getTailwindColor(palette[i], shade);
-        target.style.setProperty(`--chart-${i + 1}`, color);
+        const name = `--chart-${i + 1}`;
+        target.style.setProperty(name, color);
+        bucket.add(name);
     }
     // Store palette for runtime access
     target.style.setProperty('--chart-color-palette', palette.slice(0, maxColors).join(','));
+    bucket.add('--chart-color-palette');
 }
-//# sourceMappingURL=design-token.utils.js.map
+//# sourceMappingURL=design-token.utils.js.map