@fakhrirafiki/theme-engine 0.4.14 → 0.4.17

package/README.md

@@ -8,6 +8,9 @@ Theme system for **Next.js (App Router)**: mode (`light | dark | system`) + them
 ![npm downloads](https://img.shields.io/npm/dm/@fakhrirafiki/theme-engine)
 ![license](https://img.shields.io/npm/l/@fakhrirafiki/theme-engine)
 
+Live demo: https://theme-engine-example.vercel.app/
+Example repo: https://github.com/fakhrirafiki/theme-engine-example
+
 ## ✨ Why use this?
 
 - ⚡ **Fast setup**: 1 CSS import + 1 provider
@@ -407,7 +410,7 @@ export function ThemePresetSelect({
 
               {isActive && (
                 <span className="inline-flex items-center rounded-full bg-primary/10 px-2 py-0.5 text-[10px] font-medium text-foreground">
-                  Aktif
+                  Active
                 </span>
               )}
             </span>
@@ -415,7 +418,7 @@ export function ThemePresetSelect({
         );
       })}
 
-      {presets.length === 0 && <p className="text-xs text-muted-foreground">Belum ada tema yang tersedia.</p>}
+      {presets.length === 0 && <p className="text-xs text-muted-foreground">No themes available yet.</p>}
     </div>
   );
 }
