@codefast/theme 0.3.16-canary.2 → 0.4.0-canary.4
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 +25 -25
- 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 +26 -19
- package/src/adapters/tanstack-start/server.ts +146 -0
- package/src/constants.ts +52 -0
- package/src/core/context.tsx +22 -0
- package/src/core/provider.tsx +364 -0
- package/src/core/use-theme.ts +46 -0
- package/src/index.ts +29 -0
- package/src/script/theme-script.tsx +90 -0
- package/src/start.ts +54 -0
- package/src/types.ts +61 -0
- package/src/utils/dom.ts +85 -0
- package/src/utils/system.ts +56 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,51 @@
|
|
|
1
1
|
# @codefast/theme
|
|
2
2
|
|
|
3
|
+
## 0.4.0-canary.4
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [#495](https://github.com/codefastlabs/codefast/pull/495) [`fa338d6`](https://github.com/codefastlabs/codefast/commit/fa338d61fbfafb94beaa4d05d93d01e2c005cc91) Thanks [@thevuong](https://github.com/thevuong)! - Normalize import statement order and package.json key order repo-wide via the new oxfmt `sortImports`/`sortPackageJson` settings — purely mechanical, no runtime behavior change.
|
|
8
|
+
|
|
9
|
+
## 0.3.16-canary.3
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- [`3fc56a8`](https://github.com/codefastlabs/codefast/commit/3fc56a84c4c39c6510ce509d43daeae32fe90638) Thanks [@thevuong](https://github.com/thevuong)! - Security, correctness, and performance improvements to `ThemeProvider` and `ThemeScript`.
|
|
14
|
+
|
|
15
|
+
**Security**
|
|
16
|
+
|
|
17
|
+
- Validate `BroadcastChannel` messages with `themeSchema.safeParse` before applying — prevents injection from browser extensions or other same-origin scripts
|
|
18
|
+
- Use `JSON.stringify` in `ThemeScript` inline script to safely serialise the theme value
|
|
19
|
+
|
|
20
|
+
**Correctness**
|
|
21
|
+
|
|
22
|
+
- `ThemeProvider` now re-syncs internal state when the `theme` prop changes after mount (e.g. router re-runs the root loader), making the server the authoritative source of truth
|
|
23
|
+
- Fixed `disableTransitionOnChange` timing: animation cleanup now fires after `applyTheme` commits to the DOM instead of prematurely in the async persist `finally` block
|
|
24
|
+
- Added last-write-wins guard (`intentRef`) so rapid `setTheme` calls only commit the most recent intent
|
|
25
|
+
|
|
26
|
+
**Performance**
|
|
27
|
+
|
|
28
|
+
- `setTheme` callback is now stable across theme commits (reads `committedThemeRef` instead of capturing `theme` in deps) — prevents unnecessary re-renders in consumers
|
|
29
|
+
- `BroadcastChannel` is reused from a shared ref instead of opening a new channel on every `setTheme` call
|
|
30
|
+
- Removed obsolete `-moz-`, `-o-`, `-ms-` vendor prefixes from the `disableAnimation` CSS injection
|
|
31
|
+
|
|
32
|
+
**Features**
|
|
33
|
+
|
|
34
|
+
- `ThemeScript` accepts a new `storageKey` prop: when set, the inline script reads `localStorage` before first paint for FOUC-free client-only apps
|
|
35
|
+
- Runtime Zod validation of the `theme` prop in `ThemeProvider` guards against invalid values bypassing TypeScript
|
|
36
|
+
|
|
37
|
+
**Docs / Tests**
|
|
38
|
+
|
|
39
|
+
- Fixed README: `THEME_STORAGE_KEY` import example now correctly points to `@codefast/theme/constants`
|
|
40
|
+
- Added integration tests for the TanStack Start adapter server functions
|
|
41
|
+
- New test coverage for all security and correctness fixes above
|
|
42
|
+
|
|
43
|
+
- [`2a82188`](https://github.com/codefastlabs/codefast/commit/2a82188264c204b0b519b3324402ae962594d29b) Thanks [@thevuong](https://github.com/thevuong)! - feat(dev): enable source condition for zero-rebuild HMR in apps/docs
|
|
44
|
+
|
|
45
|
+
- [`9b94464`](https://github.com/codefastlabs/codefast/commit/9b94464be2247bd5ead32dc3d5c921ae3a52070c) Thanks [@thevuong](https://github.com/thevuong)! - Use minimum `>=` ranges in peerDependencies instead of `^` caret ranges.
|
|
46
|
+
|
|
47
|
+
- [`bed2f30`](https://github.com/codefastlabs/codefast/commit/bed2f30df74128fe3b1a98dd9d03f6bb96099164) Thanks [@thevuong](https://github.com/thevuong)! - feat(web): refactor theme management to color scheme system
|
|
48
|
+
|
|
3
49
|
## 0.3.16-canary.2
|
|
4
50
|
|
|
5
51
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -51,7 +51,7 @@ Theme management for React 19 — SSR-safe `system` resolution, optimistic updat
|
|
|
51
51
|
|
|
52
52
|
## Requirements
|
|
53
53
|
|
|
54
|
-
- React
|
|
54
|
+
- React `>=19.0.0` (and `react-dom`)
|
|
55
55
|
- TypeScript `>= 5.9` (recommended; the published types target ES2022)
|
|
56
56
|
- TanStack Start `^1` — only if you use `@codefast/theme/start`
|
|
57
57
|
|
|
@@ -94,11 +94,7 @@ function App() {
|
|
|
94
94
|
function Page() {
|
|
95
95
|
const { theme, setTheme } = useTheme();
|
|
96
96
|
|
|
97
|
-
return (
|
|
98
|
-
<button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
|
|
99
|
-
Current theme: {theme}
|
|
100
|
-
</button>
|
|
101
|
-
);
|
|
97
|
+
return <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>Current theme: {theme}</button>;
|
|
102
98
|
}
|
|
103
99
|
```
|
|
104
100
|
|
|
@@ -131,7 +127,7 @@ function RootShell({ children }: { children: React.ReactNode }) {
|
|
|
131
127
|
<html className={resolved} lang="en" style={{ colorScheme: resolved }} suppressHydrationWarning>
|
|
132
128
|
<head>
|
|
133
129
|
<HeadContent />
|
|
134
|
-
<ThemeScript theme={theme} />
|
|
130
|
+
<ThemeScript nonce={cspNonce} theme={theme} />
|
|
135
131
|
</head>
|
|
136
132
|
<body>
|
|
137
133
|
<ThemeProvider
|
|
@@ -166,8 +162,7 @@ For apps without a server framework, persist the theme in `localStorage`:
|
|
|
166
162
|
import { ThemeProvider } from "@codefast/theme";
|
|
167
163
|
|
|
168
164
|
function App() {
|
|
169
|
-
const saved =
|
|
170
|
-
typeof window !== "undefined" ? (localStorage.getItem("theme") ?? "system") : "system";
|
|
165
|
+
const saved = typeof window !== "undefined" ? (localStorage.getItem("theme") ?? "system") : "system";
|
|
171
166
|
|
|
172
167
|
return (
|
|
173
168
|
<ThemeProvider
|
|
@@ -222,7 +217,7 @@ export function ThemeSelect() {
|
|
|
222
217
|
|
|
223
218
|
The script removes any prior `light` / `dark` / `system` class on `<html>`, so it is safe to pre-render the markup with `suppressHydrationWarning`.
|
|
224
219
|
|
|
225
|
-
> **CSP note.**
|
|
220
|
+
> **CSP note.** Pass a `nonce` to `<ThemeScript nonce={...} />` when your policy requires it for inline scripts. The same nonce can also be passed to `<ThemeProvider nonce={...} />` for the temporary inline `<style>` used by `disableTransitionOnChange`.
|
|
226
221
|
|
|
227
222
|
---
|
|
228
223
|
|
|
@@ -247,15 +242,16 @@ Root provider that wires together theme state, OS subscription, optimistic updat
|
|
|
247
242
|
</ThemeProvider>
|
|
248
243
|
```
|
|
249
244
|
|
|
250
|
-
| Prop | Type
|
|
251
|
-
| --------------------------- |
|
|
252
|
-
| `theme` | `Theme`
|
|
253
|
-
| `ssrSystemTheme` | `ResolvedTheme`
|
|
254
|
-
| `persistTheme` | `(value: Theme) => Promise<void>`
|
|
255
|
-
| `
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
245
|
+
| Prop | Type | Default | Description |
|
|
246
|
+
| --------------------------- | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
247
|
+
| `theme` | `Theme` | — | Initial preference (`"light"` / `"dark"` / `"system"`). Required. |
|
|
248
|
+
| `ssrSystemTheme` | `ResolvedTheme` | — | `"light"` or `"dark"` from the SSR request (e.g. Client Hints). Used as the server snapshot when preference is `system`. |
|
|
249
|
+
| `persistTheme` | `(value: Theme) => Promise<void>` | — | Runs whenever the user changes the theme. Rejects → optimistic update reverts automatically. |
|
|
250
|
+
| `onThemePersistError` | `(error: unknown, attemptedTheme: Theme) => void` | — | Optional hook called when `persistTheme` rejects; use for custom logging/telemetry/UI feedback. |
|
|
251
|
+
| `syncThemeFromServer` | `() => Promise<Theme>` | — | Called once after mount to reconcile with the canonical source (e.g. cookie). Useful for stale HTML / duplicate-tab scenarios. |
|
|
252
|
+
| `disableTransitionOnChange` | `boolean` | `false` | Temporarily injects a style rule that disables CSS transitions while the theme swaps. Respects `prefers-reduced-motion`. |
|
|
253
|
+
| `nonce` | `string` | — | CSP nonce attached to the inline `<style>` element when `disableTransitionOnChange` is enabled. |
|
|
254
|
+
| `children` | `ReactNode` | — | Application content. |
|
|
259
255
|
|
|
260
256
|
`<ThemeProvider>` internally:
|
|
261
257
|
|
|
@@ -284,14 +280,16 @@ Throws if called outside of a `<ThemeProvider>`.
|
|
|
284
280
|
Inline script for the document head that prevents FOUC.
|
|
285
281
|
|
|
286
282
|
```tsx
|
|
287
|
-
<ThemeScript theme={theme} />
|
|
283
|
+
<ThemeScript nonce={cspNonce} theme={theme} />
|
|
288
284
|
```
|
|
289
285
|
|
|
290
|
-
| Prop
|
|
291
|
-
|
|
|
292
|
-
| `theme`
|
|
286
|
+
| Prop | Type | Description |
|
|
287
|
+
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
288
|
+
| `theme` | `Theme` | The preference to apply on initial render. `"system"` resolves via `matchMedia`. Acts as fallback when `storageKey` is provided. |
|
|
289
|
+
| `nonce` | `string` | Optional CSP nonce attached to the inline `<script>`. |
|
|
290
|
+
| `storageKey` | `string` | When set, the script reads `localStorage.getItem(storageKey)` before first paint. Use for client-only apps without an SSR cookie. |
|
|
293
291
|
|
|
294
|
-
The component
|
|
292
|
+
The component emits a `<script>` with `dangerouslySetInnerHTML` and forwards `nonce` when provided.
|
|
295
293
|
|
|
296
294
|
### `resolveTheme()`
|
|
297
295
|
|
|
@@ -321,10 +319,12 @@ Granular helpers from `@codefast/theme/utils/system` and `@codefast/theme/utils/
|
|
|
321
319
|
import {
|
|
322
320
|
DEFAULT_RESOLVED_THEME, // "dark"
|
|
323
321
|
DEFAULT_THEME, // "system"
|
|
324
|
-
THEME_STORAGE_KEY, // "ui-theme" — cookie name used by the Start adapter
|
|
325
322
|
themeSchema, // Zod: z.enum(["light", "dark", "system"])
|
|
326
323
|
themes, // readonly ["light", "dark", "system"]
|
|
327
324
|
} from "@codefast/theme";
|
|
325
|
+
|
|
326
|
+
// THEME_STORAGE_KEY lives in the /constants subpath (intentionally not re-exported from root)
|
|
327
|
+
import { THEME_STORAGE_KEY } from "@codefast/theme/constants"; // "ui-theme"
|
|
328
328
|
```
|
|
329
329
|
|
|
330
330
|
### TanStack Start adapter (`@codefast/theme/start`)
|
|
@@ -1,63 +1,61 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import * as _$zod from "zod";
|
|
3
|
-
import * as _$_tanstack_react_start0 from "@tanstack/react-start";
|
|
1
|
+
import { ColorScheme, ResolvedColorScheme } from "../../types.mjs";
|
|
4
2
|
|
|
5
3
|
//#region src/adapters/tanstack-start/server.d.ts
|
|
6
4
|
/**
|
|
7
|
-
* Data shape returned from {@link
|
|
5
|
+
* Data shape returned from {@link getRootColorSchemeServerFn} for the root route loader.
|
|
8
6
|
*
|
|
9
7
|
* @since 0.3.16-canary.0
|
|
10
8
|
*/
|
|
11
|
-
|
|
9
|
+
type RootColorSchemeLoaderData = {
|
|
12
10
|
/**
|
|
13
11
|
* Resolved `light` or `dark` from the incoming request when detectable
|
|
14
|
-
* (e.g. `Sec-CH-Prefers-Color-Scheme`). Pass to `
|
|
15
|
-
* `
|
|
16
|
-
* {@link
|
|
12
|
+
* (e.g. `Sec-CH-Prefers-Color-Scheme`). Pass to `AppearanceProvider` as `ssrColorScheme` and to
|
|
13
|
+
* `resolveColorScheme(colorScheme, ssrColorScheme)` on `<html>`. When the hint is absent, matches
|
|
14
|
+
* {@link DEFAULT_RESOLVED_COLOR_SCHEME}.
|
|
17
15
|
*/
|
|
18
|
-
|
|
16
|
+
readonly ssrColorScheme: ResolvedColorScheme;
|
|
19
17
|
/**
|
|
20
|
-
* User preference from the httpOnly cookie: `light`, `dark`, or `
|
|
18
|
+
* User preference from the httpOnly cookie: `light`, `dark`, or `automatic`.
|
|
21
19
|
*/
|
|
22
|
-
|
|
23
|
-
}
|
|
20
|
+
readonly colorScheme: ColorScheme;
|
|
21
|
+
};
|
|
24
22
|
/**
|
|
25
23
|
* Everything needed for the root shell in **one** server call (fewer loader awaits).
|
|
26
24
|
*
|
|
27
|
-
* In your shell: `
|
|
25
|
+
* In your shell: `resolveColorScheme(colorScheme, ssrColorScheme)` on `<html>`, plus `AppearanceScript` and `AppearanceProvider`.
|
|
28
26
|
*
|
|
29
27
|
* @since 0.3.16-canary.0
|
|
30
28
|
*/
|
|
31
|
-
declare const
|
|
29
|
+
declare const getRootColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, RootColorSchemeLoaderData>;
|
|
32
30
|
/**
|
|
33
|
-
* Read the user's
|
|
31
|
+
* Read the user's color scheme preference from cookies.
|
|
34
32
|
*
|
|
35
33
|
* Validates the cookie value using Zod schema for type safety.
|
|
36
|
-
* Returns {@link
|
|
34
|
+
* Returns {@link DEFAULT_COLOR_SCHEME} if cookie is missing or invalid.
|
|
37
35
|
*
|
|
38
|
-
* @returns User's stored
|
|
36
|
+
* @returns User's stored color scheme preference or default
|
|
39
37
|
*
|
|
40
38
|
* @example
|
|
41
39
|
* ```tsx
|
|
42
|
-
* const
|
|
40
|
+
* const colorScheme = await getColorSchemeServerFn();
|
|
43
41
|
* ```
|
|
44
42
|
*
|
|
45
43
|
* @since 0.3.16-canary.0
|
|
46
44
|
*/
|
|
47
|
-
declare const
|
|
45
|
+
declare const getColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, "light" | "dark" | "automatic">;
|
|
48
46
|
/**
|
|
49
|
-
* Resolved OS
|
|
47
|
+
* Resolved OS color scheme for SSR / hydration, from Client Hints when the browser sends them.
|
|
50
48
|
*
|
|
51
49
|
* Mirrors client `matchMedia("(prefers-color-scheme: dark)")` when hints are present.
|
|
52
|
-
* Prefer {@link
|
|
50
|
+
* Prefer {@link getRootColorSchemeServerFn} for root loaders.
|
|
53
51
|
*
|
|
54
52
|
* Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
|
|
55
53
|
*
|
|
56
54
|
* @since 0.3.16-canary.0
|
|
57
55
|
*/
|
|
58
|
-
declare const
|
|
56
|
+
declare const getSsrColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, ResolvedColorScheme>;
|
|
59
57
|
/**
|
|
60
|
-
* Persist
|
|
58
|
+
* Persist color scheme preference to an HTTP-only cookie.
|
|
61
59
|
*
|
|
62
60
|
* **Security:**
|
|
63
61
|
* - `httpOnly: true` - Cookie cannot be accessed from JavaScript (XSS protection)
|
|
@@ -68,23 +66,23 @@ declare const getSsrSystemThemeServerFn: _$_tanstack_react_start0.OptionalFetche
|
|
|
68
66
|
* - `maxAge: 1 year` - Preference persists across sessions
|
|
69
67
|
* - `path: '/'` - Available to all routes
|
|
70
68
|
*
|
|
71
|
-
* @param data -
|
|
69
|
+
* @param data - Color scheme to persist ('light', 'dark', or 'automatic')
|
|
72
70
|
*
|
|
73
71
|
* @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
|
|
74
72
|
*
|
|
75
73
|
* @since 0.3.16-canary.0
|
|
76
74
|
*/
|
|
77
|
-
declare const
|
|
75
|
+
declare const setColorSchemeServerFn: import("@tanstack/react-start").RequiredFetcher<undefined, import("zod").ZodEnum<{
|
|
78
76
|
light: "light";
|
|
79
77
|
dark: "dark";
|
|
80
|
-
|
|
78
|
+
automatic: "automatic";
|
|
81
79
|
}>, void>;
|
|
82
80
|
/**
|
|
83
|
-
* Default {@link
|
|
84
|
-
*
|
|
81
|
+
* Default {@link AppearanceProvider} `persistColorScheme` for the Start adapter: writes the httpOnly
|
|
82
|
+
* color scheme cookie via {@link setColorSchemeServerFn}.
|
|
85
83
|
*
|
|
86
84
|
* @since 0.3.16-canary.0
|
|
87
85
|
*/
|
|
88
|
-
declare function
|
|
86
|
+
declare function persistColorSchemeCookie(value: ColorScheme): Promise<void>;
|
|
89
87
|
//#endregion
|
|
90
|
-
export {
|
|
88
|
+
export { RootColorSchemeLoaderData, getColorSchemeServerFn, getRootColorSchemeServerFn, getSsrColorSchemeServerFn, persistColorSchemeCookie, setColorSchemeServerFn };
|
|
@@ -1,60 +1,60 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
1
|
+
import { DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME, STORAGE_KEY } from "../../constants.mjs";
|
|
2
|
+
import { colorSchemeSchema } from "../../types.mjs";
|
|
3
3
|
import { createServerFn } from "@tanstack/react-start";
|
|
4
4
|
import { getCookie, getRequestHeader, setCookie } from "@tanstack/react-start/server";
|
|
5
5
|
//#region src/adapters/tanstack-start/server.ts
|
|
6
|
-
function
|
|
7
|
-
const
|
|
8
|
-
const validationResult =
|
|
6
|
+
function readColorSchemeFromCookie() {
|
|
7
|
+
const cookieValue = getCookie(STORAGE_KEY);
|
|
8
|
+
const validationResult = colorSchemeSchema.safeParse(cookieValue);
|
|
9
9
|
if (validationResult.success) return validationResult.data;
|
|
10
|
-
return
|
|
10
|
+
return DEFAULT_COLOR_SCHEME;
|
|
11
11
|
}
|
|
12
|
-
function
|
|
12
|
+
function readSsrColorSchemeFromHeaders() {
|
|
13
13
|
const hint = getRequestHeader("Sec-CH-Prefers-Color-Scheme") ?? getRequestHeader("Prefers-Color-Scheme");
|
|
14
14
|
if (hint === "dark") return "dark";
|
|
15
15
|
if (hint === "light") return "light";
|
|
16
|
-
return
|
|
16
|
+
return DEFAULT_RESOLVED_COLOR_SCHEME;
|
|
17
17
|
}
|
|
18
18
|
/**
|
|
19
19
|
* Everything needed for the root shell in **one** server call (fewer loader awaits).
|
|
20
20
|
*
|
|
21
|
-
* In your shell: `
|
|
21
|
+
* In your shell: `resolveColorScheme(colorScheme, ssrColorScheme)` on `<html>`, plus `AppearanceScript` and `AppearanceProvider`.
|
|
22
22
|
*
|
|
23
23
|
* @since 0.3.16-canary.0
|
|
24
24
|
*/
|
|
25
|
-
const
|
|
26
|
-
|
|
27
|
-
|
|
25
|
+
const getRootColorSchemeServerFn = createServerFn().handler(() => ({
|
|
26
|
+
colorScheme: readColorSchemeFromCookie(),
|
|
27
|
+
ssrColorScheme: readSsrColorSchemeFromHeaders()
|
|
28
28
|
}));
|
|
29
29
|
/**
|
|
30
|
-
* Read the user's
|
|
30
|
+
* Read the user's color scheme preference from cookies.
|
|
31
31
|
*
|
|
32
32
|
* Validates the cookie value using Zod schema for type safety.
|
|
33
|
-
* Returns {@link
|
|
33
|
+
* Returns {@link DEFAULT_COLOR_SCHEME} if cookie is missing or invalid.
|
|
34
34
|
*
|
|
35
|
-
* @returns User's stored
|
|
35
|
+
* @returns User's stored color scheme preference or default
|
|
36
36
|
*
|
|
37
37
|
* @example
|
|
38
38
|
* ```tsx
|
|
39
|
-
* const
|
|
39
|
+
* const colorScheme = await getColorSchemeServerFn();
|
|
40
40
|
* ```
|
|
41
41
|
*
|
|
42
42
|
* @since 0.3.16-canary.0
|
|
43
43
|
*/
|
|
44
|
-
const
|
|
44
|
+
const getColorSchemeServerFn = createServerFn().handler(() => readColorSchemeFromCookie());
|
|
45
45
|
/**
|
|
46
|
-
* Resolved OS
|
|
46
|
+
* Resolved OS color scheme for SSR / hydration, from Client Hints when the browser sends them.
|
|
47
47
|
*
|
|
48
48
|
* Mirrors client `matchMedia("(prefers-color-scheme: dark)")` when hints are present.
|
|
49
|
-
* Prefer {@link
|
|
49
|
+
* Prefer {@link getRootColorSchemeServerFn} for root loaders.
|
|
50
50
|
*
|
|
51
51
|
* Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
|
|
52
52
|
*
|
|
53
53
|
* @since 0.3.16-canary.0
|
|
54
54
|
*/
|
|
55
|
-
const
|
|
55
|
+
const getSsrColorSchemeServerFn = createServerFn().handler(() => readSsrColorSchemeFromHeaders());
|
|
56
56
|
/**
|
|
57
|
-
* Persist
|
|
57
|
+
* Persist color scheme preference to an HTTP-only cookie.
|
|
58
58
|
*
|
|
59
59
|
* **Security:**
|
|
60
60
|
* - `httpOnly: true` - Cookie cannot be accessed from JavaScript (XSS protection)
|
|
@@ -65,14 +65,14 @@ const getSsrSystemThemeServerFn = createServerFn().handler(() => readSsrSystemTh
|
|
|
65
65
|
* - `maxAge: 1 year` - Preference persists across sessions
|
|
66
66
|
* - `path: '/'` - Available to all routes
|
|
67
67
|
*
|
|
68
|
-
* @param data -
|
|
68
|
+
* @param data - Color scheme to persist ('light', 'dark', or 'automatic')
|
|
69
69
|
*
|
|
70
70
|
* @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
|
|
71
71
|
*
|
|
72
72
|
* @since 0.3.16-canary.0
|
|
73
73
|
*/
|
|
74
|
-
const
|
|
75
|
-
setCookie(
|
|
74
|
+
const setColorSchemeServerFn = createServerFn({ method: "POST" }).inputValidator(colorSchemeSchema).handler(({ data }) => {
|
|
75
|
+
setCookie(STORAGE_KEY, data, {
|
|
76
76
|
httpOnly: true,
|
|
77
77
|
maxAge: 3600 * 24 * 365,
|
|
78
78
|
path: "/",
|
|
@@ -81,13 +81,13 @@ const setThemeServerFn = createServerFn({ method: "POST" }).inputValidator(theme
|
|
|
81
81
|
});
|
|
82
82
|
});
|
|
83
83
|
/**
|
|
84
|
-
* Default {@link
|
|
85
|
-
*
|
|
84
|
+
* Default {@link AppearanceProvider} `persistColorScheme` for the Start adapter: writes the httpOnly
|
|
85
|
+
* color scheme cookie via {@link setColorSchemeServerFn}.
|
|
86
86
|
*
|
|
87
87
|
* @since 0.3.16-canary.0
|
|
88
88
|
*/
|
|
89
|
-
async function
|
|
90
|
-
await
|
|
89
|
+
async function persistColorSchemeCookie(value) {
|
|
90
|
+
await setColorSchemeServerFn({ data: value });
|
|
91
91
|
}
|
|
92
92
|
//#endregion
|
|
93
|
-
export {
|
|
93
|
+
export { getColorSchemeServerFn, getRootColorSchemeServerFn, getSsrColorSchemeServerFn, persistColorSchemeCookie, setColorSchemeServerFn };
|
package/dist/constants.d.mts
CHANGED
|
@@ -1,30 +1,30 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { ColorScheme, ResolvedColorScheme } from "./types.mjs";
|
|
2
2
|
|
|
3
3
|
//#region src/constants.d.ts
|
|
4
4
|
/**
|
|
5
|
-
* Default
|
|
5
|
+
* Default color scheme when no user preference exists.
|
|
6
6
|
*
|
|
7
|
-
* Set to '
|
|
7
|
+
* Set to 'automatic' to respect OS preference by default.
|
|
8
8
|
*
|
|
9
9
|
* @since 0.3.16-canary.0
|
|
10
10
|
*/
|
|
11
|
-
declare const
|
|
11
|
+
declare const DEFAULT_COLOR_SCHEME: ColorScheme;
|
|
12
12
|
/**
|
|
13
|
-
* Fallback
|
|
13
|
+
* Fallback color scheme for SSR when system preference cannot be detected.
|
|
14
14
|
*
|
|
15
15
|
* Used during server-side rendering since `window.matchMedia()` is unavailable.
|
|
16
16
|
*
|
|
17
17
|
* @since 0.3.16-canary.0
|
|
18
18
|
*/
|
|
19
|
-
declare const
|
|
19
|
+
declare const DEFAULT_RESOLVED_COLOR_SCHEME: ResolvedColorScheme;
|
|
20
20
|
/**
|
|
21
|
-
* Cookie name for the httpOnly
|
|
21
|
+
* Cookie name for the httpOnly color scheme preference (`@codefast/theme/start`).
|
|
22
22
|
*
|
|
23
23
|
* Re-exported only from `@codefast/theme/constants` so custom middleware matches the adapter.
|
|
24
24
|
*
|
|
25
25
|
* @since 0.3.16-canary.0
|
|
26
26
|
*/
|
|
27
|
-
declare const
|
|
27
|
+
declare const STORAGE_KEY = "ui-theme";
|
|
28
28
|
/**
|
|
29
29
|
* CSS media query for detecting dark mode preference.
|
|
30
30
|
* @internal
|
|
@@ -33,13 +33,11 @@ declare const THEME_STORAGE_KEY = "ui-theme";
|
|
|
33
33
|
*/
|
|
34
34
|
declare const MEDIA = "(prefers-color-scheme: dark)";
|
|
35
35
|
/**
|
|
36
|
-
* BroadcastChannel name for cross-tab
|
|
37
|
-
*
|
|
38
|
-
* Enables instant theme updates across all open browser tabs.
|
|
36
|
+
* BroadcastChannel name for cross-tab color scheme synchronization.
|
|
39
37
|
* @internal
|
|
40
38
|
*
|
|
41
39
|
* @since 0.3.16-canary.0
|
|
42
40
|
*/
|
|
43
|
-
declare const
|
|
41
|
+
declare const SYNC_CHANNEL = "color-scheme-sync";
|
|
44
42
|
//#endregion
|
|
45
|
-
export {
|
|
43
|
+
export { DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME, MEDIA, STORAGE_KEY, SYNC_CHANNEL };
|
package/dist/constants.mjs
CHANGED
|
@@ -1,28 +1,28 @@
|
|
|
1
1
|
//#region src/constants.ts
|
|
2
2
|
/**
|
|
3
|
-
* Default
|
|
3
|
+
* Default color scheme when no user preference exists.
|
|
4
4
|
*
|
|
5
|
-
* Set to '
|
|
5
|
+
* Set to 'automatic' to respect OS preference by default.
|
|
6
6
|
*
|
|
7
7
|
* @since 0.3.16-canary.0
|
|
8
8
|
*/
|
|
9
|
-
const
|
|
9
|
+
const DEFAULT_COLOR_SCHEME = "automatic";
|
|
10
10
|
/**
|
|
11
|
-
* Fallback
|
|
11
|
+
* Fallback color scheme for SSR when system preference cannot be detected.
|
|
12
12
|
*
|
|
13
13
|
* Used during server-side rendering since `window.matchMedia()` is unavailable.
|
|
14
14
|
*
|
|
15
15
|
* @since 0.3.16-canary.0
|
|
16
16
|
*/
|
|
17
|
-
const
|
|
17
|
+
const DEFAULT_RESOLVED_COLOR_SCHEME = "dark";
|
|
18
18
|
/**
|
|
19
|
-
* Cookie name for the httpOnly
|
|
19
|
+
* Cookie name for the httpOnly color scheme preference (`@codefast/theme/start`).
|
|
20
20
|
*
|
|
21
21
|
* Re-exported only from `@codefast/theme/constants` so custom middleware matches the adapter.
|
|
22
22
|
*
|
|
23
23
|
* @since 0.3.16-canary.0
|
|
24
24
|
*/
|
|
25
|
-
const
|
|
25
|
+
const STORAGE_KEY = "ui-theme";
|
|
26
26
|
/**
|
|
27
27
|
* CSS media query for detecting dark mode preference.
|
|
28
28
|
* @internal
|
|
@@ -31,13 +31,11 @@ const THEME_STORAGE_KEY = "ui-theme";
|
|
|
31
31
|
*/
|
|
32
32
|
const MEDIA = "(prefers-color-scheme: dark)";
|
|
33
33
|
/**
|
|
34
|
-
* BroadcastChannel name for cross-tab
|
|
35
|
-
*
|
|
36
|
-
* Enables instant theme updates across all open browser tabs.
|
|
34
|
+
* BroadcastChannel name for cross-tab color scheme synchronization.
|
|
37
35
|
* @internal
|
|
38
36
|
*
|
|
39
37
|
* @since 0.3.16-canary.0
|
|
40
38
|
*/
|
|
41
|
-
const
|
|
39
|
+
const SYNC_CHANNEL = "color-scheme-sync";
|
|
42
40
|
//#endregion
|
|
43
|
-
export {
|
|
41
|
+
export { DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME, MEDIA, STORAGE_KEY, SYNC_CHANNEL };
|
package/dist/core/context.d.mts
CHANGED
|
@@ -1,19 +1,18 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import * as _$react from "react";
|
|
1
|
+
import { ColorSchemeContextType } from "../types.mjs";
|
|
3
2
|
|
|
4
3
|
//#region src/core/context.d.ts
|
|
5
|
-
type
|
|
4
|
+
type ColorSchemeContextValue = null | ColorSchemeContextType;
|
|
6
5
|
/**
|
|
7
|
-
* React context for
|
|
6
|
+
* React context for color scheme state management.
|
|
8
7
|
*
|
|
9
|
-
* Provides access to current
|
|
10
|
-
* Use {@link
|
|
8
|
+
* Provides access to current color scheme, resolved color scheme, setter function, and pending state.
|
|
9
|
+
* Use {@link useColorScheme} hook instead of consuming this context directly.
|
|
11
10
|
*
|
|
12
|
-
* @see {@link
|
|
13
|
-
* @see {@link
|
|
11
|
+
* @see {@link AppearanceProvider} - Provider component
|
|
12
|
+
* @see {@link useColorScheme} - Consumer hook
|
|
14
13
|
*
|
|
15
14
|
* @since 0.3.16-canary.0
|
|
16
15
|
*/
|
|
17
|
-
declare const
|
|
16
|
+
declare const ColorSchemeContext: import("react").Context<ColorSchemeContextValue>;
|
|
18
17
|
//#endregion
|
|
19
|
-
export {
|
|
18
|
+
export { ColorSchemeContext };
|
package/dist/core/context.mjs
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
import { createContext } from "react";
|
|
2
2
|
//#region src/core/context.tsx
|
|
3
3
|
/**
|
|
4
|
-
* React context for
|
|
4
|
+
* React context for color scheme state management.
|
|
5
5
|
*
|
|
6
|
-
* Provides access to current
|
|
7
|
-
* Use {@link
|
|
6
|
+
* Provides access to current color scheme, resolved color scheme, setter function, and pending state.
|
|
7
|
+
* Use {@link useColorScheme} hook instead of consuming this context directly.
|
|
8
8
|
*
|
|
9
|
-
* @see {@link
|
|
10
|
-
* @see {@link
|
|
9
|
+
* @see {@link AppearanceProvider} - Provider component
|
|
10
|
+
* @see {@link useColorScheme} - Consumer hook
|
|
11
11
|
*
|
|
12
12
|
* @since 0.3.16-canary.0
|
|
13
13
|
*/
|
|
14
|
-
const
|
|
14
|
+
const ColorSchemeContext = createContext(null);
|
|
15
15
|
//#endregion
|
|
16
|
-
export {
|
|
16
|
+
export { ColorSchemeContext };
|