@codefast/theme 0.10.0 → 0.12.0
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 +17 -0
- package/README.md +5 -5
- package/dist/appearance-provider.js +10 -12
- package/dist/appearance-script.js +3 -3
- package/dist/appearance.d.ts +8 -14
- package/dist/appearance.js +10 -21
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/package.json +2 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,22 @@
|
|
|
1
1
|
# @codefast/theme
|
|
2
2
|
|
|
3
|
+
## 0.12.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#1188](https://github.com/codefastlabs/codefast/pull/1188) Every `@codefast/*` package now requires Node.js 24.15 or later and drops Node 22. The packages ship as one set, so they
|
|
8
|
+
share one floor instead of each sitting on its own 22.x release. `@codefast/typescript-config` removes the `node22.json`
|
|
9
|
+
and `node22-dom.json` overlays; extend a preset alone. `codefast audit engines` reports a published package whose floor
|
|
10
|
+
differs from the highest one any published package declares.
|
|
11
|
+
|
|
12
|
+
## 0.11.0
|
|
13
|
+
|
|
14
|
+
### Minor Changes
|
|
15
|
+
|
|
16
|
+
- [#1143](https://github.com/codefastlabs/codefast/pull/1143) `@codefast/theme` no longer depends on zod, so `AppearanceProvider`, `AppearanceScript` and `appearances` stop pulling
|
|
17
|
+
it into the bundle. `appearanceSchema` is removed: check a value with the new `isAppearance` type guard, or build a
|
|
18
|
+
schema from `appearances` in your own validator (`z.enum(appearances)` with zod).
|
|
19
|
+
|
|
3
20
|
## 0.10.0
|
|
4
21
|
|
|
5
22
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -34,10 +34,10 @@ pnpm add @codefast/theme
|
|
|
34
34
|
# yarn add @codefast/theme
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
`react` and `react-dom` 19 or later are peer dependencies, and `@codefast/theme` requires Node.js
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
37
|
+
`react` and `react-dom` 19 or later are peer dependencies, and `@codefast/theme` requires Node.js 24.15 or later, Chrome
|
|
38
|
+
and Edge 136, Firefox 136, or Safari 18.4 or later in the browser ([support policy](../../SUPPORT.md#browsers)), and
|
|
39
|
+
TypeScript 7 or later for its types. The package is published on 0.x and versioned on its own track: breaking changes
|
|
40
|
+
ship as minor versions, so pin the minor version when you need stability.
|
|
41
41
|
|
|
42
42
|
## Quick start
|
|
43
43
|
|
|
@@ -220,7 +220,7 @@ Everything below ships from the root entry unless a subpath is noted.
|
|
|
220
220
|
| `AppearanceScript` | component | Inline head script that applies the stored preference before first paint. |
|
|
221
221
|
| `resolveColorScheme(appearance)` | function | Resolves an `Appearance` to a `ColorScheme`; `automatic` uses `matchMedia` on the client. |
|
|
222
222
|
| `appearances` | constant | `["light", "dark", "automatic"]` — handy for rendering selectors. |
|
|
223
|
-
| `
|
|
223
|
+
| `isAppearance(value)` | function | Type guard for an `Appearance`; for a schema, pass `appearances` to your validator. |
|
|
224
224
|
| `DEFAULT_APPEARANCE` | constant | `"automatic"` — the fallback preference. |
|
|
225
225
|
| `DEFAULT_COLOR_SCHEME` | constant | `"dark"` — the fallback when `matchMedia` is unavailable (SSR). |
|
|
226
226
|
| `Appearance`, `ColorScheme` | types | The preference and resolved-value unions. |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
2
|
import { startTransition, useCallback, useEffect, useEffectEvent, useLayoutEffect, useMemo, useOptimistic, useRef, useState, useSyncExternalStore, } from "react";
|
|
3
|
-
import {
|
|
3
|
+
import { isAppearance } from "#appearance";
|
|
4
4
|
import { AppearanceContext } from "#appearance-context";
|
|
5
5
|
import { getSystemColorScheme } from "#color-scheme";
|
|
6
6
|
import { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME, MEDIA, STORAGE_KEY, SYNC_CHANNEL } from "#constants";
|
|
@@ -51,8 +51,8 @@ function readAppearanceFromStorage(storageKey) {
|
|
|
51
51
|
return null;
|
|
52
52
|
}
|
|
53
53
|
try {
|
|
54
|
-
const
|
|
55
|
-
return
|
|
54
|
+
const stored = globalThis.window.localStorage.getItem(storageKey);
|
|
55
|
+
return isAppearance(stored) ? stored : null;
|
|
56
56
|
}
|
|
57
57
|
catch {
|
|
58
58
|
return null;
|
|
@@ -77,9 +77,7 @@ function readAppearanceFromStorage(storageKey) {
|
|
|
77
77
|
*/
|
|
78
78
|
export function AppearanceProvider({ children, disableTransition = false, nonce, onPersistError, persistAppearance, storageKey = STORAGE_KEY, appearance: initialAppearance = DEFAULT_APPEARANCE, }) {
|
|
79
79
|
// Runtime guard against invalid values bypassing TypeScript (e.g. raw API strings)
|
|
80
|
-
const safeInitialAppearance =
|
|
81
|
-
? initialAppearance
|
|
82
|
-
: DEFAULT_APPEARANCE;
|
|
80
|
+
const safeInitialAppearance = isAppearance(initialAppearance) ? initialAppearance : DEFAULT_APPEARANCE;
|
|
83
81
|
// Actual persisted appearance. Read localStorage in the initializer so the first client render
|
|
84
82
|
// already matches what AppearanceScript applied pre-paint (no flash, no post-mount settle). SSR has
|
|
85
83
|
// no localStorage, so the server renders the prop.
|
|
@@ -138,12 +136,12 @@ export function AppearanceProvider({ children, disableTransition = false, nonce,
|
|
|
138
136
|
}, [optimisticAppearance]);
|
|
139
137
|
// Validate cross-tab messages before applying to prevent injection from extensions/scripts
|
|
140
138
|
const handleCrossTabMessage = useEffectEvent((event) => {
|
|
141
|
-
const
|
|
142
|
-
if (!
|
|
139
|
+
const next = event.data;
|
|
140
|
+
if (!isAppearance(next) || next === appearance) {
|
|
143
141
|
return;
|
|
144
142
|
}
|
|
145
143
|
startTransition(() => {
|
|
146
|
-
setAppearanceState(
|
|
144
|
+
setAppearanceState(next);
|
|
147
145
|
});
|
|
148
146
|
});
|
|
149
147
|
// Cross-tab sync fallback: the `storage` event fires in OTHER tabs when this key changes.
|
|
@@ -151,12 +149,12 @@ export function AppearanceProvider({ children, disableTransition = false, nonce,
|
|
|
151
149
|
if (event.key !== storageKey) {
|
|
152
150
|
return;
|
|
153
151
|
}
|
|
154
|
-
const
|
|
155
|
-
if (!
|
|
152
|
+
const next = event.newValue;
|
|
153
|
+
if (!isAppearance(next) || next === appearance) {
|
|
156
154
|
return;
|
|
157
155
|
}
|
|
158
156
|
startTransition(() => {
|
|
159
|
-
setAppearanceState(
|
|
157
|
+
setAppearanceState(next);
|
|
160
158
|
});
|
|
161
159
|
});
|
|
162
160
|
// Keep the channel in a ref so setAppearance can broadcast without opening a new channel each time
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
|
-
import { appearances,
|
|
2
|
+
import { appearances, isAppearance } from "#appearance";
|
|
3
3
|
import { DEFAULT_APPEARANCE, MEDIA, STORAGE_KEY } from "#constants";
|
|
4
4
|
/* JSON.stringify does not escape </script>, so we replace the three characters that
|
|
5
5
|
* can form a closing tag: < > /. Unicode escapes are valid JS and safe in HTML. */
|
|
6
6
|
function toScriptSafe(value) {
|
|
7
7
|
return JSON.stringify(value).replaceAll("<", "\\u003C").replaceAll(">", "\\u003E").replaceAll("/", "\\u002F");
|
|
8
8
|
}
|
|
9
|
-
/* Derived once from
|
|
9
|
+
/* Derived once from `appearances`, so the inline script accepts exactly the values the provider does. */
|
|
10
10
|
const APPEARANCE_REMOVE_ARGS = appearances.map((s) => toScriptSafe(s)).join(",");
|
|
11
11
|
const APPEARANCE_VALID_CHECK = appearances.map((s) => `s===${toScriptSafe(s)}`).join("||");
|
|
12
12
|
// ── Component ────────────────────────────────────────────────────────────────────────────────────────────────────────
|
|
@@ -40,7 +40,7 @@ const APPEARANCE_VALID_CHECK = appearances.map((s) => `s===${toScriptSafe(s)}`).
|
|
|
40
40
|
*/
|
|
41
41
|
export function AppearanceScript({ nonce, storageKey = STORAGE_KEY, appearance = DEFAULT_APPEARANCE, }) {
|
|
42
42
|
// Guard against invalid values bypassing TypeScript so the fallback matches AppearanceProvider.
|
|
43
|
-
const safeAppearance =
|
|
43
|
+
const safeAppearance = isAppearance(appearance) ? appearance : DEFAULT_APPEARANCE;
|
|
44
44
|
// toScriptSafe = JSON.stringify + escape <>/ so </script> cannot break out of the tag.
|
|
45
45
|
// The script reads localStorage before first paint so the stored preference applies
|
|
46
46
|
// without FOUC; an absent or invalid entry falls back to fb.
|
package/dist/appearance.d.ts
CHANGED
|
@@ -1,17 +1,11 @@
|
|
|
1
|
-
import * as z from "zod";
|
|
2
1
|
/**
|
|
3
|
-
*
|
|
2
|
+
* The appearance values, in display order: `['light', 'dark', 'automatic']`.
|
|
4
3
|
*
|
|
5
|
-
*
|
|
6
|
-
* Valid values: 'light', 'dark', 'automatic'.
|
|
4
|
+
* The single source of truth for every appearance type and check. Useful for rendering appearance selectors.
|
|
7
5
|
*
|
|
8
6
|
* @since 0.5.0-canary.2
|
|
9
7
|
*/
|
|
10
|
-
export declare const
|
|
11
|
-
light: "light";
|
|
12
|
-
dark: "dark";
|
|
13
|
-
automatic: "automatic";
|
|
14
|
-
}>;
|
|
8
|
+
export declare const appearances: readonly ["light", "dark", "automatic"];
|
|
15
9
|
/**
|
|
16
10
|
* User's appearance preference.
|
|
17
11
|
*
|
|
@@ -21,7 +15,7 @@ export declare const appearanceSchema: z.ZodEnum<{
|
|
|
21
15
|
*
|
|
22
16
|
* @since 0.5.0-canary.2
|
|
23
17
|
*/
|
|
24
|
-
export type Appearance =
|
|
18
|
+
export type Appearance = (typeof appearances)[number];
|
|
25
19
|
/**
|
|
26
20
|
* Color scheme actually applied to the UI after resolving 'automatic'.
|
|
27
21
|
*
|
|
@@ -31,13 +25,13 @@ export type Appearance = z.infer<typeof appearanceSchema>;
|
|
|
31
25
|
*/
|
|
32
26
|
export type ColorScheme = Exclude<Appearance, "automatic">;
|
|
33
27
|
/**
|
|
34
|
-
*
|
|
28
|
+
* Reports whether a value is one of the {@link appearances}.
|
|
35
29
|
*
|
|
36
|
-
*
|
|
30
|
+
* Guards values that bypass TypeScript, such as stored strings, cross-tab messages and raw API data.
|
|
37
31
|
*
|
|
38
|
-
* @since 0.
|
|
32
|
+
* @since 0.11.0
|
|
39
33
|
*/
|
|
40
|
-
export declare
|
|
34
|
+
export declare function isAppearance(value: unknown): value is Appearance;
|
|
41
35
|
/**
|
|
42
36
|
* Shape of the context value provided by AppearanceProvider.
|
|
43
37
|
*
|
package/dist/appearance.js
CHANGED
|
@@ -1,30 +1,19 @@
|
|
|
1
|
-
|
|
2
|
-
/* -----------------------------------------------------------------------------
|
|
3
|
-
* Schema & Types
|
|
4
|
-
*
|
|
5
|
-
* Vocabulary follows Apple's Human Interface Guidelines: "appearance" is the
|
|
6
|
-
* user's preference (Light / Dark / Auto), "color scheme" is the resolved
|
|
7
|
-
* light-or-dark value actually applied (matching CSS `color-scheme` and
|
|
8
|
-
* `prefers-color-scheme`).
|
|
9
|
-
* -------------------------------------------------------------------------- */
|
|
1
|
+
// ── Values & Types ───────────────────────────────────────────────────────────────────────────────────────────────────
|
|
10
2
|
/**
|
|
11
|
-
*
|
|
3
|
+
* The appearance values, in display order: `['light', 'dark', 'automatic']`.
|
|
12
4
|
*
|
|
13
|
-
*
|
|
14
|
-
* Valid values: 'light', 'dark', 'automatic'.
|
|
5
|
+
* The single source of truth for every appearance type and check. Useful for rendering appearance selectors.
|
|
15
6
|
*
|
|
16
7
|
* @since 0.5.0-canary.2
|
|
17
8
|
*/
|
|
18
|
-
export const
|
|
19
|
-
"light",
|
|
20
|
-
"dark",
|
|
21
|
-
"automatic",
|
|
22
|
-
]);
|
|
9
|
+
export const appearances = ["light", "dark", "automatic"];
|
|
23
10
|
/**
|
|
24
|
-
*
|
|
11
|
+
* Reports whether a value is one of the {@link appearances}.
|
|
25
12
|
*
|
|
26
|
-
*
|
|
13
|
+
* Guards values that bypass TypeScript, such as stored strings, cross-tab messages and raw API data.
|
|
27
14
|
*
|
|
28
|
-
* @since 0.
|
|
15
|
+
* @since 0.11.0
|
|
29
16
|
*/
|
|
30
|
-
export
|
|
17
|
+
export function isAppearance(value) {
|
|
18
|
+
return appearances.some((item) => item === value);
|
|
19
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
* - **`@codefast/theme/appearance-context`**: `AppearanceContext` for rare custom wiring.
|
|
13
13
|
*/
|
|
14
14
|
export type { Appearance, AppearanceContextValue, ColorScheme } from "#appearance";
|
|
15
|
-
export { appearances,
|
|
15
|
+
export { appearances, isAppearance } from "#appearance";
|
|
16
16
|
export { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME } from "#constants";
|
|
17
17
|
export { AppearanceProvider } from "#appearance-provider";
|
|
18
18
|
export type { AppearanceProviderProps } from "#appearance-provider";
|
package/dist/index.js
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
* - **`@codefast/theme/color-scheme` / `@codefast/theme/dom`**: `getSystemColorScheme`, `applyColorScheme`, `suppressTransitions`.
|
|
12
12
|
* - **`@codefast/theme/appearance-context`**: `AppearanceContext` for rare custom wiring.
|
|
13
13
|
*/
|
|
14
|
-
export { appearances,
|
|
14
|
+
export { appearances, isAppearance } from "#appearance";
|
|
15
15
|
// Constants
|
|
16
16
|
export { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME } from "#constants";
|
|
17
17
|
// Provider & Hook (use `@codefast/theme/appearance-context` for `AppearanceContext`)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codefast/theme",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
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",
|
|
@@ -81,9 +81,6 @@
|
|
|
81
81
|
"publishConfig": {
|
|
82
82
|
"access": "public"
|
|
83
83
|
},
|
|
84
|
-
"dependencies": {
|
|
85
|
-
"zod": "^4.6.7"
|
|
86
|
-
},
|
|
87
84
|
"peerDependencies": {
|
|
88
85
|
"@types/react": ">=19.0.0",
|
|
89
86
|
"@types/react-dom": ">=19.0.0",
|
|
@@ -99,6 +96,6 @@
|
|
|
99
96
|
}
|
|
100
97
|
},
|
|
101
98
|
"engines": {
|
|
102
|
-
"node": ">=
|
|
99
|
+
"node": ">=24.15.0"
|
|
103
100
|
}
|
|
104
101
|
}
|