@@ -503,6 +506,14 @@ Note: the thrown error string might mention `useTheme` because `useThemeEngine()
 
 Ensure your `globals.css` imports `@fakhrirafiki/theme-engine/styles` (and Tailwind v4 is configured if you rely on Tailwind utilities).
 
+### Turbopack: “module factory is not available” (HMR) after upgrading
+
+This is a Next.js Turbopack dev/HMR issue that can happen after updating dependencies in `node_modules` (or when using a locally linked package that rebuilds `dist/` while `next dev` is running).
+
+- Restart `next dev` (often enough).
+- If it persists: delete `.next/` and restart.
+- Workaround: run dev server with webpack: `next dev --webpack`
+
 ---
 
 ## License

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,
@@ -4666,29 +4715,10 @@ var MoonIcon = () => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
     children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("path", { d: "m12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" })
   }
 );
-var SystemIcon = () => /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
-  "svg",
-  {
-    xmlns: "http://www.w3.org/2000/svg",
-    width: "16",
-    height: "16",
-    viewBox: "0 0 24 24",
-    fill: "none",
-    stroke: "currentColor",
-    strokeWidth: "2",
-    strokeLinecap: "round",
-    strokeLinejoin: "round",
-    className: "theme-toggle-icon",
-    children: [
-      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("rect", { width: "20", height: "14", x: "2", y: "3", rx: "2" }),
-      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("line", { x1: "8", x2: "16", y1: "21", y2: "21" }),
-      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("line", { x1: "12", x2: "12", y1: "17", y2: "21" })
-    ]
-  }
-);
 var ThemeToggle = (0, import_react3.forwardRef)(
   ({ className, size = "md", variant = "default", children, ...props }, ref) => {
     const { mode, resolvedMode, toggleMode } = useTheme();
+    const nextResolvedMode = resolvedMode === "light" ? "dark" : "light";
     const handleClick = (event) => {
       const { clientX: x, clientY: y } = event;
       toggleMode({ x, y });
@@ -4718,16 +4748,7 @@ var ThemeToggle = (0, import_react3.forwardRef)(
     );
     const renderIcon = () => {
       if (children) return children;
-      switch (mode) {
-        case "light":
-          return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(SunIcon, {});
-        case "dark":
-          return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(MoonIcon, {});
-        case "system":
-          return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(SystemIcon, {});
-        default:
-          return resolvedMode === "dark" ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(MoonIcon, {}) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(SunIcon, {});
-      }
+      return nextResolvedMode === "dark" ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(MoonIcon, {}) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(SunIcon, {});
     };
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
       "button",
@@ -4735,10 +4756,10 @@ var ThemeToggle = (0, import_react3.forwardRef)(
         ref,
         className: baseClasses,
         onClick: handleClick,
-        "data-mode": resolvedMode,
+        "data-mode": mode,
         "data-theme": resolvedMode,
-        "aria-label": `Switch to ${resolvedMode === "light" ? "dark" : "light"} mode`,
-        title: `Switch to ${resolvedMode === "light" ? "dark" : "light"} mode`,
+        "aria-label": `Switch to ${nextResolvedMode} mode`,
+        title: `Switch to ${nextResolvedMode} mode`,
         ...props,
         children: renderIcon()
       }

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,
@@ -4622,29 +4671,10 @@ var MoonIcon = () => /* @__PURE__ */ jsx3(
     children: /* @__PURE__ */ jsx3("path", { d: "m12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" })
   }
 );
-var SystemIcon = () => /* @__PURE__ */ jsxs2(
-  "svg",
-  {
-    xmlns: "http://www.w3.org/2000/svg",
-    width: "16",
-    height: "16",
-    viewBox: "0 0 24 24",
-    fill: "none",
-    stroke: "currentColor",
-    strokeWidth: "2",
-    strokeLinecap: "round",
-    strokeLinejoin: "round",
-    className: "theme-toggle-icon",
-    children: [
-      /* @__PURE__ */ jsx3("rect", { width: "20", height: "14", x: "2", y: "3", rx: "2" }),
-      /* @__PURE__ */ jsx3("line", { x1: "8", x2: "16", y1: "21", y2: "21" }),
-      /* @__PURE__ */ jsx3("line", { x1: "12", x2: "12", y1: "17", y2: "21" })
-    ]
-  }
-);
 var ThemeToggle = forwardRef(
   ({ className, size = "md", variant = "default", children, ...props }, ref) => {
     const { mode, resolvedMode, toggleMode } = useTheme();
+    const nextResolvedMode = resolvedMode === "light" ? "dark" : "light";
     const handleClick = (event) => {
       const { clientX: x, clientY: y } = event;
       toggleMode({ x, y });
@@ -4674,16 +4704,7 @@ var ThemeToggle = forwardRef(
     );
     const renderIcon = () => {
       if (children) return children;
-      switch (mode) {
-        case "light":
-          return /* @__PURE__ */ jsx3(SunIcon, {});
-        case "dark":
-          return /* @__PURE__ */ jsx3(MoonIcon, {});
-        case "system":
-          return /* @__PURE__ */ jsx3(SystemIcon, {});
-        default:
-          return resolvedMode === "dark" ? /* @__PURE__ */ jsx3(MoonIcon, {}) : /* @__PURE__ */ jsx3(SunIcon, {});
-      }
+      return nextResolvedMode === "dark" ? /* @__PURE__ */ jsx3(MoonIcon, {}) : /* @__PURE__ */ jsx3(SunIcon, {});
     };
     return /* @__PURE__ */ jsx3(
       "button",
@@ -4691,10 +4712,10 @@ var ThemeToggle = forwardRef(
         ref,
         className: baseClasses,
         onClick: handleClick,
-        "data-mode": resolvedMode,
+        "data-mode": mode,
         "data-theme": resolvedMode,
-        "aria-label": `Switch to ${resolvedMode === "light" ? "dark" : "light"} mode`,
-        title: `Switch to ${resolvedMode === "light" ? "dark" : "light"} mode`,
+        "aria-label": `Switch to ${nextResolvedMode} mode`,
+        title: `Switch to ${nextResolvedMode} mode`,
         ...props,
         children: renderIcon()
       }

package/dist/styles/components.css

@@ -26,16 +26,17 @@
 
 /* Icon transition for theme toggle */
 .theme-toggle-icon {
+  display: block;
   transition: all 0.3s ease-in-out;
   color: hsl(var(--foreground));
 }
 
 .theme-toggle[data-theme="light"] .theme-toggle-icon {
-  rotate: 0deg;
+  rotate: 180deg;
 }
 
 .theme-toggle[data-theme="dark"] .theme-toggle-icon {
-  rotate: 180deg;
+  rotate: 0deg;
 }
 
 /* ThemePresetButtons: lightweight CSS-based animations and hover affordances */
@@ -59,10 +60,7 @@
   box-shadow: 0 1px 0 hsl(var(--border) / 0.35);
   cursor: pointer;
 
-  transition:
-    transform 0.2s ease-out,
-    background-color 0.2s ease-out,
-    border-color 0.2s ease-out,
+  transition: transform 0.2s ease-out, background-color 0.2s ease-out, border-color 0.2s ease-out,
     box-shadow 0.2s ease-out;
 }
 
@@ -111,9 +109,7 @@
   z-index: 20;
   background: hsl(var(--card) / 0.95);
   border-color: hsl(var(--primary) / 0.2);
-  box-shadow:
-    0 10px 25px hsl(0 0% 0% / 0.12),
-    0 0 0 1px hsl(var(--border) / 0.35);
+  box-shadow: 0 10px 25px hsl(0 0% 0% / 0.12), 0 0 0 1px hsl(var(--border) / 0.35);
 }
 
 /* Color boxes within preset buttons - fallback only */
@@ -192,7 +188,7 @@
   .theme-preset-button {
     min-width: 120px;
   }
-  
+
   .color-palette-grid {
     grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
   }
@@ -204,7 +200,7 @@
   .theme-preset-button {
     border-width: 2px;
   }
-  
+
   .theme-color-box {
     border-width: 2px;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fakhrirafiki/theme-engine",
-  "version": "0.4.14",
+  "version": "0.4.17",
   "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",
@@ -37,7 +37,7 @@
     "type": "git",
     "url": "git+https://github.com/fakhrirafiki/theme-engine.git"
   },
-  "homepage": "https://github.com/fakhrirafiki/theme-engine",
+  "homepage": "https://theme-engine-example.vercel.app/",
   "bugs": {
     "url": "https://github.com/fakhrirafiki/theme-engine/issues"
   },