@fakhrirafiki/theme-engine 0.4.14 → 0.4.15

package/dist/index.d.mts

@@ -460,16 +460,27 @@ interface ThemeScriptProps {
      * @default 'theme-preset'
      */
     presetStorageKey?: string;
+    /**
+     * Storage key for appearance mode persistence
+     * @default 'theme-engine-theme'
+     */
+    modeStorageKey?: string;
+    /**
+     * Default appearance mode when no stored preference exists
+     * @default 'system'
+     */
+    defaultMode?: Mode;
     /**
      * Default preset ID to apply when no stored preset exists
      */
     defaultPreset?: string;
 }
 /**
- * Simplified theme script that only handles preset restoration
- * Works in harmony with ThemeProvider for dark/light mode
+ * Pre-hydration theme script.
+ * - Restores appearance mode (light/dark/system) to avoid hydration mismatch + FOUC.
+ * - Restores preset CSS variables early so Tailwind/shadcn tokens render correctly on first paint.
  */
-declare function ThemeScript({ presetStorageKey, defaultPreset }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
+declare function ThemeScript({ presetStorageKey, modeStorageKey, defaultMode, defaultPreset, }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
 
 declare const ThemeToggle: react.ForwardRefExoticComponent<ThemeToggleProps & react.RefAttributes<HTMLButtonElement>>;
 

package/dist/index.d.ts

@@ -460,16 +460,27 @@ interface ThemeScriptProps {
      * @default 'theme-preset'
      */
     presetStorageKey?: string;
+    /**
+     * Storage key for appearance mode persistence
+     * @default 'theme-engine-theme'
+     */
+    modeStorageKey?: string;
+    /**
+     * Default appearance mode when no stored preference exists
+     * @default 'system'
+     */
+    defaultMode?: Mode;
     /**
      * Default preset ID to apply when no stored preset exists
      */
     defaultPreset?: string;
 }
 /**
- * Simplified theme script that only handles preset restoration
- * Works in harmony with ThemeProvider for dark/light mode
+ * Pre-hydration theme script.
+ * - Restores appearance mode (light/dark/system) to avoid hydration mismatch + FOUC.
+ * - Restores preset CSS variables early so Tailwind/shadcn tokens render correctly on first paint.
  */
-declare function ThemeScript({ presetStorageKey, defaultPreset }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
+declare function ThemeScript({ presetStorageKey, modeStorageKey, defaultMode, defaultPreset, }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
 
 declare const ThemeToggle: react.ForwardRefExoticComponent<ThemeToggleProps & react.RefAttributes<HTMLButtonElement>>;
 

package/dist/index.js

@@ -3838,7 +3838,12 @@ function logValidationResult(result, context = "Custom presets") {
 // src/components/UnifiedThemeScript.tsx
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
-function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
+function ThemeScript({
+  presetStorageKey = "theme-preset",
+  modeStorageKey = "theme-engine-theme",
+  defaultMode = "system",
+  defaultPreset
+}) {
   const defaultPresetData = (0, import_react.useMemo)(() => {
     if (!defaultPreset) return null;
     const preset = getPresetById(defaultPreset);
@@ -3850,10 +3855,12 @@ function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
   }, [defaultPreset]);
   const scriptContent = (0, import_react.useMemo)(
     () => `
-    // Unified Theme Engine: Restore preset colors before hydration
+    // Unified Theme Engine: Restore mode + preset colors before hydration
     (function() {
       try {
         const presetStorageKey = "${presetStorageKey}";
+        const modeStorageKey = "${modeStorageKey}";
+        const defaultMode = "${defaultMode}";
         const isDev = (function() {
           try {
             return location.hostname === 'localhost' || location.hostname === '127.0.0.1';
@@ -3861,6 +3868,39 @@ function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
             return false;
           }
         })();
+
+        // ---- Mode restoration (pre-hydration) ----
+        (function() {
+          try {
+            const root = document.documentElement;
+            let storedMode = null;
+            try {
+              storedMode = localStorage.getItem(modeStorageKey);
+            } catch {}
+
+            const isValidMode = storedMode === 'light' || storedMode === 'dark' || storedMode === 'system';
+            const mode = isValidMode ? storedMode : defaultMode;
+
+            let systemMode = 'light';
+            try {
+              systemMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+            } catch {}
+
+            const resolvedMode = mode === 'system' ? systemMode : mode;
+
+            root.classList.remove('light', 'dark');
+            root.classList.add(resolvedMode);
+            root.style.colorScheme = resolvedMode;
+
+            // Expose for runtime consumers (optional)
+            try {
+              root.dataset.themeEngineMode = mode;
+              root.dataset.themeEngineResolvedMode = resolvedMode;
+            } catch {}
+          } catch (error) {
+            if (isDev) console.warn('\u{1F3A8} UnifiedThemeScript: Mode restoration failed:', error);
+          }
+        })();
         
         // CSS property categories (inline for script)
         const CSS_CATEGORIES = {
@@ -4067,7 +4107,7 @@ function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
           
         }
         
-        // Load and apply persisted preset or default preset
+        // ---- Preset restoration (pre-hydration) ----
         const storedPreset = localStorage.getItem(presetStorageKey);
         let presetToApply = null;
         
@@ -4085,10 +4125,9 @@ function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
         }
         
         if (presetToApply) {
-          // Determine current mode (will be set by ThemeProvider)
-          // Default to light if no theme class is present yet
-          const isDark = document.documentElement.classList.contains('dark');
-          const mode = isDark ? 'dark' : 'light';
+          const root = document.documentElement;
+          const resolved = (root.dataset && root.dataset.themeEngineResolvedMode) || (root.classList.contains('dark') ? 'dark' : 'light');
+          const mode = resolved === 'dark' ? 'dark' : 'light';
           const colors = presetToApply.colors && presetToApply.colors[mode];
           
           if (colors) {
@@ -4315,15 +4354,17 @@ function ThemeProvider({
 }) {
   const normalizedCustomPresets = (0, import_react2.useMemo)(() => customPresets ?? {}, [customPresets]);
   const [mode, setMode] = (0, import_react2.useState)(() => {
-    const stored = getStoredMode(modeStorageKey);
-    return stored || defaultMode;
+    return defaultMode;
   });
   const [resolvedMode, setResolvedMode] = (0, import_react2.useState)(() => {
-    if (mode === "system") {
-      return getSystemTheme();
-    }
-    return mode;
+    if (defaultMode === "dark") return "dark";
+    return "light";
   });
+  (0, import_react2.useEffect)(() => {
+    if (typeof window === "undefined") return;
+    const stored = getStoredMode(modeStorageKey);
+    if (stored) setMode(stored);
+  }, [modeStorageKey]);
   const availablePresets = (0, import_react2.useMemo)(() => {
     const merged = {};
     Object.assign(merged, tweakcnPresets);
@@ -4591,7 +4632,15 @@ function ThemeProvider({
       });
     }
   }, [presetStorageKey, defaultPreset, getAvailablePresetById, applyPresetColors, resolvedMode]);
-  const scriptElement = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(ThemeScript, { presetStorageKey, defaultPreset });
+  const scriptElement = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+    ThemeScript,
+    {
+      presetStorageKey,
+      modeStorageKey,
+      defaultMode,
+      defaultPreset
+    }
+  );
   const isUsingDefaultPreset = !!defaultPreset && currentPreset?.presetId === defaultPreset;
   const contextValue = {
     mode,

package/dist/index.mjs

@@ -3794,7 +3794,12 @@ function logValidationResult(result, context = "Custom presets") {
 // src/components/UnifiedThemeScript.tsx
 import { useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
-function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
+function ThemeScript({
+  presetStorageKey = "theme-preset",
+  modeStorageKey = "theme-engine-theme",
+  defaultMode = "system",
+  defaultPreset
+}) {
   const defaultPresetData = useMemo(() => {
     if (!defaultPreset) return null;
     const preset = getPresetById(defaultPreset);
@@ -3806,10 +3811,12 @@ function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
   }, [defaultPreset]);
   const scriptContent = useMemo(
     () => `
-    // Unified Theme Engine: Restore preset colors before hydration
+    // Unified Theme Engine: Restore mode + preset colors before hydration
     (function() {
       try {
         const presetStorageKey = "${presetStorageKey}";
+        const modeStorageKey = "${modeStorageKey}";
+        const defaultMode = "${defaultMode}";
         const isDev = (function() {
           try {
             return location.hostname === 'localhost' || location.hostname === '127.0.0.1';
@@ -3817,6 +3824,39 @@ function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
             return false;
           }
         })();
+
+        // ---- Mode restoration (pre-hydration) ----
+        (function() {
+          try {
+            const root = document.documentElement;
+            let storedMode = null;
+            try {
+              storedMode = localStorage.getItem(modeStorageKey);
+            } catch {}
+
+            const isValidMode = storedMode === 'light' || storedMode === 'dark' || storedMode === 'system';
+            const mode = isValidMode ? storedMode : defaultMode;
+
+            let systemMode = 'light';
+            try {
+              systemMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+            } catch {}
+
+            const resolvedMode = mode === 'system' ? systemMode : mode;
+
+            root.classList.remove('light', 'dark');
+            root.classList.add(resolvedMode);
+            root.style.colorScheme = resolvedMode;
+
+            // Expose for runtime consumers (optional)
+            try {
+              root.dataset.themeEngineMode = mode;
+              root.dataset.themeEngineResolvedMode = resolvedMode;
+            } catch {}
+          } catch (error) {
+            if (isDev) console.warn('\u{1F3A8} UnifiedThemeScript: Mode restoration failed:', error);
+          }
+        })();
         
         // CSS property categories (inline for script)
         const CSS_CATEGORIES = {
@@ -4023,7 +4063,7 @@ function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
           
         }
         
-        // Load and apply persisted preset or default preset
+        // ---- Preset restoration (pre-hydration) ----
         const storedPreset = localStorage.getItem(presetStorageKey);
         let presetToApply = null;
         
@@ -4041,10 +4081,9 @@ function ThemeScript({ presetStorageKey = "theme-preset", defaultPreset }) {
         }
         
         if (presetToApply) {
-          // Determine current mode (will be set by ThemeProvider)
-          // Default to light if no theme class is present yet
-          const isDark = document.documentElement.classList.contains('dark');
-          const mode = isDark ? 'dark' : 'light';
+          const root = document.documentElement;
+          const resolved = (root.dataset && root.dataset.themeEngineResolvedMode) || (root.classList.contains('dark') ? 'dark' : 'light');
+          const mode = resolved === 'dark' ? 'dark' : 'light';
           const colors = presetToApply.colors && presetToApply.colors[mode];
           
           if (colors) {
@@ -4271,15 +4310,17 @@ function ThemeProvider({
 }) {
   const normalizedCustomPresets = useMemo2(() => customPresets ?? {}, [customPresets]);
   const [mode, setMode] = useState(() => {
-    const stored = getStoredMode(modeStorageKey);
-    return stored || defaultMode;
+    return defaultMode;
   });
   const [resolvedMode, setResolvedMode] = useState(() => {
-    if (mode === "system") {
-      return getSystemTheme();
-    }
-    return mode;
+    if (defaultMode === "dark") return "dark";
+    return "light";
   });
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const stored = getStoredMode(modeStorageKey);
+    if (stored) setMode(stored);
+  }, [modeStorageKey]);
   const availablePresets = useMemo2(() => {
     const merged = {};
     Object.assign(merged, tweakcnPresets);
@@ -4547,7 +4588,15 @@ function ThemeProvider({
       });
     }
   }, [presetStorageKey, defaultPreset, getAvailablePresetById, applyPresetColors, resolvedMode]);
-  const scriptElement = /* @__PURE__ */ jsx2(ThemeScript, { presetStorageKey, defaultPreset });
+  const scriptElement = /* @__PURE__ */ jsx2(
+    ThemeScript,
+    {
+      presetStorageKey,
+      modeStorageKey,
+      defaultMode,
+      defaultPreset
+    }
+  );
   const isUsingDefaultPreset = !!defaultPreset && currentPreset?.presetId === defaultPreset;
   const contextValue = {
     mode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fakhrirafiki/theme-engine",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "Elegant theming system with smooth transitions, custom presets, semantic accent colors, and complete shadcn/ui support for modern React applications",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",