@codefast/theme 1.0.0-canary.6 → 1.0.0-canary.7

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 (50) hide show
  1. package/CHANGELOG.md +2 -0
  2. package/README.md +86 -270
  3. package/dist/{appearance-context.d.mts → appearance-context.d.ts} +3 -6
  4. package/dist/appearance-context.d.ts.map +1 -0
  5. package/dist/appearance-context.js +17 -0
  6. package/dist/appearance-context.js.map +1 -0
  7. package/dist/appearance-provider.d.ts +63 -0
  8. package/dist/appearance-provider.d.ts.map +1 -0
  9. package/dist/appearance-provider.js +240 -0
  10. package/dist/appearance-provider.js.map +1 -0
  11. package/dist/{appearance-script.d.mts → appearance-script.d.ts} +20 -27
  12. package/dist/appearance-script.d.ts.map +1 -0
  13. package/dist/appearance-script.js +51 -0
  14. package/dist/appearance-script.js.map +1 -0
  15. package/dist/{appearance.d.mts → appearance.d.ts} +13 -16
  16. package/dist/appearance.d.ts.map +1 -0
  17. package/dist/appearance.js +27 -0
  18. package/dist/appearance.js.map +1 -0
  19. package/dist/{color-scheme.d.mts → color-scheme.d.ts} +4 -7
  20. package/dist/color-scheme.d.ts.map +1 -0
  21. package/dist/color-scheme.js +37 -0
  22. package/dist/color-scheme.js.map +1 -0
  23. package/dist/{constants.d.mts → constants.d.ts} +7 -10
  24. package/dist/constants.d.ts.map +1 -0
  25. package/dist/constants.js +46 -0
  26. package/dist/constants.js.map +1 -0
  27. package/dist/{dom.d.mts → dom.d.ts} +4 -7
  28. package/dist/dom.d.ts.map +1 -0
  29. package/dist/dom.js +71 -0
  30. package/dist/dom.js.map +1 -0
  31. package/dist/index.d.ts +23 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +24 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/{use-appearance.d.mts → use-appearance.d.ts} +3 -6
  36. package/dist/use-appearance.d.ts.map +1 -0
  37. package/dist/use-appearance.js +41 -0
  38. package/dist/use-appearance.js.map +1 -0
  39. package/package.json +49 -40
  40. package/dist/appearance-context.mjs +0 -16
  41. package/dist/appearance-provider.d.mts +0 -74
  42. package/dist/appearance-provider.mjs +0 -180
  43. package/dist/appearance-script.mjs +0 -46
  44. package/dist/appearance.mjs +0 -25
  45. package/dist/color-scheme.mjs +0 -32
  46. package/dist/constants.mjs +0 -42
  47. package/dist/dom.mjs +0 -52
  48. package/dist/index.d.mts +0 -7
  49. package/dist/index.mjs +0 -7
  50. package/dist/use-appearance.mjs +0 -38
@@ -1,6 +1,4 @@
1
- import { ColorScheme } from "./appearance.mjs";
2
-
3
- //#region src/dom.d.ts
1
+ import type { ColorScheme } from "#/appearance";
4
2
  /**
5
3
  * Apply a color scheme to the DOM by updating the `<html>` element.
6
4
  *
@@ -10,7 +8,7 @@ import { ColorScheme } from "./appearance.mjs";
10
8
  *
11
9
  * @since 0.3.16-canary.0
12
10
  */
13
- declare function applyColorScheme(colorScheme: ColorScheme): void;
11
+ export declare function applyColorScheme(colorScheme: ColorScheme): void;
14
12
  /**
15
13
  * Temporarily suppress all CSS transitions during appearance changes.
16
14
  *
@@ -29,6 +27,5 @@ declare function applyColorScheme(colorScheme: ColorScheme): void;
29
27
  *
30
28
  * @since 0.3.16-canary.0
31
29
  */
