@codenhub/theme 0.1.0 → 0.1.2

package/docs/index.md

@@ -0,0 +1,60 @@
+---
+title: Overview
+---
+
+# Manage Browser Themes
+
+`@codenhub/theme` owns one thing for a browser application: deciding which theme is active, keeping it in sync with `localStorage` and the OS `prefers-color-scheme` setting, and reflecting it onto the DOM as an attribute, a class, and CSS custom properties. It fits applications that want one place to own that decision instead of scattering `matchMedia` listeners and `localStorage` reads across the codebase, while keeping selectors, visual design, and CSS entirely in application code.
+
+## Setup
+
+### Installation
+
+```sh
+pnpm add @codenhub/theme
+```
+
+### Quick start
+
+```ts
+import { createTheme } from "@codenhub/theme";
+
+const theme = createTheme().init();
+theme.set("dark");
+```
+
+`createTheme()` with no arguments configures the built-in `light` and `dark` themes. `init()` resolves the theme to apply — a stored preference if one is valid, otherwise the OS preference — and applies it to `document.documentElement`. Call `destroy()` when the manager's owner is torn down, such as in a framework component's cleanup hook; it stops listening but leaves the DOM and stored preference as they were unless told otherwise (see [Tokens, persistence, and cross-tab sync](tokens-and-persistence.md)).
+
+### Configuration
+
+Most applications configure at least `themes` and `tokenSchema` up front:
+
+```ts
+import { createTheme } from "@codenhub/theme";
+
+const theme = createTheme({
+  themes: [
+    { name: "light", colorScheme: "light", tokens: { primary: "#171717" } },
+    { name: "dark", colorScheme: "dark", tokens: { primary: "#f9fafb" } },
+  ],
+  tokenSchema: { primary: "--color-primary" },
+  storageKey: "app-theme-preference",
+  isTailwindCss: true,
+}).init();
+```
+
+`themes` replaces the built-in list entirely — include `light` and `dark` (or whatever names `defaultTheme` and `systemTheme` point at) when defining custom themes. `tokenSchema` maps the typed token names used in `ThemeDefinition.tokens` and `get()` to the CSS custom property each one writes to `document.documentElement`. See [Tokens, persistence, and cross-tab sync](tokens-and-persistence.md) for how token values are resolved and stored, and [SSR, pre-paint, and Tailwind](ssr-and-pre-paint.md) for flash-of-unstyled-content prevention and OS-preference-only applications like `isTailwindCss`.
+
+Construction validates every option and throws on invalid configuration: empty or duplicate theme names, a `defaultTheme` or `systemTheme` name that is not in `themes`, an invalid `colorScheme`, or a `shouldApplyClass` resolver that would produce an empty or whitespace-containing class.
+
+## Requirements
+
+- Browser integration uses `document.documentElement`, `localStorage`, `matchMedia`, `storage` events, and `CustomEvent`. Every one of these is read defensively: an unavailable or throwing API is treated as absent rather than crashing the caller.
+- SSR is supported by skipping unavailable browser work and using the configured `defaultTheme`. The package cannot produce server HTML attributes or prevent a flash on its own — see [SSR, pre-paint, and Tailwind](ssr-and-pre-paint.md).
+- Consumers provide CSS selectors, variables, and visual tokens. The package only ever writes an attribute, optional classes, and CSS custom properties — it ships no CSS or token values beyond the built-in `light`/`dark` definitions' names.
+
+## Next steps
+
+- [Tokens, persistence, and cross-tab sync](tokens-and-persistence.md): How `get()` resolves token values, how preferences persist to `localStorage` and sync across tabs, and how to read or clear the stored preference.
+- [SSR, pre-paint, and Tailwind](ssr-and-pre-paint.md): Preventing a flash of unstyled content before hydration, server-rendering considerations, and toggling Tailwind's `dark` class.
+- [API reference](reference/index.md): Every exported function, type, and interface member with its full signature.

package/docs/reference/index.md

