@codefast/theme 0.3.16-canary.1 → 0.3.16-canary.3

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.
@@ -1,89 +1,102 @@
1
- import { ResolvedTheme, Theme } from "../types.mjs";
1
+ import { ColorScheme, ResolvedColorScheme } from "../types.mjs";
2
2
  import { JSX, ReactNode } from "react";
3
3
 
4
4
  //#region src/core/provider.d.ts
5
- interface ThemeProviderProps {
6
- children: ReactNode;
5
+ /**
6
+ * @since 0.3.16-canary.3
7
+ */
8
+ type AppearanceProviderProps = {
9
+ readonly children: ReactNode;
7
10
  /**
8
- * When true, temporarily disables CSS transitions during theme changes.
9
- * Prevents jarring color animations when switching themes.
11
+ * When true, temporarily suppresses CSS transitions during color scheme changes.
12
+ * Prevents jarring color animations when switching appearances.
10
13
  * Default: false
11
14
  */
12
- disableTransitionOnChange?: boolean;
15
+ readonly disableTransition?: boolean;
13
16
  /**
14
- * CSP nonce for inline styles when `disableTransitionOnChange` is enabled.
17
+ * CSP nonce for inline styles when `disableTransition` is enabled.
15
18
  */
16
- nonce?: string;
19
+ readonly nonce?: string;
17
20
  /**
18
- * Async function to persist theme changes to server/storage.
21
+ * Async function to persist color scheme changes to server/storage.
19
22
  *
20
- * For TanStack Start: use `setThemeServerFn` from `@codefast/theme/start`
23
+ * For TanStack Start: use `persistColorSchemeCookie` from `@codefast/theme/start`
21
24
  * For Next.js: implement a server action
22
25
  */
23
- persistTheme?: (value: Theme) => Promise<void>;
26
+ readonly persistColorScheme?: (value: ColorScheme) => Promise<void>;
24
27
  /**
25
- * Initial theme from server (typically from cookie via loader).
28
+ * Callback invoked when `persistColorScheme` rejects.
29
+ */
30
+ readonly onPersistError?: (error: unknown, attemptedColorScheme: ColorScheme) => void;
31
+ /**
32
+ * Initial color scheme preference from the server (cookie, loader, etc.).
33
+ *
34
+ * After mount, `AppearanceProvider` re-syncs whenever this prop changes — for example, when
35
+ * the router re-runs the root loader after navigation. The server value is authoritative:
36
+ * a new prop value will override any local optimistic state.
26
37
  */
27
- theme: Theme;
38
+ readonly colorScheme: ColorScheme;
28
39
  /**
29
40
  * OS light/dark guess from the SSR request (e.g. `Sec-CH-Prefers-Color-Scheme`).
30
41
  *
31
- * When the stored preference is `system`, {@link useSyncExternalStore} uses this for
42
+ * When the stored preference is `automatic`, {@link useSyncExternalStore} uses this for
32
43
  * `getServerSnapshot` so the first client snapshot matches `matchMedia` and avoids a
33
44
  * dark → light flip after hydration.
34
45
  */
35
- ssrSystemTheme?: ResolvedTheme;
46
+ readonly ssrColorScheme?: ResolvedColorScheme;
36
47
  /**
37
- * After mount, re-read the canonical theme from the server (e.g. httpOnly cookie).
48
+ * After mount, re-read the canonical color scheme from the server (e.g. httpOnly cookie).
38
49
  *
39
- * Fixes **stale HTML / disk cache** on “Duplicate tab” or back-forward cache where the
40
- * document was saved with an old `ThemeScript` / loader value while the cookie was already updated
41
- * in another tab. Use a stable reference (e.g. `getThemeServerFn` from `@codefast/theme/start`).
50
+ * Fixes **stale HTML / disk cache** on "Duplicate tab" or back-forward cache where the
51
+ * document was saved with an old `AppearanceScript` / loader value while the cookie was already updated
52
+ * in another tab. Use a stable reference (e.g. `getColorSchemeServerFn` from `@codefast/theme/start`).
42
53
  */
43
- syncThemeFromServer?: () => Promise<Theme>;
44
- }
54
+ readonly syncFromServer?: () => Promise<ColorScheme>;
55
+ };
45
56
  /**
46
- * Provider component for theme state management.
57
+ * Provider component for color scheme state management.
47
58
  *
48
59
  * **React 19 Features Used:**
49
- * - `useOptimistic` - Immediate UI feedback while persisting theme
50
- * - `useSyncExternalStore` - SSR-safe subscription to OS theme preference
60
+ * - `useOptimistic` - Immediate UI feedback while persisting color scheme
61
+ * - `useSyncExternalStore` - SSR-safe subscription to OS color scheme preference
51
62
  * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
52
63
  *
53
64
  * @param props - Component props
54
65
  * @param props.children - React tree to provide context for
55
- * @param props.theme - Initial preference from the server (cookie, loader, etc.)
56
- * @param props.ssrSystemTheme - Best-effort `light` or `dark` from the SSR request
57
- * (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `system`, this value is used as
66
+ * @param props.colorScheme - Initial preference from the server (cookie, loader, etc.)
67
+ * @param props.ssrColorScheme - Best-effort `light` or `dark` from the SSR request
68
+ * (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `automatic`, this value is used as
58
69
  * `useSyncExternalStore`'s server snapshot so the first client snapshot matches `matchMedia`
59
- * and avoids a post-hydration flip. Omit if unavailable; falls back to {@link DEFAULT_RESOLVED_THEME}.
60
- * @param props.syncThemeFromServer - Optional one-shot RPC after mount to align with the cookie when SSR/HTML was stale.
61
- * @param props.persistTheme - Optional async handler to persist preference (cookie, server action, …)
62
- * @param props.disableTransitionOnChange - Temporarily disable CSS transitions on theme change
63
- * @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransitionOnChange` is set
70
+ * and avoids a post-hydration flip. Omit if unavailable; falls back to {@link DEFAULT_RESOLVED_COLOR_SCHEME}.
71
+ * @param props.syncFromServer - Optional one-shot RPC after mount to align with the cookie when SSR/HTML was stale.
72
+ * @param props.persistColorScheme - Optional async handler to persist preference (cookie, server action, …)
73
+ * @param props.onPersistError - Optional callback for persistence failures
74
+ * @param props.disableTransition - Temporarily suppress CSS transitions on color scheme change
75
+ * @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransition` is set
64
76
  * @returns Provider element wrapping `children`
65
77
  *
66
78
  * @example
67
79
  * ```tsx
68
80
  * // In your root layout
69
- * <ThemeProvider
70
- * theme={theme}
71
- * persistTheme={(value) => setThemeServerFn({ data: value })}
81
+ * <AppearanceProvider
82
+ * colorScheme={colorScheme}
83
+ * persistColorScheme={(value) => setColorSchemeServerFn({ data: value })}
72
84
  * >
73
85
  * {children}
74
- * </ThemeProvider>
86
+ * </AppearanceProvider>
75
87
  * ```
76
88
  *
77
89
  * @since 0.3.16-canary.0
78
90
  */