32
- declare function suppressTransitions(nonce?: string): () => void;
33
- //#endregion
34
- export { applyColorScheme, suppressTransitions };
30
+ export declare function suppressTransitions(nonce?: string): () => void;
31
+ //# sourceMappingURL=dom.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAMhD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAM/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAyC9D"}
package/dist/dom.js ADDED
@@ -0,0 +1,71 @@
1
+ /* -----------------------------------------------------------------------------
2
+ * DOM Utilities
3
+ * -------------------------------------------------------------------------- */
4
+ /**
5
+ * Apply a color scheme to the DOM by updating the `<html>` element.
6
+ *
7
+ * Updates both:
8
+ * - CSS class (for Tailwind's `dark:` variants)
9
+ * - `color-scheme` style (for native form controls and scrollbars)
10
+ *
11
+ * @since 0.3.16-canary.0
12
+ */
13
+ export function applyColorScheme(colorScheme) {
14
+ const root = window.document.documentElement;
15
+ root.classList.remove("light", "dark", "automatic");
16
+ root.classList.add(colorScheme);
17
+ root.style.colorScheme = colorScheme;
18
+ }
19
+ /**
20
+ * Temporarily suppress all CSS transitions during appearance changes.
21
+ *
22
+ * Prevents jarring color animations when switching between light/dark appearances.
23
+ * Respects user's `prefers-reduced-motion` preference (does nothing if enabled).
24
+ *
25
+ * @param nonce - Optional CSP nonce for the injected style element
26
+ * @returns Cleanup function to re-enable transitions. Call after the color scheme is applied.
27
+ *
28
+ * @example
29
+ * ```tsx
30
+ * const enableTransitions = suppressTransitions();
31
+ * applyColorScheme('dark');
32
+ * enableTransitions(); // Re-enables CSS transitions
33
+ * ```
34
+ *
35
+ * @since 0.3.16-canary.0
36
+ */
37
+ export function suppressTransitions(nonce) {
38
+ if (typeof globalThis.window === "undefined") {
39
+ return () => {
40
+ /* noop */
41
+ };
42
+ }
43
+ // Respect user's motion preferences
44
+ const prefersReducedMotion = globalThis.window.matchMedia("(prefers-reduced-motion: reduce)").matches;
45
+ if (prefersReducedMotion) {
46
+ return () => {
47
+ /* noop */
48
+ };
49
+ }
50
+ // Inject style to suppress all transitions
51
+ const css = document.createElement("style");
52
+ if (nonce) {
53
+ css.setAttribute("nonce", nonce);
54
+ }
55
+ // Only the unprefixed property is needed — all modern browsers support it
56
+ css.append(document.createTextNode(`*,*::before,*::after{transition:none!important}`));
57
+ document.head.append(css);
58
+ return () => {
59
+ // Force reflow to ensure styles are applied before removing
60
+ void window.getComputedStyle(document.body);
61
+ // Use double RAF to ensure paint happens before removing style
62
+ requestAnimationFrame(() => {
63
+ requestAnimationFrame(() => {
64
+ if (css.parentNode) {
65
+ css.remove();
66
+ }
67
+ });
68
+ });
69
+ };
70
+ }
71
+ //# sourceMappingURL=dom.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dom.js","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAEA;;gFAEgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAwB;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC;IAE7C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACpD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,WAAW,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,OAAO,UAAU,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QAC7C,OAAO,GAAG,EAAE;YACV,UAAU;QACZ,CAAC,CAAC;IACJ,CAAC;IAED,oCAAoC;IACpC,MAAM,oBAAoB,GAAG,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,kCAAkC,CAAC,CAAC,OAAO,CAAC;IAEtG,IAAI,oBAAoB,EAAE,CAAC;QACzB,OAAO,GAAG,EAAE;YACV,UAAU;QACZ,CAAC,CAAC;IACJ,CAAC;IAED,2CAA2C;IAC3C,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAE5C,IAAI,KAAK,EAAE,CAAC;QACV,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,0EAA0E;IAC1E,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,iDAAiD,CAAC,CAAC,CAAC;IAEvF,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAE1B,OAAO,GAAG,EAAE;QACV,4DAA4D;QAC5D,KAAK,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAE5C,+DAA+D;QAC/D,qBAAqB,CAAC,GAAG,EAAE;YACzB,qBAAqB,CAAC,GAAG,EAAE;gBACzB,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;oBACnB,GAAG,CAAC,MAAM,EAAE,CAAC;gBACf,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,23 @@
1
+ /**
2
+ * \@codefast/theme
3
+ *
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.
9
+ *
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.
13
+ */
14
+ export type { Appearance, AppearanceContextValue, ColorScheme } from "#/appearance";
15
+ export { appearances, appearanceSchema } from "#/appearance";
16
+ export { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME } from "#/constants";
17
+ export { AppearanceProvider } from "#/appearance-provider";
18
+ export type { AppearanceProviderProps } from "#/appearance-provider";
19
+ export { useAppearance } from "#/use-appearance";
20
+ export { AppearanceScript } from "#/appearance-script";
21
+ export type { AppearanceScriptProps } from "#/appearance-script";
22
+ export { resolveColorScheme } from "#/color-scheme";
23
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,YAAY,EAAE,UAAU,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG7D,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAGjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,24 @@
1
+ /**
2
+ * \@codefast/theme
3
+ *
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.
9
+ *
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.
13
+ */
14
+ export { appearances, appearanceSchema } from "#/appearance";
15
+ // Constants
16
+ export { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME } from "#/constants";
17
+ // Provider & Hook (use `@codefast/theme/appearance-context` for `AppearanceContext`)
18
+ export { AppearanceProvider } from "#/appearance-provider";
19
+ export { useAppearance } from "#/use-appearance";
20
+ // Script (FOUC prevention)
21
+ export { AppearanceScript } from "#/appearance-script";
22
+ // Resolution: `getSystemColorScheme` lives under `@codefast/theme/color-scheme`
23
+ export { resolveColorScheme } from "#/color-scheme";
24
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY;AACZ,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEvE,qFAAqF;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,2BAA2B;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,gFAAgF;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}
@@ -1,6 +1,4 @@
1
- import { AppearanceContextValue } from "./appearance.mjs";
2
-
3
- //#region src/use-appearance.d.ts
1
+ import type { AppearanceContextValue } from "#/appearance";
4
2
  /**
5
3
  * Hook to access appearance context.
6
4
  *
@@ -29,6 +27,5 @@ import { AppearanceContextValue } from "./appearance.mjs";
29
27
  *
30
28
  * @since 0.5.0-canary.2
31
29
  */