@@ -0,0 +1,381 @@
+---
+title: /
+group: Reference
+---
+
+<!-- Generated by `pnpm generate` from packages/theme/src. Do not edit. -->
+
+# @codenhub/theme
+
+## Functions
+
+### createTheme
+
+```ts
+export declare function createTheme<TSchema extends Record<string, string> = Record<string, string>>(options?: ThemeOptions<TSchema>): Theme<TSchema>;
+```
+
+Factory function that creates and returns a `Theme` instance.
+
+**Parameters**
+
+- `options` — Configuration options for theme definitions, persistence keys, DOM attributes, custom class resolvers, and dynamic token schemas.
+
+**Returns** — A `Theme` instance.
+
+**Throws** — If configured theme names are empty, duplicated, invalid for CSS class application, have an invalid `colorScheme`, or if the default/system themes are not present in the configured list.
+
+### getPrePaintScript
+
+```ts
+export declare function getPrePaintScript<TSchema extends Record<string, string> = Record<string, string>>(options?: ThemeOptions<TSchema>): string;
+```
+
+Generates a synchronous inline IIFE script string to inject into document `<head>`. Prevents Flash of Unstyled Content (FOUC) by applying storage or system theme before render.
+
+**Parameters**
+
+- `options` — Configuration options used to determine storage keys, attributes, default/system themes, custom class resolvers, and token schemas.
+
+**Returns** — Minified JavaScript script string.
+
+## Interfaces
+
+### SystemThemeMap
+
+```ts
+export interface SystemThemeMap
+```
+
+Mapping from OS color-scheme preferences to configured theme names.
+
+#### dark
+
+```ts
+dark: string;
+```
+
+Configured theme name used when the OS preference is dark.
+
+#### light
+
+```ts
+light: string;
+```
+
+Configured theme name used when the OS preference is light or no dark preference is detected.
+
+### Theme
+
+```ts
+export interface Theme<TSchema extends Record<string, string> = Record<string, string>>
+```
+
+Core theme preference handler. Manages initialization, switching themes, persistence to localStorage, synchronizing with the OS prefers-color-scheme preference, dynamic token mapping to CSS Custom Properties, and dispatching change events.
+
+#### clearPreference
+
+```ts
+clearPreference(): ThemeDefinition<TSchema>;
+```
+
+Removes the explicit user theme preference from storage and resets the theme to match the OS system preference.
+
+#### destroy
+
+```ts
+destroy(options?: { revertDom?: boolean; }): void;
+```
+
+Cleans up the theme instance by removing all in-process change listeners, the system preference media query listener, and the cross-tab storage listener. Resets active tokens and the active theme name to the configured `defaultTheme` so the instance can be safely re-initialized with `init()`.
+
+**Parameters**
+
+- `options` — Optional cleanup options. Set `revertDom: true` to remove configured DOM attributes, classes, and CSS custom properties applied to `document.documentElement`.
+
+#### get
+
+```ts
+get(options?: { skipComputed?: boolean; }): ThemeDefinition<TSchema>;
+```
+
+Retrieves the active theme configuration including static and computed tokens.
+
+Token values are merged in this priority order (last wins):
+
+1. CSS computed style — values read from `window.getComputedStyle` for tokens not defined in JS (unless `options.skipComputed` is true).
+2. Theme static tokens — values defined in `ThemeDefinition.tokens` for the active theme.
+3. Runtime overrides — values passed to `init()`, `set()`, `toggle()`, or other methods.
+
+**Parameters**
+
+- `options` — Optional getter options. Set `skipComputed: true` to avoid reading computed styles from the DOM via `window.getComputedStyle`, preventing potential layout reflows.
+
+#### getPrePaintScript
+
+```ts
+getPrePaintScript(): string;
+```
+
+Generates a synchronous inline IIFE script string to inject into document `<head>`. Prevents Flash of Unstyled Content (FOUC) by applying storage or system theme before render.
+
+#### getStored
+
+```ts
+getStored(): string | null;
+```
+
+Retrieves the currently stored theme preference name from `localStorage`.
+
+#### getSystem
+
+```ts
+getSystem(): ThemeDefinition<TSchema>;
+```
+
+Resolves the configured theme that matches the active OS color-scheme preference.
+
+#### init
+
+```ts
+init(tokens?: Partial<Record<keyof TSchema, string>>): this;
+```
+
+Initializes the theme manager. Resolves the active theme (using the stored preference if valid, falling back to the current OS color-scheme preference), applies classes/attributes to the DOM, and registers the media query listener for automatic system preference updates.
+
+**Parameters**
+
+- `tokens` — Optional runtime override token values to merge and apply.
+
+#### set
+
+```ts
+set(name: string, tokens?: Partial<Record<keyof TSchema, string>>): ThemeDefinition<TSchema>;
+```
+
+Activates a configured theme by name and updates the stored preference in `localStorage`.
+
+**Parameters**
+
+- `name` — The name of the configured theme to activate.
+- `tokens` — Optional runtime override token values to apply. Active overrides persist across subsequent theme changes unless cleared (by passing new overrides or an empty object).
+
+#### subscribe
+
+```ts
+subscribe(listener: ThemeChangeListener<TSchema>): () => void;
+```
+
+Registers a callback listener to receive notifications when the theme or its tokens change.
+
+**Parameters**
+
+- `listener` — Callback function invoked on theme changes.
+
+#### toggle
+
+```ts
+toggle(tokens?: Partial<Record<keyof TSchema, string>>): ThemeDefinition<TSchema>;
+```
+
+Switches away from the active theme and persists the change. If the active theme configures a `pairedTheme`, that theme is activated. Otherwise the next theme is selected from `systemTheme.light` or `systemTheme.dark` based on the active theme's `colorScheme`, not by cycling the active theme name.
+
+**Parameters**
+
+- `tokens` — Optional runtime override token values to apply. Active overrides persist across subsequent theme changes unless cleared (by passing new overrides or an empty object).
+
+### ThemeChangeDetail
+
+```ts
+export interface ThemeChangeDetail<TSchema extends Record<string, string> = Record<string, string>>
+```
+
+Payload passed to subscribers and the browser `themechange` event after a theme change.
+
+#### name
+
+```ts
+name: string;
+```
+
+Active theme name after the change.
+
+#### source
+
+```ts
+source: ThemeChangeSource;
+```
+
+Operation or browser signal that caused the change notification.
+
+#### theme
+
+```ts
+theme: ThemeDefinition<TSchema>;
+```
+
+Active theme definition after the change.
+
+### ThemeDefinition
+
+```ts
+export interface ThemeDefinition<TSchema extends Record<string, string> = Record<string, string>>
+```
+
+Theme option stored, applied to the configured DOM attribute, and mapped to the browser color scheme.
+
+#### colorScheme
+
+```ts
+colorScheme: "light" | "dark";
+```
+
+Browser color scheme applied to `document.documentElement.style.colorScheme`.
+
+#### name
+
+```ts
+name: string;
+```
+
+Unique configured theme name used for storage, DOM attributes, and generated default classes.
+
+#### pairedTheme
+
+```ts
+pairedTheme?: string;
+```
+
+Optional theme name activated when calling `toggle()` from this theme.
+
+#### tokens
+
+```ts
+tokens?: Partial<Record<keyof TSchema, string>>;
+```
+
+Optional theme-specific static token values.
+
+### ThemeOptions
+
+```ts
+export interface ThemeOptions<TSchema extends Record<string, string> = Record<string, string>>
+```
+
+Configuration for theme definitions, persistence, DOM application, and system preference mapping.
+
+#### attribute
+
+```ts
+attribute?: string;
+```
+
+Attribute set on `document.documentElement` with the active theme name.
+
+#### defaultTheme
+
+```ts
+defaultTheme?: string;
+```
+
+Configured theme name used before initialization and when browser APIs are unavailable.
+
+#### isTailwindCss
+
+```ts
+isTailwindCss?: boolean;
+```
+
+Whether to toggle Tailwind CSS's `dark` class for themes with `colorScheme: "dark"`.
+
+#### shouldApplyClass
+
+```ts
+shouldApplyClass?: boolean | ThemeClassResolver<TSchema>;
+```
+
+Whether and how to apply a theme-specific class to `document.documentElement`.
+
+#### storageKey
+
+```ts
+storageKey?: string;
+```
+
+`localStorage` key used for explicit user preferences.
+
+#### systemTheme
+
+```ts
+systemTheme?: SystemThemeMap;
+```
+
+Configured theme names selected for OS light and dark color-scheme preferences.
+
+#### themes
+
+```ts
+themes?: readonly ThemeDefinition<TSchema>[];
+```
+
+Available themes. Names must be unique, non-empty, and valid default class tokens when `shouldApplyClass` is `true`.
+
+#### tokenSchema
+
+```ts
+tokenSchema?: TSchema;
+```
+
+Schema mapping theme token names to their corresponding CSS Custom Property names.
+
+## Type aliases
+
+### ThemeChangeListener
+
+```ts
+export type ThemeChangeListener<TSchema extends Record<string, string> = Record<string, string>> = (detail: ThemeChangeDetail<TSchema>) => void;
+```
+
+In-process callback registered with `Theme.subscribe()` for applied theme changes.
+
+### ThemeChangeSource
+
+```ts
+export type ThemeChangeSource = "init" | "set" | "toggle" | "clearPreference" | "system";
+```
+
+Reason a theme change notification was emitted.
+
+### ThemeClassResolver
+
+```ts
+export type ThemeClassResolver<TSchema extends Record<string, string> = Record<string, string>> = (theme: ThemeDefinition<TSchema>) => string;
+```
+
+Resolves the single DOM class token applied for a theme when custom class application is enabled.
+
+## Variables
+
+### DARK_THEME
+
+```ts
+export declare const DARK_THEME: ThemeDefinition;
+```
+
+Built-in dark theme used by default and available for custom theme lists.
+
+### LIGHT_THEME
+
+```ts
+export declare const LIGHT_THEME: ThemeDefinition;
+```
+
+Built-in light theme used by default and available for custom theme lists.
+
+### THEME_CHANGE_EVENT
+
+```ts
+export declare const THEME_CHANGE_EVENT = "themechange";
+```
+
+Window event name dispatched with `ThemeChangeDetail` after a theme change is applied in browser environments.

