@codefast/theme 0.5.0-canary.1 → 0.5.0-canary.2

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.
Files changed (57) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +107 -178
  3. package/dist/appearance-context.d.mts +18 -0
  4. package/dist/appearance-context.mjs +16 -0
  5. package/dist/appearance-provider.d.mts +74 -0
  6. package/dist/appearance-provider.mjs +180 -0
  7. package/dist/appearance-script.d.mts +59 -0
  8. package/dist/appearance-script.mjs +46 -0
  9. package/dist/appearance.d.mts +60 -0
  10. package/dist/appearance.mjs +25 -0
  11. package/dist/color-scheme.d.mts +27 -0
  12. package/dist/color-scheme.mjs +32 -0
  13. package/dist/constants.d.mts +15 -14
  14. package/dist/constants.mjs +14 -13
  15. package/dist/{utils/dom.d.mts → dom.d.mts} +6 -8
  16. package/dist/{utils/dom.mjs → dom.mjs} +7 -9
  17. package/dist/index.d.mts +7 -7
  18. package/dist/index.mjs +7 -7
  19. package/dist/use-appearance.d.mts +34 -0
  20. package/dist/use-appearance.mjs +38 -0
  21. package/package.json +39 -63
  22. package/src/appearance-context.ts +22 -0
  23. package/src/appearance-provider.tsx +363 -0
  24. package/src/appearance-script.tsx +86 -0
  25. package/src/appearance.ts +66 -0
  26. package/src/color-scheme.ts +42 -0
  27. package/src/constants.ts +14 -13
  28. package/src/{utils/dom.ts → dom.ts} +8 -10
  29. package/src/index.ts +19 -16
  30. package/src/use-appearance.ts +46 -0
  31. package/dist/adapters/tanstack-start/server.d.mts +0 -88
  32. package/dist/adapters/tanstack-start/server.mjs +0 -93
  33. package/dist/adapters/tanstack-start/vite.d.mts +0 -12
  34. package/dist/adapters/tanstack-start/vite.mjs +0 -21
  35. package/dist/core/context.d.mts +0 -18
  36. package/dist/core/context.mjs +0 -16
  37. package/dist/core/provider.d.mts +0 -118
  38. package/dist/core/provider.mjs +0 -231
  39. package/dist/core/use-theme.d.mts +0 -34
  40. package/dist/core/use-theme.mjs +0 -38
  41. package/dist/script/theme-script.d.mts +0 -68
  42. package/dist/script/theme-script.mjs +0 -45
  43. package/dist/start.d.mts +0 -2
  44. package/dist/start.mjs +0 -2
  45. package/dist/types.d.mts +0 -60
  46. package/dist/types.mjs +0 -25
  47. package/dist/utils/system.d.mts +0 -34
  48. package/dist/utils/system.mjs +0 -40
  49. package/src/adapters/tanstack-start/server.ts +0 -146
  50. package/src/adapters/tanstack-start/vite.ts +0 -50
  51. package/src/core/context.tsx +0 -22
  52. package/src/core/provider.tsx +0 -470
  53. package/src/core/use-theme.ts +0 -46
  54. package/src/script/theme-script.tsx +0 -92
  55. package/src/start.ts +0 -54
  56. package/src/types.ts +0 -61
  57. package/src/utils/system.ts +0 -56
package/src/index.ts CHANGED
@@ -1,29 +1,32 @@
1
1
  /**
2
2
  * \@codefast/theme
3
3
  *
4
- * React 19 color scheme management: SSR-friendly `automatic` resolution, cross-tab sync, optimistic updates.
4
+ * React 19 appearance management, with vocabulary following Apple's Human Interface
5
+ * Guidelines: **appearance** is the user's preference (light / dark / automatic),
6
+ * **color scheme** is the resolved light-or-dark value actually applied. Client-only
7
+ * `localStorage` persistence, SSR-safe `automatic` resolution, cross-tab sync,
8
+ * optimistic updates.
5
9
  *
6
- * - **Root** (this module): `AppearanceProvider`, `useColorScheme`, `AppearanceScript`, `resolveColorScheme`, types, defaults.
7
- * - **`@codefast/theme/start`**: TanStack Start server functions + `persistColorSchemeCookie`.
8
- * - **`@codefast/theme/utils`**: `getSystemColorScheme`, `applyColorScheme`, `suppressTransitions`.
9
- * - **`@codefast/theme/core`**: `ColorSchemeContext` for rare custom wiring.
10
+ * - **Root** (this module): `AppearanceProvider`, `useAppearance`, `AppearanceScript`, `resolveColorScheme`, types, defaults.
11
+ * - **`@codefast/theme/color-scheme` / `@codefast/theme/dom`**: `getSystemColorScheme`, `applyColorScheme`, `suppressTransitions`.
12
+ * - **`@codefast/theme/appearance-context`**: `AppearanceContext` for rare custom wiring.
10
13
  */
