@codefast/theme 0.3.15 → 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,9 @@
1
1
  # @codefast/theme
2
2
 
3
+ ## 0.3.16-canary.1
4
+
5
+ ## 0.3.16-canary.0
6
+
3
7
  ## 0.3.15
4
8
 
5
9
  ### Patch Changes
@@ -5,6 +5,8 @@ import * as _$_tanstack_react_start0 from "@tanstack/react-start";
5
5
  //#region src/adapters/tanstack-start/server.d.ts
6
6
  /**
7
7
  * Data shape returned from {@link getRootThemeServerFn} for the root route loader.
8
+ *
9
+ * @since 0.3.16-canary.0
8
10
  */
9
11
  interface RootThemeLoaderData {
10
12
  /**
@@ -23,6 +25,8 @@ interface RootThemeLoaderData {
23
25
  * Everything needed for the root shell in **one** server call (fewer loader awaits).
24
26
  *
25
27
  * In your shell: `resolveTheme(theme, ssrSystemTheme)` on `<html>`, plus `ThemeScript` and `ThemeProvider`.
28
+ *
29
+ * @since 0.3.16-canary.0
26
30
  */
27
31
  declare const getRootThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, RootThemeLoaderData>;
28
32
  /**
@@ -37,6 +41,8 @@ declare const getRootThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<und
37
41
  * ```tsx
38
42
  * const theme = await getThemeServerFn();
39
43
  * ```
44
+ *
45
+ * @since 0.3.16-canary.0
40
46
  */
41
47
  declare const getThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, "light" | "dark" | "system">;
42
48
  /**
@@ -46,6 +52,8 @@ declare const getThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefin
46
52
  * Prefer {@link getRootThemeServerFn} for root loaders.
47
53
  *
48
54
  * Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
55
+ *
56
+ * @since 0.3.16-canary.0
49
57
  */
50
58
  declare const getSsrSystemThemeServerFn: _$_tanstack_react_start0.OptionalFetcher<undefined, undefined, ResolvedTheme>;
51
59
  /**
@@ -63,6 +71,8 @@ declare const getSsrSystemThemeServerFn: _$_tanstack_react_start0.OptionalFetche
63
71
  * @param data - Theme to persist ('light', 'dark', or 'system')
64
72
  *
65
73
  * @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
74
+ *
75
+ * @since 0.3.16-canary.0
66
76
  */
67
77
  declare const setThemeServerFn: _$_tanstack_react_start0.RequiredFetcher<undefined, _$zod.ZodEnum<{
68
78
  light: "light";
@@ -72,6 +82,8 @@ declare const setThemeServerFn: _$_tanstack_react_start0.RequiredFetcher<undefin
72
82
  /**
73
83
  * Default {@link ThemeProvider} `persistTheme` for the Start adapter: writes the httpOnly
74
84
  * theme cookie via {@link setThemeServerFn}.
85
+ *
86
+ * @since 0.3.16-canary.0
75
87
  */
76
88
  declare function persistThemeCookie(value: Theme): Promise<void>;
77
89
  //#endregion
@@ -19,6 +19,8 @@ function readSsrSystemThemeFromHeaders() {
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
+ *
23
+ * @since 0.3.16-canary.0
22
24
  */
23
25
  const getRootThemeServerFn = createServerFn().handler(() => ({
24
26
  theme: readThemeFromCookie(),
@@ -36,6 +38,8 @@ const getRootThemeServerFn = createServerFn().handler(() => ({
36
38
  * ```tsx
37
39
  * const theme = await getThemeServerFn();
38
40
  * ```
41
+ *
42
+ * @since 0.3.16-canary.0
39
43
  */
40
44
  const getThemeServerFn = createServerFn().handler(() => readThemeFromCookie());
41
45
  /**
@@ -45,6 +49,8 @@ const getThemeServerFn = createServerFn().handler(() => readThemeFromCookie());
45
49
  * Prefer {@link getRootThemeServerFn} for root loaders.
46
50
  *
47
51
  * Send `Accept-CH: Sec-CH-Prefers-Color-Scheme` (and `Vary`) so navigations include the hint.
52
+ *
53
+ * @since 0.3.16-canary.0
48
54
  */
49
55
  const getSsrSystemThemeServerFn = createServerFn().handler(() => readSsrSystemThemeFromHeaders());
50
56
  /**
@@ -62,6 +68,8 @@ const getSsrSystemThemeServerFn = createServerFn().handler(() => readSsrSystemTh
62
68
  * @param data - Theme to persist ('light', 'dark', or 'system')
63
69
  *
64
70
  * @see [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/server-functions)
71
+ *
72
+ * @since 0.3.16-canary.0
65
73
  */
66
74
  const setThemeServerFn = createServerFn({ method: "POST" }).inputValidator(themeSchema).handler(({ data }) => {
67
75
  setCookie(THEME_STORAGE_KEY, data, {
@@ -75,6 +83,8 @@ const setThemeServerFn = createServerFn({ method: "POST" }).inputValidator(theme
75
83
  /**
76
84
  * Default {@link ThemeProvider} `persistTheme` for the Start adapter: writes the httpOnly
77
85
  * theme cookie via {@link setThemeServerFn}.
86
+ *
87
+ * @since 0.3.16-canary.0
78
88
  */
79
89
  async function persistThemeCookie(value) {
80
90
  await setThemeServerFn({ data: value });
@@ -5,23 +5,31 @@ import { ResolvedTheme, Theme } from "./types.mjs";
5
5
  * Default theme when no user preference exists.
6
6
  *
7
7
  * Set to 'system' to respect OS preference by default.
8
+ *
9
+ * @since 0.3.16-canary.0
8
10
  */
9
11
  declare const DEFAULT_THEME: Theme;
10
12
  /**
11
13
  * Fallback theme for SSR when system preference cannot be detected.
12
14
  *
13
15
  * Used during server-side rendering since `window.matchMedia()` is unavailable.
16
+ *
17
+ * @since 0.3.16-canary.0
14
18
  */
15
19
  declare const DEFAULT_RESOLVED_THEME: ResolvedTheme;
16
20
  /**
17
21
  * Cookie name for the httpOnly theme preference (`@codefast/theme/start`).
18
22
  *
19
23
  * Re-exported only from `@codefast/theme/constants` so custom middleware matches the adapter.
24
+ *
25
+ * @since 0.3.16-canary.0
20
26
  */
21
27
  declare const THEME_STORAGE_KEY = "ui-theme";
22
28
  /**
23
29
  * CSS media query for detecting dark mode preference.
24
30
  * @internal
31
+ *
32
+ * @since 0.3.16-canary.0
25
33
  */
26
34
  declare const MEDIA = "(prefers-color-scheme: dark)";
27
35
  /**
@@ -29,6 +37,8 @@ declare const MEDIA = "(prefers-color-scheme: dark)";
29
37
  *
30
38
  * Enables instant theme updates across all open browser tabs.
31
39
  * @internal
40
+ *
41
+ * @since 0.3.16-canary.0
32
42
  */
33
43
  declare const THEME_CHANNEL = "theme-sync";
34
44
  //#endregion
@@ -3,23 +3,31 @@
3
3
  * Default theme when no user preference exists.
4
4
  *
5
5
  * Set to 'system' to respect OS preference by default.
6
+ *
7
+ * @since 0.3.16-canary.0
6
8
  */
7
9
  const DEFAULT_THEME = "system";
8
10
  /**
9
11
  * Fallback theme for SSR when system preference cannot be detected.
10
12
  *
11
13
  * Used during server-side rendering since `window.matchMedia()` is unavailable.
14
+ *
15
+ * @since 0.3.16-canary.0
12
16
  */
13
17
  const DEFAULT_RESOLVED_THEME = "dark";
14
18
  /**
15
19
  * Cookie name for the httpOnly theme preference (`@codefast/theme/start`).
16
20
  *
17
21
  * Re-exported only from `@codefast/theme/constants` so custom middleware matches the adapter.
22
+ *
23
+ * @since 0.3.16-canary.0
18
24
  */
19
25
  const THEME_STORAGE_KEY = "ui-theme";
20
26
  /**
21
27
  * CSS media query for detecting dark mode preference.
22
28
  * @internal
29
+ *
30
+ * @since 0.3.16-canary.0
23
31
  */
24
32
  const MEDIA = "(prefers-color-scheme: dark)";
25
33
  /**
@@ -27,6 +35,8 @@ const MEDIA = "(prefers-color-scheme: dark)";
27
35
  *
28
36
  * Enables instant theme updates across all open browser tabs.
29
37
  * @internal
38
+ *
39
+ * @since 0.3.16-canary.0
30
40
  */
31
41
  const THEME_CHANNEL = "theme-sync";
32
42
  //#endregion
@@ -11,6 +11,8 @@ type ThemeContextValue = null | ThemeContextType;
11
11
  *
12
12
  * @see {@link ThemeProvider} - Provider component
13
13
  * @see {@link useTheme} - Consumer hook
14
+ *
15
+ * @since 0.3.16-canary.0
14
16
  */
15
17
  declare const ThemeContext: _$react.Context<ThemeContextValue>;
16
18
  //#endregion
@@ -8,6 +8,8 @@ import { createContext } from "react";
8
8
  *
9
9
  * @see {@link ThemeProvider} - Provider component
10
10
  * @see {@link useTheme} - Consumer hook
11
+ *
12
+ * @since 0.3.16-canary.0
11
13
  */
12
14
  const ThemeContext = createContext(null);
13
15
  //#endregion
@@ -73,6 +73,8 @@ interface ThemeProviderProps {
73
73
  * {children}
74
74
  * </ThemeProvider>
75
75
  * ```
76
+ *
77
+ * @since 0.3.16-canary.0
76
78
  */
77
79
  declare function ThemeProvider({
78
80
  children,
@@ -55,6 +55,8 @@ function getSystemThemeSnapshot() {
55
55
  * {children}
56
56
  * </ThemeProvider>
57
57
  * ```
58
+ *
59
+ * @since 0.3.16-canary.0
58
60
  */
59
61
  function ThemeProvider({ children, disableTransitionOnChange = false, nonce, persistTheme, ssrSystemTheme, syncThemeFromServer, theme: initialTheme }) {
60
62
  const [theme, setThemeState] = useState(initialTheme);
@@ -26,6 +26,8 @@ import { ThemeContextType } from "../types.mjs";
26
26
  * );
27
27
  * }
28
28
  * ```
29
+ *
30
+ * @since 0.3.16-canary.0
29
31
  */
30
32
  declare function useTheme(): ThemeContextType;
31
33
  //#endregion
@@ -26,6 +26,8 @@ import { use } from "react";
26
26
  * );
27
27
  * }
28
28
  * ```
29
+ *
30
+ * @since 0.3.16-canary.0
29
31
  */
30
32
  function useTheme() {
31
33
  const value = use(ThemeContext);
@@ -30,6 +30,8 @@ interface ThemeScriptProps {
30
30
  * <ThemeScript theme={theme} />
31
31
  * </head>
32
32
  * ```
33
+ *
34
+ * @since 0.3.16-canary.0
33
35
  */
34
36
  declare function ThemeScript({
35
37
  theme
@@ -22,6 +22,8 @@ import { jsx } from "react/jsx-runtime";
22
22
  * <ThemeScript theme={theme} />
23
23
  * </head>
24
24
  * ```
25
+ *
26
+ * @since 0.3.16-canary.0
25
27
  */
26
28
  function ThemeScript({ theme }) {
27
29
  return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: `(function(){try{var theme="${theme}",resolvedTheme=theme;"system"===theme&&(resolvedTheme=window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"),document.documentElement.classList.remove("light","dark","system"),document.documentElement.classList.add(resolvedTheme),document.documentElement.style.colorScheme=resolvedTheme}catch(error){}})()` } });
package/dist/types.d.mts CHANGED
@@ -6,6 +6,8 @@ import { z } from "zod";
6
6
  *
7
7
  * Acts as the single source of truth for all theme-related types.
8
8
  * Valid values: 'light', 'dark', 'system'.
9
+ *
10
+ * @since 0.3.16-canary.0
9
11
  */
10
12
  declare const themeSchema: z.ZodEnum<{
11
13
  light: "light";
@@ -18,18 +20,24 @@ declare const themeSchema: z.ZodEnum<{
18
20
  * - `'light'` - Force light mode
19
21
  * - `'dark'` - Force dark mode
20
22
  * - `'system'` - Follow OS preference
23
+ *
24
+ * @since 0.3.16-canary.0
21
25
  */
22
26
  type Theme = z.infer<typeof themeSchema>;
23
27
  /**
24
28
  * Actual theme applied to the UI after resolving 'system'.
25
29
  *
26
30
  * When theme is 'system', this reflects the OS preference (light/dark).
31
+ *
32
+ * @since 0.3.16-canary.0
27
33
  */
28
34
  type ResolvedTheme = Exclude<Theme, "system">;
29
35
  /**
30
36
  * Array of all available theme options: `['light', 'dark', 'system']`.
31
37
  *
32
38
  * Useful for rendering theme selectors in UI components.
39
+ *
40
+ * @since 0.3.16-canary.0
33
41
  */
34
42
  declare const themes: ("light" | "dark" | "system")[];
35
43
  /**
@@ -39,6 +47,8 @@ declare const themes: ("light" | "dark" | "system")[];
39
47
  * - `resolvedTheme` - Actual theme applied (system resolved to light/dark)
40
48
  * - `setTheme` - Async function to update theme (triggers optimistic update)
41
49
  * - `isPending` - True while theme change is being persisted
50
+ *
51
+ * @since 0.3.16-canary.0
42
52
  */
43
53
  interface ThemeContextType {
44
54
  isPending: boolean;
package/dist/types.mjs CHANGED
@@ -5,6 +5,8 @@ import { z } from "zod";
5
5
  *
6
6
  * Acts as the single source of truth for all theme-related types.
7
7
  * Valid values: 'light', 'dark', 'system'.
8
+ *
9
+ * @since 0.3.16-canary.0
8
10
  */
9
11
  const themeSchema = z.enum([
10
12
  "light",
@@ -15,6 +17,8 @@ const themeSchema = z.enum([
15
17
  * Array of all available theme options: `['light', 'dark', 'system']`.
16
18
  *
17
19
  * Useful for rendering theme selectors in UI components.
20
+ *
21
+ * @since 0.3.16-canary.0
18
22
  */
19
23
  const themes = themeSchema.options;
20
24
  //#endregion
@@ -9,6 +9,8 @@ import { ResolvedTheme } from "../types.mjs";
9
9
  * - `color-scheme` style (for native form controls and scrollbars)
10
10
  *
11
11
  * @param resolved - The resolved theme to apply ('light' or 'dark')
12
+ *
13
+ * @since 0.3.16-canary.0
12
14
  */
13
15
  declare function applyTheme(resolved: ResolvedTheme): void;
14
16
  /**
@@ -26,6 +28,8 @@ declare function applyTheme(resolved: ResolvedTheme): void;
26
28
  * applyTheme('dark');
27
29
  * enableTransitions(); // Re-enables CSS transitions
28
30
  * ```
31
+ *
32
+ * @since 0.3.16-canary.0
29
33
  */
30
34
  declare function disableAnimation(nonce?: string): () => void;
31
35
  //#endregion
@@ -7,6 +7,8 @@
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
+ *
11
+ * @since 0.3.16-canary.0
10
12
  */
11
13
  function applyTheme(resolved) {
12
14
  const root = window.document.documentElement;
@@ -29,6 +31,8 @@ function applyTheme(resolved) {
29
31
  * applyTheme('dark');
30
32
  * enableTransitions(); // Re-enables CSS transitions
31
33
  * ```
34
+ *
35
+ * @since 0.3.16-canary.0
32
36
  */
33
37
  function disableAnimation(nonce) {
34
38
  if (typeof globalThis.window === "undefined") return () => {};
@@ -8,6 +8,8 @@ import { ResolvedTheme, Theme } from "../types.mjs";
8
8
  * Returns {@link DEFAULT_RESOLVED_THEME} during SSR since `window` is unavailable.
9
9
  *
10
10
  * @returns 'light' or 'dark' based on OS preference
11
+ *
12
+ * @since 0.3.16-canary.0
11
13
  */
12
14
  declare function getSystemTheme(): ResolvedTheme;
13
15
  /**
@@ -24,6 +26,8 @@ declare function getSystemTheme(): ResolvedTheme;
24
26
  * (`Sec-CH-Prefers-Color-Scheme`) so `<html class>` matches the real OS preference.
25
27
  * Ignored for non-`system` themes and on the client (where {@link getSystemTheme} wins).
26
28
  * @returns The resolved theme to apply (`light` or `dark`)
29
+ *
30
+ * @since 0.3.16-canary.0
27
31
  */
28
32
  declare function resolveTheme(theme: Theme, ssrSystemTheme?: ResolvedTheme): ResolvedTheme;
29
33
  //#endregion
@@ -7,6 +7,8 @@ import { DEFAULT_RESOLVED_THEME } from "../constants.mjs";
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
+ *
11
+ * @since 0.3.16-canary.0
10
12
  */
11
13
  function getSystemTheme() {
12
14
  if (typeof globalThis.window === "undefined") return DEFAULT_RESOLVED_THEME;
@@ -26,6 +28,8 @@ function getSystemTheme() {
26
28
  * (`Sec-CH-Prefers-Color-Scheme`) so `<html class>` matches the real OS preference.
27
29
  * Ignored for non-`system` themes and on the client (where {@link getSystemTheme} wins).
28
30
  * @returns The resolved theme to apply (`light` or `dark`)
31
+ *
32
+ * @since 0.3.16-canary.0
29
33
  */
30
34
  function resolveTheme(theme, ssrSystemTheme) {
31
35
  if (theme !== "system") return theme;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codefast/theme",
3
- "version": "0.3.15",
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",
@@ -100,25 +100,26 @@
100
100
  "access": "public"
101
101
  },
102
102
  "dependencies": {
103
- "zod": "^4.4.2"
103
+ "zod": "^4.4.3"
104
104
  },
105
105
  "devDependencies": {
106
- "@tanstack/react-start": "^1.167.61",
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.20260502.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.15"
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
  }