32
- declare function useAppearance(): AppearanceContextValue;
33
- //#endregion
34
- export { useAppearance };
30
+ export declare function useAppearance(): AppearanceContextValue;
31
+ //# sourceMappingURL=use-appearance.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-appearance.d.ts","sourceRoot":"","sources":["../src/use-appearance.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAO3D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,IAAI,sBAAsB,CAQtD"}
@@ -0,0 +1,41 @@
1
+ import { use } from "react";
2
+ import { AppearanceContext } from "#/appearance-context";
3
+ /* -----------------------------------------------------------------------------
4
+ * Hook
5
+ * -------------------------------------------------------------------------- */
6
+ /**
7
+ * Hook to access appearance context.
8
+ *
9
+ * Uses React 19's `use()` API for context consumption, enabling:
10
+ * - Conditional context reading
11
+ * - Better Suspense boundary integration
12
+ *
13
+ * @returns Appearance context with `appearance`, `colorScheme`, `setAppearance`, and `isPending`
14
+ * @throws Error if called outside of AppearanceProvider
15
+ *
16
+ * @example
17
+ * ```tsx
18
+ * function AppearanceToggle() {
19
+ * const { appearance, setAppearance, isPending } = useAppearance();
20
+ *
21
+ * return (
22
+ * <button
23
+ * onClick={() => setAppearance(appearance === 'dark' ? 'light' : 'dark')}
24
+ * disabled={isPending}
25
+ * >
26
+ * {appearance}
27
+ * </button>
28
+ * );
29
+ * }
30
+ * ```
31
+ *
32
+ * @since 0.5.0-canary.2
33
+ */
34
+ export function useAppearance() {
35
+ const value = use(AppearanceContext);
36
+ if (!value) {
37
+ throw new Error("useAppearance must be used within an AppearanceProvider");
38
+ }
39
+ return value;
40
+ }
41
+ //# sourceMappingURL=use-appearance.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-appearance.js","sourceRoot":"","sources":["../src/use-appearance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAG5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;gFAEgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAErC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codefast/theme",
3
- "version": "1.0.0-canary.6",
3
+ "version": "1.0.0-canary.7",
4
4
  "description": "Appearance management for React 19 with HIG-inspired vocabulary - optimistic updates, cross-tab sync, and FOUC-free SSR",
5
5
  "keywords": [
6
6
  "dark-mode",
@@ -31,9 +31,9 @@
31
31
  ],
32
32
  "type": "module",
33
33
  "sideEffects": false,
