@codefast/theme 0.3.15 → 0.3.16-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.
- package/CHANGELOG.md +2 -0
- package/dist/adapters/tanstack-start/server.d.mts +12 -0
- package/dist/adapters/tanstack-start/server.mjs +20 -10
- package/dist/constants.d.mts +10 -0
- package/dist/constants.mjs +14 -4
- package/dist/core/context.d.mts +2 -0
- package/dist/core/context.mjs +4 -2
- package/dist/core/provider.d.mts +2 -0
- package/dist/core/provider.mjs +5 -3
- package/dist/core/use-theme.d.mts +2 -0
- package/dist/core/use-theme.mjs +6 -4
- package/dist/script/theme-script.d.mts +2 -0
- package/dist/script/theme-script.mjs +5 -3
- package/dist/types.d.mts +10 -0
- package/dist/types.mjs +6 -2
- package/dist/utils/dom.d.mts +4 -0
- package/dist/utils/dom.mjs +9 -5
- package/dist/utils/system.d.mts +4 -0
- package/dist/utils/system.mjs +8 -4
- package/package.json +5 -5
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,8 @@ import * as _$_tanstack_react_start0 from "@tanstack/react-start";
|
|
|
5
5
|
//#region src/adapters/tanstack-start/server.d.ts
|
|
6
6
|
/**
|
|
7
7
|
* Data shape returned from {@link getRootThemeServerFn} for the root route loader.
|
|
8
|
+
*
|
|
9
|
+
* @since 0.3.16-canary.0
|
|
8
10
|
*/
|
|
9
11
|
interface RootThemeLoaderData {
|
|
10
12
|
/**
|
|
@@ -23,6 +25,8 @@ interface RootThemeLoaderData {
|
|
|
23
25
|
* Everything needed for the root shell in **one** server call (fewer loader awaits).
|
|
24
26
|
*
|
|
25
27
|
* In your shell: `resolveTheme(theme, ssrSystemTheme)` on `<html>`, plus `ThemeScript` and `ThemeProvider`.
|
|
28
|
+
*
|
|
29
|
+
* @since 0.3.16-canary.0
|
|
26
30
|
*/
|
|
27
31
|
declare const getRootThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, RootThemeLoaderData>;
|
|
28
32
|
/**
|
|
@@ -37,6 +41,8 @@ declare const getRootThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<und
|
|
|
37
41
|
* ```tsx
|
|
38
42
|
* const theme = await getThemeServerFn();
|
|
39
43
|
* ```
|
|
44
|
+
*
|
|
45
|
+
* @since 0.3.16-canary.0
|
|
40
46
|
*/
|
|
41
47
|
declare const getThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, "light" | "dark" | "system">;
|
|
42
48
|
/**
|
|
@@ -46,6 +52,8 @@ declare const getThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefin
|
|
|
46
52
|
* Prefer {@link getRootThemeServerFn} for root loaders.
|
|
47
53
|
*
|
|
48
54
|
* Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
|
|
55
|
+
*
|
|
56
|
+
* @since 0.3.16-canary.0
|
|
49
57
|
*/
|
|
50
58
|
declare const getSsrSystemThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, ResolvedTheme>;
|
|
51
59
|
/**
|
|
@@ -63,6 +71,8 @@ declare const getSsrSystemThemeServerFn: _$_tanstack_react_start0.OptionalFetche
|
|
|
63
71
|
* @param data - Theme to persist ('light', 'dark', or 'system')
|
|
64
72
|
*
|
|
65
73
|
* @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
|
|
74
|
+
*
|
|
75
|
+
* @since 0.3.16-canary.0
|
|
66
76
|
*/
|
|
67
77
|
declare const setThemeServerFn: _$_tanstack_react_start0.RequiredFetcher<undefined, _$zod.ZodEnum<{
|
|
68
78
|
light: "light";
|
|
@@ -72,6 +82,8 @@ declare const setThemeServerFn: _$_tanstack_react_start0.RequiredFetcher<undefin
|
|
|
72
82
|
/**
|
|
73
83
|
* Default {@link ThemeProvider} `persistTheme` for the Start adapter: writes the httpOnly
|
|
74
84
|
* theme cookie via {@link setThemeServerFn}.
|
|
85
|
+
*
|
|
86
|
+
* @since 0.3.16-canary.0
|
|
75
87
|
*/
|
|
76
88
|
declare function persistThemeCookie(value: Theme): Promise<void>;
|
|
77
89
|
//#endregion
|
|
@@ -17,8 +17,10 @@ function readSsrSystemThemeFromHeaders() {
|
|
|
17
17
|
}
|
|
18
18
|
/**
|
|
19
19
|
* Everything needed for the root shell in **one** server call (fewer loader awaits).
|
|
20
|
-
*
|
|
20
|
+
*
|
|
21
21
|
* In your shell: `resolveTheme(theme, ssrSystemTheme)` on `<html>`, plus `ThemeScript` and `ThemeProvider`.
|
|
22
|
+
*
|
|
23
|
+
* @since 0.3.16-canary.0
|
|
22
24
|
*/
|
|
23
25
|
const getRootThemeServerFn = createServerFn().handler(() => ({
|
|
24
26
|
theme: readThemeFromCookie(),
|
|
@@ -26,42 +28,48 @@ const getRootThemeServerFn = createServerFn().handler(() => ({
|
|
|
26
28
|
}));
|
|
27
29
|
/**
|
|
28
30
|
* Read the user's theme preference from cookies.
|
|
29
|
-
*
|
|
31
|
+
*
|
|
30
32
|
* Validates the cookie value using Zod schema for type safety.
|
|
31
33
|
* Returns {@link DEFAULT_THEME} if cookie is missing or invalid.
|
|
32
|
-
*
|
|
34
|
+
*
|
|
33
35
|
* @returns User's stored theme preference or default
|
|
34
|
-
*
|
|
36
|
+
*
|
|
35
37
|
* @example
|
|
36
38
|
* ```tsx
|
|
37
39
|
* const theme = await getThemeServerFn();
|
|
38
40
|
* ```
|
|
41
|
+
*
|
|
42
|
+
* @since 0.3.16-canary.0
|
|
39
43
|
*/
|
|
40
44
|
const getThemeServerFn = createServerFn().handler(() => readThemeFromCookie());
|
|
41
45
|
/**
|
|
42
46
|
* Resolved OS theme for SSR / hydration, from Client Hints when the browser sends them.
|
|
43
|
-
*
|
|
47
|
+
*
|
|
44
48
|
* Mirrors client `matchMedia("(prefers-color-scheme: dark)")` when hints are present.
|
|
45
49
|
* Prefer {@link getRootThemeServerFn} for root loaders.
|
|
46
|
-
*
|
|
50
|
+
*
|
|
47
51
|
* Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
|
|
52
|
+
*
|
|
53
|
+
* @since 0.3.16-canary.0
|
|
48
54
|
*/
|
|
49
55
|
const getSsrSystemThemeServerFn = createServerFn().handler(() => readSsrSystemThemeFromHeaders());
|
|
50
56
|
/**
|
|
51
57
|
* Persist theme preference to an HTTP-only cookie.
|
|
52
|
-
*
|
|
58
|
+
*
|
|
53
59
|
* **Security:**
|
|
54
60
|
* - `httpOnly: true` - Cookie cannot be accessed from JavaScript (XSS protection)
|
|
55
61
|
* - `secure: true` in production - Cookie only sent over HTTPS
|
|
56
62
|
* - `sameSite: 'lax'` - Prevents CSRF while allowing navigation
|
|
57
|
-
*
|
|
63
|
+
*
|
|
58
64
|
* **Cookie Settings:**
|
|
59
65
|
* - `maxAge: 1 year` - Preference persists across sessions
|
|
60
66
|
* - `path: '/'` - Available to all routes
|
|
61
|
-
*
|
|
67
|
+
*
|
|
62
68
|
* @param data - Theme to persist ('light', 'dark', or 'system')
|
|
63
|
-
*
|
|
69
|
+
*
|
|
64
70
|
* @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
|
|
71
|
+
*
|
|
72
|
+
* @since 0.3.16-canary.0
|
|
65
73
|
*/
|
|
66
74
|
const setThemeServerFn = createServerFn({ method: "POST" }).inputValidator(themeSchema).handler(({ data }) => {
|
|
67
75
|
setCookie(THEME_STORAGE_KEY, data, {
|
|
@@ -75,6 +83,8 @@ const setThemeServerFn = createServerFn({ method: "POST" }).inputValidator(theme
|
|
|
75
83
|
/**
|
|
76
84
|
* Default {@link ThemeProvider} `persistTheme` for the Start adapter: writes the httpOnly
|
|
77
85
|
* theme cookie via {@link setThemeServerFn}.
|
|
86
|
+
*
|
|
87
|
+
* @since 0.3.16-canary.0
|
|
78
88
|
*/
|
|
79
89
|
async function persistThemeCookie(value) {
|
|
80
90
|
await setThemeServerFn({ data: value });
|
package/dist/constants.d.mts
CHANGED
|
@@ -5,23 +5,31 @@ import { ResolvedTheme, Theme } from "./types.mjs";
|
|
|
5
5
|
* Default theme when no user preference exists.
|
|
6
6
|
*
|
|
7
7
|
* Set to 'system' to respect OS preference by default.
|
|
8
|
+
*
|
|
9
|
+
* @since 0.3.16-canary.0
|
|
8
10
|
*/
|
|
9
11
|
declare const DEFAULT_THEME: Theme;
|
|
10
12
|
/**
|
|
11
13
|
* Fallback theme for SSR when system preference cannot be detected.
|
|
12
14
|
*
|
|
13
15
|
* Used during server-side rendering since `window.matchMedia()` is unavailable.
|
|
16
|
+
*
|
|
17
|
+
* @since 0.3.16-canary.0
|
|
14
18
|
*/
|
|
15
19
|
declare const DEFAULT_RESOLVED_THEME: ResolvedTheme;
|
|
16
20
|
/**
|
|
17
21
|
* Cookie name for the httpOnly theme preference (`@codefast/theme/start`).
|
|
18
22
|
*
|
|
19
23
|
* Re-exported only from `@codefast/theme/constants` so custom middleware matches the adapter.
|
|
24
|
+
*
|
|
25
|
+
* @since 0.3.16-canary.0
|
|
20
26
|
*/
|
|
21
27
|
declare const THEME_STORAGE_KEY = "ui-theme";
|
|
22
28
|
/**
|
|
23
29
|
* CSS media query for detecting dark mode preference.
|
|
24
30
|
* @internal
|
|
31
|
+
*
|
|
32
|
+
* @since 0.3.16-canary.0
|
|
25
33
|
*/
|
|
26
34
|
declare const MEDIA = "(prefers-color-scheme: dark)";
|
|
27
35
|
/**
|
|
@@ -29,6 +37,8 @@ declare const MEDIA = "(prefers-color-scheme: dark)";
|
|
|
29
37
|
*
|
|
30
38
|
* Enables instant theme updates across all open browser tabs.
|
|
31
39
|
* @internal
|
|
40
|
+
*
|
|
41
|
+
* @since 0.3.16-canary.0
|
|
32
42
|
*/
|
|
33
43
|
declare const THEME_CHANNEL = "theme-sync";
|
|
34
44
|
//#endregion
|
package/dist/constants.mjs
CHANGED
|
@@ -1,32 +1,42 @@
|
|
|
1
1
|
//#region src/constants.ts
|
|
2
2
|
/**
|
|
3
3
|
* Default theme when no user preference exists.
|
|
4
|
-
*
|
|
4
|
+
*
|
|
5
5
|
* Set to 'system' to respect OS preference by default.
|
|
6
|
+
*
|
|
7
|
+
* @since 0.3.16-canary.0
|
|
6
8
|
*/
|
|
7
9
|
const DEFAULT_THEME = "system";
|
|
8
10
|
/**
|
|
9
11
|
* Fallback theme for SSR when system preference cannot be detected.
|
|
10
|
-
*
|
|
12
|
+
*
|
|
11
13
|
* Used during server-side rendering since `window.matchMedia()` is unavailable.
|
|
14
|
+
*
|
|
15
|
+
* @since 0.3.16-canary.0
|
|
12
16
|
*/
|
|
13
17
|
const DEFAULT_RESOLVED_THEME = "dark";
|
|
14
18
|
/**
|
|
15
19
|
* Cookie name for the httpOnly theme preference (`@codefast/theme/start`).
|
|
16
|
-
*
|
|
20
|
+
*
|
|
17
21
|
* Re-exported only from `@codefast/theme/constants` so custom middleware matches the adapter.
|
|
22
|
+
*
|
|
23
|
+
* @since 0.3.16-canary.0
|
|
18
24
|
*/
|
|
19
25
|
const THEME_STORAGE_KEY = "ui-theme";
|
|
20
26
|
/**
|
|
21
27
|
* CSS media query for detecting dark mode preference.
|
|
22
28
|
* @internal
|
|
29
|
+
*
|
|
30
|
+
* @since 0.3.16-canary.0
|
|
23
31
|
*/
|
|
24
32
|
const MEDIA = "(prefers-color-scheme: dark)";
|
|
25
33
|
/**
|
|
26
34
|
* BroadcastChannel name for cross-tab theme synchronization.
|
|
27
|
-
*
|
|
35
|
+
*
|
|
28
36
|
* Enables instant theme updates across all open browser tabs.
|
|
29
37
|
* @internal
|
|
38
|
+
*
|
|
39
|
+
* @since 0.3.16-canary.0
|
|
30
40
|
*/
|
|
31
41
|
const THEME_CHANNEL = "theme-sync";
|
|
32
42
|
//#endregion
|
package/dist/core/context.d.mts
CHANGED
|
@@ -11,6 +11,8 @@ type ThemeContextValue = null | ThemeContextType;
|
|
|
11
11
|
*
|
|
12
12
|
* @see {@link ThemeProvider} - Provider component
|
|
13
13
|
* @see {@link useTheme} - Consumer hook
|
|
14
|
+
*
|
|
15
|
+
* @since 0.3.16-canary.0
|
|
14
16
|
*/
|
|
15
17
|
declare const ThemeContext: _$react.Context<ThemeContextValue>;
|
|
16
18
|
//#endregion
|
package/dist/core/context.mjs
CHANGED
|
@@ -2,12 +2,14 @@ import { createContext } from "react";
|
|
|
2
2
|
//#region src/core/context.tsx
|
|
3
3
|
/**
|
|
4
4
|
* React context for theme state management.
|
|
5
|
-
*
|
|
5
|
+
*
|
|
6
6
|
* Provides access to current theme, resolved theme, setter function, and pending state.
|
|
7
7
|
* Use {@link useTheme} hook instead of consuming this context directly.
|
|
8
|
-
*
|
|
8
|
+
*
|
|
9
9
|
* @see {@link ThemeProvider} - Provider component
|
|
10
10
|
* @see {@link useTheme} - Consumer hook
|
|
11
|
+
*
|
|
12
|
+
* @since 0.3.16-canary.0
|
|
11
13
|
*/
|
|
12
14
|
const ThemeContext = createContext(null);
|
|
13
15
|
//#endregion
|
package/dist/core/provider.d.mts
CHANGED
package/dist/core/provider.mjs
CHANGED
|
@@ -26,12 +26,12 @@ function getSystemThemeSnapshot() {
|
|
|
26
26
|
}
|
|
27
27
|
/**
|
|
28
28
|
* Provider component for theme state management.
|
|
29
|
-
*
|
|
29
|
+
*
|
|
30
30
|
* **React 19 Features Used:**
|
|
31
31
|
* - `useOptimistic` - Immediate UI feedback while persisting theme
|
|
32
32
|
* - `useSyncExternalStore` - SSR-safe subscription to OS theme preference
|
|
33
33
|
* - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
|
|
34
|
-
*
|
|
34
|
+
*
|
|
35
35
|
* @param props - Component props
|
|
36
36
|
* @param props.children - React tree to provide context for
|
|
37
37
|
* @param props.theme - Initial preference from the server (cookie, loader, etc.)
|
|
@@ -44,7 +44,7 @@ function getSystemThemeSnapshot() {
|
|
|
44
44
|
* @param props.disableTransitionOnChange - Temporarily disable CSS transitions on theme change
|
|
45
45
|
* @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransitionOnChange` is set
|
|
46
46
|
* @returns Provider element wrapping `children`
|
|
47
|
-
*
|
|
47
|
+
*
|
|
48
48
|
* @example
|
|
49
49
|
* ```tsx
|
|
50
50
|
* // In your root layout
|
|
@@ -55,6 +55,8 @@ function getSystemThemeSnapshot() {
|
|
|
55
55
|
* {children}
|
|
56
56
|
* </ThemeProvider>
|
|
57
57
|
* ```
|
|
58
|
+
*
|
|
59
|
+
* @since 0.3.16-canary.0
|
|
58
60
|
*/
|
|
59
61
|
function ThemeProvider({ children, disableTransitionOnChange = false, nonce, persistTheme, ssrSystemTheme, syncThemeFromServer, theme: initialTheme }) {
|
|
60
62
|
const [theme, setThemeState] = useState(initialTheme);
|
package/dist/core/use-theme.mjs
CHANGED
|
@@ -3,19 +3,19 @@ import { use } from "react";
|
|
|
3
3
|
//#region src/core/use-theme.ts
|
|
4
4
|
/**
|
|
5
5
|
* Hook to access theme 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
11
|
* @returns Theme context with `theme`, `resolvedTheme`, `setTheme`, and `isPending`
|
|
12
12
|
* @throws Error if called outside of ThemeProvider
|
|
13
|
-
*
|
|
13
|
+
*
|
|
14
14
|
* @example
|
|
15
15
|
* ```tsx
|
|
16
16
|
* function ThemeToggle() {
|
|
17
17
|
* const { theme, setTheme, isPending } = useTheme();
|
|
18
|
-
*
|
|
18
|
+
*
|
|
19
19
|
* return (
|
|
20
20
|
* <button
|
|
21
21
|
* onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
|
|
@@ -26,6 +26,8 @@ import { use } from "react";
|
|
|
26
26
|
* );
|
|
27
27
|
* }
|
|
28
28
|
* ```
|
|
29
|
+
*
|
|
30
|
+
* @since 0.3.16-canary.0
|
|
29
31
|
*/
|
|
30
32
|
function useTheme() {
|
|
31
33
|
const value = use(ThemeContext);
|
|
@@ -2,19 +2,19 @@ import { jsx } from "react/jsx-runtime";
|
|
|
2
2
|
//#region src/script/theme-script.tsx
|
|
3
3
|
/**
|
|
4
4
|
* Inline script that prevents Flash of Unstyled Content (FOUC).
|
|
5
|
-
*
|
|
5
|
+
*
|
|
6
6
|
* **Why this is needed:**
|
|
7
7
|
* React hydration occurs after the browser has already painted the page.
|
|
8
8
|
* Without this script, users would briefly see the wrong theme before
|
|
9
9
|
* React takes over and applies the correct one.
|
|
10
|
-
*
|
|
10
|
+
*
|
|
11
11
|
* **How it works:**
|
|
12
12
|
* This script runs synchronously in the `<head>` before first paint:
|
|
13
13
|
* 1. Resolves 'system' to 'light' or 'dark' using `matchMedia()`
|
|
14
14
|
* 2. Removes prior `light` / `dark` / `system` classes on `<html>` (SSR may
|
|
15
15
|
* have applied the wrong resolved class for `system`, e.g. default `dark`)
|
|
16
16
|
* 3. Adds the resolved theme class and sets `color-scheme` for native controls
|
|
17
|
-
*
|
|
17
|
+
*
|
|
18
18
|
* @example
|
|
19
19
|
* ```tsx
|
|
20
20
|
* // In __root.tsx (TanStack Start)
|
|
@@ -22,6 +22,8 @@ import { jsx } from "react/jsx-runtime";
|
|
|
22
22
|
* <ThemeScript theme={theme} />
|
|
23
23
|
* </head>
|
|
24
24
|
* ```
|
|
25
|
+
*
|
|
26
|
+
* @since 0.3.16-canary.0
|
|
25
27
|
*/
|
|
26
28
|
function ThemeScript({ theme }) {
|
|
27
29
|
return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: `(function(){try{var theme="${theme}",resolvedTheme=theme;"system"===theme&&(resolvedTheme=window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"),document.documentElement.classList.remove("light","dark","system"),document.documentElement.classList.add(resolvedTheme),document.documentElement.style.colorScheme=resolvedTheme}catch(error){}})()` } });
|
package/dist/types.d.mts
CHANGED
|
@@ -6,6 +6,8 @@ import { z } from "zod";
|
|
|
6
6
|
*
|
|
7
7
|
* Acts as the single source of truth for all theme-related types.
|
|
8
8
|
* Valid values: 'light', 'dark', 'system'.
|
|
9
|
+
*
|
|
10
|
+
* @since 0.3.16-canary.0
|
|
9
11
|
*/
|
|
10
12
|
declare const themeSchema: z.ZodEnum<{
|
|
11
13
|
light: "light";
|
|
@@ -18,18 +20,24 @@ declare const themeSchema: z.ZodEnum<{
|
|
|
18
20
|
* - `'light'` - Force light mode
|
|
19
21
|
* - `'dark'` - Force dark mode
|
|
20
22
|
* - `'system'` - Follow OS preference
|
|
23
|
+
*
|
|
24
|
+
* @since 0.3.16-canary.0
|
|
21
25
|
*/
|
|
22
26
|
type Theme = z.infer<typeof themeSchema>;
|
|
23
27
|
/**
|
|
24
28
|
* Actual theme applied to the UI after resolving 'system'.
|
|
25
29
|
*
|
|
26
30
|
* When theme is 'system', this reflects the OS preference (light/dark).
|
|
31
|
+
*
|
|
32
|
+
* @since 0.3.16-canary.0
|
|
27
33
|
*/
|
|
28
34
|
type ResolvedTheme = Exclude<Theme, "system">;
|
|
29
35
|
/**
|
|
30
36
|
* Array of all available theme options: `['light', 'dark', 'system']`.
|
|
31
37
|
*
|
|
32
38
|
* Useful for rendering theme selectors in UI components.
|
|
39
|
+
*
|
|
40
|
+
* @since 0.3.16-canary.0
|
|
33
41
|
*/
|
|
34
42
|
declare const themes: ("light" | "dark" | "system")[];
|
|
35
43
|
/**
|
|
@@ -39,6 +47,8 @@ declare const themes: ("light" | "dark" | "system")[];
|
|
|
39
47
|
* - `resolvedTheme` - Actual theme applied (system resolved to light/dark)
|
|
40
48
|
* - `setTheme` - Async function to update theme (triggers optimistic update)
|
|
41
49
|
* - `isPending` - True while theme change is being persisted
|
|
50
|
+
*
|
|
51
|
+
* @since 0.3.16-canary.0
|
|
42
52
|
*/
|
|
43
53
|
interface ThemeContextType {
|
|
44
54
|
isPending: boolean;
|
package/dist/types.mjs
CHANGED
|
@@ -2,9 +2,11 @@ import { z } from "zod";
|
|
|
2
2
|
//#region src/types.ts
|
|
3
3
|
/**
|
|
4
4
|
* Zod schema for theme validation.
|
|
5
|
-
*
|
|
5
|
+
*
|
|
6
6
|
* Acts as the single source of truth for all theme-related types.
|
|
7
7
|
* Valid values: 'light', 'dark', 'system'.
|
|
8
|
+
*
|
|
9
|
+
* @since 0.3.16-canary.0
|
|
8
10
|
*/
|
|
9
11
|
const themeSchema = z.enum([
|
|
10
12
|
"light",
|
|
@@ -13,8 +15,10 @@ const themeSchema = z.enum([
|
|
|
13
15
|
]);
|
|
14
16
|
/**
|
|
15
17
|
* Array of all available theme options: `['light', 'dark', 'system']`.
|
|
16
|
-
*
|
|
18
|
+
*
|
|
17
19
|
* Useful for rendering theme selectors in UI components.
|
|
20
|
+
*
|
|
21
|
+
* @since 0.3.16-canary.0
|
|
18
22
|
*/
|
|
19
23
|
const themes = themeSchema.options;
|
|
20
24
|
//#endregion
|
package/dist/utils/dom.d.mts
CHANGED
|
@@ -9,6 +9,8 @@ import { ResolvedTheme } from "../types.mjs";
|
|
|
9
9
|
* - `color-scheme` style (for native form controls and scrollbars)
|
|
10
10
|
*
|
|
11
11
|
* @param resolved - The resolved theme to apply ('light' or 'dark')
|
|
12
|
+
*
|
|
13
|
+
* @since 0.3.16-canary.0
|
|
12
14
|
*/
|
|
13
15
|
declare function applyTheme(resolved: ResolvedTheme): void;
|
|
14
16
|
/**
|
|
@@ -26,6 +28,8 @@ declare function applyTheme(resolved: ResolvedTheme): void;
|
|
|
26
28
|
* applyTheme('dark');
|
|
27
29
|
* enableTransitions(); // Re-enables CSS transitions
|
|
28
30
|
* ```
|
|
31
|
+
*
|
|
32
|
+
* @since 0.3.16-canary.0
|
|
29
33
|
*/
|
|
30
34
|
declare function disableAnimation(nonce?: string): () => void;
|
|
31
35
|
//#endregion
|
package/dist/utils/dom.mjs
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
//#region src/utils/dom.ts
|
|
2
2
|
/**
|
|
3
3
|
* Apply theme to the DOM by updating `<html>` element.
|
|
4
|
-
*
|
|
4
|
+
*
|
|
5
5
|
* Updates both:
|
|
6
6
|
* - CSS class (for Tailwind's `dark:` variants)
|
|
7
7
|
* - `color-scheme` style (for native form controls and scrollbars)
|
|
8
|
-
*
|
|
8
|
+
*
|
|
9
9
|
* @param resolved - The resolved theme to apply ('light' or 'dark')
|
|
10
|
+
*
|
|
11
|
+
* @since 0.3.16-canary.0
|
|
10
12
|
*/
|
|
11
13
|
function applyTheme(resolved) {
|
|
12
14
|
const root = window.document.documentElement;
|
|
@@ -16,19 +18,21 @@ function applyTheme(resolved) {
|
|
|
16
18
|
}
|
|
17
19
|
/**
|
|
18
20
|
* Temporarily disable all CSS transitions during theme changes.
|
|
19
|
-
*
|
|
21
|
+
*
|
|
20
22
|
* Prevents jarring color animations when switching between light/dark themes.
|
|
21
23
|
* Respects user's `prefers-reduced-motion` preference (does nothing if enabled).
|
|
22
|
-
*
|
|
24
|
+
*
|
|
23
25
|
* @param nonce - Optional CSP nonce for the injected style element
|
|
24
26
|
* @returns Cleanup function to re-enable transitions. Call after theme is applied.
|
|
25
|
-
*
|
|
27
|
+
*
|
|
26
28
|
* @example
|
|
27
29
|
* ```tsx
|
|
28
30
|
* const enableTransitions = disableAnimation();
|
|
29
31
|
* applyTheme('dark');
|
|
30
32
|
* enableTransitions(); // Re-enables CSS transitions
|
|
31
33
|
* ```
|
|
34
|
+
*
|
|
35
|
+
* @since 0.3.16-canary.0
|
|
32
36
|
*/
|
|
33
37
|
function disableAnimation(nonce) {
|
|
34
38
|
if (typeof globalThis.window === "undefined") return () => {};
|
package/dist/utils/system.d.mts
CHANGED
|
@@ -8,6 +8,8 @@ import { ResolvedTheme, Theme } from "../types.mjs";
|
|
|
8
8
|
* Returns {@link DEFAULT_RESOLVED_THEME} during SSR since `window` is unavailable.
|
|
9
9
|
*
|
|
10
10
|
* @returns 'light' or 'dark' based on OS preference
|
|
11
|
+
*
|
|
12
|
+
* @since 0.3.16-canary.0
|
|
11
13
|
*/
|
|
12
14
|
declare function getSystemTheme(): ResolvedTheme;
|
|
13
15
|
/**
|
|
@@ -24,6 +26,8 @@ declare function getSystemTheme(): ResolvedTheme;
|
|
|
24
26
|
* (`Sec-CH-Prefers-Color-Scheme`) so `<html class>` matches the real OS preference.
|
|
25
27
|
* Ignored for non-`system` themes and on the client (where {@link getSystemTheme} wins).
|
|
26
28
|
* @returns The resolved theme to apply (`light` or `dark`)
|
|
29
|
+
*
|
|
30
|
+
* @since 0.3.16-canary.0
|
|
27
31
|
*/
|
|
28
32
|
declare function resolveTheme(theme: Theme, ssrSystemTheme?: ResolvedTheme): ResolvedTheme;
|
|
29
33
|
//#endregion
|
package/dist/utils/system.mjs
CHANGED
|
@@ -2,11 +2,13 @@ import { DEFAULT_RESOLVED_THEME } from "../constants.mjs";
|
|
|
2
2
|
//#region src/utils/system.ts
|
|
3
3
|
/**
|
|
4
4
|
* Detect the user's OS theme preference.
|
|
5
|
-
*
|
|
5
|
+
*
|
|
6
6
|
* Uses `matchMedia()` to query the `prefers-color-scheme` media feature.
|
|
7
7
|
* Returns {@link DEFAULT_RESOLVED_THEME} during SSR since `window` is unavailable.
|
|
8
|
-
*
|
|
8
|
+
*
|
|
9
9
|
* @returns 'light' or 'dark' based on OS preference
|
|
10
|
+
*
|
|
11
|
+
* @since 0.3.16-canary.0
|
|
10
12
|
*/
|
|
11
13
|
function getSystemTheme() {
|
|
12
14
|
if (typeof globalThis.window === "undefined") return DEFAULT_RESOLVED_THEME;
|
|
@@ -14,18 +16,20 @@ function getSystemTheme() {
|
|
|
14
16
|
}
|
|
15
17
|
/**
|
|
16
18
|
* Resolve theme preference to actual light/dark value.
|
|
17
|
-
*
|
|
19
|
+
*
|
|
18
20
|
* - 'light' → 'light'
|
|
19
21
|
* - 'dark' → 'dark'
|
|
20
22
|
* - 'system' → on the client, result of {@link getSystemTheme}; on the server,
|
|
21
23
|
* `ssrSystemTheme` when provided, otherwise {@link DEFAULT_RESOLVED_THEME}
|
|
22
|
-
*
|
|
24
|
+
*
|
|
23
25
|
* @param theme - User's theme preference (`light`, `dark`, or `system`)
|
|
24
26
|
* @param ssrSystemTheme - When `theme` is `system` and this runs during SSR (no `window`),
|
|
25
27
|
* uses this as the resolved appearance—typically from Client Hints
|
|
26
28
|
* (`Sec-CH-Prefers-Color-Scheme`) so `<html class>` matches the real OS preference.
|
|
27
29
|
* Ignored for non-`system` themes and on the client (where {@link getSystemTheme} wins).
|
|
28
30
|
* @returns The resolved theme to apply (`light` or `dark`)
|
|
31
|
+
*
|
|
32
|
+
* @since 0.3.16-canary.0
|
|
29
33
|
*/
|
|
30
34
|
function resolveTheme(theme, ssrSystemTheme) {
|
|
31
35
|
if (theme !== "system") return theme;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codefast/theme",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.16-canary.0",
|
|
4
4
|
"description": "Theme management with React 19 features - optimistic updates, cross-tab sync, and SSR support",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"dark-mode",
|
|
@@ -100,22 +100,22 @@
|
|
|
100
100
|
"access": "public"
|
|
101
101
|
},
|
|
102
102
|
"dependencies": {
|
|
103
|
-
"zod": "^4.4.
|
|
103
|
+
"zod": "^4.4.3"
|
|
104
104
|
},
|
|
105
105
|
"devDependencies": {
|
|
106
|
-
"@tanstack/react-start": "^1.167.
|
|
106
|
+
"@tanstack/react-start": "^1.167.62",
|
|
107
107
|
"@testing-library/dom": "^10.4.1",
|
|
108
108
|
"@testing-library/jest-dom": "^6.9.1",
|
|
109
109
|
"@testing-library/react": "^16.3.2",
|
|
110
110
|
"@testing-library/user-event": "^14.6.1",
|
|
111
111
|
"@types/node": "^25.6.0",
|
|
112
|
-
"@typescript/native-preview": "7.0.0-dev.
|
|
112
|
+
"@typescript/native-preview": "7.0.0-dev.20260504.1",
|
|
113
113
|
"@vitejs/plugin-react": "^6.0.1",
|
|
114
114
|
"@vitest/coverage-v8": "^4.1.5",
|
|
115
115
|
"jsdom": "^29.1.1",
|
|
116
116
|
"typescript": "^6.0.3",
|
|
117
117
|
"vitest": "^4.1.5",
|
|
118
|
-
"@codefast/typescript-config": "0.3.
|
|
118
|
+
"@codefast/typescript-config": "0.3.16-canary.0"
|
|
119
119
|
},
|
|
120
120
|
"peerDependencies": {
|
|
121
121
|
"@tanstack/react-start": "^1.0",
|