@codefast/theme 0.3.11 → 0.3.12-canary.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 (47) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +56 -27
  3. package/dist/adapters/tanstack-start/server.d.ts +41 -13
  4. package/dist/adapters/tanstack-start/server.d.ts.map +1 -0
  5. package/dist/adapters/tanstack-start/server.js +91 -64
  6. package/dist/constants.d.ts +9 -12
  7. package/dist/constants.d.ts.map +1 -0
  8. package/dist/constants.js +31 -28
  9. package/dist/core/context.d.ts +4 -7
  10. package/dist/core/context.d.ts.map +1 -0
  11. package/dist/core/context.js +9 -12
  12. package/dist/core/index.d.ts +4 -4
  13. package/dist/core/index.d.ts.map +1 -0
  14. package/dist/core/index.js +3 -4
  15. package/dist/core/provider.d.ts +56 -35
  16. package/dist/core/provider.d.ts.map +1 -0
  17. package/dist/core/provider.js +155 -109
  18. package/dist/core/use-theme.d.ts +3 -6
  19. package/dist/core/use-theme.d.ts.map +1 -0
  20. package/dist/core/use-theme.js +35 -33
  21. package/dist/index.d.ts +17 -9
  22. package/dist/index.d.ts.map +1 -0
  23. package/dist/index.js +19 -9
  24. package/dist/script/index.d.ts +2 -2
  25. package/dist/script/index.d.ts.map +1 -0
  26. package/dist/script/index.js +1 -2
  27. package/dist/script/theme-script.d.ts +12 -15
  28. package/dist/script/theme-script.d.ts.map +1 -0
  29. package/dist/script/theme-script.js +30 -27
  30. package/dist/start.d.ts +47 -0
  31. package/dist/start.d.ts.map +1 -0
  32. package/dist/start.js +46 -0
  33. package/dist/types.d.ts +13 -16
  34. package/dist/types.d.ts.map +1 -0
  35. package/dist/types.js +14 -18
  36. package/dist/utils/dom.d.ts +4 -7
  37. package/dist/utils/dom.d.ts.map +1 -0
  38. package/dist/utils/dom.js +62 -46
  39. package/dist/utils/index.d.ts +3 -3
  40. package/dist/utils/index.d.ts.map +1 -0
  41. package/dist/utils/index.js +2 -3
  42. package/dist/utils/system.d.ts +12 -10
  43. package/dist/utils/system.d.ts.map +1 -0
  44. package/dist/utils/system.js +38 -25
  45. package/package.json +17 -11
  46. package/dist/adapters/tanstack-start/index.d.ts +0 -2
  47. package/dist/adapters/tanstack-start/index.js +0 -2
@@ -1,30 +1,44 @@
1
- import { Theme } from "../types.js";
2
- import { JSX, ReactNode } from "react";
3
-
4
- //#region src/core/provider.d.ts
1
+ import type { JSX, ReactNode } from "react";
2
+ import type { ResolvedTheme, Theme } from "#types";
5
3
  interface ThemeProviderProps {
6
- children: ReactNode;
7
- /**
8
- * When true, temporarily disables CSS transitions during theme changes.
9
- * Prevents jarring color animations when switching themes.
10
- * Default: false
11
- */
12
- disableTransitionOnChange?: boolean;
13
- /**
14
- * CSP nonce for inline styles when `disableTransitionOnChange` is enabled.
15
- */
16
- nonce?: string;
17
- /**
18
- * Async function to persist theme changes to server/storage.
19
- *
20
- * For TanStack Start: use `setThemeServerFn` from `@codefast/theme/tanstack-start`
21
- * For Next.js: implement a server action
22
- */
23
- persistTheme?: (value: Theme) => Promise<void>;
24
- /**
25
- * Initial theme from server (typically from cookie via loader).
26
- */
27
- theme: Theme;
4
+ children: ReactNode;
5
+ /**
6
+ * When true, temporarily disables CSS transitions during theme changes.
7
+ * Prevents jarring color animations when switching themes.
8
+ * Default: false
9
+ */
10
+ disableTransitionOnChange?: boolean;
11
+ /**
12
+ * CSP nonce for inline styles when `disableTransitionOnChange` is enabled.
13
+ */
14
+ nonce?: string;
15
+ /**
16
+ * Async function to persist theme changes to server/storage.
17
+ *
18
+ * For TanStack Start: use `setThemeServerFn` from `@codefast/theme/start`
19
+ * For Next.js: implement a server action
20
+ */
21
+ persistTheme?: (value: Theme) => Promise<void>;
22
+ /**
23
+ * Initial theme from server (typically from cookie via loader).
24
+ */
25
+ theme: Theme;
26
+ /**
27
+ * OS light/dark guess from the SSR request (e.g. `Sec-CH-Prefers-Color-Scheme`).
28
+ *
29
+ * When the stored preference is `system`, {@link useSyncExternalStore} uses this for
30
+ * `getServerSnapshot` so the first client snapshot matches `matchMedia` and avoids a
31
+ * dark → light flip after hydration.
32
+ */
33
+ ssrSystemTheme?: ResolvedTheme;
34
+ /**
35
+ * After mount, re-read the canonical theme from the server (e.g. httpOnly cookie).
36
+ *
37
+ * Fixes **stale HTML / disk cache** on “Duplicate tab” or back-forward cache where the
38
+ * document was saved with an old `ThemeScript` / loader value while the cookie was already updated
39
+ * in another tab. Use a stable reference (e.g. `getThemeServerFn` from `@codefast/theme/start`).
40
+ */
41
+ syncThemeFromServer?: () => Promise<Theme>;
28
42
  }