34
- "main": "./dist/index.mjs",
35
- "module": "./dist/index.mjs",
36
- "types": "./dist/index.d.mts",
34
+ "main": "./dist/index.js",
35
+ "module": "./dist/index.js",
36
+ "types": "./dist/index.d.ts",
37
37
  "imports": {
38
38
  "#/tests/*": [
39
39
  "./tests/*",
@@ -42,59 +42,69 @@
42
42
  "./tests/*/index.ts",
43
43
  "./tests/*/index.tsx"
44
44
  ],
45
- "#/*": [
46
- "./src/*",
47
- "./src/*.ts",
48
- "./src/*.tsx",
49
- "./src/*/index.ts",
50
- "./src/*/index.tsx"
51
- ]
45
+ "#/*": {
46
+ "source": [
47
+ "./src/*",
48
+ "./src/*.ts",
49
+ "./src/*.tsx",
50
+ "./src/*/index.ts",
51
+ "./src/*/index.tsx"
52
+ ],
53
+ "types": [
54
+ "./dist/*.d.ts",
55
+ "./dist/*/index.d.ts"
56
+ ],
57
+ "default": [
58
+ "./dist/*.js",
59
+ "./dist/*/index.js"
60
+ ]
61
+ }
52
62
  },
53
63
  "exports": {
54
64
  ".": {
55
65
  "source": "./src/index.ts",
56
- "types": "./dist/index.d.mts",
57
- "import": "./dist/index.mjs"
66
+ "types": "./dist/index.d.ts",
67
+ "import": "./dist/index.js"
58
68
  },
59
69
  "./appearance": {
60
70
  "source": "./src/appearance.ts",
61
- "types": "./dist/appearance.d.mts",
62
- "import": "./dist/appearance.mjs"
71
+ "types": "./dist/appearance.d.ts",
72
+ "import": "./dist/appearance.js"
63
73
  },
64
74
  "./appearance-context": {
65
75
  "source": "./src/appearance-context.ts",
66
- "types": "./dist/appearance-context.d.mts",
67
- "import": "./dist/appearance-context.mjs"
76
+ "types": "./dist/appearance-context.d.ts",
77
+ "import": "./dist/appearance-context.js"
68
78
  },
69
79
  "./appearance-provider": {
70
80
  "source": "./src/appearance-provider.tsx",
71
- "types": "./dist/appearance-provider.d.mts",
72
- "import": "./dist/appearance-provider.mjs"
81
+ "types": "./dist/appearance-provider.d.ts",
82
+ "import": "./dist/appearance-provider.js"
73
83
  },
74
84
  "./appearance-script": {
75
85
  "source": "./src/appearance-script.tsx",
76
- "types": "./dist/appearance-script.d.mts",
77
- "import": "./dist/appearance-script.mjs"
86
+ "types": "./dist/appearance-script.d.ts",
87
+ "import": "./dist/appearance-script.js"
78
88
  },
79
89
  "./color-scheme": {
80
90
  "source": "./src/color-scheme.ts",
81
- "types": "./dist/color-scheme.d.mts",
82
- "import": "./dist/color-scheme.mjs"
91
+ "types": "./dist/color-scheme.d.ts",
92
+ "import": "./dist/color-scheme.js"
83
93
  },
84
94
  "./constants": {
85
95
  "source": "./src/constants.ts",
86
- "types": "./dist/constants.d.mts",
87
- "import": "./dist/constants.mjs"
96
+ "types": "./dist/constants.d.ts",
97
+ "import": "./dist/constants.js"
88
98
  },
89
99
  "./dom": {
90
100
  "source": "./src/dom.ts",
91
- "types": "./dist/dom.d.mts",
92
- "import": "./dist/dom.mjs"
101
+ "types": "./dist/dom.d.ts",
102
+ "import": "./dist/dom.js"
93
103
  },
94
104
  "./use-appearance": {
95
105
  "source": "./src/use-appearance.ts",
96
- "types": "./dist/use-appearance.d.mts",
97
- "import": "./dist/use-appearance.mjs"
106
+ "types": "./dist/use-appearance.d.ts",
107
+ "import": "./dist/use-appearance.js"
98
108
  },
99
109
  "./package.json": "./package.json"
100
110
  },
@@ -109,16 +119,14 @@
109
119
  "@testing-library/jest-dom": "^6.9.1",
