npm - @usetheo/ui - Versions diffs - 0.6.2-next.0 → 0.6.3-next.0 - Mend

@usetheo/ui 0.6.2-next.0 → 0.6.3-next.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.6.3-next.0] - 2026-05-23
+Patch — eliminate React hydration mismatch in `<ThemeProvider>`. Reported
+by the TheoKit framework team (2026-05-23): every SSR'd app using
+`<ThemeSwitcher>` threw `Hydration failed because the server rendered
+text didn't match the client` on every page reload after a user had
+changed themes, then re-rendered the entire React tree client-side,
+defeating SSR.
+### Fixed
+- **SSR hydration mismatch on `<ThemeProvider>`** — three `useState`
+  calls (`themeName`, `mode`, `density`) previously ran their initializer
+  on BOTH server (no `window`, returned default) AND client at hydration
+  time (with `window`, returned `localStorage.getItem(…)`). The two
+  diverged → React threw + discarded the SSR'd tree on every page load.
+  Fixed by initializing with the SSR default ALWAYS, then promoting to
+  the stored value via a post-mount `useEffect` after hydration. The
+  visible-text nodes the React reconciler compares (switcher label,
+  `sr-only` announcement, `aria-label`) now match server → client.
+  Stored preferences still apply within one render tick of mount;
+  `<ThemeScript>` continues to set `data-theme` / `data-mode` /
+  `data-density` on `<html>` before React mounts to suppress the
+  1-frame visual flicker. (#TBD)
+- **Persist effect first-mount guard** — a `useRef`-based skip-first
+  flag prevents the persist effect from writing the SSR-safe defaults
+  to `localStorage` between mount and the post-mount hydration
+  setState. Previously, the brief window between commit and the
+  hydration effect could clobber the user's stored preference if the
+  page closed mid-render. After the first call, every subsequent
+  change (user-driven OR hydration-promoted) persists normally. (#TBD)
+### Added
+- **`<ThemeScript defaultDensity>` prop** — the inline `<script>`
+  bootstrap now also sets `data-density` on `<html>` from
+  `localStorage.getItem(":density")` (or `defaultDensity`, default
+  `"comfortable"`) so density-driven layouts have zero FOUC at first
+  paint. Mirrors `ThemeProvider`'s `defaultDensity`. (#TBD)
+### Notes
+- Pattern mirrors `next-themes` (Vercel), `MantineProvider`, and
+  shadcn/ui's theme scaffold. The 1-frame state-promotion delay is the
+  React-canonical price for SSR-safe client-only state. `<ThemeScript>`
+  pre-paints the `<html>` attributes so the visible layer doesn't
+  flicker.
+- Two new unit tests guard the regression:
+  - `does NOT write to localStorage on first mount when nothing changes
+    (persist gate)` — verifies the skip-first guard.
+  - `writes to localStorage AFTER a user-driven change (persist fires
+    post-hydration)` — verifies the gate releases after the first call.
+- Existing `reads initial theme name from localStorage` and `reads
+  initial mode from localStorage` tests continue to pass because
+  testing-library's `render()` flushes effects synchronously inside
+  `act()`, so by the assertion phase the post-mount hydration effect
+  has already promoted the stored value.
 ## [0.6.2-next.0] - 2026-05-23
 Patch — restore `cursor: pointer` on interactive buttons. Tailwind v4

package/dist/index.d.ts CHANGED Viewed

@@ -194,6 +194,14 @@ interface ThemeScriptProps {
     defaultTheme?: string;
     /** Mode to apply when no persisted value exists. Default `"dark"`. */
     defaultMode?: ThemeMode;
+    /**
+     * Density to apply when no persisted value exists. Default `"comfortable"`.
+     * Mirrors `ThemeProvider`'s `defaultDensity` so the inline-script and
+     * the React provider agree on the SSR-default density (and the
+     * `data-density` attribute set by this script matches what
+     * `ThemeProvider` promotes via its post-mount hydration effect).
+     */
+    defaultDensity?: "compact" | "comfortable" | "spacious";
     /**
      * localStorage namespace. Must match the `storageKey` passed to
      * `<ThemeProvider>`. Default `"theo-ui:theme"`. Pass `null` to disable
@@ -201,7 +209,7 @@ interface ThemeScriptProps {
      */
     storageKey?: string | null;
 }
-declare function ThemeScript({ defaultTheme, defaultMode, storageKey, }: ThemeScriptProps): JSX$1.Element;
+declare function ThemeScript({ defaultTheme, defaultMode, defaultDensity, storageKey, }: ThemeScriptProps): JSX$1.Element;
 interface ThemeSwitcherProps {
     className?: string;

package/dist/index.js CHANGED Viewed

@@ -188,35 +188,25 @@ function ThemeProvider({
   useEffect(() => {
     setThemes(mergedThemes);
   }, [mergedThemes]);
-  const [themeName, setThemeName] = useState(() => {
-    if (typeof window === "undefined" || !storageKey) return defaultTheme;
-    try {
-      return window.localStorage.getItem(`${storageKey}:name`) ?? defaultTheme;
-    } catch (err) {
-      warnStorageFailure("read theme name", err);
-      return defaultTheme;
-    }
-  });
-  const [mode, setModeState] = useState(() => {
-    if (typeof window === "undefined" || !storageKey) return defaultMode;
-    try {
-      const stored = window.localStorage.getItem(`${storageKey}:mode`);
-      return stored === "dark" || stored === "light" ? stored : defaultMode;
-    } catch (err) {
-      warnStorageFailure("read theme mode", err);
-      return defaultMode;
-    }
-  });
-  const [density, setDensityState] = useState(() => {
-    if (typeof window === "undefined" || !storageKey) return defaultDensity;
+  const [themeName, setThemeName] = useState(defaultTheme);
+  const [mode, setModeState] = useState(defaultMode);
+  const [density, setDensityState] = useState(defaultDensity);
+  const skipFirstPersistRef = useRef(true);
+  useEffect(() => {
+    if (typeof window === "undefined" || !storageKey) return;
     try {
-      const stored = window.localStorage.getItem(`${storageKey}:density`);
-      return stored === "compact" || stored === "comfortable" || stored === "spacious" ? stored : defaultDensity;
+      const storedName = window.localStorage.getItem(`${storageKey}:name`);
+      const storedMode = window.localStorage.getItem(`${storageKey}:mode`);
+      const storedDensity = window.localStorage.getItem(`${storageKey}:density`);
+      if (storedName) setThemeName(storedName);
+      if (storedMode === "dark" || storedMode === "light") setModeState(storedMode);
+      if (storedDensity === "compact" || storedDensity === "comfortable" || storedDensity === "spacious") {
+        setDensityState(storedDensity);
+      }
     } catch (err) {
-      warnStorageFailure("read density", err);
-      return defaultDensity;
+      warnStorageFailure("read theme + mode + density", err);
     }
-  });
+  }, [storageKey]);
   useEffect(() => {
     injectThemeCss(themes);
   }, [themes]);
@@ -232,6 +222,10 @@ function ThemeProvider({
     injectDensityCss();
   }, [themeName, mode, density, themes]);
   useEffect(() => {
+    if (skipFirstPersistRef.current) {
+      skipFirstPersistRef.current = false;
+      return;
+    }
     if (typeof window === "undefined" || !storageKey) return;
     try {
       window.localStorage.setItem(`${storageKey}:name`, themeName);
@@ -285,18 +279,20 @@ function useTheme() {
 function safe(value) {
   return JSON.stringify(value).replace(/</g, "\\u003c");
 }
-function buildScript(defaultTheme, defaultMode, storageKey) {
+function buildScript(defaultTheme, defaultMode, defaultDensity, storageKey) {
   const k = safe(storageKey);
   const t = safe(defaultTheme);
   const m = safe(defaultMode);
-  return `(function(){try{var k=${k};var d=document.documentElement;var t=null;var m=null;if(k){t=localStorage.getItem(k+":name");m=localStorage.getItem(k+":mode");}d.setAttribute("data-theme",t||${t});d.setAttribute("data-mode",m||${m});if((m||${m})==="dark"){d.classList.add("dark");}}catch(e){}})();`;
+  const dn = safe(defaultDensity);
+  return `(function(){try{var k=${k};var d=document.documentElement;var t=null;var m=null;var dn=null;if(k){t=localStorage.getItem(k+":name");m=localStorage.getItem(k+":mode");dn=localStorage.getItem(k+":density");}d.setAttribute("data-theme",t||${t});d.setAttribute("data-mode",m||${m});d.setAttribute("data-density",dn||${dn});if((m||${m})==="dark"){d.classList.add("dark");}}catch(e){}})();`;
 }
 function ThemeScript({
   defaultTheme = "violet-forge",
   defaultMode = "dark",
+  defaultDensity = "comfortable",
   storageKey = "theo-ui:theme"
 }) {
-  const code = buildScript(defaultTheme, defaultMode, storageKey);
+  const code = buildScript(defaultTheme, defaultMode, defaultDensity, storageKey);
   return /* @__PURE__ */ jsx("script", { suppressHydrationWarning: true, dangerouslySetInnerHTML: { __html: code } });
 }
 function ThemeSwitcher({ className, showModeToggle = true }) {