@codefast/theme 0.3.11-canary.2 → 0.3.12-canary.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +40 -0
- package/README.md +56 -27
- package/dist/adapters/tanstack-start/server.d.ts +41 -13
- package/dist/adapters/tanstack-start/server.d.ts.map +1 -0
- package/dist/adapters/tanstack-start/server.js +91 -64
- package/dist/constants.d.ts +9 -12
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +31 -28
- package/dist/core/context.d.ts +4 -7
- package/dist/core/context.d.ts.map +1 -0
- package/dist/core/context.js +9 -12
- package/dist/core/index.d.ts +4 -4
- package/dist/core/index.d.ts.map +1 -0
- package/dist/core/index.js +3 -4
- package/dist/core/provider.d.ts +56 -35
- package/dist/core/provider.d.ts.map +1 -0
- package/dist/core/provider.js +155 -109
- package/dist/core/use-theme.d.ts +3 -6
- package/dist/core/use-theme.d.ts.map +1 -0
- package/dist/core/use-theme.js +35 -33
- package/dist/index.d.ts +17 -9
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +19 -9
- package/dist/script/index.d.ts +2 -2
- package/dist/script/index.d.ts.map +1 -0
- package/dist/script/index.js +1 -2
- package/dist/script/theme-script.d.ts +12 -15
- package/dist/script/theme-script.d.ts.map +1 -0
- package/dist/script/theme-script.js +30 -27
- package/dist/start.d.ts +47 -0
- package/dist/start.d.ts.map +1 -0
- package/dist/start.js +46 -0
- package/dist/types.d.ts +13 -16
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +14 -18
- package/dist/utils/dom.d.ts +4 -7
- package/dist/utils/dom.d.ts.map +1 -0
- package/dist/utils/dom.js +62 -46
- package/dist/utils/index.d.ts +3 -3
- package/dist/utils/index.d.ts.map +1 -0
- package/dist/utils/index.js +2 -3
- package/dist/utils/system.d.ts +12 -10
- package/dist/utils/system.d.ts.map +1 -0
- package/dist/utils/system.js +38 -25
- package/package.json +17 -11
- package/dist/adapters/tanstack-start/index.d.ts +0 -2
- package/dist/adapters/tanstack-start/index.js +0 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,45 @@
|
|
|
1
1
|
# @codefast/theme
|
|
2
2
|
|
|
3
|
+
## 0.3.12-canary.0
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [`b3dfccb`](https://github.com/codefastlabs/codefast/commit/b3dfccbccff8961ca75a4671ae39e7616a7fa59c) Thanks [@thevuong](https://github.com/thevuong)! - refactor: switch package build scripts from tsdown to TypeScript build configs, align UI CSS exports to source CSS paths, and remove obsolete migration tooling
|
|
8
|
+
|
|
9
|
+
- [`cb53569`](https://github.com/codefastlabs/codefast/commit/cb5356985d4f349dd12a32f9de85cc7d13e8cc74) Thanks [@thevuong](https://github.com/thevuong)! - refactor: migrate package dependencies to catalog references
|
|
10
|
+
|
|
11
|
+
- [`5f01705`](https://github.com/codefastlabs/codefast/commit/5f01705816cbac5ef012e46a0e11a642e76a36d0) Thanks [@thevuong](https://github.com/thevuong)! - refactor: migrate ui to Node subpath imports
|
|
12
|
+
|
|
13
|
+
- [`f82e0fb`](https://github.com/codefastlabs/codefast/commit/f82e0fb9cd98f4d6d06b915ffe45ce2e642eb97d) Thanks [@thevuong](https://github.com/thevuong)! - feat: enhance theme management and SSR support
|
|
14
|
+
|
|
15
|
+
- [`82b37c0`](https://github.com/codefastlabs/codefast/commit/82b37c02ad0086114082cc02be54a60d0c4478a6) Thanks [@thevuong](https://github.com/thevuong)! - refactor: rename typecheck scripts to check-types for consistency
|
|
16
|
+
|
|
17
|
+
- [`3f647bc`](https://github.com/codefastlabs/codefast/commit/3f647bce65e4c12d3349f06a5a3a80acf13b03de) Thanks [@thevuong](https://github.com/thevuong)! - refactor: align remaining alias references to subpath imports
|
|
18
|
+
|
|
19
|
+
- [`b84dd5b`](https://github.com/codefastlabs/codefast/commit/b84dd5b614180d6b59e04d17671003b02ef3aa67) Thanks [@thevuong](https://github.com/thevuong)! - refactor: migrate theme to Node subpath imports
|
|
20
|
+
|
|
21
|
+
- [`59b0ce9`](https://github.com/codefastlabs/codefast/commit/59b0ce932cec3c07356acaf4c7cb52b3f538096b) Thanks [@thevuong](https://github.com/thevuong)! - chore: enhance theme handling and update scripts
|
|
22
|
+
|
|
23
|
+
## 0.3.11
|
|
24
|
+
|
|
25
|
+
### Patch Changes
|
|
26
|
+
|
|
27
|
+
- [`dd5130a`](https://github.com/codefastlabs/codefast/commit/dd5130adb5649dca6773614ffda262cdde732d8f) Thanks [@thevuong](https://github.com/thevuong)! - chore(deps): downgrade @rslib/core to 0.19.1 in package.json and pnpm-lock.yaml
|
|
28
|
+
|
|
29
|
+
- [`135c6be`](https://github.com/codefastlabs/codefast/commit/135c6bed9d1bc1e96bad3173adab1bf32d74322f) Thanks [@thevuong](https://github.com/thevuong)! - chore: update linting and formatting scripts in package.json
|
|
30
|
+
|
|
31
|
+
- [`610cf7a`](https://github.com/codefastlabs/codefast/commit/610cf7a7f9b6e5b37be21e7675ea363ef1020639) Thanks [@thevuong](https://github.com/thevuong)! - fix(hooks): handle missing `navigator.clipboard.writeText` gracefully
|
|
32
|
+
|
|
33
|
+
- [`42758ab`](https://github.com/codefastlabs/codefast/commit/42758ab9d8f548ea9f4a806a7dbb7ed295fe2390) Thanks [@thevuong](https://github.com/thevuong)! - chore: update package configurations and TypeScript settings
|
|
34
|
+
|
|
35
|
+
- [`d2abc63`](https://github.com/codefastlabs/codefast/commit/d2abc636245526ec402811d8585d93684865dde6) Thanks [@thevuong](https://github.com/thevuong)! - chore(deps): update package versions and configurations
|
|
36
|
+
|
|
37
|
+
- [`3e90474`](https://github.com/codefastlabs/codefast/commit/3e90474fbbb9f8ac626c5949bfdbac2eaf1cb3e8) Thanks [@thevuong](https://github.com/thevuong)! - chore: update project configuration and dependencies
|
|
38
|
+
|
|
39
|
+
- [`92d1ed7`](https://github.com/codefastlabs/codefast/commit/92d1ed7650b19f91824cfb38ec238857a3d95876) Thanks [@thevuong](https://github.com/thevuong)! - build: replace rslib with tsdown in library packages
|
|
40
|
+
|
|
41
|
+
- [`5c09d4c`](https://github.com/codefastlabs/codefast/commit/5c09d4ce2df564dc7ac6727b00cfa668164a1af4) Thanks [@thevuong](https://github.com/thevuong)! - refactor(config): rename `check-types` to `typecheck` and update usage
|
|
42
|
+
|
|
3
43
|
## 0.3.11-canary.2
|
|
4
44
|
|
|
5
45
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -39,7 +39,19 @@ Theme management for React 19 applications with optimistic updates, cross-tab sy
|
|
|
39
39
|
- **Cross-tab Sync** -- Theme changes propagate instantly across all open browser tabs.
|
|
40
40
|
- **Optimistic Updates** -- Immediate UI feedback during asynchronous theme persistence.
|
|
41
41
|
- **SSR Ready** -- Inline script prevents flash of unstyled content (FOUC) on server-rendered pages.
|
|
42
|
-
- **
|
|
42
|
+
- **TanStack Start** -- `@codefast/theme/start` bundles cookie persistence and loader helpers.
|
|
43
|
+
|
|
44
|
+
## Public entry points
|
|
45
|
+
|
|
46
|
+
| Import | Contents |
|
|
47
|
+
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| `@codefast/theme` | `ThemeProvider`, `useTheme`, `ThemeScript`, `resolveTheme`, types, `themes`, defaults |
|
|
49
|
+
| `@codefast/theme/start` | `getRootThemeServerFn`, `getThemeServerFn`, `getSsrSystemThemeServerFn`, `setThemeServerFn`, `persistThemeCookie`, `RootThemeLoaderData` |
|
|
50
|
+
| `@codefast/theme/utils` | `getSystemTheme`, `applyTheme`, `disableAnimation`, `resolveTheme` |
|
|
51
|
+
| `@codefast/theme/core` | `ThemeContext`, `ThemeProvider`, `useTheme` |
|
|
52
|
+
| `@codefast/theme/script` | `ThemeScript` |
|
|
53
|
+
| `@codefast/theme/constants` | `DEFAULT_THEME`, `DEFAULT_RESOLVED_THEME`, `THEME_STORAGE_KEY`, … |
|
|
54
|
+
| `@codefast/theme/types` | `themeSchema`, types |
|
|
43
55
|
|
|
44
56
|
## Installation
|
|
45
57
|
|
|
@@ -99,35 +111,47 @@ function Page() {
|
|
|
99
111
|
|
|
100
112
|
### TanStack Start
|
|
101
113
|
|
|
102
|
-
|
|
114
|
+
Server persistence and loader data live in `@codefast/theme/start`. Your shell keeps full control of `<html>` / `<head>` / `<body>`.
|
|
103
115
|
|
|
104
116
|
```tsx
|
|
105
|
-
// routes/__root.tsx
|
|
117
|
+
// routes/__root.tsx (pattern; adjust to your router setup)
|
|
118
|
+
import { HeadContent, Scripts, createRootRouteWithContext } from "@tanstack/react-router";
|
|
119
|
+
import { getRootThemeServerFn, getThemeServerFn, persistThemeCookie } from "@codefast/theme/start";
|
|
106
120
|
import { ThemeProvider, ThemeScript, resolveTheme } from "@codefast/theme";
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
const theme = await getThemeServerFn();
|
|
112
|
-
return { theme };
|
|
113
|
-
},
|
|
114
|
-
component: RootComponent,
|
|
115
|
-
head: ({ loaderData }) => ({
|
|
116
|
-
scripts: [{ tag: ThemeScript, props: { theme: loaderData?.theme ?? "system" } }],
|
|
117
|
-
}),
|
|
121
|
+
|
|
122
|
+
export const Route = createRootRouteWithContext<YourContext>()({
|
|
123
|
+
loader: async () => getRootThemeServerFn(),
|
|
124
|
+
shellComponent: RootShell,
|
|
118
125
|
});
|
|
119
126
|
|
|
120
|
-
function
|
|
121
|
-
const { theme } = Route.useLoaderData();
|
|
127
|
+
function RootShell({ children }: { children: React.ReactNode }) {
|
|
128
|
+
const { theme, ssrSystemTheme } = Route.useLoaderData();
|
|
129
|
+
const resolved = resolveTheme(theme, ssrSystemTheme);
|
|
122
130
|
|
|
123
131
|
return (
|
|
124
|
-
<
|
|
125
|
-
<
|
|
126
|
-
|
|
132
|
+
<html className={resolved} lang="en" style={{ colorScheme: resolved }} suppressHydrationWarning>
|
|
133
|
+
<head>
|
|
134
|
+
<HeadContent />
|
|
135
|
+
<ThemeScript theme={theme} />
|
|
136
|
+
</head>
|
|
137
|
+
<body>
|
|
138
|
+
<ThemeProvider
|
|
139
|
+
theme={theme}
|
|
140
|
+
ssrSystemTheme={ssrSystemTheme}
|
|
141
|
+
persistTheme={persistThemeCookie}
|
|
142
|
+
syncThemeFromServer={getThemeServerFn}
|
|
143
|
+
>
|
|
144
|
+
{children}
|
|
145
|
+
</ThemeProvider>
|
|
146
|
+
<Scripts />
|
|
147
|
+
</body>
|
|
148
|
+
</html>
|
|
127
149
|
);
|
|
128
150
|
}
|
|
129
151
|
```
|
|
130
152
|
|
|
153
|
+
Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` and include both that header and `Cookie` in response `Vary` so cached HTML is not reused with the wrong theme. `syncThemeFromServer` covers remaining stale-document edge cases (e.g. duplicate tab).
|
|
154
|
+
|
|
131
155
|
### Generic React (Client-Side)
|
|
132
156
|
|
|
133
157
|
For client-side React applications without a server framework, persist the theme to `localStorage`:
|
|
@@ -212,13 +236,15 @@ Root provider component that manages theme state and context.
|
|
|
212
236
|
</ThemeProvider>
|
|
213
237
|
```
|
|
214
238
|
|
|
215
|
-
| Prop | Type | Default | Description
|
|
216
|
-
| --------------------------- | --------------------------------- | ------- |
|
|
217
|
-
| `theme` | `Theme` | -- | Initial theme value (`'light'`, `'dark'`, or `'system'`)
|
|
218
|
-
| `
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
| `
|
|
239
|
+
| Prop | Type | Default | Description |
|
|
240
|
+
| --------------------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
241
|
+
| `theme` | `Theme` | -- | Initial theme value (`'light'`, `'dark'`, or `'system'`) |
|
|
242
|
+
| `ssrSystemTheme` | `ResolvedTheme` | -- | Optional `light`/`dark` from SSR (e.g. Client Hints) so `system` hydrates without flipping |
|
|
243
|
+
| `syncThemeFromServer` | `() => Promise<Theme>` | -- | Once after mount, re-read cookie/source of truth (fixes stale cached HTML on duplicate tab). Use `getThemeServerFn` from `@codefast/theme/start` |
|
|
244
|
+
| `persistTheme` | `(value: Theme) => Promise<void>` | -- | Callback invoked when the user changes the theme |
|
|
245
|
+
| `disableTransitionOnChange` | `boolean` | `false` | Disable CSS transitions during theme changes to avoid visual flicker |
|
|
246
|
+
| `nonce` | `string` | -- | CSP nonce for inline `<style>` elements |
|
|
247
|
+
| `children` | `React.ReactNode` | -- | Application content |
|
|
222
248
|
|
|
223
249
|
### useTheme
|
|
224
250
|
|
|
@@ -255,7 +281,8 @@ Utility function that resolves a theme value to either `'light'` or `'dark'`.
|
|
|
255
281
|
```typescript
|
|
256
282
|
import { resolveTheme } from "@codefast/theme";
|
|
257
283
|
|
|
258
|
-
const resolved = resolveTheme("system"); //
|
|
284
|
+
const resolved = resolveTheme("system"); // client: OS via matchMedia
|
|
285
|
+
const ssr = resolveTheme("system", "light"); // server: pass Client-Hint–backed value
|
|
259
286
|
```
|
|
260
287
|
|
|
261
288
|
### themes
|
|
@@ -285,6 +312,8 @@ pnpm test --filter=@codefast/theme
|
|
|
285
312
|
pnpm test:coverage --filter=@codefast/theme
|
|
286
313
|
```
|
|
287
314
|
|
|
315
|
+
Package build/dev scripts use TypeScript directly via `tsc -p tsconfig.build.json` (watch mode for `pnpm dev --filter=@codefast/theme`).
|
|
316
|
+
|
|
288
317
|
## License
|
|
289
318
|
|
|
290
319
|
Distributed under the MIT License. See [LICENSE](../../LICENSE) for more details.
|
|
@@ -1,8 +1,24 @@
|
|
|
1
|
-
import { Theme } from "
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
import type { ResolvedTheme, Theme } from "#types";
|
|
2
|
+
/**
|
|
3
|
+
* Data shape returned from {@link getRootThemeServerFn} for the root route loader.
|
|
4
|
+
*/
|
|
5
|
+
export interface RootThemeLoaderData {
|
|
6
|
+
/**
|
|
7
|
+
* Resolved `light` or `dark` from the incoming request when detectable
|
|
8
|
+
* (e.g. `Sec-CH-Prefers-Color-Scheme`). Pass to `ThemeProvider` as `ssrSystemTheme` and to
|
|
9
|
+
* `resolveTheme(theme, ssrSystemTheme)` on `<html>`. When the hint is absent, matches
|
|
10
|
+
* {@link DEFAULT_RESOLVED_THEME}.
|
|
11
|
+
*/
|
|
12
|
+
ssrSystemTheme: ResolvedTheme;
|
|
13
|
+
/** User preference from the httpOnly cookie: `light`, `dark`, or `system`. */
|
|
14
|
+
theme: Theme;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Everything needed for the root shell in **one** server call (fewer loader awaits).
|
|
18
|
+
*
|
|
19
|
+
* In your shell: `resolveTheme(theme, ssrSystemTheme)` on `<html>`, plus `ThemeScript` and `ThemeProvider`.
|
|
20
|
+
*/
|
|
21
|
+
export declare const getRootThemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, RootThemeLoaderData>;
|
|
6
22
|
/**
|
|
7
23
|
* Read the user's theme preference from cookies.
|
|
8
24
|
*
|
|
@@ -16,7 +32,16 @@ import * as _$_tanstack_react_start0 from "@tanstack/react-start";
|
|
|
16
32
|
* const theme = await getThemeServerFn();
|
|
17
33
|
* ```
|
|
18
34
|
*/
|
|
19
|
-
declare const getThemeServerFn:
|
|
35
|
+
export declare const getThemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, "light" | "dark" | "system">;
|
|
36
|
+
/**
|
|
37
|
+
* Resolved OS theme for SSR / hydration, from Client Hints when the browser sends them.
|
|
38
|
+
*
|
|
39
|
+
* Mirrors client `matchMedia("(prefers-color-scheme: dark)")` when hints are present.
|
|
40
|
+
* Prefer {@link getRootThemeServerFn} for root loaders.
|
|
41
|
+
*
|
|
42
|
+
* Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
|
|
43
|
+
*/
|
|
44
|
+
export declare const getSsrSystemThemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, ResolvedTheme>;
|
|
20
45
|
/**
|
|
21
46
|
* Persist theme preference to an HTTP-only cookie.
|
|
22
47
|
*
|
|
@@ -33,11 +58,14 @@ declare const getThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefin
|
|
|
33
58
|
*
|
|
34
59
|
* @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
|
|
35
60
|
*/
|
|
36
|
-
declare const setThemeServerFn:
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
61
|
+
export declare const setThemeServerFn: import("@tanstack/react-start").RequiredFetcher<undefined, import("zod").ZodEnum<{
|
|
62
|
+
light: "light";
|
|
63
|
+
dark: "dark";
|
|
64
|
+
system: "system";
|
|
40
65
|
}>, void>;
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
66
|
+
/**
|
|
67
|
+
* Default {@link ThemeProvider} `persistTheme` for the Start adapter: writes the httpOnly
|
|
68
|
+
* theme cookie via {@link setThemeServerFn}.
|
|
69
|
+
*/
|
|
70
|
+
export declare function persistThemeCookie(value: Theme): Promise<void>;
|
|
71
|
+
//# sourceMappingURL=server.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/adapters/tanstack-start/server.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAmCnD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,cAAc,EAAE,aAAa,CAAC;IAC9B,8EAA8E;IAC9E,KAAK,EAAE,KAAK,CAAC;CACd;AASD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,4FAKhC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,oGAA+D,CAAC;AAE7F;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,sFAErC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB;;;;SAUzB,CAAC;AAEL;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpE"}
|
|
@@ -1,70 +1,97 @@
|
|
|
1
|
-
import { DEFAULT_THEME, THEME_STORAGE_KEY } from "../../constants.js";
|
|
2
|
-
import { themeSchema } from "../../types.js";
|
|
3
1
|
import { createServerFn } from "@tanstack/react-start";
|
|
4
|
-
import { getCookie, setCookie } from "@tanstack/react-start/server";
|
|
5
|
-
|
|
2
|
+
import { getCookie, getRequestHeader, setCookie } from "@tanstack/react-start/server";
|
|
3
|
+
import { themeSchema } from "#types";
|
|
4
|
+
import { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, THEME_STORAGE_KEY } from "#constants";
|
|
5
|
+
/* -----------------------------------------------------------------------------
|
|
6
|
+
* Request helpers (one round-trip when composed)
|
|
7
|
+
* -------------------------------------------------------------------------- */
|
|
8
|
+
function readThemeFromCookie() {
|
|
9
|
+
const cookieTheme = getCookie(THEME_STORAGE_KEY);
|
|
10
|
+
const validationResult = themeSchema.safeParse(cookieTheme);
|
|
11
|
+
if (validationResult.success) {
|
|
12
|
+
return validationResult.data;
|
|
13
|
+
}
|
|
14
|
+
return DEFAULT_THEME;
|
|
15
|
+
}
|
|
16
|
+
function readSsrSystemThemeFromHeaders() {
|
|
17
|
+
const hint = getRequestHeader("Sec-CH-Prefers-Color-Scheme") ?? getRequestHeader("Prefers-Color-Scheme");
|
|
18
|
+
if (hint === "dark") {
|
|
19
|
+
return "dark";
|
|
20
|
+
}
|
|
21
|
+
if (hint === "light") {
|
|
22
|
+
return "light";
|
|
23
|
+
}
|
|
24
|
+
return DEFAULT_RESOLVED_THEME;
|
|
25
|
+
}
|
|
26
|
+
/* -----------------------------------------------------------------------------
|
|
27
|
+
* Server Functions
|
|
28
|
+
*
|
|
29
|
+
* These functions run on the server and handle cookie-based theme persistence.
|
|
30
|
+
* Cookies are httpOnly for security - the client cannot read them directly.
|
|
31
|
+
* -------------------------------------------------------------------------- */
|
|
6
32
|
/**
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
33
|
+
* Everything needed for the root shell in **one** server call (fewer loader awaits).
|
|
34
|
+
*
|
|
35
|
+
* In your shell: `resolveTheme(theme, ssrSystemTheme)` on `<html>`, plus `ThemeScript` and `ThemeProvider`.
|
|
36
|
+
*/
|
|
37
|
+
export const getRootThemeServerFn = createServerFn().handler(() => ({
|
|
38
|
+
theme: readThemeFromCookie(),
|
|
39
|
+
ssrSystemTheme: readSsrSystemThemeFromHeaders(),
|
|
40
|
+
}));
|
|
41
|
+
/**
|
|
42
|
+
* Read the user's theme preference from cookies.
|
|
43
|
+
*
|
|
44
|
+
* Validates the cookie value using Zod schema for type safety.
|
|
45
|
+
* Returns {@link DEFAULT_THEME} if cookie is missing or invalid.
|
|
46
|
+
*
|
|
47
|
+
* @returns User's stored theme preference or default
|
|
48
|
+
*
|
|
49
|
+
* @example
|
|
50
|
+
* ```tsx
|
|
51
|
+
* const theme = await getThemeServerFn();
|
|
52
|
+
* ```
|
|
53
|
+
*/
|
|
54
|
+
export const getThemeServerFn = createServerFn().handler(() => readThemeFromCookie());
|
|
55
|
+
/**
|
|
56
|
+
* Resolved OS theme for SSR / hydration, from Client Hints when the browser sends them.
|
|
57
|
+
*
|
|
58
|
+
* Mirrors client `matchMedia("(prefers-color-scheme: dark)")` when hints are present.
|
|
59
|
+
* Prefer {@link getRootThemeServerFn} for root loaders.
|
|
60
|
+
*
|
|
61
|
+
* Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
|
|
62
|
+
*/
|
|
63
|
+
export const getSsrSystemThemeServerFn = createServerFn().handler(() => readSsrSystemThemeFromHeaders());
|
|
25
64
|
/**
|
|
26
|
-
* Persist theme preference to an HTTP-only cookie.
|
|
27
|
-
*
|
|
28
|
-
* **Security:**
|
|
29
|
-
* - `httpOnly: true` - Cookie cannot be accessed from JavaScript (XSS protection)
|
|
30
|
-
* - `secure: true` in production - Cookie only sent over HTTPS
|
|
31
|
-
* - `sameSite: 'lax'` - Prevents CSRF while allowing navigation
|
|
32
|
-
*
|
|
33
|
-
* **Cookie Settings:**
|
|
34
|
-
* - `maxAge: 1 year` - Preference persists across sessions
|
|
35
|
-
* - `path: '/'` - Available to all routes
|
|
36
|
-
*
|
|
37
|
-
* @param data - Theme to persist ('light', 'dark', or 'system')
|
|
38
|
-
*
|
|
39
|
-
* @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
|
|
40
|
-
*/
|
|
41
|
-
const setThemeServerFn = createServerFn({ method: "POST" })
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
65
|
+
* Persist theme preference to an HTTP-only cookie.
|
|
66
|
+
*
|
|
67
|
+
* **Security:**
|
|
68
|
+
* - `httpOnly: true` - Cookie cannot be accessed from JavaScript (XSS protection)
|
|
69
|
+
* - `secure: true` in production - Cookie only sent over HTTPS
|
|
70
|
+
* - `sameSite: 'lax'` - Prevents CSRF while allowing navigation
|
|
71
|
+
*
|
|
72
|
+
* **Cookie Settings:**
|
|
73
|
+
* - `maxAge: 1 year` - Preference persists across sessions
|
|
74
|
+
* - `path: '/'` - Available to all routes
|
|
75
|
+
*
|
|
76
|
+
* @param data - Theme to persist ('light', 'dark', or 'system')
|
|
77
|
+
*
|
|
78
|
+
* @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
|
|
79
|
+
*/
|
|
80
|
+
export const setThemeServerFn = createServerFn({ method: "POST" })
|
|
81
|
+
.inputValidator(themeSchema)
|
|
82
|
+
.handler(({ data }) => {
|
|
83
|
+
setCookie(THEME_STORAGE_KEY, data, {
|
|
84
|
+
httpOnly: true,
|
|
85
|
+
maxAge: 60 * 60 * 24 * 365, // 1 year
|
|
86
|
+
path: "/",
|
|
87
|
+
sameSite: "lax",
|
|
88
|
+
secure: process.env.NODE_ENV === "production",
|
|
89
|
+
});
|
|
49
90
|
});
|
|
50
91
|
/**
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
* @returns Async function compatible with ThemeProvider's persistTheme prop
|
|
57
|
-
*
|
|
58
|
-
* @example
|
|
59
|
-
* ```tsx
|
|
60
|
-
* <ThemeProvider persistTheme={(value) => setThemeServerFn({ data: value })}>
|
|
61
|
-
* ```
|
|
62
|
-
*/
|
|
63
|
-
const persistThemeHandler = async (value) => {
|
|
64
|
-
await setThemeServerFn({ data: value });
|
|
65
|
-
};
|
|
66
|
-
function createPersistTheme() {
|
|
67
|
-
return persistThemeHandler;
|
|
92
|
+
* Default {@link ThemeProvider} `persistTheme` for the Start adapter: writes the httpOnly
|
|
93
|
+
* theme cookie via {@link setThemeServerFn}.
|
|
94
|
+
*/
|
|
95
|
+
export async function persistThemeCookie(value) {
|
|
96
|
+
await setThemeServerFn({ data: value });
|
|
68
97
|
}
|
|
69
|
-
//#endregion
|
|
70
|
-
export { createPersistTheme, getThemeServerFn, setThemeServerFn };
|
package/dist/constants.d.ts
CHANGED
|
@@ -1,35 +1,32 @@
|
|
|
1
|
-
import { ResolvedTheme, Theme } from "
|
|
2
|
-
|
|
3
|
-
//#region src/constants.d.ts
|
|
1
|
+
import type { ResolvedTheme, Theme } from "#types";
|
|
4
2
|
/**
|
|
5
3
|
* Default theme when no user preference exists.
|
|
6
4
|
*
|
|
7
5
|
* Set to 'system' to respect OS preference by default.
|
|
8
6
|
*/
|
|
9
|
-
declare const DEFAULT_THEME: Theme;
|
|
7
|
+
export declare const DEFAULT_THEME: Theme;
|
|
10
8
|
/**
|
|
11
9
|
* Fallback theme for SSR when system preference cannot be detected.
|
|
12
10
|
*
|
|
13
11
|
* Used during server-side rendering since `window.matchMedia()` is unavailable.
|
|
14
12
|
*/
|
|
15
|
-
declare const DEFAULT_RESOLVED_THEME: ResolvedTheme;
|
|
13
|
+
export declare const DEFAULT_RESOLVED_THEME: ResolvedTheme;
|
|
16
14
|
/**
|
|
17
|
-
* Cookie
|
|
15
|
+
* Cookie name for the httpOnly theme preference (`@codefast/theme/start`).
|
|
18
16
|
*
|
|
19
|
-
*
|
|
17
|
+
* Re-exported only from `@codefast/theme/constants` so custom middleware matches the adapter.
|
|
20
18
|
*/
|
|
21
|
-
declare const THEME_STORAGE_KEY = "ui-theme";
|
|
19
|
+
export declare const THEME_STORAGE_KEY = "ui-theme";
|
|
22
20
|
/**
|
|
23
21
|
* CSS media query for detecting dark mode preference.
|
|
24
22
|
* @internal
|
|
25
23
|
*/
|
|
26
|
-
declare const MEDIA = "(prefers-color-scheme: dark)";
|
|
24
|
+
export declare const MEDIA = "(prefers-color-scheme: dark)";
|
|
27
25
|
/**
|
|
28
26
|
* BroadcastChannel name for cross-tab theme synchronization.
|
|
29
27
|
*
|
|
30
28
|
* Enables instant theme updates across all open browser tabs.
|
|
31
29
|
* @internal
|
|
32
30
|
*/
|
|
33
|
-
declare const THEME_CHANNEL = "theme-sync";
|
|
34
|
-
//#
|
|
35
|
-
export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, MEDIA, THEME_CHANNEL, THEME_STORAGE_KEY };
|
|
31
|
+
export declare const THEME_CHANNEL = "theme-sync";
|
|
32
|
+
//# sourceMappingURL=constants.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAMnD;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,KAAgB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAsB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAM5C;;;GAGG;AACH,eAAO,MAAM,KAAK,iCAAiC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,eAAe,CAAC"}
|
package/dist/constants.js
CHANGED
|
@@ -1,33 +1,36 @@
|
|
|
1
|
-
|
|
1
|
+
/* -----------------------------------------------------------------------------
|
|
2
|
+
* Public Constants
|
|
3
|
+
* -------------------------------------------------------------------------- */
|
|
2
4
|
/**
|
|
3
|
-
* Default theme when no user preference exists.
|
|
4
|
-
*
|
|
5
|
-
* Set to 'system' to respect OS preference by default.
|
|
6
|
-
*/
|
|
7
|
-
const DEFAULT_THEME = "system";
|
|
5
|
+
* Default theme when no user preference exists.
|
|
6
|
+
*
|
|
7
|
+
* Set to 'system' to respect OS preference by default.
|
|
8
|
+
*/
|
|
9
|
+
export const DEFAULT_THEME = "system";
|
|
8
10
|
/**
|
|
9
|
-
* Fallback theme for SSR when system preference cannot be detected.
|
|
10
|
-
*
|
|
11
|
-
* Used during server-side rendering since `window.matchMedia()` is unavailable.
|
|
12
|
-
*/
|
|
13
|
-
const DEFAULT_RESOLVED_THEME = "dark";
|
|
11
|
+
* Fallback theme for SSR when system preference cannot be detected.
|
|
12
|
+
*
|
|
13
|
+
* Used during server-side rendering since `window.matchMedia()` is unavailable.
|
|
14
|
+
*/
|
|
15
|
+
export const DEFAULT_RESOLVED_THEME = "dark";
|
|
14
16
|
/**
|
|
15
|
-
* Cookie
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*/
|
|
19
|
-
const THEME_STORAGE_KEY = "ui-theme";
|
|
17
|
+
* Cookie name for the httpOnly theme preference (`@codefast/theme/start`).
|
|
18
|
+
*
|
|
19
|
+
* Re-exported only from `@codefast/theme/constants` so custom middleware matches the adapter.
|
|
20
|
+
*/
|
|
21
|
+
export const THEME_STORAGE_KEY = "ui-theme";
|
|
22
|
+
/* -----------------------------------------------------------------------------
|
|
23
|
+
* Internal Constants
|
|
24
|
+
* -------------------------------------------------------------------------- */
|
|
20
25
|
/**
|
|
21
|
-
* CSS media query for detecting dark mode preference.
|
|
22
|
-
* @internal
|
|
23
|
-
*/
|
|
24
|
-
const MEDIA = "(prefers-color-scheme: dark)";
|
|
26
|
+
* CSS media query for detecting dark mode preference.
|
|
27
|
+
* @internal
|
|
28
|
+
*/
|
|
29
|
+
export const MEDIA = "(prefers-color-scheme: dark)";
|
|
25
30
|
/**
|
|
26
|
-
* BroadcastChannel name for cross-tab theme synchronization.
|
|
27
|
-
*
|
|
28
|
-
* Enables instant theme updates across all open browser tabs.
|
|
29
|
-
* @internal
|
|
30
|
-
*/
|
|
31
|
-
const THEME_CHANNEL = "theme-sync";
|
|
32
|
-
//#endregion
|
|
33
|
-
export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, MEDIA, THEME_CHANNEL, THEME_STORAGE_KEY };
|
|
31
|
+
* BroadcastChannel name for cross-tab theme synchronization.
|
|
32
|
+
*
|
|
33
|
+
* Enables instant theme updates across all open browser tabs.
|
|
34
|
+
* @internal
|
|
35
|
+
*/
|
|
36
|
+
export const THEME_CHANNEL = "theme-sync";
|
package/dist/core/context.d.ts
CHANGED
|
@@ -1,7 +1,4 @@
|
|
|
1
|
-
import { ThemeContextType } from "
|
|
2
|
-
import * as _$react from "react";
|
|
3
|
-
|
|
4
|
-
//#region src/core/context.d.ts
|
|
1
|
+
import type { ThemeContextType } from "#types";
|
|
5
2
|
type ThemeContextValue = null | ThemeContextType;
|
|
6
3
|
/**
|
|
7
4
|
* React context for theme state management.
|
|
@@ -12,6 +9,6 @@ type ThemeContextValue = null | ThemeContextType;
|
|
|
12
9
|
* @see {@link ThemeProvider} - Provider component
|
|
13
10
|
* @see {@link useTheme} - Consumer hook
|
|
14
11
|
*/
|
|
15
|
-
declare const ThemeContext:
|
|
16
|
-
|
|
17
|
-
|
|
12
|
+
export declare const ThemeContext: import("react").Context<ThemeContextValue>;
|
|
13
|
+
export {};
|
|
14
|
+
//# sourceMappingURL=context.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAM/C,KAAK,iBAAiB,GAAG,IAAI,GAAG,gBAAgB,CAAC;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,4CAAyC,CAAC"}
|
package/dist/core/context.js
CHANGED
|
@@ -1,14 +1,11 @@
|
|
|
1
1
|
import { createContext } from "react";
|
|
2
|
-
//#region src/core/context.tsx
|
|
3
2
|
/**
|
|
4
|
-
* React context for theme state management.
|
|
5
|
-
*
|
|
6
|
-
* Provides access to current theme, resolved theme, setter function, and pending state.
|
|
7
|
-
* Use {@link useTheme} hook instead of consuming this context directly.
|
|
8
|
-
*
|
|
9
|
-
* @see {@link ThemeProvider} - Provider component
|
|
10
|
-
* @see {@link useTheme} - Consumer hook
|
|
11
|
-
*/
|
|
12
|
-
const ThemeContext = createContext(null);
|
|
13
|
-
//#endregion
|
|
14
|
-
export { ThemeContext };
|
|
3
|
+
* React context for theme state management.
|
|
4
|
+
*
|
|
5
|
+
* Provides access to current theme, resolved theme, setter function, and pending state.
|
|
6
|
+
* Use {@link useTheme} hook instead of consuming this context directly.
|
|
7
|
+
*
|
|
8
|
+
* @see {@link ThemeProvider} - Provider component
|
|
9
|
+
* @see {@link useTheme} - Consumer hook
|
|
10
|
+
*/
|
|
11
|
+
export const ThemeContext = createContext(null);
|
package/dist/core/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
1
|
+
export { ThemeContext } from "#core/context";
|
|
2
|
+
export { ThemeProvider } from "#core/provider";
|
|
3
|
+
export { useTheme } from "#core/use-theme";
|
|
4
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC"}
|
package/dist/core/index.js
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
export { ThemeContext, ThemeProvider, useTheme };
|
|
1
|
+
export { ThemeContext } from "#core/context";
|
|
2
|
+
export { ThemeProvider } from "#core/provider";
|
|
3
|
+
export { useTheme } from "#core/use-theme";
|