110
120
  "@testing-library/react": "^16.3.2",
111
121
  "@testing-library/user-event": "^14.6.1",
112
- "@types/node": "^26.1.0",
113
- "@typescript/native-preview": "7.0.0-dev.20260704.1",
122
+ "@types/node": "^26.1.1",
114
123
  "@vitejs/plugin-react": "^6.0.3",
115
- "@vitest/coverage-v8": "^4.1.9",
124
+ "@vitest/coverage-v8": "^4.1.10",
116
125
  "jsdom": "^29.1.1",
117
- "tsdown": "^0.22.3",
118
- "typescript": "^6.0.3",
119
- "vite": "^8.1.3",
120
- "vitest": "^4.1.9",
121
- "@codefast/typescript-config": "1.0.0-canary.6"
126
+ "typescript": "^7.0.2",
127
+ "vite": "^8.1.5",
128
+ "vitest": "^4.1.10",
129
+ "@codefast/typescript-config": "1.0.0-canary.7"
122
130
  },
123
131
  "peerDependencies": {
124
132
  "@types/react": ">=19.0.0",
@@ -138,8 +146,8 @@
138
146
  "node": ">=24.0.0"
139
147
  },
140
148
  "scripts": {
141
- "build": "tsdown",
142
- "check-types": "tsgo --noEmit",
149
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
150
+ "check-types": "tsc --noEmit",
143
151
  "clean": "rm -rf dist",
144
152
  "test": "vitest run",
145
153
  "test:coverage": "vitest run --coverage",
@@ -147,6 +155,7 @@
147
155
  "test:integration": "vitest run tests/integration",
148
156
  "test:type": "vitest run tests/types",
149
157
  "test:unit": "vitest run tests/unit",
150
- "test:watch": "vitest"
158
+ "test:watch": "vitest",
159
+ "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput"
151
160
  }
152
161
  }