package/docs/ssr-and-pre-paint.md

@@ -0,0 +1,46 @@
+---
+title: SSR, Pre-Paint, and Tailwind
+---
+
+# SSR, Pre-Paint, and Tailwind
+
+## Preventing a flash of unstyled content
+
+A client-side `init()` call runs after the page has already painted once, which is visible as a flash from the default theme to the resolved one. `getPrePaintScript()` — available as a method on an existing manager, or as the standalone `getPrePaintScript(options)` export when no manager exists yet — returns a synchronous, minified inline IIFE string that duplicates the same stored-preference-then-system-preference resolution, and applies the configured attribute, classes, and any static tokens before the browser paints:
+
+```ts
+import { getPrePaintScript } from "@codenhub/theme";
+
+const script = getPrePaintScript({ storageKey: "app-theme-preference" });
+```
+
+Inject the returned string into a blocking `<script>` in the document `<head>`, before any stylesheet or content that depends on the theme:
+
+```html
+<head>
+  <script>
+    /* inline the string returned by getPrePaintScript() here */
+  </script>
+</head>
+```
+
+Pass the same `themes`, `tokenSchema`, `defaultTheme`, `systemTheme`, `storageKey`, `attribute`, `shouldApplyClass`, and `isTailwindCss` options used to construct the manager, so the pre-paint script and the later `init()` call resolve to the same theme. `getPrePaintScript()` only serializes **static** tokens from each theme's `ThemeDefinition.tokens` — and only when `tokenSchema` is passed to it — runtime overrides passed to `init(tokens)` are applied after hydration, during client-side execution, and cannot be part of a script that runs before any application code.
+
+## Server-side rendering
+
+Without browser APIs, `Theme` methods skip storage reads/writes, DOM updates, and listener registration; `getSystem()` falls back to `defaultTheme`. Every method call remains safe to make during SSR — nothing throws for a missing `window`, `document`, or `localStorage` — but the package cannot produce server-rendered HTML attributes on its own. To avoid a flash on a server-rendered page, either:
+
+- Render the server markup with the same attribute/class the pre-paint script would apply (requiring the server to read the same cookie or header a real theme service would use), or
+- Rely on the pre-paint script above to correct the DOM before first paint, accepting that server-rendered markup itself does not carry theme state.
+
+Keep any server-side resolution logic — stored names, system mapping, storage key, attribute, classes, color scheme — aligned with the options passed to `createTheme()` and `getPrePaintScript()`; a mismatch reintroduces the flash it exists to prevent.
+
+## Tailwind's `dark` class
+
+Set `isTailwindCss: true` to toggle Tailwind CSS's `dark` class on `document.documentElement` alongside the configured attribute, for every theme whose `colorScheme` is `"dark"`. This is independent of `shouldApplyClass` (below) — a Tailwind app commonly wants both the `dark` class for Tailwind's `dark:` variant and, when `shouldApplyClass` is left at its default, a `theme-${name}` class for custom per-theme CSS.
+
+## Classes and cleanup
+
+`shouldApplyClass` controls whether and how a class is applied to `document.documentElement` alongside the attribute: `true` (the default) applies `theme-${name}`, `false` applies no class, and a `ThemeClassResolver` function receives the active `ThemeDefinition` and returns one custom class token — throwing if it returns an empty or whitespace-containing string.
+
+`destroy(options?)` removes the media-query and storage listeners and clears in-process subscribers and runtime tokens, leaving the instance safe to `init()` again. By default it does **not** touch the DOM or stored preference. Pass `{ revertDom: true }` to also remove the configured attribute, classes, and CSS custom properties from `document.documentElement` — useful when unmounting a scoped theme manager that should leave no trace, such as in a component test or a preview pane.

