@codefast/theme 0.3.13 → 0.3.14-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,17 @@
1
1
  # @codefast/theme
2
2
 
3
+ ## 0.3.14-canary.1
4
+
5
+ ## 0.3.14-canary.0
6
+
7
+ ### Patch Changes
8
+
9
+ - [`b728f3e`](https://github.com/codefastlabs/codefast/commit/b728f3e74c94ce448b48b2cfd3e7a119b9649cb1) Thanks [@thevuong](https://github.com/thevuong)! - docs(theme): update README.md for clarity and structure
10
+
11
+ - [`b44597c`](https://github.com/codefastlabs/codefast/commit/b44597c9ec3a121a707aa269d7f68550ae1da72a) Thanks [@thevuong](https://github.com/thevuong)! - docs: enhance type annotations and comments for clarity across multiple files
12
+
13
+ - [`8109f4e`](https://github.com/codefastlabs/codefast/commit/8109f4e1f8186b91c296d25d640594b43493cdef) Thanks [@thevuong](https://github.com/thevuong)! - docs: update README.md files across packages for consistency and clarity
14
+
3
15
  ## 0.3.13
4
16
 
5
17
  ### Patch Changes
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @codefast/theme
2
2
 
3
- Theme management for React 19 applications with optimistic updates, cross-tab synchronization, and SSR support.
3
+ Theme management for React 19 — SSR-safe `system` resolution, optimistic updates, cross-tab sync, and a drop-in TanStack Start adapter.
4
4
 
5
5
  [![CI](https://github.com/codefastlabs/codefast/actions/workflows/release.yml/badge.svg)](https://github.com/codefastlabs/codefast/actions/workflows/release.yml)
6
6
  [![npm version](https://img.shields.io/npm/v/@codefast/theme.svg)](https://www.npmjs.com/package/@codefast/theme)
@@ -8,80 +8,75 @@ Theme management for React 19 applications with optimistic updates, cross-tab sy
8
8
  [![bundle size](https://img.shields.io/bundlephobia/minzip/@codefast/theme)](https://bundlephobia.com/package/@codefast/theme)
9
9
  [![license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
10
 
11
+ ---
12
+
11
13
  ## Table of Contents
12
14
 
13
- - [Overview](#overview)
15
+ - [Why @codefast/theme](#why-codefasttheme)
16
+ - [Requirements](#requirements)
14
17
  - [Installation](#installation)
15
18
  - [Quick Start](#quick-start)
16
- - [Usage](#usage)
19
+ - [Recipes](#recipes)
17
20
  - [TanStack Start](#tanstack-start)
18
- - [Generic React (Client-Side)](#generic-react-client-side)
19
- - [Theme Toggle Component](#theme-toggle-component)
20
- - [SSR and FOUC Prevention](#ssr-and-fouc-prevention)
21
+ - [Client-only React (localStorage)](#client-only-react-localstorage)
22
+ - [Theme toggle](#theme-toggle)
23
+ - [SSR and FOUC prevention](#ssr-and-fouc-prevention)
21
24
  - [API Reference](#api-reference)
22
- - [ThemeProvider](#themeprovider)
23
- - [useTheme](#usetheme)
24
- - [ThemeScript](#themescript)
25
- - [resolveTheme](#resolvetheme)
26
- - [themes](#themes)
25
+ - [`<ThemeProvider>`](#themeprovider)
26
+ - [`useTheme()`](#usetheme)
27
+ - [`<ThemeScript>`](#themescript)
28
+ - [`resolveTheme()`](#resolvetheme)
29
+ - [`getSystemTheme()` / `applyTheme()` / `disableAnimation()`](#getsystemtheme--applytheme--disableanimation)
30
+ - [`themes`, `themeSchema`, and defaults](#themes-themeschema-and-defaults)
31
+ - [TanStack Start adapter (`@codefast/theme/start`)](#tanstack-start-adapter-codefastthemestart)
32
+ - [Package exports](#package-exports)
27
33
  - [Contributing](#contributing)
28
34
  - [License](#license)
29
35
  - [Changelog](#changelog)
30
36
 
31
- ## Overview
37
+ ---
32
38
 
33
- `@codefast/theme` provides a complete theme management solution built specifically for React 19. It leverages modern React APIs for the best possible user experience.
39
+ ## Why @codefast/theme
34
40
 
35
- **Key features:**
41
+ `@codefast/theme` is a focused theme-state primitive built around the React 19 concurrent APIs. Drop it at the root of your app, persist the user's preference however you want, and let the hook and inline script keep the DOM in sync.
36
42
 
37
- - **React 19 Optimized** -- Uses `useOptimistic`, `useSyncExternalStore`, and `useEffectEvent` for seamless transitions.
38
- - **System Theme Detection** -- Automatically detects and follows the operating system preference.
39
- - **Cross-tab Sync** -- Theme changes propagate instantly across all open browser tabs.
40
- - **Optimistic Updates** -- Immediate UI feedback during asynchronous theme persistence.
41
- - **SSR Ready** -- Inline script prevents flash of unstyled content (FOUC) on server-rendered pages.
42
- - **TanStack Start** -- `@codefast/theme/start` bundles cookie persistence and loader helpers.
43
+ - **React 19 first.** Uses `useOptimistic`, `useSyncExternalStore`, and `useEffectEvent` to keep theme changes immediate, hydration-safe, and free of needless re-renders.
44
+ - **SSR-friendly.** A tiny inline `<ThemeScript>` runs before first paint so `system` never flashes the wrong appearance. Works with Client Hints (`Sec-CH-Prefers-Color-Scheme`) when you have them.
45
+ - **Cross-tab sync.** Theme changes propagate between tabs over `BroadcastChannel`.
46
+ - **Optimistic setters.** `setTheme(value)` updates the UI immediately and reverts automatically if persistence fails.
47
+ - **TanStack Start adapter.** `@codefast/theme/start` ships cookie-based persistence plus loader/server helpers. Everything else stays vanilla.
48
+ - **Tree-shakeable.** Side-effect-free ESM with granular subpaths; bring in only the pieces you use.
43
49
 
44
- ## Public entry points
50
+ ---
45
51
 
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 |
52
+ ## Requirements
55
53
 
56
- ## Installation
54
+ - React `^19` (and `react-dom`)
55
+ - TypeScript `>= 5.9` (recommended; the published types target ES2022)
56
+ - TanStack Start `^1` — only if you use `@codefast/theme/start`
57
57
 
58
- ```bash
59
- pnpm add @codefast/theme
60
- ```
58
+ All peers except `react` / `react-dom` are optional.
59
+
60
+ ---
61
61
 
62
- Or using npm:
62
+ ## Installation
63
63
 
64
64
  ```bash
65
+ pnpm add @codefast/theme
66
+ # or
65
67
  npm install @codefast/theme
68
+ # or
69
+ yarn add @codefast/theme
66
70
  ```
67
71
 
68
- **Peer dependencies:**
72
+ Peer dependencies:
69
73
 
70
74
  ```bash
71
75
  pnpm add react react-dom
76
+ pnpm add @tanstack/react-start # only if using @codefast/theme/start
72
77
  ```
73
78
 
74
- **Optional peer dependencies (for TanStack Start):**
75
-
76
- ```bash
77
- pnpm add @tanstack/react-start
78
- ```
79
-
80
- **Requirements:**
81
-
82
- - Node.js >= 24.0.0 (LTS)
83
- - React >= 19.0.0
84
- - TypeScript >= 5.9.2 (recommended)
79
+ ---
85
80
 
86
81
  ## Quick Start
87
82
 
@@ -107,19 +102,23 @@ function Page() {
107
102
  }
108
103
  ```
109
104
 
110
- ## Usage
105
+ `theme` accepts `"light"`, `"dark"`, or `"system"`. `resolvedTheme` from `useTheme()` always narrows to `"light" | "dark"`.
106
+
107
+ ---
108
+
109
+ ## Recipes
111
110
 
112
111
  ### TanStack Start
113
112
 
114
- Server persistence and loader data live in `@codefast/theme/start`. Your shell keeps full control of `<html>` / `<head>` / `<body>`.
113
+ Server-side persistence lives in `@codefast/theme/start`. The shell keeps full control over `<html>` / `<head>` / `<body>` — the adapter only provides the loader data and cookie helpers.
115
114
 
116
115
  ```tsx
117
- // routes/__root.tsx (pattern; adjust to your router setup)
116
+ // routes/__root.tsx (adjust to your router setup)
118
117
  import { HeadContent, Scripts, createRootRouteWithContext } from "@tanstack/react-router";
119
118
  import { getRootThemeServerFn, getThemeServerFn, persistThemeCookie } from "@codefast/theme/start";
120
119
  import { ThemeProvider, ThemeScript, resolveTheme } from "@codefast/theme";
121
120
 
122
- export const Route = createRootRouteWithContext<YourContext>()({
121
+ export const Route = createRootRouteWithContext<YourRouterContext>()({
123
122
  loader: async () => getRootThemeServerFn(),
124
123
  shellComponent: RootShell,
125
124
  });
@@ -150,21 +149,29 @@ function RootShell({ children }: { children: React.ReactNode }) {
150
149
  }
151
150
  ```
152
151
 
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).
152
+ To keep cached HTML honest when serving `system`, advertise the Client Hint and add the right `Vary` header:
153
+
154
+ ```
155
+ Accept-CH: Sec-CH-Prefers-Color-Scheme
156
+ Vary: Sec-CH-Prefers-Color-Scheme, Cookie
157
+ ```
154
158
 
155
- ### Generic React (Client-Side)
159
+ `syncThemeFromServer` re-reads the cookie once after mount and covers edge cases like duplicate-tab restores where the HTML is older than the cookie.
156
160
 
157
- For client-side React applications without a server framework, persist the theme to `localStorage`:
161
+ ### Client-only React (localStorage)
162
+
163
+ For apps without a server framework, persist the theme in `localStorage`:
158
164
 
159
165
  ```tsx
160
166
  import { ThemeProvider } from "@codefast/theme";
161
167
 
162
168
  function App() {
163
- const savedTheme = localStorage.getItem("theme") ?? "system";
169
+ const saved =
170
+ typeof window !== "undefined" ? (localStorage.getItem("theme") ?? "system") : "system";
164
171
 
165
172
  return (
166
173
  <ThemeProvider
167
- theme={savedTheme}
174
+ theme={saved}
168
175
  persistTheme={async (value) => {
169
176
  localStorage.setItem("theme", value);
170
177
  }}
@@ -175,21 +182,23 @@ function App() {
175
182
  }
176
183
  ```
177
184
 
178
- ### Theme Toggle Component
179
-
180
- Build a theme switcher using the `useTheme` hook and the `themes` constant:
185
+ ### Theme toggle
181
186
 
182
187
  ```tsx
183
- import { useTheme, themes } from "@codefast/theme";
188
+ import { themes, useTheme } from "@codefast/theme";
184
189
 
185
- function ThemeToggle() {
190
+ export function ThemeSelect() {
186
191
  const { theme, setTheme, isPending } = useTheme();
187
192
 
188
193
  return (
189
- <select value={theme} onChange={(e) => setTheme(e.target.value)} disabled={isPending}>
190
- {themes.map((t) => (
191
- <option key={t} value={t}>
192
- {t.charAt(0).toUpperCase() + t.slice(1)}
194
+ <select
195
+ value={theme}
196
+ disabled={isPending}
197
+ onChange={(event) => setTheme(event.target.value as (typeof themes)[number])}
198
+ >
199
+ {themes.map((value) => (
200
+ <option key={value} value={value}>
201
+ {value[0].toUpperCase() + value.slice(1)}
193
202
  </option>
194
203
  ))}
195
204
  </select>
@@ -197,127 +206,183 @@ function ThemeToggle() {
197
206
  }
198
207
  ```
199
208
 
200
- ## SSR and FOUC Prevention
209
+ `isPending` is `true` while the optimistic value differs from the persisted value — useful for disabling the control until persistence settles.
201
210
 
202
- When server-rendering your application, include `ThemeScript` in the `<head>` to prevent a flash of unstyled content. The script runs synchronously before the page paints, applying the correct theme class to the `<html>` element.
211
+ ---
203
212
 
204
- ```tsx
205
- import { ThemeScript } from "@codefast/theme";
213
+ ## SSR and FOUC prevention
206
214
 
207
- // In your HTML head (framework-specific)
208
- <ThemeScript theme="system" />;
209
- ```
210
-
211
- For Content Security Policy (CSP) environments, pass a `nonce` to both `ThemeScript` and `ThemeProvider`:
215
+ `<ThemeScript>` injects a tiny synchronous `<script>` into the document head. It runs before first paint, resolves `system` via `matchMedia`, and adds the appropriate class + `color-scheme` to `<html>`:
212
216
 
213
217
  ```tsx
214
- <ThemeScript theme="system" nonce={cspNonce} />
215
- <ThemeProvider theme="system" nonce={cspNonce}>
216
- <App />
217
- </ThemeProvider>
218
+ <head>
219
+ <ThemeScript theme="system" />
220
+ </head>
218
221
  ```
219
222
 
223
+ The script removes any prior `light` / `dark` / `system` class on `<html>`, so it is safe to pre-render the markup with `suppressHydrationWarning`.
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>`.
226
+
227
+ ---
228
+
220
229
  ## API Reference
221
230
 
222
- ### ThemeProvider
231
+ ### `<ThemeProvider>`
223
232
 
224
- Root provider component that manages theme state and context.
233
+ Root provider that wires together theme state, OS subscription, optimistic updates, and cross-tab broadcast.
225
234
 
226
235
  ```tsx
227
236
  <ThemeProvider
228
- theme="system"
237
+ theme={initialTheme}
238
+ ssrSystemTheme="light"
229
239
  persistTheme={async (value) => {
230
- /* save theme */
240
+ /* … */
231
241
  }}
232
- disableTransitionOnChange={false}
233
- nonce="abc123"
242
+ syncThemeFromServer={getThemeServerFn}
243
+ disableTransitionOnChange
244
+ nonce={cspNonce}
234
245
  >
235
246
  {children}
236
247
  </ThemeProvider>
237
248
  ```
238
249
 
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 |
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. |
259
+
260
+ `<ThemeProvider>` internally:
248
261
 
249
- ### useTheme
262
+ 1. Tracks the persisted `theme` and an `optimisticTheme` for immediate feedback.
263
+ 2. Subscribes to `(prefers-color-scheme: dark)` through `useSyncExternalStore` with a server snapshot backed by `ssrSystemTheme`.
264
+ 3. Applies the resolved class + `color-scheme` to `<html>` whenever it changes.
265
+ 4. Broadcasts the new value over `BroadcastChannel("theme-sync")` so other tabs stay in sync.
250
266
 
251
- Hook that returns the current theme state and a setter function.
267
+ ### `useTheme()`
252
268
 
253
269
  ```tsx
254
270
  const { theme, resolvedTheme, setTheme, isPending } = useTheme();
255
271
  ```
256
272
 
257
- | Property | Type | Description |
258
- | --------------- | --------------------------------- | ------------------------------------------------------------------------- |
259
- | `theme` | `Theme` | Current theme preference (`'light'`, `'dark'`, or `'system'`) |
260
- | `resolvedTheme` | `ResolvedTheme` | Resolved theme after evaluating system preference (`'light'` or `'dark'`) |
261
- | `setTheme` | `(value: Theme) => Promise<void>` | Function to update the theme |
262
- | `isPending` | `boolean` | `true` while an optimistic theme update is in progress |
273
+ | Field | Type | Description |
274
+ | --------------- | --------------------------------- | ------------------------------------------------------------------------------- |
275
+ | `theme` | `Theme` | Current preference (reflects the optimistic value while a change is pending). |
276
+ | `resolvedTheme` | `ResolvedTheme` | `"light"` or `"dark"` — the value actually applied to `<html>`. |
277
+ | `setTheme` | `(value: Theme) => Promise<void>` | Update + persist. Resolves once persistence settles; on failure the UI reverts. |
278
+ | `isPending` | `boolean` | `true` while `optimisticTheme !== theme` (i.e. a change is in flight). |
263
279
 
264
- ### ThemeScript
280
+ Throws if called outside of a `<ThemeProvider>`.
265
281
 
266
- Inline script component for SSR that prevents FOUC by applying the theme before first paint.
282
+ ### `<ThemeScript>`
283
+
284
+ Inline script for the document head that prevents FOUC.
267
285
 
268
286
  ```tsx
269
- <ThemeScript theme="system" nonce="optional-csp-nonce" />
287
+ <ThemeScript theme={theme} />
270
288
  ```
271
289
 
272
- | Prop | Type | Description |
273
- | ------- | -------- | ---------------------------------- |
274
- | `theme` | `Theme` | The theme to apply on initial load |
275
- | `nonce` | `string` | Optional CSP nonce |
290
+ | Prop | Type | Description |
291
+ | ------- | ------- | -------------------------------------------------------------------------------- |
292
+ | `theme` | `Theme` | The preference to apply on initial render. `"system"` resolves via `matchMedia`. |
276
293
 
277
- ### resolveTheme
294
+ The component only emits a `<script>` with `dangerouslySetInnerHTML`. It does not currently accept a `nonce` — see the [CSP note](#ssr-and-fouc-prevention).
278
295
 
279
- Utility function that resolves a theme value to either `'light'` or `'dark'`.
296
+ ### `resolveTheme()`
280
297
 
281
- ```typescript
298
+ ```tsx
282
299
  import { resolveTheme } from "@codefast/theme";
283
300
 
284
- const resolved = resolveTheme("system"); // client: OS via matchMedia
285
- const ssr = resolveTheme("system", "light"); // server: pass Client-Hint–backed value
301
+ resolveTheme("dark"); // → "dark"
302
+ resolveTheme("system"); // client: OS preference via matchMedia
303
+ resolveTheme("system", "light"); // server: use Client Hints fallback
286
304
  ```
287
305
 
288
- ### themes
306
+ Returns a `ResolvedTheme` (`"light" | "dark"`). On the server without an `ssrSystemTheme`, falls back to `DEFAULT_RESOLVED_THEME` (`"dark"`).
307
+
308
+ ### `getSystemTheme()` / `applyTheme()` / `disableAnimation()`
289
309
 
290
- A constant array containing all available theme values.
310
+ Granular helpers from `@codefast/theme/utils/system` and `@codefast/theme/utils/dom` for custom integrations:
291
311
 
292
- ```typescript
293
- import { themes } from "@codefast/theme";
312
+ | Function | Summary |
313
+ | -------------------------- | ------------------------------------------------------------------------------------------------------ |
314
+ | `getSystemTheme()` | Returns `"light"` or `"dark"` using `matchMedia("(prefers-color-scheme: dark)")`. SSR-safe. |
315
+ | `applyTheme(resolved)` | Toggles `light` / `dark` / `system` classes on `<html>` and sets `color-scheme`. |
316
+ | `disableAnimation(nonce?)` | Returns a cleanup that re-enables CSS transitions. No-op when `prefers-reduced-motion: reduce` is set. |
294
317
 
295
- console.log(themes); // ['light', 'dark', 'system']
318
+ ### `themes`, `themeSchema`, and defaults
319
+
320
+ ```tsx
321
+ import {
322
+ DEFAULT_RESOLVED_THEME, // "dark"
323
+ DEFAULT_THEME, // "system"
324
+ THEME_STORAGE_KEY, // "ui-theme" — cookie name used by the Start adapter
325
+ themeSchema, // Zod: z.enum(["light", "dark", "system"])
326
+ themes, // readonly ["light", "dark", "system"]
327
+ } from "@codefast/theme";
296
328
  ```
297
329
 
298
- ## Contributing
330
+ ### TanStack Start adapter (`@codefast/theme/start`)
299
331
 
300
- We welcome contributions! Please see the [contributing guide](../../README.md#contributing) in the root of this repository for detailed instructions on how to get started.
332
+ Server functions and helpers for cookie-backed persistence. All helpers are safe to import from both server and client module graphs — but only run from the appropriate context.
301
333
 
302
- For package-specific development:
334
+ | Export | Kind | Purpose |
335
+ | --------------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
336
+ | `getRootThemeServerFn` | Server fn | Reads `{ theme, ssrSystemTheme }` from cookie + Client Hints. Use in your root route loader. |
337
+ | `getThemeServerFn` | Server fn | Reads only the stored theme. Stable reference — pass directly to `<ThemeProvider syncThemeFromServer>`. |
338
+ | `getSsrSystemThemeServerFn` | Server fn | Reads only the SSR system hint (Client-Hint value). |
339
+ | `setThemeServerFn` | Server fn | Writes the theme cookie from a server action. |
340
+ | `persistThemeCookie` | Helper | Drop-in `persistTheme` prop for `<ThemeProvider>`; wraps `setThemeServerFn`. |
341
+ | `RootThemeLoaderData` | Type | Shape of the loader payload returned by `getRootThemeServerFn`. |
303
342
 
304
- ```bash
305
- # Development mode with watch
306
- pnpm dev --filter=@codefast/theme
343
+ ---
344
+
345
+ ## Package exports
346
+
347
+ The root `@codefast/theme` entry re-exports the common surface. Granular subpaths are available for bundler-aware tree-shaking.
348
+
349
+ | Subpath | Contents |
350
+ | ------------------------------------------------ | ------------------------------------------------------------------------------------- |
351
+ | `@codefast/theme` | `ThemeProvider`, `useTheme`, `ThemeScript`, `resolveTheme`, types, `themes`, defaults |
352
+ | `@codefast/theme/start` | TanStack Start server functions + `persistThemeCookie`, `RootThemeLoaderData` |
353
+ | `@codefast/theme/adapters/tanstack-start/server` | Same exports as `/start`, reached via the full adapter path |
354
+ | `@codefast/theme/core/provider` | `ThemeProvider` |
355
+ | `@codefast/theme/core/use-theme` | `useTheme` |
356
+ | `@codefast/theme/core/context` | Raw `ThemeContext` for custom providers |
357
+ | `@codefast/theme/script/theme-script` | `ThemeScript` |
358
+ | `@codefast/theme/utils/system` | `getSystemTheme`, `resolveTheme` |
359
+ | `@codefast/theme/utils/dom` | `applyTheme`, `disableAnimation` |
360
+ | `@codefast/theme/constants` | `DEFAULT_THEME`, `DEFAULT_RESOLVED_THEME`, `THEME_STORAGE_KEY` |
361
+ | `@codefast/theme/types` | `Theme`, `ResolvedTheme`, `ThemeContextType`, `themes`, `themeSchema` |
362
+
363
+ See `package.json → exports` for the authoritative list.
307
364
 
308
- # Run tests
309
- pnpm test --filter=@codefast/theme
365
+ ---
310
366
 
311
- # Run tests with coverage
312
- pnpm test:coverage --filter=@codefast/theme
367
+ ## Contributing
368
+
369
+ This package lives in the [Codefast monorepo](https://github.com/codefastlabs/codefast). From the repo root:
370
+
371
+ ```bash
372
+ pnpm --filter @codefast/theme build
373
+ pnpm --filter @codefast/theme test
374
+ pnpm --filter @codefast/theme check-types
375
+ pnpm --filter @codefast/theme dev # watch-mode build
313
376
  ```
314
377
 
315
- Package build/dev scripts use TypeScript directly via `tsc -p tsconfig.build.json` (watch mode for `pnpm dev --filter=@codefast/theme`).
378
+ ---
316
379
 
317
380
  ## License
318
381
 
319
- Distributed under the MIT License. See [LICENSE](../../LICENSE) for more details.
382
+ [MIT](https://opensource.org/licenses/MIT) — see [`package.json`](./package.json).
383
+
384
+ ---
320
385
 
321
386
  ## Changelog
322
387
 
323
- See [CHANGELOG.md](./CHANGELOG.md) for a complete list of changes and version history.
388
+ See [CHANGELOG.md](./CHANGELOG.md) for the full version history. Releases are also published on [npm](https://www.npmjs.com/package/@codefast/theme?activeTab=versions).
@@ -14,7 +14,9 @@ interface RootThemeLoaderData {
14
14
  * {@link DEFAULT_RESOLVED_THEME}.
15
15
  */
16
16
  ssrSystemTheme: ResolvedTheme;
17
- /** User preference from the httpOnly cookie: `light`, `dark`, or `system`. */
17
+ /**
18
+ * User preference from the httpOnly cookie: `light`, `dark`, or `system`.
19
+ */
18
20
  theme: Theme;
19
21
  }
20
22
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codefast/theme",
3
- "version": "0.3.13",
3
+ "version": "0.3.14-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",
@@ -108,7 +108,7 @@
108
108
  "jsdom": "^29.0.2",
109
109
  "typescript": "^6.0.2",
110
110
  "vitest": "^4.1.4",
111
- "@codefast/typescript-config": "0.3.13"
111
+ "@codefast/typescript-config": "0.3.14-canary.1"
112
112
  },
113
113
  "peerDependencies": {
114
114
  "@tanstack/react-start": "^1.0",