@thangnqdev/ui 0.2.2 → 0.2.3

package/dist/index.js

@@ -2,7 +2,7 @@ export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Avatar, A
 export { Alert, AlertDescription, AlertTitle, CircularProgress, EmptyState, feedback_exports as Feedback, ProgressBar, Skeleton, SkeletonCircle, SkeletonText, Spinner, alertVariants, progressVariants, spinnerVariants } from './chunk-WAFHC4DQ.js';
 export { glass_exports as Glass, GlassBadge, GlassButton, GlassCard } from './chunk-A7P3O5Z5.js';
 export { bento_exports as Bento, BentoCard, BentoGrid } from './chunk-C4SUXMI3.js';
-export { core_exports as Core, ThemeProvider, useTheme } from './chunk-DUPPPGXY.js';
+export { core_exports as Core, ThemeProvider, useTheme } from './chunk-2ANJFOIU.js';
 export { AspectRatio, Container, Divider, Flex, Grid, GridItem, HStack, layout_exports as Layout, PageHeader, PageLayout, PageSidebar, ScrollArea, Section, Spacer, Stack, VStack, containerVariants, dividerVariants, flexVariants, gridItemVariants, gridVariants, sectionVariants, stackVariants } from './chunk-2OXZK6IP.js';
 export { Blockquote, Code, CodeBlock, Heading, Link, Text, typography_exports as Typography, headingVariants, linkVariants, textVariants } from './chunk-ATYGDTMK.js';
 export { ButtonGroup, buttons_exports as Buttons, IconButton, SplitButton, ToggleButton, ToggleGroup, buttonGroupVariants, iconButtonVariants, toggleVariants } from './chunk-KUQWUTZA.js';

package/llms.txt

@@ -1,7 +1,7 @@
 # @thangnqdev/ui — Full Architecture Component System Contract
 
 > Machine-readable specification for AI Coding Agents (Claude Code, Antigravity, Cursor, Qwen, Codex).
-> Package: `@thangnqdev/ui` (v0.2.2)
+> Package: `@thangnqdev/ui` (v0.2.3)
 > Total Registered SSOT Components: 145
 > Aesthetic Core: Spatial Optics, Editorial Bento, and Enterprise-grade Accessible Primitives.
 > Sub-module Exports: `core`, `layout`, `typography`, `buttons`, `forms`, `overlays`, `navigation`, `data-display`, `feedback`, `glass`, `bento`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thangnqdev/ui",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "description": "Spatial Optics & Editorial Bento UI System with Machine-Readable AI Contracts",
   "license": "MIT",

package/src/core/ThemeProvider.tsx

@@ -1,4 +1,13 @@
-import React, { createContext, useContext, useEffect, useState, useMemo, useCallback } from 'react';
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 
 export type Theme = 'dark' | 'light' | 'system';
 
@@ -17,7 +26,13 @@ interface ThemeContextType {
   toggleTheme: () => void;
 }
 