package/docs/tokens-and-persistence.md

@@ -0,0 +1,51 @@
+---
+title: Tokens, Persistence, and Cross-Tab Sync
+---
+
+# Tokens, Persistence, and Cross-Tab Sync
+
+## Token resolution
+
+`tokenSchema` maps typed token names to the CSS custom property each one writes, such as `{ primary: "--color-primary" }`. Once configured, `get()` returns the active `ThemeDefinition` with every schema key resolved from three sources, in this priority order (last wins):
+
+1. **Computed style** — for a token not defined in JS, the value is read from `window.getComputedStyle(document.documentElement)` in browser environments.
+2. **Theme static tokens** — values set on the active theme's own `ThemeDefinition.tokens`.
+3. **Runtime overrides** — values passed to `init()`, `set()`, or `toggle()`.
+
+```ts
+const theme = createTheme({
+  themes: [{ name: "brand", colorScheme: "light", tokens: { accent: "#ff6600" } }],
+  tokenSchema: { accent: "--color-accent" },
+}).init();
+
+theme.set("brand", { accent: "#00c853" }); // runtime override wins over the static "#ff6600"
+theme.get().tokens?.accent; // "#00c853"
+```
+
+Reading computed values can force a synchronous layout reflow. Pass `{ skipComputed: true }` to `get()` to skip that source and avoid the reflow when only the JS-known values are needed.
+
+Runtime overrides persist across subsequent theme changes until explicitly replaced — pass a new object, including `{}`, to `init()`, `set()`, or `toggle()` to clear or replace them. Passing a token key that is not in `tokenSchema` throws.
+
+## Persistence
+
+An explicit preference set through `set()` or `toggle()` is written to `localStorage` under `storageKey` (default `"app-theme-preference"`). `getStored()` returns that value when it names a currently configured theme, or `null` when it is unset, invalid, or storage is unavailable (for example during SSR). `clearPreference()` removes the stored value and re-applies whichever theme `getSystem()` currently resolves to.
+
+Storage reads, writes, and removals that throw — a full quota, a disabled storage API, a private-browsing restriction — are logged with `console.error` and treated the same as unavailable storage; they never throw out of `Theme` methods.
+
+## Cross-tab sync
+
+Every tab running `createTheme().init()` against the same `storageKey` stays in sync: a `storage` event fires in every other tab when one tab writes a new preference, and each one applies the change if it names a valid configured theme. A tab with its own runtime token overrides keeps them — only the active theme name changes from cross-tab sync, not tokens passed in-process.
+
+The OS `prefers-color-scheme` media query applies automatically only while no valid stored preference exists. Once a tab (or a previous session) has stored an explicit preference, later system-preference changes are ignored until `clearPreference()` runs.
+
+## Reacting to changes
+
+`subscribe(listener)` registers a callback invoked after every applied change — from `init()`, `set()`, `toggle()`, `clearPreference()`, or an accepted `system` or cross-tab update — and returns an unsubscribe function:
+
+```ts
+const unsubscribe = theme.subscribe(({ name, source }) => {
+  console.log(`theme is now "${name}" (${source})`);
+});
+```
+
+A subscriber that throws is logged and does not stop other subscribers from running. Browsers also receive a `window` `CustomEvent` named by the exported `THEME_CHANGE_EVENT` constant (`"themechange"`) carrying the same detail, for code that prefers DOM events over `subscribe()`.