29
43
  /**
30
44
  * Provider component for theme state management.
@@ -34,6 +48,19 @@ interface ThemeProviderProps {
34
48
  * - `useSyncExternalStore` - SSR-safe subscription to OS theme preference
35
49
  * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
36
50
  *
51
+ * @param props - Component props
52
+ * @param props.children - React tree to provide context for
53
+ * @param props.theme - Initial preference from the server (cookie, loader, etc.)
54
+ * @param props.ssrSystemTheme - Best-effort `light` or `dark` from the SSR request
55
+ * (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `system`, this value is used as
56
+ * `useSyncExternalStore`'s server snapshot so the first client snapshot matches `matchMedia`
57
+ * and avoids a post-hydration flip. Omit if unavailable; falls back to {@link DEFAULT_RESOLVED_THEME}.
58
+ * @param props.syncThemeFromServer - Optional one-shot RPC after mount to align with the cookie when SSR/HTML was stale.
59
+ * @param props.persistTheme - Optional async handler to persist preference (cookie, server action, …)
60
+ * @param props.disableTransitionOnChange - Temporarily disable CSS transitions on theme change
61
+ * @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransitionOnChange` is set
62
+ * @returns Provider element wrapping `children`
63
+ *
37
64
  * @example
38
65
  * ```tsx
39
66
  * // In your root layout
@@ -45,12 +72,6 @@ interface ThemeProviderProps {
45
72
  * </ThemeProvider>
46
73
  * ```
47
74
  */