11
14
 
12
15
  // Types & Schema
13
- export type { ResolvedColorScheme, ColorScheme, ColorSchemeContextType } from "#/types";
14
- export { colorSchemes, colorSchemeSchema } from "#/types";
16
+ export type { Appearance, AppearanceContextType, ColorScheme } from "#/appearance";
17
+ export { appearances, appearanceSchema } from "#/appearance";
15
18
 
16
19
  // Constants
17
- export { DEFAULT_RESOLVED_COLOR_SCHEME, DEFAULT_COLOR_SCHEME } from "#/constants";
20
+ export { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME } from "#/constants";
18
21
 
19
- // Core (Provider, Hook — use `@codefast/theme/core` for `ColorSchemeContext`)
20
- export { AppearanceProvider } from "#/core/provider";
21
- export type { AppearanceProviderProps } from "#/core/provider";
22
- export { useColorScheme } from "#/core/use-theme";
22
+ // Provider & Hook (use `@codefast/theme/appearance-context` for `AppearanceContext`)
23
+ export { AppearanceProvider } from "#/appearance-provider";
24
+ export type { AppearanceProviderProps } from "#/appearance-provider";
25
+ export { useAppearance } from "#/use-appearance";
23
26
 
24
27
  // Script (FOUC prevention)
25
- export { AppearanceScript } from "#/script/theme-script";
26
- export type { AppearanceScriptProps } from "#/script/theme-script";
28
+ export { AppearanceScript } from "#/appearance-script";
29
+ export type { AppearanceScriptProps } from "#/appearance-script";
27
30
 