-const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
+const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
+
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+function isTheme(value: string | null): value is Theme {
+  return value === 'dark' || value === 'light' || value === 'system';
+}
 
 export function ThemeProvider({
   children,
@@ -28,9 +43,10 @@ export function ThemeProvider({
 }: ThemeProviderProps) {
   // Always initialize identically on SSR and initial client pass to avoid hydration mismatches
   const [theme, setThemeState] = useState<Theme>(defaultTheme);
-  const [resolvedTheme, setResolvedTheme] = useState<'dark' | 'light'>(
+  const [resolvedTheme, setResolvedTheme] = useState<'dark' | 'light'>(
     defaultTheme === 'dark' ? 'dark' : 'light'
-  );
+  );
+  const pendingStoredThemeRef = useRef<{ storageKey: string; theme: Theme } | null>(null);
 
   const computeResolved = useCallback(
     (t: Theme): 'dark' | 'light' => {
@@ -42,69 +58,71 @@ export function ThemeProvider({
     [enableSystem]
   );
 
-  // Client-side initialization: read storage once mounted
-  useEffect(() => {
-    if (typeof window === 'undefined') return;
-
-    try {
+  const applyResolvedTheme = useCallback(
+    (nextResolvedTheme: 'dark' | 'light') => {
+      setResolvedTheme(nextResolvedTheme);
+
+      if (typeof document === 'undefined') return;
+
+      const root = document.documentElement;
+      root.setAttribute(attribute, nextResolvedTheme);
+      root.classList.toggle('dark', nextResolvedTheme === 'dark');
+      root.classList.toggle('light', nextResolvedTheme === 'light');
+    },
+    [attribute]
+  );
+
+  // Read the persisted value before paint. The pending ref prevents the DOM/storage
+  // sync below from writing defaultTheme over a different persisted theme first.
+  useIsomorphicLayoutEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    let initialTheme = defaultTheme;
+    try {
       const stored = window.localStorage?.getItem(storageKey);
-      if (stored === 'dark' || stored === 'light' || stored === 'system') {
-        setThemeState(stored);
-      }
-    } catch {
-      // Ignore storage access errors in restricted iframe/incognito environments
-    }
+      if (isTheme(stored)) initialTheme = stored;
+    } catch {
+      // Ignore storage access errors in restricted iframe/incognito environments
+    }
+
+    pendingStoredThemeRef.current = { storageKey, theme: initialTheme };
+    setThemeState((currentTheme) => (currentTheme === initialTheme ? currentTheme : initialTheme));
   }, [storageKey]);
-
-  // Sync theme changes to DOM and storage
-  useEffect(() => {
-    if (typeof document === 'undefined') return;
-
-    const root = document.documentElement;
-    const currentResolved = computeResolved(theme);
-    setResolvedTheme(currentResolved);
-
-    root.setAttribute(attribute, currentResolved);
-    if (currentResolved === 'dark') {
-      root.classList.add('dark');
-      root.classList.remove('light');
-    } else {
-      root.classList.add('light');
-      root.classList.remove('dark');
-    }
-
-    if (typeof window !== 'undefined' && typeof window.localStorage !== 'undefined') {
-      try {
+
+  // Apply user changes before paint. Storage initialization and user updates now
+  // have a single write direction, so a click cannot oscillate light <-> dark.
+  useIsomorphicLayoutEffect(() => {
+    const pendingStoredTheme = pendingStoredThemeRef.current;
+    if (pendingStoredTheme?.storageKey === storageKey) {
+      if (pendingStoredTheme.theme !== theme) return;
+      pendingStoredThemeRef.current = null;
+    }
+
+    const currentResolved = computeResolved(theme);
+    applyResolvedTheme(currentResolved);
+
+    if (typeof window !== 'undefined' && typeof window.localStorage !== 'undefined') {
+      try {
         window.localStorage.setItem(storageKey, theme);
       } catch {
-        // Ignore storage access errors
-      }
-    }
-  }, [theme, attribute, computeResolved, storageKey]);
+        // Ignore storage access errors
+      }
+    }
+  }, [theme, computeResolved, applyResolvedTheme, storageKey]);
 
   // System media query listener
   useEffect(() => {
     if (theme !== 'system' || !enableSystem || typeof window === 'undefined' || !window.matchMedia) return;
 
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
-    const handleChange = () => {
-      const newResolved = mediaQuery.matches ? 'dark' : 'light';
-      setResolvedTheme(newResolved);
-      if (typeof document !== 'undefined') {
-        document.documentElement.setAttribute(attribute, newResolved);
-        if (newResolved === 'dark') {
-          document.documentElement.classList.add('dark');
-          document.documentElement.classList.remove('light');
-        } else {
-          document.documentElement.classList.add('light');
-          document.documentElement.classList.remove('dark');
-        }
-      }
-    };
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const handleChange = () => {
+      const newResolved = mediaQuery.matches ? 'dark' : 'light';
+      applyResolvedTheme(newResolved);
+    };
 
-    mediaQuery.addEventListener('change', handleChange);
-    return () => mediaQuery.removeEventListener('change', handleChange);
-  }, [theme, enableSystem, attribute]);
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, [theme, enableSystem, applyResolvedTheme]);
 
   const toggleTheme = () => {
     setThemeState((prev) => {

package/ui-contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "packageName": "@thangnqdev/ui",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "totalComponents": 145,
   "modules": {
     "core": {

package/dist/chunk-DUPPPGXY.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/index.ts","../src/core/ThemeProvider.tsx"],"names":[],"mappings":"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","file":"chunk-DUPPPGXY.js","sourcesContent":["export * from './ThemeProvider';\r\nexport * from '../utils/cn';\r\n","import React, { createContext, useContext, useEffect, useState, useMemo, useCallback } from 'react';\r\n\r\nexport type Theme = 'dark' | 'light' | 'system';\r\n\r\nexport interface ThemeProviderProps {\r\n  children: React.ReactNode;\r\n  defaultTheme?: Theme;\r\n  storageKey?: string;\r\n  attribute?: string;\r\n  enableSystem?: boolean;\r\n}\r\n\r\ninterface ThemeContextType {\r\n  theme: Theme;\r\n  resolvedTheme: 'dark' | 'light';\r\n  setTheme: (theme: Theme) => void;\r\n  toggleTheme: () => void;\r\n}\r\n\r\nconst ThemeContext = createContext<ThemeContextType | undefined>(undefined);\r\n\r\nexport function ThemeProvider({\r\n  children,\r\n  defaultTheme = 'light',\n  storageKey = 'ui-theme',\r\n  attribute = 'data-theme',\r\n  enableSystem = true,\r\n}: ThemeProviderProps) {\r\n  // Always initialize identically on SSR and initial client pass to avoid hydration mismatches\r\n  const [theme, setThemeState] = useState<Theme>(defaultTheme);\r\n  const [resolvedTheme, setResolvedTheme] = useState<'dark' | 'light'>(\r\n    defaultTheme === 'dark' ? 'dark' : 'light'\n  );\r\n\r\n  const computeResolved = useCallback(\r\n    (t: Theme): 'dark' | 'light' => {\r\n      if (t === 'system' && enableSystem && typeof window !== 'undefined' && window.matchMedia) {\r\n        return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';\r\n      }\r\n      return t === 'dark' ? 'dark' : 'light';\r\n    },\r\n    [enableSystem]\r\n  );\r\n\r\n  // Client-side initialization: read storage once mounted\r\n  useEffect(() => {\r\n    if (typeof window === 'undefined') return;\r\n\r\n    try {\r\n      const stored = window.localStorage?.getItem(storageKey);\n      if (stored === 'dark' || stored === 'light' || stored === 'system') {\n        setThemeState(stored);\n      }\n    } catch {\r\n      // Ignore storage access errors in restricted iframe/incognito environments\r\n    }\r\n  }, [storageKey]);\n\r\n  // Sync theme changes to DOM and storage\r\n  useEffect(() => {\r\n    if (typeof document === 'undefined') return;\r\n\r\n    const root = document.documentElement;\r\n    const currentResolved = computeResolved(theme);\r\n    setResolvedTheme(currentResolved);\r\n\r\n    root.setAttribute(attribute, currentResolved);\r\n    if (currentResolved === 'dark') {\r\n      root.classList.add('dark');\r\n      root.classList.remove('light');\r\n    } else {\r\n      root.classList.add('light');\r\n      root.classList.remove('dark');\r\n    }\r\n\r\n    if (typeof window !== 'undefined' && typeof window.localStorage !== 'undefined') {\r\n      try {\r\n        window.localStorage.setItem(storageKey, theme);\r\n      } catch {\r\n        // Ignore storage access errors\r\n      }\r\n    }\r\n  }, [theme, attribute, computeResolved, storageKey]);\r\n\r\n  // System media query listener\r\n  useEffect(() => {\r\n    if (theme !== 'system' || !enableSystem || typeof window === 'undefined' || !window.matchMedia) return;\r\n\r\n    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');\r\n    const handleChange = () => {\r\n      const newResolved = mediaQuery.matches ? 'dark' : 'light';\r\n      setResolvedTheme(newResolved);\r\n      if (typeof document !== 'undefined') {\r\n        document.documentElement.setAttribute(attribute, newResolved);\r\n        if (newResolved === 'dark') {\r\n          document.documentElement.classList.add('dark');\r\n          document.documentElement.classList.remove('light');\r\n        } else {\r\n          document.documentElement.classList.add('light');\r\n          document.documentElement.classList.remove('dark');\r\n        }\r\n      }\r\n    };\r\n\r\n    mediaQuery.addEventListener('change', handleChange);\r\n    return () => mediaQuery.removeEventListener('change', handleChange);\r\n  }, [theme, enableSystem, attribute]);\r\n\r\n  const toggleTheme = () => {\r\n    setThemeState((prev) => {\r\n      if (prev === 'dark') return 'light';\r\n      return 'dark';\r\n    });\r\n  };\r\n\r\n  const value = useMemo(\r\n    () => ({\r\n      theme,\r\n      resolvedTheme,\r\n      setTheme: setThemeState,\r\n      toggleTheme,\r\n    }),\r\n    [theme, resolvedTheme]\r\n  );\r\n\r\n  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;\r\n}\r\n\r\nexport function useTheme(): ThemeContextType {\r\n  const context = useContext(ThemeContext);\r\n  if (!context) {\r\n    throw new Error('useTheme must be used within a ThemeProvider');\r\n  }\r\n  return context;\r\n}\r\n"]}