@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 CHANGED
@@ -1,5 +1,51 @@
1
1
  # @codefast/theme
2
2
 
3
+ ## 0.3.16-canary.3
4
+
5
+ ### Patch Changes
6
+
7
+ - [`3fc56a8`](https://github.com/codefastlabs/codefast/commit/3fc56a84c4c39c6510ce509d43daeae32fe90638) Thanks [@thevuong](https://github.com/thevuong)! - Security, correctness, and performance improvements to `ThemeProvider` and `ThemeScript`.
8
+
9
+ **Security**
10
+
11
+ - Validate `BroadcastChannel` messages with `themeSchema.safeParse` before applying — prevents injection from browser extensions or other same-origin scripts
12
+ - Use `JSON.stringify` in `ThemeScript` inline script to safely serialise the theme value
13
+
14
+ **Correctness**
15
+
16
+ - `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
17
+ - Fixed `disableTransitionOnChange` timing: animation cleanup now fires after `applyTheme` commits to the DOM instead of prematurely in the async persist `finally` block
18
+ - Added last-write-wins guard (`intentRef`) so rapid `setTheme` calls only commit the most recent intent
19
+
20
+ **Performance**
21
+
22
+ - `setTheme` callback is now stable across theme commits (reads `committedThemeRef` instead of capturing `theme` in deps) — prevents unnecessary re-renders in consumers
23
+ - `BroadcastChannel` is reused from a shared ref instead of opening a new channel on every `setTheme` call
24
+ - Removed obsolete `-moz-`, `-o-`, `-ms-` vendor prefixes from the `disableAnimation` CSS injection
25
+
26
+ **Features**
27
+
28
+ - `ThemeScript` accepts a new `storageKey` prop: when set, the inline script reads `localStorage` before first paint for FOUC-free client-only apps
29
+ - Runtime Zod validation of the `theme` prop in `ThemeProvider` guards against invalid values bypassing TypeScript
30
+
31
+ **Docs / Tests**
32
+
33
+ - Fixed README: `THEME_STORAGE_KEY` import example now correctly points to `@codefast/theme/constants`
34
+ - Added integration tests for the TanStack Start adapter server functions
35
+ - New test coverage for all security and correctness fixes above
36
+
37
+ - [`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
38
+
39
+ - [`9b94464`](https://github.com/codefastlabs/codefast/commit/9b94464be2247bd5ead32dc3d5c921ae3a52070c) Thanks [@thevuong](https://github.com/thevuong)! - Use minimum `>=` ranges in peerDependencies instead of `^` caret ranges.
40
+
41
+ - [`bed2f30`](https://github.com/codefastlabs/codefast/commit/bed2f30df74128fe3b1a98dd9d03f6bb96099164) Thanks [@thevuong](https://github.com/thevuong)! - feat(web): refactor theme management to color scheme system
42
+
43
+ ## 0.3.16-canary.2
44
+
45
+ ### Patch Changes
46
+
47
+ - [`1ad2cb7`](https://github.com/codefastlabs/codefast/commit/1ad2cb73a3f6f8bff2b001e9df2f2492efd89aa2) Thanks [@thevuong](https://github.com/thevuong)! - chore: align package config globs
48
+
3
49
  ## 0.3.16-canary.1
4
50
 
5
51
  ## 0.3.16-canary.0
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 `^19` (and `react-dom`)
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
 
@@ -131,7 +131,7 @@ function RootShell({ children }: { children: React.ReactNode }) {
131
131
  <html className={resolved} lang="en" style={{ colorScheme: resolved }} suppressHydrationWarning>
132
132
  <head>
133
133
  <HeadContent />
134
- <ThemeScript theme={theme} />
134
+ <ThemeScript nonce={cspNonce} theme={theme} />
135
135
  </head>
136
136
  <body>
137
137
  <ThemeProvider
@@ -222,7 +222,7 @@ export function ThemeSelect() {
222
222
 
223
223
  The script removes any prior `light` / `dark` / `system` class on `<html>`, so it is safe to pre-render the markup with `suppressHydrationWarning`.
224
224
 
225
- > **CSP note.** `<ThemeScript>` currently does not accept a `nonce`. If your CSP forbids inline scripts, either add a specific hash for the generated snippet or serve the same logic from a hashed static file. The `disableTransitionOnChange` option on `<ThemeProvider>` _does_ accept a `nonce` because it injects inline `<style>`.
225
+ > **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
226
 
227
227
  ---
228
228
 
@@ -247,15 +247,16 @@ Root provider that wires together theme state, OS subscription, optimistic updat
247
247
  </ThemeProvider>
248
248
  ```
249
249
 
250
- | Prop | Type | Default | Description |
251
- | --------------------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
252
- | `theme` | `Theme` | — | Initial preference (`"light"` / `"dark"` / `"system"`). Required. |
253
- | `ssrSystemTheme` | `ResolvedTheme` | — | `"light"` or `"dark"` from the SSR request (e.g. Client Hints). Used as the server snapshot when preference is `system`. |
254
- | `persistTheme` | `(value: Theme) => Promise<void>` | — | Runs whenever the user changes the theme. Rejects → optimistic update reverts automatically. |
255
- | `syncThemeFromServer` | `() => Promise<Theme>` | — | Called once after mount to reconcile with the canonical source (e.g. cookie). Useful for stale HTML / duplicate-tab scenarios. |
256
- | `disableTransitionOnChange` | `boolean` | `false` | Temporarily injects a style rule that disables CSS transitions while the theme swaps. Respects `prefers-reduced-motion`. |
257
- | `nonce` | `string` | — | CSP nonce attached to the inline `<style>` element when `disableTransitionOnChange` is enabled. |
258
- | `children` | `ReactNode` | — | Application content. |
250
+ | Prop | Type | Default | Description |
251
+ | --------------------------- | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
252
+ | `theme` | `Theme` | — | Initial preference (`"light"` / `"dark"` / `"system"`). Required. |
253
+ | `ssrSystemTheme` | `ResolvedTheme` | — | `"light"` or `"dark"` from the SSR request (e.g. Client Hints). Used as the server snapshot when preference is `system`. |
254
+ | `persistTheme` | `(value: Theme) => Promise<void>` | — | Runs whenever the user changes the theme. Rejects → optimistic update reverts automatically. |
255
+ | `onThemePersistError` | `(error: unknown, attemptedTheme: Theme) => void` | — | Optional hook called when `persistTheme` rejects; use for custom logging/telemetry/UI feedback. |
256
+ | `syncThemeFromServer` | `() => Promise<Theme>` | — | Called once after mount to reconcile with the canonical source (e.g. cookie). Useful for stale HTML / duplicate-tab scenarios. |
257
+ | `disableTransitionOnChange` | `boolean` | `false` | Temporarily injects a style rule that disables CSS transitions while the theme swaps. Respects `prefers-reduced-motion`. |
258
+ | `nonce` | `string` | — | CSP nonce attached to the inline `<style>` element when `disableTransitionOnChange` is enabled. |
259
+ | `children` | `ReactNode` | — | Application content. |
259
260
 
260
261
  `<ThemeProvider>` internally:
261
262
 
@@ -284,14 +285,16 @@ Throws if called outside of a `<ThemeProvider>`.
284
285
  Inline script for the document head that prevents FOUC.
285
286
 
286
287
  ```tsx
287
- <ThemeScript theme={theme} />
288
+ <ThemeScript nonce={cspNonce} theme={theme} />
288
289
  ```
289
290
 
290
- | Prop | Type | Description |
291
- | ------- | ------- | -------------------------------------------------------------------------------- |
292
- | `theme` | `Theme` | The preference to apply on initial render. `"system"` resolves via `matchMedia`. |
291
+ | Prop | Type | Description |
292
+ | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
293
+ | `theme` | `Theme` | The preference to apply on initial render. `"system"` resolves via `matchMedia`. Acts as fallback when `storageKey` is provided. |
294
+ | `nonce` | `string` | Optional CSP nonce attached to the inline `<script>`. |
295
+ | `storageKey` | `string` | When set, the script reads `localStorage.getItem(storageKey)` before first paint. Use for client-only apps without an SSR cookie. |
293
296
 
294
- The component only emits a `<script>` with `dangerouslySetInnerHTML`. It does not currently accept a `nonce` — see the [CSP note](#ssr-and-fouc-prevention).
297
+ The component emits a `<script>` with `dangerouslySetInnerHTML` and forwards `nonce` when provided.
295
298
 
296
299
  ### `resolveTheme()`
297
300
 
@@ -321,10 +324,12 @@ Granular helpers from `@codefast/theme/utils/system` and `@codefast/theme/utils/
321
324
  import {
322
325
  DEFAULT_RESOLVED_THEME, // "dark"
323
326
  DEFAULT_THEME, // "system"
324
- THEME_STORAGE_KEY, // "ui-theme" — cookie name used by the Start adapter
325
327
  themeSchema, // Zod: z.enum(["light", "dark", "system"])
326
328
  themes, // readonly ["light", "dark", "system"]
327
329
  } from "@codefast/theme";
330
+
331
+ // THEME_STORAGE_KEY lives in the /constants subpath (intentionally not re-exported from root)
332
+ import { THEME_STORAGE_KEY } from "@codefast/theme/constants"; // "ui-theme"
328
333
  ```
329
334
 
330
335
  ### TanStack Start adapter (`@codefast/theme/start`)
@@ -1,63 +1,61 @@
1
- import { ResolvedTheme, Theme } from "../../types.mjs";
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 getRootThemeServerFn} for the root route loader.
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
- interface RootThemeLoaderData {
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 `ThemeProvider` as `ssrSystemTheme` and to
15
- * `resolveTheme(theme, ssrSystemTheme)` on `<html>`. When the hint is absent, matches
16
- * {@link DEFAULT_RESOLVED_THEME}.
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
- ssrSystemTheme: ResolvedTheme;
16
+ readonly ssrColorScheme: ResolvedColorScheme;
19
17
  /**
20
- * User preference from the httpOnly cookie: `light`, `dark`, or `system`.
18
+ * User preference from the httpOnly cookie: `light`, `dark`, or `automatic`.
21
19
  */
22
- theme: Theme;
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: `resolveTheme(theme, ssrSystemTheme)` on `<html>`, plus `ThemeScript` and `ThemeProvider`.
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 getRootThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, RootThemeLoaderData>;
29
+ declare const getRootColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, RootColorSchemeLoaderData>;
32
30
  /**
33
- * Read the user's theme preference from cookies.
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 DEFAULT_THEME} if cookie is missing or invalid.
34
+ * Returns {@link DEFAULT_COLOR_SCHEME} if cookie is missing or invalid.
37
35
  *
38
- * @returns User's stored theme preference or default
36
+ * @returns User's stored color scheme preference or default
39
37
  *
40
38
  * @example
41
39
  * ```tsx
42
- * const theme = await getThemeServerFn();
40
+ * const colorScheme = await getColorSchemeServerFn();
43
41
  * ```
44
42
  *
45
43
  * @since 0.3.16-canary.0
46
44
  */
47
- declare const getThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, "light" | "dark" | "system">;
45
+ declare const getColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, "light" | "dark" | "automatic">;
48
46
  /**
49
- * Resolved OS theme for SSR / hydration, from Client Hints when the browser sends them.
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 getRootThemeServerFn} for root loaders.
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 getSsrSystemThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, ResolvedTheme>;
56
+ declare const getSsrColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, ResolvedColorScheme>;
59
57
  /**
60
- * Persist theme preference to an HTTP-only cookie.
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 - Theme to persist ('light', 'dark', or 'system')
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 setThemeServerFn: _$_tanstack_react_start0.RequiredFetcher<undefined, _$zod.ZodEnum<{
75
+ declare const setColorSchemeServerFn: import("@tanstack/react-start").RequiredFetcher<undefined, import("zod").ZodEnum<{
78
76
  light: "light";
79
77
  dark: "dark";
80
- system: "system";
78
+ automatic: "automatic";
81
79
  }>, void>;
82
80
  /**
83
- * Default {@link ThemeProvider} `persistTheme` for the Start adapter: writes the httpOnly
84
- * theme cookie via {@link setThemeServerFn}.
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 persistThemeCookie(value: Theme): Promise<void>;
86
+ declare function persistColorSchemeCookie(value: ColorScheme): Promise<void>;
89
87
  //#endregion
90
- export { RootThemeLoaderData, getRootThemeServerFn, getSsrSystemThemeServerFn, getThemeServerFn, persistThemeCookie, setThemeServerFn };
88
+ export { RootColorSchemeLoaderData, getColorSchemeServerFn, getRootColorSchemeServerFn, getSsrColorSchemeServerFn, persistColorSchemeCookie, setColorSchemeServerFn };
@@ -1,60 +1,60 @@
1
- import { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, THEME_STORAGE_KEY } from "../../constants.mjs";
2
- import { themeSchema } from "../../types.mjs";
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 readThemeFromCookie() {
7
- const cookieTheme = getCookie(THEME_STORAGE_KEY);
8
- const validationResult = themeSchema.safeParse(cookieTheme);
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 DEFAULT_THEME;
10
+ return DEFAULT_COLOR_SCHEME;
11
11
  }
12
- function readSsrSystemThemeFromHeaders() {
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 DEFAULT_RESOLVED_THEME;
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: `resolveTheme(theme, ssrSystemTheme)` on `<html>`, plus `ThemeScript` and `ThemeProvider`.
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 getRootThemeServerFn = createServerFn().handler(() => ({
26
- theme: readThemeFromCookie(),
27
- ssrSystemTheme: readSsrSystemThemeFromHeaders()
25
+ const getRootColorSchemeServerFn = createServerFn().handler(() => ({
26
+ colorScheme: readColorSchemeFromCookie(),
27
+ ssrColorScheme: readSsrColorSchemeFromHeaders()
28
28
  }));
29
29
  /**
30
- * Read the user's theme preference from cookies.
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 DEFAULT_THEME} if cookie is missing or invalid.
33
+ * Returns {@link DEFAULT_COLOR_SCHEME} if cookie is missing or invalid.
34
34
  *
35
- * @returns User's stored theme preference or default
35
+ * @returns User's stored color scheme preference or default
36
36
  *
37
37
  * @example
38
38
  * ```tsx
39
- * const theme = await getThemeServerFn();
39
+ * const colorScheme = await getColorSchemeServerFn();
40
40
  * ```
41
41
  *
42
42
  * @since 0.3.16-canary.0
43
43
  */
44
- const getThemeServerFn = createServerFn().handler(() => readThemeFromCookie());
44
+ const getColorSchemeServerFn = createServerFn().handler(() => readColorSchemeFromCookie());
45
45
  /**
46
- * Resolved OS theme for SSR / hydration, from Client Hints when the browser sends them.
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 getRootThemeServerFn} for root loaders.
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 getSsrSystemThemeServerFn = createServerFn().handler(() => readSsrSystemThemeFromHeaders());
55
+ const getSsrColorSchemeServerFn = createServerFn().handler(() => readSsrColorSchemeFromHeaders());
56
56
  /**
57
- * Persist theme preference to an HTTP-only cookie.
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 - Theme to persist ('light', 'dark', or 'system')
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 setThemeServerFn = createServerFn({ method: "POST" }).inputValidator(themeSchema).handler(({ data }) => {
75
- setCookie(THEME_STORAGE_KEY, data, {
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 ThemeProvider} `persistTheme` for the Start adapter: writes the httpOnly
85
- * theme cookie via {@link setThemeServerFn}.
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 persistThemeCookie(value) {
90
- await setThemeServerFn({ data: value });
89
+ async function persistColorSchemeCookie(value) {
90
+ await setColorSchemeServerFn({ data: value });
91
91
  }
92
92
  //#endregion
93
- export { getRootThemeServerFn, getSsrSystemThemeServerFn, getThemeServerFn, persistThemeCookie, setThemeServerFn };
93
+ export { getColorSchemeServerFn, getRootColorSchemeServerFn, getSsrColorSchemeServerFn, persistColorSchemeCookie, setColorSchemeServerFn };
@@ -1,30 +1,30 @@
1
- import { ResolvedTheme, Theme } from "./types.mjs";
1
+ import { ColorScheme, ResolvedColorScheme } from "./types.mjs";
2
2
 
3
3
  //#region src/constants.d.ts
4
4
  /**
5
- * Default theme when no user preference exists.
5
+ * Default color scheme when no user preference exists.
6
6
  *
7
- * Set to 'system' to respect OS preference by default.
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 DEFAULT_THEME: Theme;
11
+ declare const DEFAULT_COLOR_SCHEME: ColorScheme;
12
12
  /**
13
- * Fallback theme for SSR when system preference cannot be detected.
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 DEFAULT_RESOLVED_THEME: ResolvedTheme;
19
+ declare const DEFAULT_RESOLVED_COLOR_SCHEME: ResolvedColorScheme;
20
20
  /**
21
- * Cookie name for the httpOnly theme preference (`@codefast/theme/start`).
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 THEME_STORAGE_KEY = "ui-theme";
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 theme synchronization.
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 THEME_CHANNEL = "theme-sync";
41
+ declare const SYNC_CHANNEL = "color-scheme-sync";
44
42
  //#endregion
45
- export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, MEDIA, THEME_CHANNEL, THEME_STORAGE_KEY };
43
+ export { DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME, MEDIA, STORAGE_KEY, SYNC_CHANNEL };
@@ -1,28 +1,28 @@
1
1
  //#region src/constants.ts
2
2
  /**
3
- * Default theme when no user preference exists.
3
+ * Default color scheme when no user preference exists.
4
4
  *
5
- * Set to 'system' to respect OS preference by default.
5
+ * Set to 'automatic' to respect OS preference by default.
6
6
  *
7
7
  * @since 0.3.16-canary.0
8
8
  */
9
- const DEFAULT_THEME = "system";
9
+ const DEFAULT_COLOR_SCHEME = "automatic";
10
10
  /**
11
- * Fallback theme for SSR when system preference cannot be detected.
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 DEFAULT_RESOLVED_THEME = "dark";
17
+ const DEFAULT_RESOLVED_COLOR_SCHEME = "dark";
18
18
  /**
19
- * Cookie name for the httpOnly theme preference (`@codefast/theme/start`).
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 THEME_STORAGE_KEY = "ui-theme";
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 theme synchronization.
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 THEME_CHANNEL = "theme-sync";
39
+ const SYNC_CHANNEL = "color-scheme-sync";
42
40
  //#endregion
43
- export { DEFAULT_RESOLVED_THEME, DEFAULT_THEME, MEDIA, THEME_CHANNEL, THEME_STORAGE_KEY };
41
+ export { DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME, MEDIA, STORAGE_KEY, SYNC_CHANNEL };
@@ -1,19 +1,18 @@
1
- import { ThemeContextType } from "../types.mjs";
2
- import * as _$react from "react";
1
+ import { ColorSchemeContextType } from "../types.mjs";
3
2
 
4
3
  //#region src/core/context.d.ts
5
- type ThemeContextValue = null | ThemeContextType;
4
+ type ColorSchemeContextValue = null | ColorSchemeContextType;
6
5
  /**
7
- * React context for theme state management.
6
+ * React context for color scheme state management.
8
7
  *
9
- * Provides access to current theme, resolved theme, setter function, and pending state.
10
- * Use {@link useTheme} hook instead of consuming this context directly.
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 ThemeProvider} - Provider component
13
- * @see {@link useTheme} - Consumer hook
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 ThemeContext: _$react.Context<ThemeContextValue>;
16
+ declare const ColorSchemeContext: import("react").Context<ColorSchemeContextValue>;
18
17
  //#endregion
19
- export { ThemeContext };
18
+ export { ColorSchemeContext };
@@ -1,16 +1,16 @@
1
1
  import { createContext } from "react";
2
2
  //#region src/core/context.tsx
3
3
  /**
4
- * React context for theme state management.
4
+ * React context for color scheme state management.
5
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.
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 ThemeProvider} - Provider component
10
- * @see {@link useTheme} - Consumer hook
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 ThemeContext = createContext(null);
14
+ const ColorSchemeContext = createContext(null);
15
15
  //#endregion
16
- export { ThemeContext };
16
+ export { ColorSchemeContext };