@djangocfg/ui-core 2.1.550 → 2.1.555

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.550",
+  "version": "2.1.555",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -130,7 +130,7 @@
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.550",
+    "@djangocfg/i18n": "^2.1.555",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -206,9 +206,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/eslint-config": "^2.1.550",
-    "@djangocfg/i18n": "^2.1.550",
-    "@djangocfg/typescript-config": "^2.1.550",
+    "@djangocfg/eslint-config": "^2.1.555",
+    "@djangocfg/i18n": "^2.1.555",
+    "@djangocfg/typescript-config": "^2.1.555",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

package/src/hooks/media/useMediaQuery.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useCallback, useSyncExternalStore } from 'react';
 
 /**
  * Tailwind v4 default breakpoints (rem → px at 16px base).
@@ -23,29 +23,44 @@ export type Breakpoint = keyof typeof BREAKPOINTS
 /**
  * Reactive media query hook.
  *
+ * WHY useSyncExternalStore:
+ *   A media query has no server value, so the hydration render MUST return the
+ *   same `false` the server rendered — reading `matchMedia` there makes React
+ *   throw "server rendered HTML didn't match the client" for any component that
+ *   branches on the result (a narrow-viewport `<Sidebar>` renders its drawer
+ *   branch against the server's desktop markup). `getServerSnapshot` is the
+ *   only reliable way to pin that first render: React calls it during hydration
+ *   as well as on the server, then re-renders with the real match after mount.
+ *   A lazy `useState` initializer cannot express that distinction.
+ *
+ *   Consequence to design around: the first painted frame is always the
+ *   `false` branch. Components that must not flash should let CSS decide
+ *   (Tailwind `md:` variants) rather than branch in JS.
+ *
  * @example
  * const isPhone   = useMediaQuery('(max-width: 639px)')
  * const isDark    = useMediaQuery('(prefers-color-scheme: dark)')
  * const isLandscape = useMediaQuery('(orientation: landscape)')
  */
 export function useMediaQuery(query: string): boolean {
-  // Lazy initializer: read the real match on first render in the browser
-  // so we never paint a "desktop" frame on a phone (and vice-versa) before
-  // the first effect runs. SSR / non-browser → false.
-  const [matches, setMatches] = useState<boolean>(() => {
-    if (typeof window === 'undefined') return false
-    return window.matchMedia(query).matches
-  })
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (typeof window === 'undefined' || !window.matchMedia) return () => {}
+      const mediaQuery = window.matchMedia(query)
+      mediaQuery.addEventListener('change', onChange)
+      return () => mediaQuery.removeEventListener('change', onChange)
+    },
+    [query]
+  )
 
-  useEffect(() => {
-    const mediaQuery = window.matchMedia(query)
-    // Re-sync once on mount in case the lazy initializer was skipped
-    // (e.g. hydration mismatch where SSR gave false).
-    setMatches(mediaQuery.matches)
-    const handler = (event: MediaQueryListEvent) => setMatches(event.matches)
-    mediaQuery.addEventListener('change', handler)
-    return () => mediaQuery.removeEventListener('change', handler)
+  const getSnapshot = useCallback(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return false
+    return window.matchMedia(query).matches
   }, [query])
 
-  return matches
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}
+
+function getServerSnapshot(): boolean {
+  return false
 }