48
- declare function ThemeProvider({
49
- children,
50
- disableTransitionOnChange,
51
- nonce,
52
- persistTheme,
53
- theme: initialTheme
54
- }: ThemeProviderProps): JSX.Element;
55
- //#endregion
56
- export { ThemeProvider };
75
+ export declare function ThemeProvider({ children, disableTransitionOnChange, nonce, persistTheme, ssrSystemTheme, syncThemeFromServer, theme: initialTheme, }: ThemeProviderProps): JSX.Element;
76
+ export {};
77
+ //# sourceMappingURL=provider.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/core/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAc5C,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAoB,MAAM,QAAQ,CAAC;AAwCrE,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;IACb;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;CAC5C;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,yBAAiC,EACjC,KAAK,EACL,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,KAAK,EAAE,YAAY,GACpB,EAAE,kBAAkB,GAAG,GAAG,CAAC,OAAO,CAwIlC"}
@@ -1,117 +1,163 @@
1
- import { DEFAULT_RESOLVED_THEME, MEDIA, THEME_CHANNEL } from "../constants.js";
2
- import { ThemeContext } from "./context.js";
3
- import { applyTheme, disableAnimation } from "../utils/dom.js";
4
- import { getSystemTheme } from "../utils/system.js";
5
- import { startTransition, useCallback, useEffect, useEffectEvent, useMemo, useOptimistic, useState, useSyncExternalStore } from "react";
6
- import { jsx } from "react/jsx-runtime";
7
- //#region src/core/provider.tsx
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { startTransition, useCallback, useEffect, useEffectEvent, useMemo, useOptimistic, useRef, useState, useSyncExternalStore, } from "react";
3
+ import { DEFAULT_RESOLVED_THEME, MEDIA, THEME_CHANNEL } from "#constants";
4
+ import { ThemeContext } from "#core/context";
5
+ import { applyTheme, disableAnimation, getSystemTheme } from "#utils";
6
+ /* -----------------------------------------------------------------------------
7
+ * System Theme Subscription
8
+ *
9
+ * These functions power `useSyncExternalStore` for reactive system theme detection.
10
+ * This pattern ensures SSR safety and efficient re-renders on OS preference changes.
11
+ * -------------------------------------------------------------------------- */
8
12
  /**
9
- * Subscribe to OS theme preference changes.
10
- *
11
- * @param callback - Function to call when system theme changes
12
- * @returns Cleanup function to remove the listener
13
- */
13
+ * Subscribe to OS theme preference changes.
14
+ *
15
+ * @param callback - Function to call when system theme changes
16
+ * @returns Cleanup function to remove the listener
17
+ */
14
18
  function subscribeToSystemTheme(callback) {
15
- const mediaQuery = window.matchMedia(MEDIA);
16
- mediaQuery.addEventListener("change", callback);
17
- return () => {
18
- mediaQuery.removeEventListener("change", callback);
19
- };
19
+ const mediaQuery = window.matchMedia(MEDIA);
20
+ mediaQuery.addEventListener("change", callback);
21
+ return () => {
22
+ mediaQuery.removeEventListener("change", callback);
23
+ };
20
24
  }
21
25
  /**
22
- * Get current system theme on the client.
23
- */
26
+ * Get current system theme on the client.
27
+ */
24
28
  function getSystemThemeSnapshot() {
25
- return getSystemTheme();
29
+ return getSystemTheme();
26
30
  }
