@codefast/theme 0.5.0-canary.5 → 0.5.0-canary.6
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 +45 -0
- package/README.md +86 -270
- package/dist/{appearance-context.d.mts → appearance-context.d.ts} +3 -6
- package/dist/appearance-context.d.ts.map +1 -0
- package/dist/appearance-context.js +17 -0
- package/dist/appearance-context.js.map +1 -0
- package/dist/appearance-provider.d.ts +63 -0
- package/dist/appearance-provider.d.ts.map +1 -0
- package/dist/appearance-provider.js +240 -0
- package/dist/appearance-provider.js.map +1 -0
- package/dist/{appearance-script.d.mts → appearance-script.d.ts} +20 -27
- package/dist/appearance-script.d.ts.map +1 -0
- package/dist/appearance-script.js +51 -0
- package/dist/appearance-script.js.map +1 -0
- package/dist/{appearance.d.mts → appearance.d.ts} +13 -16
- package/dist/appearance.d.ts.map +1 -0
- package/dist/appearance.js +27 -0
- package/dist/appearance.js.map +1 -0
- package/dist/{color-scheme.d.mts → color-scheme.d.ts} +4 -7
- package/dist/color-scheme.d.ts.map +1 -0
- package/dist/color-scheme.js +37 -0
- package/dist/color-scheme.js.map +1 -0
- package/dist/{constants.d.mts → constants.d.ts} +7 -10
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +46 -0
- package/dist/constants.js.map +1 -0
- package/dist/{dom.d.mts → dom.d.ts} +4 -7
- package/dist/dom.d.ts.map +1 -0
- package/dist/dom.js +71 -0
- package/dist/dom.js.map +1 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +24 -0
- package/dist/index.js.map +1 -0
- package/dist/{use-appearance.d.mts → use-appearance.d.ts} +3 -6
- package/dist/use-appearance.d.ts.map +1 -0
- package/dist/use-appearance.js +41 -0
- package/dist/use-appearance.js.map +1 -0
- package/package.json +47 -39
- package/dist/appearance-context.mjs +0 -16
- package/dist/appearance-provider.d.mts +0 -74
- package/dist/appearance-provider.mjs +0 -180
- package/dist/appearance-script.mjs +0 -46
- package/dist/appearance.mjs +0 -25
- package/dist/color-scheme.mjs +0 -32
- package/dist/constants.mjs +0 -42
- package/dist/dom.mjs +0 -52
- package/dist/index.d.mts +0 -7
- package/dist/index.mjs +0 -7
- package/dist/use-appearance.mjs +0 -38
|
@@ -1,6 +1,4 @@
|
|
|
1
|
-
import { ColorScheme } from "
|
|
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
|
-
//#
|
|
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
|
package/dist/dom.js.map
ADDED
|
@@ -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"}
|
package/dist/index.d.ts
ADDED
|
@@ -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 "
|
|
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
|
-
//#
|
|
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": "0.5.0-canary.
|
|
3
|
+
"version": "0.5.0-canary.6",
|
|
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.
|
|
35
|
-
"module": "./dist/index.
|
|
36
|
-
"types": "./dist/index.d.
|
|
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
|
-
"
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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.
|
|
57
|
-
"import": "./dist/index.
|
|
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.
|
|
62
|
-
"import": "./dist/appearance.
|
|
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.
|
|
67
|
-
"import": "./dist/appearance-context.
|
|
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.
|
|
72
|
-
"import": "./dist/appearance-provider.
|
|
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.
|
|
77
|
-
"import": "./dist/appearance-script.
|
|
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.
|
|
82
|
-
"import": "./dist/color-scheme.
|
|
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.
|
|
87
|
-
"import": "./dist/constants.
|
|
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.
|
|
92
|
-
"import": "./dist/dom.
|
|
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.
|
|
97
|
-
"import": "./dist/use-appearance.
|
|
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.
|
|
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.
|
|
124
|
+
"@vitest/coverage-v8": "^4.1.10",
|
|
116
125
|
"jsdom": "^29.1.1",
|
|
117
|
-
"
|
|
118
|
-
"
|
|
119
|
-
"
|
|
120
|
-
"
|
|
121
|
-
"@codefast/typescript-config": "0.5.0-canary.5"
|
|
126
|
+
"typescript": "^7.0.2",
|
|
127
|
+
"vite": "^8.1.5",
|
|
128
|
+
"vitest": "^4.1.10",
|
|
129
|
+
"@codefast/typescript-config": "0.5.0-canary.6"
|
|
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": "
|
|
142
|
-
"check-types": "
|
|
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",
|
|
@@ -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 };
|