28
- // Utilities: DOM + `getSystemColorScheme` live under `@codefast/theme/utils`
29
- export { resolveColorScheme } from "#/utils/system";
31
+ // Resolution: `getSystemColorScheme` lives under `@codefast/theme/color-scheme`
32
+ export { resolveColorScheme } from "#/color-scheme";
@@ -0,0 +1,46 @@
1
+ import { use } from "react";
2
+
3
+ import type { AppearanceContextType } from "#/appearance";
4
+ import { AppearanceContext } from "#/appearance-context";
5
+
6
+ /* -----------------------------------------------------------------------------
7
+ * Hook
8
+ * -------------------------------------------------------------------------- */
9
+
10
+ /**
11
+ * Hook to access appearance context.
12
+ *
13
+ * Uses React 19's `use()` API for context consumption, enabling:
14
+ * - Conditional context reading
15
+ * - Better Suspense boundary integration
16
+ *
17
+ * @returns Appearance context with `appearance`, `colorScheme`, `setAppearance`, and `isPending`
18
+ * @throws Error if called outside of AppearanceProvider
19
+ *
20
+ * @example
21
+ * ```tsx
22
+ * function AppearanceToggle() {
23
+ * const { appearance, setAppearance, isPending } = useAppearance();
24
+ *
25
+ * return (
26
+ * <button
27
+ * onClick={() => setAppearance(appearance === 'dark' ? 'light' : 'dark')}
28
+ * disabled={isPending}
29
+ * >
30
+ * {appearance}
31
+ * </button>
32
+ * );
33
+ * }
34
+ * ```
35
+ *
36
+ * @since 0.5.0-canary.2
37
+ */
38
+ export function useAppearance(): AppearanceContextType {
39
+ const value = use(AppearanceContext);
40
+
41
+ if (!value) {
42
+ throw new Error("useAppearance must be used within an AppearanceProvider");
43
+ }
44
+
45
+ return value;
46
+ }
@@ -1,88 +0,0 @@
1
- import { ColorScheme, ResolvedColorScheme } from "../../types.mjs";
2
-
3
- //#region src/adapters/tanstack-start/server.d.ts
4
- /**
5
- * Data shape returned from {@link getRootColorSchemeServerFn} for the root route loader.
6
- *
7
- * @since 0.3.16-canary.0
8
- */
9
- type RootColorSchemeLoaderData = {
10
- /**
11
- * Resolved `light` or `dark` from the incoming request when detectable
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}.
15
- */
16
- readonly ssrColorScheme: ResolvedColorScheme;
17
- /**
18
- * User preference from the httpOnly cookie: `light`, `dark`, or `automatic`.
19
- */
20
- readonly colorScheme: ColorScheme;
21
- };
22
- /**
23
- * Everything needed for the root shell in **one** server call (fewer loader awaits).
24
- *
25
- * In your shell: `resolveColorScheme(colorScheme, ssrColorScheme)` on `<html>`, plus `AppearanceScript` and `AppearanceProvider`.
26
- *
27
- * @since 0.3.16-canary.0
28
- */
29
- declare const getRootColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, RootColorSchemeLoaderData>;
30
- /**
31
- * Read the user's color scheme preference from cookies.
32
- *
33
- * Validates the cookie value using Zod schema for type safety.
34
- * Returns {@link DEFAULT_COLOR_SCHEME} if cookie is missing or invalid.
35
- *
36
- * @returns User's stored color scheme preference or default
37
- *
38
- * @example
39
- * ```tsx
40
- * const colorScheme = await getColorSchemeServerFn();
41
- * ```
42
- *
43
- * @since 0.3.16-canary.0
44
- */
45
- declare const getColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, "light" | "dark" | "automatic">;
46
- /**
47
- * Resolved OS color scheme for SSR / hydration, from Client Hints when the browser sends them.
48
- *
49
- * Mirrors client `matchMedia("(prefers-color-scheme: dark)")` when hints are present.
50
- * Prefer {@link getRootColorSchemeServerFn} for root loaders.
51
- *
52
- * Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
53
- *
54
- * @since 0.3.16-canary.0
55
- */
56
- declare const getSsrColorSchemeServerFn: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, ResolvedColorScheme>;
57
- /**
58
- * Persist color scheme preference to an HTTP-only cookie.
59
- *
60
- * **Security:**
61
- * - `httpOnly: true` - Cookie cannot be accessed from JavaScript (XSS protection)
62
- * - `secure: true` in production - Cookie only sent over HTTPS
63
- * - `sameSite: 'lax'` - Prevents CSRF while allowing navigation
64
- *
65
- * **Cookie Settings:**
66
- * - `maxAge: 1 year` - Preference persists across sessions
67
- * - `path: '/'` - Available to all routes
68
- *
69
- * @param data - Color scheme to persist ('light', 'dark', or 'automatic')
70
- *
71
- * @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
72
- *
73
- * @since 0.3.16-canary.0
74
- */
75
- declare const setColorSchemeServerFn: import("@tanstack/react-start").RequiredFetcher<undefined, import("zod").ZodEnum<{
76
- light: "light";
77
- dark: "dark";
78
- automatic: "automatic";
79
- }>, void>;
80
- /**
81
- * Default {@link AppearanceProvider} `persistColorScheme` for the Start adapter: writes the httpOnly
82
- * color scheme cookie via {@link setColorSchemeServerFn}.
83
- *
84
- * @since 0.3.16-canary.0
85
- */
86
- declare function persistColorSchemeCookie(value: ColorScheme): Promise<void>;
87
- //#endregion
88
- export { RootColorSchemeLoaderData, getColorSchemeServerFn, getRootColorSchemeServerFn, getSsrColorSchemeServerFn, persistColorSchemeCookie, setColorSchemeServerFn };
@@ -1,93 +0,0 @@
1
- import { DEFAULT_COLOR_SCHEME, DEFAULT_RESOLVED_COLOR_SCHEME, STORAGE_KEY } from "../../constants.mjs";
2
- import { colorSchemeSchema } from "../../types.mjs";
3
- import { createServerFn } from "@tanstack/react-start";
4
- import { getCookie, getRequestHeader, setCookie } from "@tanstack/react-start/server";
5
- //#region src/adapters/tanstack-start/server.ts
6
- function readColorSchemeFromCookie() {
7
- const cookieValue = getCookie(STORAGE_KEY);
8
- const validationResult = colorSchemeSchema.safeParse(cookieValue);
9
- if (validationResult.success) return validationResult.data;
10
- return DEFAULT_COLOR_SCHEME;
11
- }
12
- function readSsrColorSchemeFromHeaders() {
13
- const hint = getRequestHeader("Sec-CH-Prefers-Color-Scheme") ?? getRequestHeader("Prefers-Color-Scheme");
14
- if (hint === "dark") return "dark";
15
- if (hint === "light") return "light";
16
- return DEFAULT_RESOLVED_COLOR_SCHEME;
17
- }
18
- /**
19
- * Everything needed for the root shell in **one** server call (fewer loader awaits).
20
- *
21
- * In your shell: `resolveColorScheme(colorScheme, ssrColorScheme)` on `<html>`, plus `AppearanceScript` and `AppearanceProvider`.
22
- *
23
- * @since 0.3.16-canary.0
24
- */
25
- const getRootColorSchemeServerFn = createServerFn().handler(() => ({
26
- colorScheme: readColorSchemeFromCookie(),
27
- ssrColorScheme: readSsrColorSchemeFromHeaders()
28
- }));
29
- /**
30
- * Read the user's color scheme preference from cookies.
31
- *
32
- * Validates the cookie value using Zod schema for type safety.
33
- * Returns {@link DEFAULT_COLOR_SCHEME} if cookie is missing or invalid.
34
- *
35
- * @returns User's stored color scheme preference or default
36
- *
37
- * @example
38
- * ```tsx
39
- * const colorScheme = await getColorSchemeServerFn();
40
- * ```
41
- *
42
- * @since 0.3.16-canary.0
43
- */
44
- const getColorSchemeServerFn = createServerFn().handler(() => readColorSchemeFromCookie());
45
- /**
46
- * Resolved OS color scheme for SSR / hydration, from Client Hints when the browser sends them.
47
- *
48
- * Mirrors client `matchMedia("(prefers-color-scheme: dark)")` when hints are present.
49
- * Prefer {@link getRootColorSchemeServerFn} for root loaders.
50
- *
51
- * Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
52
- *
53
- * @since 0.3.16-canary.0
54
- */
55
- const getSsrColorSchemeServerFn = createServerFn().handler(() => readSsrColorSchemeFromHeaders());
56
- /**
57
- * Persist color scheme preference to an HTTP-only cookie.
58
- *
59
- * **Security:**
60
- * - `httpOnly: true` - Cookie cannot be accessed from JavaScript (XSS protection)
61
- * - `secure: true` in production - Cookie only sent over HTTPS
62
- * - `sameSite: 'lax'` - Prevents CSRF while allowing navigation
63
- *
64
- * **Cookie Settings:**
65
- * - `maxAge: 1 year` - Preference persists across sessions
66
- * - `path: '/'` - Available to all routes
67
- *
68
- * @param data - Color scheme to persist ('light', 'dark', or 'automatic')
69
- *
70
- * @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
71
- *
72
- * @since 0.3.16-canary.0
73
- */
74
- const setColorSchemeServerFn = createServerFn({ method: "POST" }).validator(colorSchemeSchema).handler(({ data }) => {
75
- setCookie(STORAGE_KEY, data, {
76
- httpOnly: true,
77
- maxAge: 3600 * 24 * 365,
78
- path: "/",
79
- sameSite: "lax",
80
- secure: process.env.NODE_ENV === "production"
81
- });
82
- });
83
- /**
84
- * Default {@link AppearanceProvider} `persistColorScheme` for the Start adapter: writes the httpOnly
85
- * color scheme cookie via {@link setColorSchemeServerFn}.
86
- *
87
- * @since 0.3.16-canary.0
88
- */
89
- async function persistColorSchemeCookie(value) {
90
- await setColorSchemeServerFn({ data: value });
91
- }
92
- //#endregion
93
- export { getColorSchemeServerFn, getRootColorSchemeServerFn, getSsrColorSchemeServerFn, persistColorSchemeCookie, setColorSchemeServerFn };
@@ -1,12 +0,0 @@
1
- import { Plugin } from "vite";
2
-
3
- //#region src/adapters/tanstack-start/vite.d.ts
4
- /**
5
- * Create the Vite plugin that lets a TanStack Start app consume `@codefast/theme`'s server
6
- * functions from npm without manual `ssr.noExternal` / `optimizeDeps.exclude` configuration.
7
- *
8
- * @since 0.5.0-canary.0
9
- */
10
- declare function codefastTheme(): Plugin;
11
- //#endregion
12
- export { codefastTheme };
@@ -1,21 +0,0 @@
1
- //#region src/adapters/tanstack-start/vite.ts
2
- const PACKAGE_NAME = "@codefast/theme";
3
- /**
4
- * Create the Vite plugin that lets a TanStack Start app consume `@codefast/theme`'s server
5
- * functions from npm without manual `ssr.noExternal` / `optimizeDeps.exclude` configuration.
6
- *
7
- * @since 0.5.0-canary.0
8
- */
9
- function codefastTheme() {
10
- return {
11
- name: "codefast:theme",
12
- config() {
13
- return {
14
- ssr: { noExternal: [PACKAGE_NAME] },
15
- optimizeDeps: { exclude: [PACKAGE_NAME] }
16
- };
17
- }
18
- };
19
- }
20
- //#endregion
21
- export { codefastTheme };
@@ -1,18 +0,0 @@
1
- import { ColorSchemeContextType } from "../types.mjs";
2
-
3
- //#region src/core/context.d.ts
4
- type ColorSchemeContextValue = null | ColorSchemeContextType;
5
- /**
6
- * React context for color scheme state management.
7
- *
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.
10
- *
11
- * @see {@link AppearanceProvider} - Provider component
12
- * @see {@link useColorScheme} - Consumer hook
13
- *
14
- * @since 0.3.16-canary.0
15
- */
16
- declare const ColorSchemeContext: import("react").Context<ColorSchemeContextValue>;
17
- //#endregion
18
- export { ColorSchemeContext };
@@ -1,16 +0,0 @@
1
- import { createContext } from "react";
2
- //#region src/core/context.tsx
3
- /**
4
- * React context for color scheme state management.
5
- *
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
- *
9
- * @see {@link AppearanceProvider} - Provider component
10
- * @see {@link useColorScheme} - Consumer hook
11
- *
12
- * @since 0.3.16-canary.0
13
- */
14
- const ColorSchemeContext = createContext(null);
15
- //#endregion
16
- export { ColorSchemeContext };
@@ -1,118 +0,0 @@
1
- import { ColorScheme, ResolvedColorScheme } from "../types.mjs";
2
- import { JSX, ReactNode } from "react";
3
-
4
- //#region src/core/provider.d.ts
5
- /**
6
- * @since 0.3.16-canary.3
7
- */
8
- type AppearanceProviderProps = {
9
- readonly children: ReactNode;
10
- /**
11
- * When true, temporarily suppresses CSS transitions during color scheme changes.
12
- * Prevents jarring color animations when switching appearances.
13
- * Default: false
14
- */
15
- readonly disableTransition?: boolean;
16
- /**
17
- * CSP nonce for inline styles when `disableTransition` is enabled.
18
- */
19
- readonly nonce?: string;
20
- /**
21
- * Async function to persist color scheme changes to server/storage.
22
- *
23
- * For TanStack Start: use `persistColorSchemeCookie` from `@codefast/theme/start`
24
- * For Next.js: implement a server action
25
- */
26
- readonly persistColorScheme?: (value: ColorScheme) => Promise<void>;
27
- /**
28
- * Callback invoked when `persistColorScheme` rejects.
29
- */
30
- readonly onPersistError?: (error: unknown, attemptedColorScheme: ColorScheme) => void;
31
- /**
32
- * Initial color scheme preference from the server (cookie, loader, etc.).
33
- *
34
- * After mount, `AppearanceProvider` re-syncs whenever this prop changes — for example, when
35
- * the router re-runs the root loader after navigation. The server value is authoritative:
36
- * a new prop value will override any local optimistic state.
37
- */
38
- readonly colorScheme: ColorScheme;
39
- /**
40
- * OS light/dark guess from the SSR request (e.g. `Sec-CH-Prefers-Color-Scheme`).
41
- *
42
- * When the stored preference is `automatic`, {@link useSyncExternalStore} uses this for
43
- * `getServerSnapshot` so the first client snapshot matches `matchMedia` and avoids a
44
- * dark → light flip after hydration.
45
- */
46
- readonly ssrColorScheme?: ResolvedColorScheme;
47
- /**
48
- * After mount, re-read the canonical color scheme from the server (e.g. httpOnly cookie).
49
- *
50
- * Fixes **stale HTML / disk cache** on "Duplicate tab" or back-forward cache where the
51
- * document was saved with an old `AppearanceScript` / loader value while the cookie was already updated
52
- * in another tab. Use a stable reference (e.g. `getColorSchemeServerFn` from `@codefast/theme/start`).
53
- */
54
- readonly syncFromServer?: () => Promise<ColorScheme>;
55
- /**
56
- * Persist + restore the preference in `localStorage` under this key — the client-only path
57
- * (no server framework, no cookie, no loader).
58
- *
59
- * When set, the provider reads the stored value in its initial client render (so the first paint
60
- * already matches the preference — no flash, no post-mount settle), auto-persists changes to
61
- * `localStorage` (unless {@link persistColorScheme} is also given, which then wins), and syncs across
62
- * tabs via the `storage` event. Pair with `<AppearanceScript storageKey={…} />` using the **same key**.
63
- *
64
- * @remarks SSR has no `localStorage`, so the server renders the {@link AppearanceProviderProps.colorScheme}
65
- * prop. For a returning visitor whose stored preference differs, components that render
66
- * preference-dependent markup hydrate-reconcile once; gate them behind a mounted flag to avoid that.
67
- */
68
- readonly storageKey?: string;
69
- };
70
- /**
71
- * Provider component for color scheme state management.
72
- *
73
- * **React 19 Features Used:**
74
- * - `useOptimistic` - Immediate UI feedback while persisting color scheme
75
- * - `useSyncExternalStore` - SSR-safe subscription to OS color scheme preference
76
- * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
77
- *
78
- * @param props - Component props
79
- * @param props.children - React tree to provide context for
80
- * @param props.colorScheme - Initial preference from the server (cookie, loader, etc.)
81
- * @param props.ssrColorScheme - Best-effort `light` or `dark` from the SSR request
82
- * (e.g. `Sec-CH-Prefers-Color-Scheme`). When preference is `automatic`, this value is used as
83
- * `useSyncExternalStore`'s server snapshot so the first client snapshot matches `matchMedia`
84
- * and avoids a post-hydration flip. Omit if unavailable; falls back to {@link DEFAULT_RESOLVED_COLOR_SCHEME}.
85
- * @param props.syncFromServer - Optional one-shot RPC after mount to align with the cookie when SSR/HTML was stale.
86
- * @param props.storageKey - Optional localStorage key for the client-only path: restore in the initial render, auto-persist, cross-tab sync.
87
- * @param props.persistColorScheme - Optional async handler to persist preference (cookie, server action, …)
88
- * @param props.onPersistError - Optional callback for persistence failures
89
- * @param props.disableTransition - Temporarily suppress CSS transitions on color scheme change
90
- * @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransition` is set
91
- * @returns Provider element wrapping `children`
92
- *
93
- * @example
94
- * ```tsx
95
- * // In your root layout
96
- * <AppearanceProvider
97
- * colorScheme={colorScheme}
98
- * persistColorScheme={(value) => setColorSchemeServerFn({ data: value })}
99
- * >
100
- * {children}
101
- * </AppearanceProvider>
102
- * ```
103
- *
104
- * @since 0.3.16-canary.0
105
- */
106
- declare function AppearanceProvider({
107
- children,
108
- disableTransition,
109
- nonce,
110
- onPersistError,
111
- persistColorScheme,
112
- ssrColorScheme,
113
- storageKey,
114
- syncFromServer,
115
- colorScheme: initialColorScheme
116
- }: AppearanceProviderProps): JSX.Element;
117
- //#endregion
118
- export { AppearanceProvider, AppearanceProviderProps };