31
+ /* -----------------------------------------------------------------------------
32
+ * Component
33
+ * -------------------------------------------------------------------------- */
27
34
  /**
28
- * Server snapshot returns default theme since `matchMedia` is unavailable during SSR.
29
- */
30
- function getServerSnapshot() {
31
- return DEFAULT_RESOLVED_THEME;
35
+ * Provider component for theme state management.
36
+ *
37
+ * **React 19 Features Used:**
38
+ * - `useOptimistic` - Immediate UI feedback while persisting theme
39
+ * - `useSyncExternalStore` - SSR-safe subscription to OS theme preference
40
+ * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
41
+ *
42
+ * @param props - Component props
43
+ * @param props.children - React tree to provide context for
44
+ * @param props.theme - Initial preference from the server (cookie, loader, etc.)
45
+ * @param props.ssrSystemTheme - Best-effort `light` or `dark` from the SSR request
46
+ * (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `system`, this value is used as
47
+ * `useSyncExternalStore`'s server snapshot so the first client snapshot matches `matchMedia`
48
+ * and avoids a post-hydration flip. Omit if unavailable; falls back to {@link DEFAULT_RESOLVED_THEME}.
49
+ * @param props.syncThemeFromServer - Optional one-shot RPC after mount to align with the cookie when SSR/HTML was stale.
50
+ * @param props.persistTheme - Optional async handler to persist preference (cookie, server action, …)
51
+ * @param props.disableTransitionOnChange - Temporarily disable CSS transitions on theme change
52
+ * @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransitionOnChange` is set
53
+ * @returns Provider element wrapping `children`
54
+ *
55
+ * @example
56
+ * ```tsx
57
+ * // In your root layout
58
+ * <ThemeProvider
59
+ * theme={theme}
60
+ * persistTheme={(value) => setThemeServerFn({ data: value })}
61
+ * >
62
+ * {children}
63
+ * </ThemeProvider>
64
+ * ```
65
+ */
66
+ export function ThemeProvider({ children, disableTransitionOnChange = false, nonce, persistTheme, ssrSystemTheme, syncThemeFromServer, theme: initialTheme, }) {
67
+ // Actual persisted theme (source of truth after server confirms)
68
+ const [theme, setThemeState] = useState(initialTheme);
69
+ // Optimistic theme - immediately reflects user's intent while async operation runs
70
+ // Automatically reverts to `theme` if the transition fails
71
+ const [optimisticTheme, setOptimisticTheme] = useOptimistic(theme);
72
+ // True when there's a pending theme change (optimistic !== actual)
73
+ const isPending = optimisticTheme !== theme;
74
+ const syncThemeFromServerRef = useRef(syncThemeFromServer);
75
+ syncThemeFromServerRef.current = syncThemeFromServer;
76
+ useEffect(() => {
77
+ const sync = syncThemeFromServerRef.current;
78
+ if (!sync) {
79
+ return;
80
+ }
81
+ let cancelled = false;
82
+ void (async () => {
83
+ try {
84
+ const serverTheme = await sync();
85
+ if (cancelled) {
86
+ return;
87
+ }
88
+ startTransition(() => {
89
+ setThemeState((prev) => (prev === serverTheme ? prev : serverTheme));
90
+ });
91
+ }
92
+ catch {
93
+ /* keep SSR / loader state */
94
+ }
95
+ })();
96
+ return () => {
97
+ cancelled = true;
98
+ };
99
+ }, []);
100
+ const getServerSnapshot = useCallback(() => {
101
+ return ssrSystemTheme ?? DEFAULT_RESOLVED_THEME;
102
+ }, [ssrSystemTheme]);
103
+ // Subscribe to OS preference changes (SSR-safe via useSyncExternalStore)
104
+ const systemTheme = useSyncExternalStore(subscribeToSystemTheme, getSystemThemeSnapshot, getServerSnapshot);
105
+ // Compute the actual theme to apply: resolve 'system' to light/dark
106
+ const resolvedTheme = useMemo(() => (optimisticTheme === "system" ? systemTheme : optimisticTheme), [optimisticTheme, systemTheme]);
107
+ // Apply theme class and color-scheme to <html> when resolved theme changes
108
+ useEffect(() => {
109
+ applyTheme(resolvedTheme);
110
+ }, [resolvedTheme]);
111
+ // Handle cross-tab theme sync via BroadcastChannel
112
+ const handleCrossTabMessage = useEffectEvent((event) => {
113
+ const newTheme = event.data;
114
+ if (newTheme === theme)
115
+ return;
116
+ startTransition(() => {
117
+ setThemeState(newTheme);
118
+ });
119
+ });
120
+ useEffect(() => {
121
+ const channel = new BroadcastChannel(THEME_CHANNEL);
122
+ channel.addEventListener("message", handleCrossTabMessage);
123
+ return () => {
124
+ channel.removeEventListener("message", handleCrossTabMessage);
125
+ channel.close();
126
+ };
127
+ }, []);
128
+ const setTheme = useCallback(async (value) => {
129
+ await Promise.resolve();
130
+ if (value === theme)
131
+ return;
132
+ // Optionally disable animations during theme switch
133
+ const enable = disableTransitionOnChange ? disableAnimation(nonce) : null;
134
+ // Wrap in startTransition for proper concurrent mode handling
135
+ startTransition(async () => {
136
+ // Show new theme immediately (optimistic update)
137
+ setOptimisticTheme(value);
138
+ try {
139
+ // Persist to server/storage
140
+ if (persistTheme) {
141
+ await persistTheme(value);
142
+ }
143
+ // Server confirmed - commit to actual state
144
+ setThemeState(value);
145
+ // Notify other tabs
146
+ const channel = new BroadcastChannel(THEME_CHANNEL);
147
+ channel.postMessage(value);
148
+ channel.close();
149
+ }
150
+ catch (error) {
151
+ // On failure, useOptimistic automatically reverts to `theme`
152
+ console.error("Failed to set theme:", error);
153
+ }
154
+ finally {
155
+ // Re-enable animations
156
+ enable?.();
157
+ }
158
+ });
159
+ }, [theme, disableTransitionOnChange, nonce, setOptimisticTheme, persistTheme]);
160
+ // Expose optimistic theme so consumers see immediate updates
161
+ const value = useMemo(() => ({ isPending, resolvedTheme, setTheme, theme: optimisticTheme }), [optimisticTheme, resolvedTheme, setTheme, isPending]);
162
+ return _jsx(ThemeContext, { value: value, children: children });
32
163
  }
33
- /**
34
- * Provider component for theme state management.
35
- *
36
- * **React 19 Features Used:**
37
- * - `useOptimistic` - Immediate UI feedback while persisting theme
38
- * - `useSyncExternalStore` - SSR-safe subscription to OS theme preference
39
- * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
40
- *
41
- * @example
42
- * ```tsx
43
- * // In your root layout
44
- * <ThemeProvider
45
- * theme={theme}
46
- * persistTheme={(value) => setThemeServerFn({ data: value })}
47
- * >
48
- * {children}
49
- * </ThemeProvider>
50
- * ```
51
- */
52
- function ThemeProvider({ children, disableTransitionOnChange = false, nonce, persistTheme, theme: initialTheme }) {
53
- const [theme, setThemeState] = useState(initialTheme);
54
- const [optimisticTheme, setOptimisticTheme] = useOptimistic(theme);
55
- const isPending = optimisticTheme !== theme;
56
- const systemTheme = useSyncExternalStore(subscribeToSystemTheme, getSystemThemeSnapshot, getServerSnapshot);
57
- const resolvedTheme = useMemo(() => optimisticTheme === "system" ? systemTheme : optimisticTheme, [optimisticTheme, systemTheme]);
58
- useEffect(() => {
59
- applyTheme(resolvedTheme);
60
- }, [resolvedTheme]);
61
- const handleCrossTabMessage = useEffectEvent((event) => {
62
- const newTheme = event.data;
63
- if (newTheme === theme) return;
64
- startTransition(() => {
65
- setThemeState(newTheme);
66
- });
67
- });
68
- useEffect(() => {
69
- const channel = new BroadcastChannel(THEME_CHANNEL);
70
- channel.addEventListener("message", handleCrossTabMessage);
71
- return () => {
72
- channel.removeEventListener("message", handleCrossTabMessage);
73
- channel.close();
74
- };
75
- }, []);
76
- const setTheme = useCallback(async (value) => {
77
- await Promise.resolve();
78
- if (value === theme) return;
79
- const enable = disableTransitionOnChange ? disableAnimation(nonce) : null;
80
- startTransition(async () => {
81
- setOptimisticTheme(value);
82
- try {
83
- if (persistTheme) await persistTheme(value);
84
- setThemeState(value);
85
- const channel = new BroadcastChannel(THEME_CHANNEL);
86
- channel.postMessage(value);
87
- channel.close();
88
- } catch (error) {
89
- console.error("Failed to set theme:", error);
90
- } finally {
91
- enable?.();
92
- }
93
- });
94
- }, [
95
- theme,
96
- disableTransitionOnChange,
97
- nonce,
98
- setOptimisticTheme,
99
- persistTheme
100
- ]);
101
- return /* @__PURE__ */ jsx(ThemeContext, {
102
- value: useMemo(() => ({
103
- isPending,
104
- resolvedTheme,
105
- setTheme,
106
- theme: optimisticTheme
107
- }), [
108
- optimisticTheme,
109
- resolvedTheme,
110
- setTheme,
111
- isPending
112
- ]),
113
- children
114
- });
115
- }
116
- //#endregion
117
- export { ThemeProvider };
@@ -1,6 +1,4 @@
1
- import { ThemeContextType } from "../types.js";
2
-
3
- //#region src/core/use-theme.d.ts
1
+ import type { ThemeContextType } from "#types";
4
2
  /**
5
3
  * Hook to access theme context.
6
4
  *
@@ -27,6 +25,5 @@ import { ThemeContextType } from "../types.js";
27
25
  * }
28
26
  * ```
29
27
  */
30
- declare function useTheme(): ThemeContextType;
31
- //#endregion
32
- export { useTheme };
28
+ export declare function useTheme(): ThemeContextType;
29
+ //# sourceMappingURL=use-theme.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-theme.d.ts","sourceRoot":"","sources":["../../src/core/use-theme.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAQ/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,IAAI,gBAAgB,CAQ3C"}
@@ -1,36 +1,38 @@
1
- import { ThemeContext } from "./context.js";
2
1
  import { use } from "react";
3
- //#region src/core/use-theme.ts
2
+ import { ThemeContext } from "#core/context";
3
+ /* -----------------------------------------------------------------------------
4
+ * Hook
5
+ * -------------------------------------------------------------------------- */
4
6
  /**
5
- * Hook to access theme context.
6
- *
7
- * Uses React 19's `use()` API for context consumption, enabling:
8
- * - Conditional context reading
9
- * - Better Suspense boundary integration
10
- *
11
- * @returns Theme context with `theme`, `resolvedTheme`, `setTheme`, and `isPending`
12
- * @throws Error if called outside of ThemeProvider
13
- *
14
- * @example
15
- * ```tsx
16
- * function ThemeToggle() {
17
- * const { theme, setTheme, isPending } = useTheme();
18
- *
19
- * return (
20
- * <button
21
- * onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
22
- * disabled={isPending}
23
- * >
24
- * {theme}
25
- * </button>
26
- * );
27
- * }
28
- * ```
29
- */
30
- function useTheme() {
31
- const value = use(ThemeContext);
32
- if (!value) throw new Error("useTheme must be used within a ThemeProvider");
33
- return value;
7
+ * Hook to access theme context.
8
+ *
9
+ * Uses React 19's `use()` API for context consumption, enabling:
10
+ * - Conditional context reading
11
+ * - Better Suspense boundary integration
12
+ *
13
+ * @returns Theme context with `theme`, `resolvedTheme`, `setTheme`, and `isPending`
14
+ * @throws Error if called outside of ThemeProvider
15
+ *
16
+ * @example
17
+ * ```tsx
18
+ * function ThemeToggle() {
19
+ * const { theme, setTheme, isPending } = useTheme();
20
+ *
21
+ * return (
22
+ * <button
23
+ * onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
24
+ * disabled={isPending}
25
+ * >
26
+ * {theme}
27
+ * </button>
28
+ * );
29
+ * }
30
+ * ```
31
+ */
32
+ export function useTheme() {
33
+ const value = use(ThemeContext);
34
+ if (!value) {
35
+ throw new Error("useTheme must be used within a ThemeProvider");
36
+ }
37
+ return value;
34
38
  }
35
- //#endregion
36
- export { useTheme };
package/dist/index.d.ts CHANGED
@@ -1,9 +1,17 @@
1
- import { ResolvedTheme, Theme, ThemeContextType, themeSchema, themes } from "./types.js";
2
- import { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, THEME_STORAGE_KEY } from "./constants.js";
3
- import { ThemeContext } from "./core/context.js";
4
- import { ThemeProvider } from "./core/provider.js";
5
- import { useTheme } from "./core/use-theme.js";
6
- import { ThemeScript } from "./script/theme-script.js";
7
- import { applyTheme, disableAnimation } from "./utils/dom.js";
8
- import { getSystemTheme, resolveTheme } from "./utils/system.js";
9
- export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, type ResolvedTheme, THEME_STORAGE_KEY, type Theme, ThemeContext, type ThemeContextType, ThemeProvider, ThemeScript, applyTheme, disableAnimation, getSystemTheme, resolveTheme, themeSchema, themes, useTheme };
1
+ /**
2
+ * \@codefast/theme
3
+ *
4
+ * React 19 theme management: SSR-friendly `system` resolution, cross-tab sync, optimistic updates.
5
+ *
6
+ * - **Root** (this module): `ThemeProvider`, `useTheme`, `ThemeScript`, `resolveTheme`, types, defaults.
7
+ * - **`@codefast/theme/start`**: TanStack Start server functions + `persistThemeCookie`.
8
+ * - **`@codefast/theme/utils`**: `getSystemTheme`, `applyTheme`, `disableAnimation`.
9
+ * - **`@codefast/theme/core`**: `ThemeContext` for rare custom wiring.
10
+ */
11
+ export type { ResolvedTheme, Theme, ThemeContextType } from "#types";
12
+ export { themes, themeSchema } from "#types";
13
+ export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME } from "#constants";
14
+ export { ThemeProvider, useTheme } from "#core";
15
+ export { ThemeScript } from "#script";
16
+ export { resolveTheme } from "#utils/system";
17
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EAAE,aAAa,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAG7C,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGnE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGhD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}
package/dist/index.js CHANGED
@@ -1,9 +1,19 @@
1
- import { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, THEME_STORAGE_KEY } from "./constants.js";
2
- import { themeSchema, themes } from "./types.js";
3
- import { ThemeContext } from "./core/context.js";
4
- import { applyTheme, disableAnimation } from "./utils/dom.js";
5
- import { getSystemTheme, resolveTheme } from "./utils/system.js";
6
- import { ThemeProvider } from "./core/provider.js";
7
- import { useTheme } from "./core/use-theme.js";
8
- import { ThemeScript } from "./script/theme-script.js";
9
- export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, THEME_STORAGE_KEY, ThemeContext, ThemeProvider, ThemeScript, applyTheme, disableAnimation, getSystemTheme, resolveTheme, themeSchema, themes, useTheme };
1
+ /**
2
+ * \@codefast/theme
3
+ *
4
+ * React 19 theme management: SSR-friendly `system` resolution, cross-tab sync, optimistic updates.
5
+ *
6
+ * - **Root** (this module): `ThemeProvider`, `useTheme`, `ThemeScript`, `resolveTheme`, types, defaults.
7
+ * - **`@codefast/theme/start`**: TanStack Start server functions + `persistThemeCookie`.
8
+ * - **`@codefast/theme/utils`**: `getSystemTheme`, `applyTheme`, `disableAnimation`.
9
+ * - **`@codefast/theme/core`**: `ThemeContext` for rare custom wiring.
10
+ */
11
+ export { themes, themeSchema } from "#types";
12
+ // Constants
13
+ export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME } from "#constants";
14
+ // Core (Provider, Hook — use `@codefast/theme/core` for `ThemeContext`)
15
+ export { ThemeProvider, useTheme } from "#core";
16
+ // Script (FOUC prevention)
17
+ export { ThemeScript } from "#script";
18
+ // Utilities: DOM + `getSystemTheme` live under `@codefast/theme/utils`
19
+ export { resolveTheme } from "#utils/system";
@@ -1,2 +1,2 @@
1
- import { ThemeScript } from "./theme-script.js";
2
- export { ThemeScript };
1
+ export { ThemeScript } from "#script/theme-script";
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/script/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}
@@ -1,2 +1 @@
1
- import { ThemeScript } from "./theme-script.js";
2
- export { ThemeScript };
1
+ export { ThemeScript } from "#script/theme-script";
@@ -1,12 +1,10 @@
1
- import { Theme } from "../types.js";
2
- import { JSX } from "react";
3
-
4
- //#region src/script/theme-script.d.ts
1
+ import type { JSX } from "react";
2
+ import type { Theme } from "#types";
5
3
  interface ThemeScriptProps {
6
- /**
7
- * Initial theme from server (e.g., from cookie via loader).
8
- */
9
- theme: Theme;
4
+ /**
5
+ * Initial theme from server (e.g., from cookie via loader).
6
+ */
7
+ theme: Theme;
10
8
  }