79
- declare function ThemeProvider({
91
+ declare function AppearanceProvider({
80
92
  children,
81
- disableTransitionOnChange,
93
+ disableTransition,
82
94
  nonce,
83
- persistTheme,
84
- ssrSystemTheme,
85
- syncThemeFromServer,
86
- theme: initialTheme
87
- }: ThemeProviderProps): JSX.Element;
95
+ onPersistError,
96
+ persistColorScheme,
97
+ ssrColorScheme,
98
+ syncFromServer,
99
+ colorScheme: initialColorScheme
100
+ }: AppearanceProviderProps): JSX.Element;
88
101
  //#endregion
89
- export { ThemeProvider };
102
+ export { AppearanceProvider, AppearanceProviderProps };
@@ -1,17 +1,18 @@
1
- import { MEDIA, THEME_CHANNEL } from "../constants.mjs";
2
- import { ThemeContext } from "./context.mjs";
3
- import { applyTheme, disableAnimation } from "../utils/dom.mjs";
4
- import { getSystemTheme } from "../utils/system.mjs";
1
+ import { DEFAULT_COLOR_SCHEME, MEDIA, SYNC_CHANNEL } from "../constants.mjs";
2
+ import { colorSchemeSchema } from "../types.mjs";
3
+ import { ColorSchemeContext } from "./context.mjs";
4
+ import { applyColorScheme, suppressTransitions } from "../utils/dom.mjs";
5
+ import { getSystemColorScheme } from "../utils/system.mjs";
5
6
  import { startTransition, useCallback, useEffect, useEffectEvent, useMemo, useOptimistic, useRef, useState, useSyncExternalStore } from "react";
