@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.
- package/CHANGELOG.md +46 -0
- package/README.md +23 -18
- package/dist/adapters/tanstack-start/server.d.mts +28 -30
- package/dist/adapters/tanstack-start/server.mjs +29 -29
- package/dist/constants.d.mts +11 -13
- package/dist/constants.mjs +10 -12
- package/dist/core/context.d.mts +9 -10
- package/dist/core/context.mjs +7 -7
- package/dist/core/provider.d.mts +57 -44
- package/dist/core/provider.mjs +103 -67
- package/dist/core/use-theme.d.mts +10 -10
- package/dist/core/use-theme.mjs +12 -12
- package/dist/index.d.mts +7 -7
- package/dist/index.mjs +7 -7
- package/dist/script/theme-script.d.mts +41 -15
- package/dist/script/theme-script.mjs +20 -9
- package/dist/start.d.mts +2 -2
- package/dist/start.mjs +2 -2
- package/dist/types.d.mts +28 -28
- package/dist/types.mjs +9 -9
- package/dist/utils/dom.d.mts +11 -11
- package/dist/utils/dom.mjs +12 -12
- package/dist/utils/system.d.mts +13 -13
- package/dist/utils/system.mjs +17 -17
- package/package.json +25 -18
- package/src/adapters/tanstack-start/server.ts +150 -0
- package/src/constants.ts +52 -0
- package/src/core/context.tsx +22 -0
- package/src/core/provider.tsx +377 -0
- package/src/core/use-theme.ts +47 -0
- package/src/index.ts +29 -0
- package/src/script/theme-script.tsx +103 -0
- package/src/start.ts +54 -0
- package/src/types.ts +61 -0
- package/src/utils/dom.ts +87 -0
- package/src/utils/system.ts +57 -0
package/dist/core/provider.d.mts
CHANGED
|
@@ -1,89 +1,102 @@
|
|
|
1
|
-
import {
|
|
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
|
-
|
|
6
|
-
|
|
5
|
+
/**
|
|
6
|
+
* @since 0.3.16-canary.3
|
|
7
|
+
*/
|
|
8
|
+
type AppearanceProviderProps = {
|
|
9
|
+
readonly children: ReactNode;
|
|
7
10
|
/**
|
|
8
|
-
* When true, temporarily
|
|
9
|
-
* Prevents jarring color animations when switching
|
|
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
|
-
|
|
15
|
+
readonly disableTransition?: boolean;
|
|
13
16
|
/**
|
|
14
|
-
* CSP nonce for inline styles when `
|
|
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
|
|
21
|
+
* Async function to persist color scheme changes to server/storage.
|
|
19
22
|
*
|
|
20
|
-
* For TanStack Start: use `
|
|
23
|
+
* For TanStack Start: use `persistColorSchemeCookie` from `@codefast/theme/start`
|
|
21
24
|
* For Next.js: implement a server action
|
|
22
25
|
*/
|
|
23
|
-
|
|
26
|
+
readonly persistColorScheme?: (value: ColorScheme) => Promise<void>;
|
|
24
27
|
/**
|
|
25
|
-
*
|
|
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
|
-
|
|
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 `
|
|
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
|
-
|
|
46
|
+
readonly ssrColorScheme?: ResolvedColorScheme;
|
|
36
47
|
/**
|
|
37
|
-
* After mount, re-read the canonical
|
|
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
|
|
40
|
-
* document was saved with an old `
|
|
41
|
-
* in another tab. Use a stable reference (e.g. `
|
|
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
|
-
|
|
44
|
-
}
|
|
54
|
+
readonly syncFromServer?: () => Promise<ColorScheme>;
|
|
55
|
+
};
|
|
45
56
|
/**
|
|
46
|
-
* Provider component for
|
|
57
|
+
* Provider component for color scheme state management.
|
|
47
58
|
*
|
|
48
59
|
* **React 19 Features Used:**
|
|
49
|
-
* - `useOptimistic` - Immediate UI feedback while persisting
|
|
50
|
-
* - `useSyncExternalStore` - SSR-safe subscription to OS
|
|
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.
|
|
56
|
-
* @param props.
|
|
57
|
-
* (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `
|
|
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
|
|
60
|
-
* @param props.
|
|
61
|
-
* @param props.
|
|
62
|
-
* @param props.
|
|
63
|
-
* @param props.
|
|
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
|
-
* <
|
|
70
|
-
*
|
|
71
|
-
*
|
|
81
|
+
* <AppearanceProvider
|
|
82
|
+
* colorScheme={colorScheme}
|
|
83
|
+
* persistColorScheme={(value) => setColorSchemeServerFn({ data: value })}
|
|
72
84
|
* >
|
|
73
85
|
* {children}
|
|
74
|
-
* </
|
|
86
|
+
* </AppearanceProvider>
|
|
75
87
|
* ```
|
|
76
88
|
*
|
|
77
89
|
* @since 0.3.16-canary.0
|
|
78
90
|
*/
|
|
79
|
-
declare function
|
|
91
|
+
declare function AppearanceProvider({
|
|
80
92
|
children,
|
|
81
|
-
|
|
93
|
+
disableTransition,
|
|
82
94
|
nonce,
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
95
|
+
onPersistError,
|
|
96
|
+
persistColorScheme,
|
|
97
|
+
ssrColorScheme,
|
|
98
|
+
syncFromServer,
|
|
99
|
+
colorScheme: initialColorScheme
|
|
100
|
+
}: AppearanceProviderProps): JSX.Element;
|
|
88
101
|
//#endregion
|
|
89
|
-
export {
|
|
102
|
+
export { AppearanceProvider, AppearanceProviderProps };
|
package/dist/core/provider.mjs
CHANGED
|
@@ -1,17 +1,18 @@
|
|
|
1
|
-
import { MEDIA,
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
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
|
|
10
|
+
* Subscribe to OS color scheme preference changes.
|
|
10
11
|
*
|
|
11
|
-
* @param callback - Function to call when system
|
|
12
|
+
* @param callback - Function to call when system color scheme changes
|
|
12
13
|
* @returns Cleanup function to remove the listener
|
|
13
14
|
*/
|
|
14
|
-
function
|
|
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
|
-
*
|
|
23
|
+
* Safely create a color scheme BroadcastChannel when supported by the environment.
|
|
23
24
|
*/
|
|
24
|
-
function
|
|
25
|
-
|
|
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
|
|
34
|
+
* Provider component for color scheme state management.
|
|
29
35
|
*
|
|
30
36
|
* **React 19 Features Used:**
|
|
31
|
-
* - `useOptimistic` - Immediate UI feedback while persisting
|
|
32
|
-
* - `useSyncExternalStore` - SSR-safe subscription to OS
|
|
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.
|
|
38
|
-
* @param props.
|
|
39
|
-
* (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `
|
|
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
|
|
42
|
-
* @param props.
|
|
43
|
-
* @param props.
|
|
44
|
-
* @param props.
|
|
45
|
-
* @param props.
|
|
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
|
-
* <
|
|
52
|
-
*
|
|
53
|
-
*
|
|
58
|
+
* <AppearanceProvider
|
|
59
|
+
* colorScheme={colorScheme}
|
|
60
|
+
* persistColorScheme={(value) => setColorSchemeServerFn({ data: value })}
|
|
54
61
|
* >
|
|
55
62
|
* {children}
|
|
56
|
-
* </
|
|
63
|
+
* </AppearanceProvider>
|
|
57
64
|
* ```
|
|
58
65
|
*
|
|
59
66
|
* @since 0.3.16-canary.0
|
|
60
67
|
*/
|
|
61
|
-
function
|
|
62
|
-
const
|
|
63
|
-
const [
|
|
64
|
-
const
|
|
65
|
-
const
|
|
66
|
-
|
|
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
|
-
|
|
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
|
|
91
|
+
const serverColorScheme = await sync();
|
|
74
92
|
if (cancelled) return;
|
|
75
93
|
startTransition(() => {
|
|
76
|
-
|
|
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
|
|
85
|
-
return
|
|
86
|
-
}, [
|
|
87
|
-
const
|
|
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
|
-
|
|
90
|
-
|
|
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
|
|
93
|
-
if (
|
|
115
|
+
const result = colorSchemeSchema.safeParse(event.data);
|
|
116
|
+
if (!result.success || result.data === colorScheme) return;
|
|
94
117
|
startTransition(() => {
|
|
95
|
-
|
|
118
|
+
setColorSchemeState(result.data);
|
|
96
119
|
});
|
|
97
120
|
});
|
|
98
121
|
useEffect(() => {
|
|
99
|
-
const 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
|
|
132
|
+
const setColorScheme = useCallback(async (value) => {
|
|
107
133
|
await Promise.resolve();
|
|
108
|
-
if (value ===
|
|
109
|
-
|
|
134
|
+
if (value === committedColorSchemeRef.current) return;
|
|
135
|
+
if (disableTransition) enableTransitionsRef.current = suppressTransitions(nonce);
|
|
110
136
|
startTransition(async () => {
|
|
111
|
-
|
|
137
|
+
intentRef.current = value;
|
|
138
|
+
setOptimisticColorScheme(value);
|
|
112
139
|
try {
|
|
113
|
-
if (
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
-
|
|
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
|
-
|
|
126
|
-
disableTransitionOnChange,
|
|
161
|
+
disableTransition,
|
|
127
162
|
nonce,
|
|
128
|
-
|
|
129
|
-
|
|
163
|
+
setOptimisticColorScheme,
|
|
164
|
+
persistColorScheme,
|
|
165
|
+
onPersistError
|
|
130
166
|
]);
|
|
131
|
-
return /* @__PURE__ */ jsx(
|
|
167
|
+
return /* @__PURE__ */ jsx(ColorSchemeContext, {
|
|
132
168
|
value: useMemo(() => ({
|
|
133
169
|
isPending,
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
170
|
+
resolvedColorScheme,
|
|
171
|
+
setColorScheme,
|
|
172
|
+
colorScheme: optimisticColorScheme
|
|
137
173
|
}), [
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
174
|
+
optimisticColorScheme,
|
|
175
|
+
resolvedColorScheme,
|
|
176
|
+
setColorScheme,
|
|
141
177
|
isPending
|
|
142
178
|
]),
|
|
143
179
|
children
|
|
144
180
|
});
|
|
145
181
|
}
|
|
146
182
|
//#endregion
|
|
147
|
-
export {
|
|
183
|
+
export { AppearanceProvider };
|
|
@@ -1,27 +1,27 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { ColorSchemeContextType } from "../types.mjs";
|
|
2
2
|
|
|
3
3
|
//#region src/core/use-theme.d.ts
|
|
4
4
|
/**
|
|
5
|
-
* Hook to access
|
|
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
|
|
12
|
-
* @throws Error if called outside of
|
|
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
|
|
17
|
-
* const {
|
|
16
|
+
* function AppearanceToggle() {
|
|
17
|
+
* const { colorScheme, setPreferredColorScheme, isPending } = useColorScheme();
|
|
18
18
|
*
|
|
19
19
|
* return (
|
|
20
20
|
* <button
|
|
21
|
-
* onClick={() =>
|
|
21
|
+
* onClick={() => setPreferredColorScheme(colorScheme === 'dark' ? 'light' : 'dark')}
|
|
22
22
|
* disabled={isPending}
|
|
23
23
|
* >
|
|
24
|
-
* {
|
|
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
|
|
32
|
+
declare function useColorScheme(): ColorSchemeContextType;
|
|
33
33
|
//#endregion
|
|
34
|
-
export {
|
|
34
|
+
export { useColorScheme };
|
package/dist/core/use-theme.mjs
CHANGED
|
@@ -1,27 +1,27 @@
|
|
|
1
|
-
import {
|
|
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
|
|
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
|
|
12
|
-
* @throws Error if called outside of
|
|
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
|
|
17
|
-
* const {
|
|
16
|
+
* function AppearanceToggle() {
|
|
17
|
+
* const { colorScheme, setPreferredColorScheme, isPending } = useColorScheme();
|
|
18
18
|
*
|
|
19
19
|
* return (
|
|
20
20
|
* <button
|
|
21
|
-
* onClick={() =>
|
|
21
|
+
* onClick={() => setPreferredColorScheme(colorScheme === 'dark' ? 'light' : 'dark')}
|
|
22
22
|
* disabled={isPending}
|
|
23
23
|
* >
|
|
24
|
-
* {
|
|
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
|
|
33
|
-
const value = use(
|
|
34
|
-
if (!value) throw new Error("
|
|
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 {
|
|
38
|
+
export { useColorScheme };
|
package/dist/index.d.mts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
7
|
-
export {
|
|
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 {
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
7
|
-
export {
|
|
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 {
|
|
1
|
+
import { ColorScheme } from "../types.mjs";
|
|
2
2
|
import { JSX } from "react";
|
|
3
3
|
|
|
4
4
|
//#region src/script/theme-script.d.ts
|
|
5
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
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
|
|
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 '
|
|
22
|
-
* 2. Removes prior `light` / `dark` / `
|
|
23
|
-
* have applied the wrong resolved class for `
|
|
24
|
-
* 3. Adds the resolved
|
|
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
|
-
* <
|
|
54
|
+
* <AppearanceScript colorScheme={colorScheme} />
|
|
31
55
|
* </head>
|
|
32
56
|
* ```
|
|
33
57
|
*
|
|
34
58
|
* @since 0.3.16-canary.0
|
|
35
59
|
*/
|
|
36
|
-
declare function
|
|
37
|
-
|
|
38
|
-
|
|
60
|
+
declare function AppearanceScript({
|
|
61
|
+
nonce,
|
|
62
|
+
storageKey,
|
|
63
|
+
colorScheme
|
|
64
|
+
}: AppearanceScriptProps): JSX.Element;
|
|
39
65
|
//#endregion
|
|
40
|
-
export {
|
|
66
|
+
export { AppearanceScript, AppearanceScriptProps };
|