11
9
  /**
12
10
  * Inline script that prevents Flash of Unstyled Content (FOUC).
@@ -19,8 +17,9 @@ interface ThemeScriptProps {
19
17
  * **How it works:**
20
18
  * This script runs synchronously in the `<head>` before first paint:
21
19
  * 1. Resolves 'system' to 'light' or 'dark' using `matchMedia()`
22
- * 2. Adds the theme class to `<html>` immediately
23
- * 3. Sets `color-scheme` for native form controls and scrollbars
20
+ * 2. Removes prior `light` / `dark` / `system` classes on `<html>` (SSR may
21
+ * have applied the wrong resolved class for `system`, e.g. default `dark`)
22
+ * 3. Adds the resolved theme class and sets `color-scheme` for native controls
24
23
  *
25
24
  * @example
26
25
  * ```tsx
@@ -30,8 +29,6 @@ interface ThemeScriptProps {
30
29
  * </head>
31
30
  * ```
32
31
  */
33
- declare function ThemeScript({
34
- theme
35
- }: ThemeScriptProps): JSX.Element;
36
- //#endregion
37
- export { ThemeScript };
32
+ export declare function ThemeScript({ theme }: ThemeScriptProps): JSX.Element;
33
+ export {};
34
+ //# sourceMappingURL=theme-script.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"theme-script.d.ts","sourceRoot":"","sources":["../../src/script/theme-script.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAEjC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAMpC,UAAU,gBAAgB;IACxB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;CACd;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAAG,GAAG,CAAC,OAAO,CAKpE"}