@codefast/theme 0.5.0-canary.5 → 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 +4 -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,46 +0,0 @@
1
- import { appearances } from "./appearance.mjs";
2
- import { DEFAULT_APPEARANCE, MEDIA, STORAGE_KEY } from "./constants.mjs";
3
- import { jsx } from "react/jsx-runtime";
4
- //#region src/appearance-script.tsx
5
- function toScriptSafe(value) {
6
- return JSON.stringify(value).replaceAll("<", "\\u003C").replaceAll(">", "\\u003E").replaceAll("/", "\\u002F");
7
- }
8
- const APPEARANCE_REMOVE_ARGS = appearances.map((s) => toScriptSafe(s)).join(",");
9
- const APPEARANCE_VALID_CHECK = appearances.map((s) => `s===${toScriptSafe(s)}`).join("||");
10
- /**
11
- * Inline script that prevents Flash of Unstyled Content (FOUC).
12
- *
13
- * **Why this is needed:**
14
- * React hydration occurs after the browser has already painted the page.
15
- * Without this script, users would briefly see the wrong appearance before
16
- * React takes over and applies the correct one.
17
- *
18
- * **How it works:**
19
- * This script runs synchronously in the `<head>` before first paint:
20
- * 1. Reads the stored preference from `localStorage`, falling back to `appearance`
21
- * 2. Resolves 'automatic' to 'light' or 'dark' using `matchMedia()`
22
- * 3. Removes prior `light` / `dark` / `automatic` classes on `<html>` (SSR may
23
- * have applied the wrong resolved class for `automatic`, e.g. default `dark`)
24
- * 4. Adds the resolved color scheme class and sets `color-scheme` for native controls
25
- * 5. Writes the *preference* to `data-appearance` so preference-aware UI (e.g. a 3-state toggle)
26
- * can render the right state from CSS on first paint, without a hydration flash
27
- *
28
- * @example
29
- * ```tsx
30
- * // In __root.tsx (TanStack Start)
31
- * <head>
32
- * <AppearanceScript />
33
- * </head>
34
- * ```
35
- *
36
- * @since 0.5.0-canary.2
37
- */
38
- function AppearanceScript({ nonce, storageKey = STORAGE_KEY, appearance = DEFAULT_APPEARANCE }) {
39
- return /* @__PURE__ */ jsx("script", {
40
- dangerouslySetInnerHTML: { __html: `(function(){try{var sk=${toScriptSafe(storageKey)},fb=${toScriptSafe(appearance)},s=localStorage.getItem(sk),appearance=(${APPEARANCE_VALID_CHECK})?s:fb,colorScheme=appearance;"automatic"===appearance&&(colorScheme=window.matchMedia(${toScriptSafe(MEDIA)}).matches?"dark":"light"),document.documentElement.classList.remove(${APPEARANCE_REMOVE_ARGS}),document.documentElement.classList.add(colorScheme),document.documentElement.style.colorScheme=colorScheme,document.documentElement.dataset.appearance=appearance}catch(e){}})()` },
41
- suppressHydrationWarning: true,
42
- ...nonce === void 0 ? {} : { nonce }
43
- });
44
- }
45
- //#endregion
46
- export { AppearanceScript };
@@ -1,25 +0,0 @@
1
- import { z } from "zod";
2
- //#region src/appearance.ts
3
- /**
4
- * Zod schema for appearance validation.
5
- *
6
- * Acts as the single source of truth for all appearance-related types.
7
- * Valid values: 'light', 'dark', 'automatic'.
8
- *
9
- * @since 0.5.0-canary.2
10
- */
11
- const appearanceSchema = z.enum([
12
- "light",
13
- "dark",
14
- "automatic"
15
- ]);
16
- /**
17
- * Array of all available appearance options: `['light', 'dark', 'automatic']`.
18
- *
19
- * Useful for rendering appearance selectors in UI components.
20
- *
21
- * @since 0.5.0-canary.2
22
- */
23
- const appearances = appearanceSchema.options;
24
- //#endregion
25
- export { appearanceSchema, appearances };
@@ -1,32 +0,0 @@
1
- import { DEFAULT_COLOR_SCHEME } from "./constants.mjs";
2
- //#region src/color-scheme.ts
3
- /**
4
- * Detect the OS color scheme preference.
5
- *
6
- * Uses `matchMedia()` to query the `prefers-color-scheme` media feature.
7
- * Returns {@link DEFAULT_COLOR_SCHEME} during SSR since `window` is unavailable.
8
- *
9
- * @returns 'light' or 'dark' based on OS preference
10
- *
11
- * @since 0.3.16-canary.0
12
- */
13
- function getSystemColorScheme() {
14
- if (typeof globalThis.window === "undefined") return DEFAULT_COLOR_SCHEME;
15
- return globalThis.window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
16
- }
17
- /**
18
- * Resolve an appearance preference to the color scheme to apply.
19
- *
20
- * - 'light' → 'light'
21
- * - 'dark' → 'dark'
22
- * - 'automatic' → on the client, result of {@link getSystemColorScheme};
23
- * on the server, {@link DEFAULT_COLOR_SCHEME}
24
- *
25
- * @since 0.3.16-canary.0
26
- */
27
- function resolveColorScheme(appearance) {
28
- if (appearance !== "automatic") return appearance;
29
- return getSystemColorScheme();
30
- }
31
- //#endregion
32
- export { getSystemColorScheme, resolveColorScheme };
@@ -1,42 +0,0 @@
1
- //#region src/constants.ts
2
- /**
3
- * Default appearance preference when no stored value exists.
4
- *
5
- * Set to 'automatic' to respect OS preference by default.
6
- *
7
- * @since 0.5.0-canary.2
8
- */
9
- const DEFAULT_APPEARANCE = "automatic";
10
- /**
11
- * Fallback color scheme when the system color scheme cannot be detected.
12
- *
13
- * Applies wherever `window.matchMedia()` is unavailable, e.g. during server render.
14
- *
15
- * @since 0.5.0-canary.2
16
- */
17
- const DEFAULT_COLOR_SCHEME = "dark";
18
- /**
19
- * Default `localStorage` key for the appearance preference, shared by
20
- * `AppearanceScript` and `AppearanceProvider`.
21
- *
22
- * Re-exported only from `@codefast/theme/constants` so custom integrations can match it exactly.
23
- *
24
- * @since 0.3.16-canary.0
25
- */
26
- const STORAGE_KEY = "ui-appearance";
27
- /**
28
- * CSS media query for detecting dark mode preference.
29
- * @internal
30
- *
31
- * @since 0.3.16-canary.0
32
- */
33
- const MEDIA = "(prefers-color-scheme: dark)";
34
- /**
35
- * BroadcastChannel name for cross-tab appearance synchronization.
36
- * @internal
37
- *
38
- * @since 0.3.16-canary.0
39
- */
40
- const SYNC_CHANNEL = "appearance-sync";
41
- //#endregion
42
- export { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME, MEDIA, STORAGE_KEY, SYNC_CHANNEL };
package/dist/dom.mjs DELETED
@@ -1,52 +0,0 @@
1
- //#region src/dom.ts
2
- /**
3
- * Apply a color scheme to the DOM by updating the `<html>` element.
4
- *
5
- * Updates both:
6
- * - CSS class (for Tailwind's `dark:` variants)
7
- * - `color-scheme` style (for native form controls and scrollbars)
8
- *
9
- * @since 0.3.16-canary.0
10
- */
11
- function applyColorScheme(colorScheme) {
12
- const root = window.document.documentElement;
13
- root.classList.remove("light", "dark", "automatic");
14
- root.classList.add(colorScheme);
15
- root.style.colorScheme = colorScheme;
16
- }
17
- /**
18
- * Temporarily suppress all CSS transitions during appearance changes.
19
- *
20
- * Prevents jarring color animations when switching between light/dark appearances.
21
- * Respects user's `prefers-reduced-motion` preference (does nothing if enabled).
22
- *
23
- * @param nonce - Optional CSP nonce for the injected style element
24
- * @returns Cleanup function to re-enable transitions. Call after the color scheme is applied.
25
- *
26
- * @example
27
- * ```tsx
28
- * const enableTransitions = suppressTransitions();
29
- * applyColorScheme('dark');
30
- * enableTransitions(); // Re-enables CSS transitions
31
- * ```
32
- *
33
- * @since 0.3.16-canary.0
34
- */
35
- function suppressTransitions(nonce) {
36
- if (typeof globalThis.window === "undefined") return () => {};
37
- if (globalThis.window.matchMedia("(prefers-reduced-motion: reduce)").matches) return () => {};
38
- const css = document.createElement("style");
39
- if (nonce) css.setAttribute("nonce", nonce);
40
- css.append(document.createTextNode(`*,*::before,*::after{transition:none!important}`));
41
- document.head.append(css);
42
- return () => {
43
- window.getComputedStyle(document.body);
44
- requestAnimationFrame(() => {
45
- requestAnimationFrame(() => {
46
- if (css.parentNode) css.remove();
47
- });
48
- });
49
- };
50
- }
51
- //#endregion
52
- export { applyColorScheme, suppressTransitions };
package/dist/index.d.mts DELETED
@@ -1,7 +0,0 @@
1
- import { Appearance, AppearanceContextValue, ColorScheme, appearanceSchema, appearances } from "./appearance.mjs";
2
- import { AppearanceProvider, AppearanceProviderProps } from "./appearance-provider.mjs";
3
- import { AppearanceScript, AppearanceScriptProps } from "./appearance-script.mjs";
4
- import { resolveColorScheme } from "./color-scheme.mjs";
5
- import { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME } from "./constants.mjs";
6
- import { useAppearance } from "./use-appearance.mjs";
7
- export { type Appearance, type AppearanceContextValue, AppearanceProvider, type AppearanceProviderProps, AppearanceScript, type AppearanceScriptProps, type ColorScheme, DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME, appearanceSchema, appearances, resolveColorScheme, useAppearance };
package/dist/index.mjs DELETED
@@ -1,7 +0,0 @@
1
- import { appearanceSchema, appearances } from "./appearance.mjs";
2
- import { DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME } from "./constants.mjs";
3
- import { resolveColorScheme } from "./color-scheme.mjs";
4
- import { AppearanceProvider } from "./appearance-provider.mjs";
5
- import { AppearanceScript } from "./appearance-script.mjs";
6
- import { useAppearance } from "./use-appearance.mjs";
7
- export { AppearanceProvider, AppearanceScript, DEFAULT_APPEARANCE, DEFAULT_COLOR_SCHEME, appearanceSchema, appearances, resolveColorScheme, useAppearance };
@@ -1,38 +0,0 @@
1
- import { AppearanceContext } from "./appearance-context.mjs";
2
- import { use } from "react";
3
- //#region src/use-appearance.ts
4
- /**
5
- * Hook to access appearance context.
6
- *
7
- * Uses React 19's `use()` API for context consumption, enabling:
8
- * - Conditional context reading
9
- * - Better Suspense boundary integration
10
- *
11
- * @returns Appearance context with `appearance`, `colorScheme`, `setAppearance`, and `isPending`
12
- * @throws Error if called outside of AppearanceProvider
13
- *
14
- * @example
15
- * ```tsx
16
- * function AppearanceToggle() {
17
- * const { appearance, setAppearance, isPending } = useAppearance();
18
- *
19
- * return (
20
- * <button
21
- * onClick={() => setAppearance(appearance === 'dark' ? 'light' : 'dark')}
22
- * disabled={isPending}
23
- * >
24
- * {appearance}
25
- * </button>
26
- * );
27
- * }
28
- * ```
29
- *
30
- * @since 0.5.0-canary.2
31
- */
32
- function useAppearance() {
33
- const value = use(AppearanceContext);
34
- if (!value) throw new Error("useAppearance must be used within an AppearanceProvider");
35
- return value;
36
- }
37
- //#endregion
38
- export { useAppearance };