@codefast/theme 0.3.16-canary.0 → 0.3.16-canary.1

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,7 @@
1
1
  # @codefast/theme
2
2
 
3
+ ## 0.3.16-canary.1
4
+
3
5
  ## 0.3.16-canary.0
4
6
 
5
7
  ## 0.3.15
@@ -17,7 +17,7 @@ function readSsrSystemThemeFromHeaders() {
17
17
  }
18
18
  /**
19
19
  * Everything needed for the root shell in **one** server call (fewer loader awaits).
20
- *
20
+ *
21
21
  * In your shell: `resolveTheme(theme, ssrSystemTheme)` on `<html>`, plus `ThemeScript` and `ThemeProvider`.
22
22
  *
23
23
  * @since 0.3.16-canary.0
@@ -28,12 +28,12 @@ const getRootThemeServerFn = createServerFn().handler(() => ({
28
28
  }));
29
29
  /**
30
30
  * Read the user's theme preference from cookies.
31
- *
31
+ *
32
32
  * Validates the cookie value using Zod schema for type safety.
33
33
  * Returns {@link DEFAULT_THEME} if cookie is missing or invalid.
34
- *
34
+ *
35
35
  * @returns User's stored theme preference or default
36
- *
36
+ *
37
37
  * @example
38
38
  * ```tsx
39
39
  * const theme = await getThemeServerFn();
@@ -44,10 +44,10 @@ const getRootThemeServerFn = createServerFn().handler(() => ({
44
44
  const getThemeServerFn = createServerFn().handler(() => readThemeFromCookie());
45
45
  /**
46
46
  * Resolved OS theme 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
49
  * Prefer {@link getRootThemeServerFn} 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
@@ -55,18 +55,18 @@ const getThemeServerFn = createServerFn().handler(() => readThemeFromCookie());
55
55
  const getSsrSystemThemeServerFn = createServerFn().handler(() => readSsrSystemThemeFromHeaders());
56
56
  /**
57
57
  * Persist theme preference to an HTTP-only cookie.
58
- *
58
+ *
59
59
  * **Security:**
60
60
  * - `httpOnly: true` - Cookie cannot be accessed from JavaScript (XSS protection)
61
61
  * - `secure: true` in production - Cookie only sent over HTTPS
62
62
  * - `sameSite: 'lax'` - Prevents CSRF while allowing navigation
63
- *
63
+ *
64
64
  * **Cookie Settings:**
65
65
  * - `maxAge: 1 year` - Preference persists across sessions
66
66
  * - `path: '/'` - Available to all routes
67
- *
67
+ *
68
68
  * @param data - Theme to persist ('light', 'dark', or 'system')
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
@@ -1,7 +1,7 @@
1
1
  //#region src/constants.ts
2
2
  /**
3
3
  * Default theme when no user preference exists.
4
- *
4
+ *
5
5
  * Set to 'system' to respect OS preference by default.
6
6
  *
7
7
  * @since 0.3.16-canary.0
@@ -9,7 +9,7 @@
9
9
  const DEFAULT_THEME = "system";
10
10
  /**
11
11
  * Fallback theme 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
@@ -17,7 +17,7 @@ const DEFAULT_THEME = "system";
17
17
  const DEFAULT_RESOLVED_THEME = "dark";
18
18
  /**
19
19
  * Cookie name for the httpOnly theme 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
@@ -32,7 +32,7 @@ const THEME_STORAGE_KEY = "ui-theme";
32
32
  const MEDIA = "(prefers-color-scheme: dark)";
33
33
  /**
34
34
  * BroadcastChannel name for cross-tab theme synchronization.
35
- *
35
+ *
36
36
  * Enables instant theme updates across all open browser tabs.
37
37
  * @internal
38
38
  *
@@ -2,10 +2,10 @@ import { createContext } from "react";
2
2
  //#region src/core/context.tsx
3
3
  /**
4
4
  * React context for theme state management.
5
- *
5
+ *
6
6
  * Provides access to current theme, resolved theme, setter function, and pending state.
7
7
  * Use {@link useTheme} hook instead of consuming this context directly.
8
- *
8
+ *
9
9
  * @see {@link ThemeProvider} - Provider component
10
10
  * @see {@link useTheme} - Consumer hook
11
11
  *
@@ -26,12 +26,12 @@ function getSystemThemeSnapshot() {
26
26
  }
27
27
  /**
28
28
  * Provider component for theme state management.
29
- *
29
+ *
30
30
  * **React 19 Features Used:**
31
31
  * - `useOptimistic` - Immediate UI feedback while persisting theme
32
32
  * - `useSyncExternalStore` - SSR-safe subscription to OS theme preference
33
33
  * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
34
- *
34
+ *
35
35
  * @param props - Component props
36
36
  * @param props.children - React tree to provide context for
37
37
  * @param props.theme - Initial preference from the server (cookie, loader, etc.)
@@ -44,7 +44,7 @@ function getSystemThemeSnapshot() {
44
44
  * @param props.disableTransitionOnChange - Temporarily disable CSS transitions on theme change
45
45
  * @param props.nonce - CSP nonce for inline transition-blocking styles when `disableTransitionOnChange` is set
46
46
  * @returns Provider element wrapping `children`
47
- *
47
+ *
48
48
  * @example
49
49
  * ```tsx
50
50
  * // In your root layout
@@ -3,19 +3,19 @@ import { use } from "react";
3
3
  //#region src/core/use-theme.ts
4
4
  /**
5
5
  * Hook to access theme context.
6
- *
6
+ *
7
7
  * Uses React 19's `use()` API for context consumption, enabling:
8
8
  * - Conditional context reading
9
9
  * - Better Suspense boundary integration
10
- *
10
+ *
11
11
  * @returns Theme context with `theme`, `resolvedTheme`, `setTheme`, and `isPending`
12
12
  * @throws Error if called outside of ThemeProvider
13
- *
13
+ *
14
14
  * @example
15
15
  * ```tsx
16
16
  * function ThemeToggle() {
17
17
  * const { theme, setTheme, isPending } = useTheme();
18
- *
18
+ *
19
19
  * return (
20
20
  * <button
21
21
  * onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
@@ -2,19 +2,19 @@ import { jsx } from "react/jsx-runtime";
2
2
  //#region src/script/theme-script.tsx
3
3
  /**
4
4
  * Inline script that prevents Flash of Unstyled Content (FOUC).
5
- *
5
+ *
6
6
  * **Why this is needed:**
7
7
  * React hydration occurs after the browser has already painted the page.
8
8
  * Without this script, users would briefly see the wrong theme before
9
9
  * React takes over and applies the correct one.
10
- *
10
+ *
11
11
  * **How it works:**
12
12
  * This script runs synchronously in the `<head>` before first paint:
13
13
  * 1. Resolves 'system' to 'light' or 'dark' using `matchMedia()`
14
14
  * 2. Removes prior `light` / `dark` / `system` classes on `<html>` (SSR may
15
15
  * have applied the wrong resolved class for `system`, e.g. default `dark`)
16
16
  * 3. Adds the resolved theme class and sets `color-scheme` for native controls
17
- *
17
+ *
18
18
  * @example
19
19
  * ```tsx
20
20
  * // In __root.tsx (TanStack Start)
package/dist/types.mjs CHANGED
@@ -2,7 +2,7 @@ import { z } from "zod";
2
2
  //#region src/types.ts
3
3
  /**
4
4
  * Zod schema for theme validation.
5
- *
5
+ *
6
6
  * Acts as the single source of truth for all theme-related types.
7
7
  * Valid values: 'light', 'dark', 'system'.
8
8
  *
@@ -15,7 +15,7 @@ const themeSchema = z.enum([
15
15
  ]);
16
16
  /**
17
17
  * Array of all available theme options: `['light', 'dark', 'system']`.
18
- *
18
+ *
19
19
  * Useful for rendering theme selectors in UI components.
20
20
  *
21
21
  * @since 0.3.16-canary.0
@@ -1,11 +1,11 @@
1
1
  //#region src/utils/dom.ts
2
2
  /**
3
3
  * Apply theme to the DOM by updating `<html>` element.
4
- *
4
+ *
5
5
  * Updates both:
6
6
  * - CSS class (for Tailwind's `dark:` variants)
7
7
  * - `color-scheme` style (for native form controls and scrollbars)
8
- *
8
+ *
9
9
  * @param resolved - The resolved theme to apply ('light' or 'dark')
10
10
  *
11
11
  * @since 0.3.16-canary.0
@@ -18,13 +18,13 @@ function applyTheme(resolved) {
18
18
  }
19
19
  /**
20
20
  * Temporarily disable all CSS transitions during theme changes.
21
- *
21
+ *
22
22
  * Prevents jarring color animations when switching between light/dark themes.
23
23
  * Respects user's `prefers-reduced-motion` preference (does nothing if enabled).
24
- *
24
+ *
25
25
  * @param nonce - Optional CSP nonce for the injected style element
26
26
  * @returns Cleanup function to re-enable transitions. Call after theme is applied.
27
- *
27
+ *
28
28
  * @example
29
29
  * ```tsx
30
30
  * const enableTransitions = disableAnimation();
@@ -2,10 +2,10 @@ import { DEFAULT_RESOLVED_THEME } from "../constants.mjs";
2
2
  //#region src/utils/system.ts
3
3
  /**
4
4
  * Detect the user's OS theme preference.
5
- *
5
+ *
6
6
  * Uses `matchMedia()` to query the `prefers-color-scheme` media feature.
7
7
  * Returns {@link DEFAULT_RESOLVED_THEME} during SSR since `window` is unavailable.
8
- *
8
+ *
9
9
  * @returns 'light' or 'dark' based on OS preference
10
10
  *
11
11
  * @since 0.3.16-canary.0
@@ -16,12 +16,12 @@ function getSystemTheme() {
16
16
  }
17
17
  /**
18
18
  * Resolve theme preference to actual light/dark value.
19
- *
19
+ *
20
20
  * - 'light' → 'light'
21
21
  * - 'dark' → 'dark'
22
22
  * - 'system' → on the client, result of {@link getSystemTheme}; on the server,
23
23
  * `ssrSystemTheme` when provided, otherwise {@link DEFAULT_RESOLVED_THEME}
24
- *
24
+ *
25
25
  * @param theme - User's theme preference (`light`, `dark`, or `system`)
26
26
  * @param ssrSystemTheme - When `theme` is `system` and this runs during SSR (no `window`),
27
27
  * uses this as the resolved appearance—typically from Client Hints
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codefast/theme",
3
- "version": "0.3.16-canary.0",
3
+ "version": "0.3.16-canary.1",
4
4
  "description": "Theme management with React 19 features - optimistic updates, cross-tab sync, and SSR support",
5
5
  "keywords": [
6
6
  "dark-mode",
@@ -103,22 +103,23 @@
103
103
  "zod": "^4.4.3"
104
104
  },
105
105
  "devDependencies": {
106
- "@tanstack/react-start": "^1.167.62",
106
+ "@tanstack/react-start": "^1.167.65",
107
107
  "@testing-library/dom": "^10.4.1",
108
108
  "@testing-library/jest-dom": "^6.9.1",
109
109
  "@testing-library/react": "^16.3.2",
110
110
  "@testing-library/user-event": "^14.6.1",
111
- "@types/node": "^25.6.0",
112
- "@typescript/native-preview": "7.0.0-dev.20260504.1",
111
+ "@types/node": "^25.6.2",
112
+ "@typescript/native-preview": "7.0.0-dev.20260509.2",
113
113
  "@vitejs/plugin-react": "^6.0.1",
114
114
  "@vitest/coverage-v8": "^4.1.5",
115
115
  "jsdom": "^29.1.1",
116
+ "tsdown": "^0.22.0",
116
117
  "typescript": "^6.0.3",
117
118
  "vitest": "^4.1.5",
118
- "@codefast/typescript-config": "0.3.16-canary.0"
119
+ "@codefast/typescript-config": "0.3.16-canary.1"
119
120
  },
120
121
  "peerDependencies": {
121
- "@tanstack/react-start": "^1.0",
122
+ "@tanstack/react-start": "^1.167.65",
122
123
  "@types/react": "^19.0",
123
124
  "@types/react-dom": "^19.0",
124
125
  "react": "^19.0",
@@ -135,6 +136,9 @@
135
136
  "optional": true
136
137
  }
137
138
  },
139
+ "engines": {
140
+ "node": ">=22.0.0"
141
+ },
138
142
  "scripts": {
139
143
  "build": "tsdown",
140
144
  "check-types": "tsgo --noEmit",
@@ -142,6 +146,10 @@
142
146
  "dev": "tsdown --watch",
143
147
  "test": "vitest run",
144
148
  "test:coverage": "vitest run --coverage",
149
+ "test:e2e": "vitest run tests/e2e",
150
+ "test:integration": "vitest run tests/integration",
151
+ "test:type": "vitest run tests/types",
152
+ "test:unit": "vitest run tests/unit",
145
153
  "test:watch": "vitest"
146
154
  }
147
155
  }