6
7
  import { jsx } from "react/jsx-runtime";
7
8
  //#region src/core/provider.tsx
8
9
  /**
9
- * Subscribe to OS theme preference changes.
10
+ * Subscribe to OS color scheme preference changes.
10
11
  *
11
- * @param callback - Function to call when system theme changes
12
+ * @param callback - Function to call when system color scheme changes
12
13
  * @returns Cleanup function to remove the listener
13
14
  */
14
- function subscribeToSystemTheme(callback) {
15
+ function subscribeToSystemColorScheme(callback) {
15
16
  const mediaQuery = window.matchMedia(MEDIA);
16
17
  mediaQuery.addEventListener("change", callback);
17
18
  return () => {
@@ -19,61 +20,78 @@ function subscribeToSystemTheme(callback) {
19
20
  };
20
21
  }
21
22
  /**
22
- * Get current system theme on the client.
23
+ * Safely create a color scheme BroadcastChannel when supported by the environment.
23
24
  */
24
- function getSystemThemeSnapshot() {
25
- return getSystemTheme();
25
+ function createColorSchemeChannel() {
26
+ if (typeof BroadcastChannel === "undefined") return null;
27
+ try {
28
+ return new BroadcastChannel(SYNC_CHANNEL);
29
+ } catch {
30
+ return null;
31
+ }
26
32
  }
27
33
  /**
28
- * Provider component for theme state management.
34
+ * Provider component for color scheme state management.
29
35
  *
30
36
  * **React 19 Features Used:**
31
- * - `useOptimistic` - Immediate UI feedback while persisting theme
32
- * - `useSyncExternalStore` - SSR-safe subscription to OS theme preference
37
+ * - `useOptimistic` - Immediate UI feedback while persisting color scheme
38
+ * - `useSyncExternalStore` - SSR-safe subscription to OS color scheme preference
33
39
  * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
34
40
  *
35
41
  * @param props - Component props
36
42
  * @param props.children - React tree to provide context for
37
- * @param props.theme - Initial preference from the server (cookie, loader, etc.)
38
- * @param props.ssrSystemTheme - Best-effort `light` or `dark` from the SSR request
39
- * (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `system`, this value is used as
43
+ * @param props.colorScheme - Initial preference from the server (cookie, loader, etc.)
44
+ * @param props.ssrColorScheme - Best-effort `light` or `dark` from the SSR request
45
+ * (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `automatic`, this value is used as
40
46
  * `useSyncExternalStore`'s server snapshot so the first client snapshot matches `matchMedia`
41
- * and avoids a post-hydration flip. Omit if unavailable; falls back to {@link DEFAULT_RESOLVED_THEME}.
42
- * @param props.syncThemeFromServer - Optional one-shot RPC after mount to align with the cookie when SSR/HTML was stale.
43
- * @param props.persistTheme - Optional async handler to persist preference (cookie, server action, …)
44
- * @param props.disableTransitionOnChange - Temporarily disable CSS transitions on theme change
45
- * @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransitionOnChange` is set
47
+ * and avoids a post-hydration flip. Omit if unavailable; falls back to {@link DEFAULT_RESOLVED_COLOR_SCHEME}.
48
+ * @param props.syncFromServer - Optional one-shot RPC after mount to align with the cookie when SSR/HTML was stale.
49
+ * @param props.persistColorScheme - Optional async handler to persist preference (cookie, server action, …)
50
+ * @param props.onPersistError - Optional callback for persistence failures
51
+ * @param props.disableTransition - Temporarily suppress CSS transitions on color scheme change
52
+ * @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransition` is set
46
53
  * @returns Provider element wrapping `children`
47
54
  *
48
55
  * @example
49
56
  * ```tsx
50
57
  * // In your root layout
51
- * <ThemeProvider
52
- * theme={theme}
53
- * persistTheme={(value) => setThemeServerFn({ data: value })}
58
+ * <AppearanceProvider
59
+ * colorScheme={colorScheme}
60
+ * persistColorScheme={(value) => setColorSchemeServerFn({ data: value })}
54
61
  * >
55
62
  * {children}
56
- * </ThemeProvider>
63
+ * </AppearanceProvider>
57
64
  * ```
58
65
  *
59
66
  * @since 0.3.16-canary.0
60
67
  */
61
- function ThemeProvider({ children, disableTransitionOnChange = false, nonce, persistTheme, ssrSystemTheme, syncThemeFromServer, theme: initialTheme }) {
62
- const [theme, setThemeState] = useState(initialTheme);
63
- const [optimisticTheme, setOptimisticTheme] = useOptimistic(theme);
64
- const isPending = optimisticTheme !== theme;
65
- const syncThemeFromServerRef = useRef(syncThemeFromServer);
66
- syncThemeFromServerRef.current = syncThemeFromServer;
68
+ function AppearanceProvider({ children, disableTransition = false, nonce, onPersistError, persistColorScheme, ssrColorScheme, syncFromServer, colorScheme: initialColorScheme }) {
69
+ const safeInitialColorScheme = colorSchemeSchema.safeParse(initialColorScheme).success ? initialColorScheme : DEFAULT_COLOR_SCHEME;
70
+ const [colorScheme, setColorSchemeState] = useState(safeInitialColorScheme);
71
+ const [optimisticColorScheme, setOptimisticColorScheme] = useOptimistic(colorScheme);
72
+ const isPending = optimisticColorScheme !== colorScheme;
73
+ const committedColorSchemeRef = useRef(colorScheme);
74
+ committedColorSchemeRef.current = colorScheme;
75
+ const channelRef = useRef(null);
76
+ const enableTransitionsRef = useRef(null);
77
+ const intentRef = useRef(null);
67
78
  useEffect(() => {
68
- const sync = syncThemeFromServerRef.current;
79
+ startTransition(() => {
80
+ setColorSchemeState((prev) => prev === safeInitialColorScheme ? prev : safeInitialColorScheme);
81
+ });
82
+ }, [safeInitialColorScheme]);
83
+ const syncFromServerRef = useRef(syncFromServer);
84
+ syncFromServerRef.current = syncFromServer;
85
+ useEffect(() => {
86
+ const sync = syncFromServerRef.current;
69
87
  if (!sync) return;
70
88
  let cancelled = false;
71
89
  (async () => {
72
90
  try {
73
- const serverTheme = await sync();
91
+ const serverColorScheme = await sync();
74
92
  if (cancelled) return;
75
93
  startTransition(() => {
76
- setThemeState((prev) => prev === serverTheme ? prev : serverTheme);
94
+ setColorSchemeState((prev) => prev === serverColorScheme ? prev : serverColorScheme);
77
95
  });
78
96
  } catch {}
79
97
  })();
@@ -81,67 +99,85 @@ function ThemeProvider({ children, disableTransitionOnChange = false, nonce, per
81
99
  cancelled = true;
82
100
  };
83
101
  }, []);
84
- const systemTheme = useSyncExternalStore(subscribeToSystemTheme, getSystemThemeSnapshot, useCallback(() => {
85
- return ssrSystemTheme ?? "dark";
86
- }, [ssrSystemTheme]));
87
- const resolvedTheme = useMemo(() => optimisticTheme === "system" ? systemTheme : optimisticTheme, [optimisticTheme, systemTheme]);
102
+ const systemColorScheme = useSyncExternalStore(subscribeToSystemColorScheme, getSystemColorScheme, useCallback(() => {
103
+ return ssrColorScheme ?? "dark";
104
+ }, [ssrColorScheme]));
105
+ const resolvedColorScheme = useMemo(() => optimisticColorScheme === "automatic" ? systemColorScheme : optimisticColorScheme, [optimisticColorScheme, systemColorScheme]);
88
106
  useEffect(() => {
89
- applyTheme(resolvedTheme);
90
- }, [resolvedTheme]);
107
+ applyColorScheme(resolvedColorScheme);
108
+ const enable = enableTransitionsRef.current;
109
+ if (enable) {
110
+ enableTransitionsRef.current = null;
111
+ enable();
112
+ }
113
+ }, [resolvedColorScheme]);
91
114
  const handleCrossTabMessage = useEffectEvent((event) => {
92
- const newTheme = event.data;
93
- if (newTheme === theme) return;
115
+ const result = colorSchemeSchema.safeParse(event.data);
116
+ if (!result.success || result.data === colorScheme) return;
94
117
  startTransition(() => {
95
- setThemeState(newTheme);
118
+ setColorSchemeState(result.data);
96
119
  });
97
120
  });
98
121
  useEffect(() => {
99
- const channel = new BroadcastChannel(THEME_CHANNEL);
122
+ const channel = createColorSchemeChannel();
123
+ if (!channel) return;
124
+ channelRef.current = channel;
100
125
  channel.addEventListener("message", handleCrossTabMessage);
101
126
  return () => {
127
+ channelRef.current = null;
102
128
  channel.removeEventListener("message", handleCrossTabMessage);
103
129
  channel.close();
104
130
  };
105
131
  }, []);
106
- const setTheme = useCallback(async (value) => {
132
+ const setColorScheme = useCallback(async (value) => {
107
133
  await Promise.resolve();
108
- if (value === theme) return;
109
- const enable = disableTransitionOnChange ? disableAnimation(nonce) : null;
134
+ if (value === committedColorSchemeRef.current) return;
135
+ if (disableTransition) enableTransitionsRef.current = suppressTransitions(nonce);
110
136
  startTransition(async () => {
111
- setOptimisticTheme(value);
137
+ intentRef.current = value;
138
+ setOptimisticColorScheme(value);
112
139
  try {
113
- if (persistTheme) await persistTheme(value);
114
- setThemeState(value);
115
- const channel = new BroadcastChannel(THEME_CHANNEL);
116
- channel.postMessage(value);
117
- channel.close();
140
+ if (persistColorScheme) await persistColorScheme(value);
141
+ if (intentRef.current === value) {
142
+ setColorSchemeState(value);
143
+ channelRef.current?.postMessage(value);
144
+ }
118
145
  } catch (error) {
119
- console.error("Failed to set theme:", error);
146
+ if (onPersistError) try {
147
+ onPersistError(error, value);
148
+ } catch (callbackError) {
149
+ console.error("Failed to handle color scheme persist error:", callbackError);
150
+ }
151
+ else console.error("Failed to set color scheme:", error);
120
152
  } finally {
121
- enable?.();
153
+ const enable = enableTransitionsRef.current;
154
+ if (enable) {
155
+ enableTransitionsRef.current = null;
156
+ enable();
157
+ }
122
158
  }
123
159
  });
124
160
  }, [
125
- theme,
126
- disableTransitionOnChange,
161
+ disableTransition,
127
162
  nonce,
128
- setOptimisticTheme,
129
- persistTheme
163
+ setOptimisticColorScheme,
164
+ persistColorScheme,
165
+ onPersistError
130
166
  ]);
131
- return /* @__PURE__ */ jsx(ThemeContext, {
167
+ return /* @__PURE__ */ jsx(ColorSchemeContext, {
132
168
  value: useMemo(() => ({
133
169
  isPending,
134
- resolvedTheme,
135
- setTheme,
136
- theme: optimisticTheme
170
+ resolvedColorScheme,
171
+ setColorScheme,
172
+ colorScheme: optimisticColorScheme
137
173
  }), [
138
- optimisticTheme,
139
- resolvedTheme,
140
- setTheme,
174
+ optimisticColorScheme,
175
+ resolvedColorScheme,
176
+ setColorScheme,
141
177
  isPending
142
178
  ]),
143
179
  children
144
180
  });
145
181
  }
146
182
  //#endregion
147
- export { ThemeProvider };
183
+ export { AppearanceProvider };
@@ -1,27 +1,27 @@
1
- import { ThemeContextType } from "../types.mjs";
1
+ import { ColorSchemeContextType } from "../types.mjs";
2
2
 
3
3
  //#region src/core/use-theme.d.ts
4
4
  /**
5
- * Hook to access theme context.
5
+ * Hook to access color scheme context.
6
6
  *
7
7
  * Uses React 19's `use()` API for context consumption, enabling:
8
8
  * - Conditional context reading
9
9
  * - Better Suspense boundary integration
10
10
  *
11
- * @returns Theme context with `theme`, `resolvedTheme`, `setTheme`, and `isPending`
12
- * @throws Error if called outside of ThemeProvider
11
+ * @returns Color scheme context with `colorScheme`, `resolvedColorScheme`, `setPreferredColorScheme`, and `isPending`
12
+ * @throws Error if called outside of AppearanceProvider
13
13
  *
14
14
  * @example
15
15
  * ```tsx
16
- * function ThemeToggle() {
17
- * const { theme, setTheme, isPending } = useTheme();
16
+ * function AppearanceToggle() {
17
+ * const { colorScheme, setPreferredColorScheme, isPending } = useColorScheme();
18
18
  *
19
19
  * return (
20
20
  * <button
21
- * onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
21
+ * onClick={() => setPreferredColorScheme(colorScheme === 'dark' ? 'light' : 'dark')}
22
22
  * disabled={isPending}
23
23
  * >
24
- * {theme}
24
+ * {colorScheme}
25
25
  * </button>
26
26
  * );
27
27
  * }
@@ -29,6 +29,6 @@ import { ThemeContextType } from "../types.mjs";
29
29
  *
30
30
  * @since 0.3.16-canary.0
31
31
  */
32
- declare function useTheme(): ThemeContextType;
32
+ declare function useColorScheme(): ColorSchemeContextType;
33
33
  //#endregion
34
- export { useTheme };
34
+ export { useColorScheme };
@@ -1,27 +1,27 @@
1
- import { ThemeContext } from "./context.mjs";
1
+ import { ColorSchemeContext } from "./context.mjs";
2
2
  import { use } from "react";
3
3
  //#region src/core/use-theme.ts
4
4
  /**
5
- * Hook to access theme context.
5
+ * Hook to access color scheme context.
6
6
  *
7
7
  * Uses React 19's `use()` API for context consumption, enabling:
8
8
  * - Conditional context reading
9
9
  * - Better Suspense boundary integration
10
10
  *
11
- * @returns Theme context with `theme`, `resolvedTheme`, `setTheme`, and `isPending`
12
- * @throws Error if called outside of ThemeProvider
11
+ * @returns Color scheme context with `colorScheme`, `resolvedColorScheme`, `setPreferredColorScheme`, and `isPending`
12
+ * @throws Error if called outside of AppearanceProvider
13
13
  *
14
14
  * @example
15
15
  * ```tsx
16
- * function ThemeToggle() {
17
- * const { theme, setTheme, isPending } = useTheme();
16
+ * function AppearanceToggle() {
17
+ * const { colorScheme, setPreferredColorScheme, isPending } = useColorScheme();
18
18
  *
19
19
  * return (
20
20
  * <button
21
- * onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
21
+ * onClick={() => setPreferredColorScheme(colorScheme === 'dark' ? 'light' : 'dark')}
22
22
  * disabled={isPending}
23
23
  * >
24
- * {theme}
24
+ * {colorScheme}
25
25
  * </button>
26
26
  * );
27
27
  * }
@@ -29,10 +29,10 @@ import { use } from "react";
29
29
  *
30
30
  * @since 0.3.16-canary.0
31
31
  */
32
- function useTheme() {
33
- const value = use(ThemeContext);
34
- if (!value) throw new Error("useTheme must be used within a ThemeProvider");
32
+ function useColorScheme() {
33
+ const value = use(ColorSchemeContext);
34
+ if (!value) throw new Error("useColorScheme must be used within an AppearanceProvider");
35
35
  return value;
36
36
  }
37
37
  //#endregion
38
- export { useTheme };
38
+ export { useColorScheme };
package/dist/index.d.mts CHANGED
@@ -1,7 +1,7 @@
1
- import { ResolvedTheme, Theme, ThemeContextType, themeSchema, themes } from "./types.mjs";
2
- import { DEFAULT_RESOLVED_THEME, DEFAULT_THEME } from "./constants.mjs";
3
- import { ThemeProvider } from "./core/provider.mjs";
4
- import { useTheme } from "./core/use-theme.mjs";
5
- import { ThemeScript } from "./script/theme-script.mjs";
6
- import { resolveTheme } from "./utils/system.mjs";
7
- export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, type ResolvedTheme, type Theme, type ThemeContextType, ThemeProvider, ThemeScript, resolveTheme, themeSchema, themes, useTheme };
1
+ import { ColorScheme, ColorSchemeContextType, ResolvedColorScheme, colorSchemeSchema, colorSchemes } from "./types.mjs";
2
+ import { DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME } from "./constants.mjs";
3
+ import { AppearanceProvider, AppearanceProviderProps } from "./core/provider.mjs";
4
+ import { useColorScheme } from "./core/use-theme.mjs";
5
+ import { AppearanceScript, AppearanceScriptProps } from "./script/theme-script.mjs";
6
+ import { resolveColorScheme } from "./utils/system.mjs";
7
+ export { AppearanceProvider, type AppearanceProviderProps, AppearanceScript, type AppearanceScriptProps, type ColorScheme, type ColorSchemeContextType, DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME, type ResolvedColorScheme, colorSchemeSchema, colorSchemes, resolveColorScheme, useColorScheme };
package/dist/index.mjs CHANGED
@@ -1,7 +1,7 @@
1
- import { DEFAULT_RESOLVED_THEME, DEFAULT_THEME } from "./constants.mjs";
2
- import { themeSchema, themes } from "./types.mjs";
3
- import { resolveTheme } from "./utils/system.mjs";
4
- import { ThemeProvider } from "./core/provider.mjs";
5
- import { useTheme } from "./core/use-theme.mjs";
6
- import { ThemeScript } from "./script/theme-script.mjs";
7
- export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, ThemeProvider, ThemeScript, resolveTheme, themeSchema, themes, useTheme };
1
+ import { DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME } from "./constants.mjs";
2
+ import { colorSchemeSchema, colorSchemes } from "./types.mjs";
3
+ import { resolveColorScheme } from "./utils/system.mjs";
4
+ import { AppearanceProvider } from "./core/provider.mjs";
5
+ import { useColorScheme } from "./core/use-theme.mjs";
6
+ import { AppearanceScript } from "./script/theme-script.mjs";
7
+ export { AppearanceProvider, AppearanceScript, DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME, colorSchemeSchema, colorSchemes, resolveColorScheme, useColorScheme };
@@ -1,40 +1,66 @@
1
- import { Theme } from "../types.mjs";
1
+ import { ColorScheme } from "../types.mjs";
2
2
  import { JSX } from "react";
3
3
 
4
4
  //#region src/script/theme-script.d.ts
5
- interface ThemeScriptProps {
5
+ /**
6
+ * @since 0.3.16-canary.3
7
+ */
8
+ type AppearanceScriptProps = {
9
+ /**
10
+ * Initial color scheme from server (e.g., from cookie via loader).
11
+ *
12
+ * When `storageKey` is provided, this acts as a fallback if the storage entry is absent
13
+ * or contains an unrecognised value.
14
+ */
15
+ readonly colorScheme: ColorScheme;
16
+ /**
17
+ * CSP nonce applied to the inline script element.
18
+ */
19
+ readonly nonce?: string;
6
20
  /**
7
- * Initial theme from server (e.g., from cookie via loader).
21
+ * When provided, the inline script reads `localStorage.getItem(storageKey)` before
22
+ * first paint and uses that value if it is a recognised color scheme (`"light"`, `"dark"`,
23
+ * or `"automatic"`). Falls back to `colorScheme` when the key is absent or invalid.
24
+ *
25
+ * Use this for client-only React apps that persist the color scheme in `localStorage` instead
26
+ * of an HTTP cookie to prevent FOUC.
27
+ *
28
+ * @example
29
+ * ```tsx
30
+ * <AppearanceScript colorScheme="automatic" storageKey="my-app-color-scheme" />
31
+ * ```
8
32
  */
9
- theme: Theme;
10
- }
33
+ readonly storageKey?: string;
34
+ };
11
35
  /**
12
36
  * Inline script that prevents Flash of Unstyled Content (FOUC).
13
37
  *
14
38
  * **Why this is needed:**
15
39
  * React hydration occurs after the browser has already painted the page.
16
- * Without this script, users would briefly see the wrong theme before
40
+ * Without this script, users would briefly see the wrong appearance before
17
41
  * React takes over and applies the correct one.
18
42
  *
19
43
  * **How it works:**
20
44
  * This script runs synchronously in the `<head>` before first paint:
21
- * 1. Resolves 'system' to 'light' or 'dark' using `matchMedia()`
22
- * 2. Removes prior `light` / `dark` / `system` classes on `<html>` (SSR may
23
- * have applied the wrong resolved class for `system`, e.g. default `dark`)
24
- * 3. Adds the resolved theme class and sets `color-scheme` for native controls
45
+ * 1. Resolves 'automatic' to 'light' or 'dark' using `matchMedia()`
46
+ * 2. Removes prior `light` / `dark` / `automatic` classes on `<html>` (SSR may
47
+ * have applied the wrong resolved class for `automatic`, e.g. default `dark`)
48
+ * 3. Adds the resolved color scheme class and sets `color-scheme` for native controls
25
49
  *
26
50
  * @example
27
51
  * ```tsx
28
52
  * // In __root.tsx (TanStack Start)
29
53
  * <head>
30
- * <ThemeScript theme={theme} />
54
+ * <AppearanceScript colorScheme={colorScheme} />
31
55
  * </head>
32
56
  * ```
33
57
  *
34
58
  * @since 0.3.16-canary.0
35
59
  */
36
- declare function ThemeScript({
37
- theme
38
- }: ThemeScriptProps): JSX.Element;
60
+ declare function AppearanceScript({
61
+ nonce,
62
+ storageKey,
63
+ colorScheme
64
+ }: AppearanceScriptProps): JSX.Element;
39
65
  //#endregion
40
- export { ThemeScript };
66
+ export { AppearanceScript, AppearanceScriptProps };