@@ -1,16 +0,0 @@
1
- import { createContext } from "react";
2
- //#region src/appearance-context.ts
3
- /**
4
- * React context for appearance state management.
5
- *
6
- * Provides access to the current appearance, resolved color scheme, setter function, and pending state.
7
- * Use {@link useAppearance} hook instead of consuming this context directly.
8
- *
9
- * @see {@link AppearanceProvider} - Provider component
10
- * @see {@link useAppearance} - Consumer hook
11
- *
12
- * @since 0.5.0-canary.2
13
- */
14
- const AppearanceContext = createContext(null);
15
- //#endregion
16
- export { AppearanceContext };
@@ -1,74 +0,0 @@
1
- import { Appearance } from "./appearance.mjs";
2
- import { JSX, ReactNode } from "react";
3
-
4
- //#region src/appearance-provider.d.ts
5
- /**
6
- * @since 0.5.0-canary.2
7
- */
8
- type AppearanceProviderProps = {
9
- readonly children: ReactNode;
10
- /**
11
- * When true, temporarily suppresses CSS transitions during appearance 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
- * Custom async persistence for appearance changes; replaces the `localStorage` auto-persist.
22
- */
23
- readonly persistAppearance?: (value: Appearance) => Promise<void>;
24
- /**
25
- * Callback invoked when `persistAppearance` rejects.
26
- */
27
- readonly onPersistError?: (error: unknown, attemptedAppearance: Appearance) => void;
28
- /**
29
- * Fallback preference when storage has no valid entry — also what SSR renders.
30
- * Defaults to {@link DEFAULT_APPEARANCE}.
31
- */
32
- readonly appearance?: Appearance;
33
- /**
34
- * `localStorage` key the preference is restored from and persisted under.
35
- * Defaults to {@link STORAGE_KEY}; pair with `<AppearanceScript>` using the **same key**.
36
- *
37
- * The provider reads the stored value in its initial client render (so the first paint already
38
- * matches the preference — no flash, no post-mount settle), auto-persists changes to
39
- * `localStorage` (unless {@link persistAppearance} is also given, which then wins), and syncs
40
- * across tabs via the `storage` event.
41
- *
42
- * @remarks SSR has no `localStorage`, so the server renders the {@link AppearanceProviderProps.appearance}
43
- * prop. For a returning visitor whose stored preference differs, components that render
44
- * preference-dependent markup hydrate-reconcile once; gate them behind a mounted flag to avoid that.
45
- */
46
- readonly storageKey?: string;
47
- };
48
- /**
49
- * Provider component for appearance state management.
50
- *
51
- * **React 19 Features Used:**
52
- * - `useOptimistic` - Immediate UI feedback while persisting the preference
53
- * - `useSyncExternalStore` - SSR-safe subscription to the OS color scheme preference
54
- * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
55
- *
56
- * @example
57
- * ```tsx
58
- * // In your root layout — pair with <AppearanceScript /> using the same storage key
59
- * <AppearanceProvider>{children}</AppearanceProvider>
60
- * ```
61
- *
62
- * @since 0.5.0-canary.2
63
- */
64
- declare function AppearanceProvider({
65
- children,
66
- disableTransition,
67
- nonce,
68
- onPersistError,
69
- persistAppearance,
70
- storageKey,
71
- appearance: initialAppearance
72
- }: AppearanceProviderProps): JSX.Element;
73
- //#endregion
74
- export { AppearanceProvider, AppearanceProviderProps };
@@ -1,180 +0,0 @@
1
- import { AppearanceContext } from "./appearance-context.mjs";
2
- import { appearanceSchema } from "./appearance.mjs";
3
- import { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME, MEDIA, STORAGE_KEY, SYNC_CHANNEL } from "./constants.mjs";
4
- import { getSystemColorScheme } from "./color-scheme.mjs";
5
- import { applyColorScheme, suppressTransitions } from "./dom.mjs";
6
- import { startTransition, useCallback, useEffect, useEffectEvent, useMemo, useOptimistic, useRef, useState, useSyncExternalStore } from "react";
7
- import { jsx } from "react/jsx-runtime";
8
- //#region src/appearance-provider.tsx
9
- /**
10
- * Subscribe to OS color scheme preference changes.
11
- *
12
- * @param callback - Function to call when the OS color scheme changes
13
- * @returns Cleanup function to remove the listener
14
- */
15
- function subscribeToSystemColorScheme(callback) {
16
- const mediaQuery = window.matchMedia(MEDIA);
17
- mediaQuery.addEventListener("change", callback);
18
- return () => {
19
- mediaQuery.removeEventListener("change", callback);
20
- };
21
- }
22
- /** SSR has no `matchMedia`; render the default until the first client snapshot takes over. */
23
- function getServerSnapshot() {
24
- return DEFAULT_COLOR_SCHEME;
25
- }
26
- /**
27
- * Safely create an appearance BroadcastChannel when supported by the environment.
28
- */
29
- function createAppearanceChannel() {
30
- if (typeof BroadcastChannel === "undefined") return null;
31
- try {
32
- return new BroadcastChannel(SYNC_CHANNEL);
33
- } catch {
34
- return null;
35
- }
36
- }
37
- /**
38
- * Read + validate the persisted preference from localStorage. Returns null when unavailable
39
- * (SSR, private mode) or when the stored value is not a recognised appearance.
40
- */
41
- function readAppearanceFromStorage(storageKey) {
42
- if (typeof globalThis.window === "undefined") return null;
43
- try {
44
- const result = appearanceSchema.safeParse(globalThis.window.localStorage.getItem(storageKey));
45
- return result.success ? result.data : null;
46
- } catch {
47
- return null;
48
- }
49
- }
50
- /**
51
- * Provider component for appearance state management.
52
- *
53
- * **React 19 Features Used:**
54
- * - `useOptimistic` - Immediate UI feedback while persisting the preference
55
- * - `useSyncExternalStore` - SSR-safe subscription to the OS color scheme preference
56
- * - `useEffectEvent` - Stable callback for cross-tab sync without effect re-runs
57
- *
58
- * @example
59
- * ```tsx
60
- * // In your root layout — pair with <AppearanceScript /> using the same storage key
61
- * <AppearanceProvider>{children}</AppearanceProvider>
62
- * ```
63
- *
64
- * @since 0.5.0-canary.2
65
- */
66
- function AppearanceProvider({ children, disableTransition = false, nonce, onPersistError, persistAppearance, storageKey = STORAGE_KEY, appearance: initialAppearance = DEFAULT_APPEARANCE }) {
67
- const safeInitialAppearance = appearanceSchema.safeParse(initialAppearance).success ? initialAppearance : DEFAULT_APPEARANCE;
68
- const [appearance, setAppearanceState] = useState(() => readAppearanceFromStorage(storageKey) ?? safeInitialAppearance);
69
- const [optimisticAppearance, setOptimisticAppearance] = useOptimistic(appearance);
70
- const isPending = optimisticAppearance !== appearance;
71
- const committedAppearanceRef = useRef(appearance);
72
- committedAppearanceRef.current = appearance;
73
- const channelRef = useRef(null);
74
- const enableTransitionsRef = useRef(null);
75
- const intentRef = useRef(null);
76
- const persist = useMemo(() => {
77
- if (persistAppearance) return persistAppearance;
78
- return async (value) => {
79
- try {
80
- globalThis.window.localStorage.setItem(storageKey, value);
81
- } catch {}
82
- };
83
- }, [persistAppearance, storageKey]);
84
- const systemColorScheme = useSyncExternalStore(subscribeToSystemColorScheme, getSystemColorScheme, getServerSnapshot);
85
- const colorScheme = useMemo(() => optimisticAppearance === "automatic" ? systemColorScheme : optimisticAppearance, [optimisticAppearance, systemColorScheme]);
86
- useEffect(() => {
87
- applyColorScheme(colorScheme);
88
- const enable = enableTransitionsRef.current;
89
- if (enable) {
90
- enableTransitionsRef.current = null;
91
- enable();
92
- }
93
- }, [colorScheme]);
94
- useEffect(() => {
95
- globalThis.window.document.documentElement.dataset.appearance = optimisticAppearance;
96
- }, [optimisticAppearance]);
97
- const handleCrossTabMessage = useEffectEvent((event) => {
98
- const result = appearanceSchema.safeParse(event.data);
99
- if (!result.success || result.data === appearance) return;
100
- startTransition(() => {
101
- setAppearanceState(result.data);
102
- });
103
- });
104
- const handleStorageEvent = useEffectEvent((event) => {
105
- if (event.key !== storageKey) return;
106
- const result = appearanceSchema.safeParse(event.newValue);
107
- if (!result.success || result.data === appearance) return;
108
- startTransition(() => {
109
- setAppearanceState(result.data);
110
- });
111
- });
112
- useEffect(() => {
113
- const channel = createAppearanceChannel();
114
- if (!channel) return;
115
- channelRef.current = channel;
116
- channel.addEventListener("message", handleCrossTabMessage);
117
- return () => {
118
- channelRef.current = null;
119
- channel.removeEventListener("message", handleCrossTabMessage);
120
- channel.close();
121
- };
122
- }, []);
123
- useEffect(() => {
124
- globalThis.window.addEventListener("storage", handleStorageEvent);
125
- return () => {
126
- globalThis.window.removeEventListener("storage", handleStorageEvent);
127
- };
128
- }, []);
129
- const setAppearance = useCallback(async (value) => {
130
- await Promise.resolve();
131
- if (value === committedAppearanceRef.current) return;
132
- if (disableTransition) enableTransitionsRef.current = suppressTransitions(nonce);
133
- startTransition(async () => {
134
- intentRef.current = value;
135
- setOptimisticAppearance(value);
136
- try {
137
- await persist(value);
138
- if (intentRef.current === value) {
139
- setAppearanceState(value);
140
- channelRef.current?.postMessage(value);
141
- }
142
- } catch (error) {
143
- if (onPersistError) try {
144
- onPersistError(error, value);
145
- } catch (callbackError) {
146
- console.error("Failed to handle appearance persist error:", callbackError);
147
- }
148
- else console.error("Failed to set appearance:", error);
149
- } finally {
150
- const enable = enableTransitionsRef.current;
151
- if (enable) {
152
- enableTransitionsRef.current = null;
153
- enable();
154
- }
155
- }
156
- });
157
- }, [
158
- disableTransition,
159
- nonce,
160
- setOptimisticAppearance,
161
- persist,
162
- onPersistError
163
- ]);
164
- return /* @__PURE__ */ jsx(AppearanceContext, {
165
- value: useMemo(() => ({
166
- isPending,
167
- colorScheme,
168
- setAppearance,
169
- appearance: optimisticAppearance
170
- }), [
171
- optimisticAppearance,
172
- colorScheme,
173
- setAppearance,
174
- isPending
175
- ]),
176
- children
177
- });
178
- }
179
- //#endregion
180
- export { AppearanceProvider };