@codenhub/theme 0.0.3 → 0.1.1

package/dist/index.js

@@ -1,483 +1 @@
-//#region src/constants.ts
-/** Window event name dispatched with `ThemeChangeDetail` after a theme change is applied in browser environments. */
-const THEME_CHANGE_EVENT = "themechange";
-/**
-* Default `localStorage` key used to store the user's explicit theme preference.
-*
-* @internal
-*/
-const DEFAULT_STORAGE_KEY = "app-theme-preference";
-/**
-* Default HTML attribute set on `document.documentElement` to reflect the active theme.
-*
-* @internal
-*/
-const DEFAULT_ATTRIBUTE = "data-theme";
-/**
-* Default CSS class name applied to `document.documentElement` when a dark color scheme theme is active.
-*
-* @internal
-*/
-const DARK_CLASS = "dark";
-/**
-* Media query used to detect if the user's OS preference is set to a dark color scheme.
-*
-* @internal
-*/
-const PREFERS_DARK_QUERY = "(prefers-color-scheme: dark)";
-/**
-* Regular expression used to match and validate whitespace characters in CSS class names.
-*
-* @internal
-*/
-const CLASS_TOKEN_WHITESPACE = /\s/;
-/** Built-in light theme used by default and available for custom theme lists. */
-const LIGHT_THEME = Object.freeze({
-	name: "light",
-	colorScheme: "light"
-});
-/** Built-in dark theme used by default and available for custom theme lists. */
-const DARK_THEME = Object.freeze({
-	name: "dark",
-	colorScheme: "dark"
-});
-/**
-* Default resolved options used to initialize theme management when custom options are not provided.
-*
-* @internal
-*/
-const DEFAULT_OPTIONS = Object.freeze({
-	themes: Object.freeze([LIGHT_THEME, DARK_THEME]),
-	defaultTheme: LIGHT_THEME.name,
-	systemTheme: Object.freeze({
-		light: LIGHT_THEME.name,
-		dark: DARK_THEME.name
-	}),
-	storageKey: DEFAULT_STORAGE_KEY,
-	attribute: DEFAULT_ATTRIBUTE,
-	isTailwindCss: false,
-	shouldApplyClass: true
-});
-//#endregion
-//#region src/class-resolver.ts
-/**
-* Resolves the single DOM class token applied for a theme.
-*
-* @returns The class string, or `null` when class application is disabled.
-* @internal
-*/
-const getThemeClass = (theme, shouldApplyClass) => {
-	if (shouldApplyClass === false) return null;
-	if (typeof shouldApplyClass === "function") {
-		const className = shouldApplyClass(theme);
-		assertClassToken(className, `Theme class resolver returned an invalid class for theme: ${theme.name}.`);
-		return className;
-	}
-	const className = `theme-${theme.name}`;
-	assertClassToken(className, `Theme name cannot be used as a default theme class: ${theme.name}.`);
-	return className;
-};
-/**
-* Asserts that a value is a valid single DOM class token (non-empty string, no whitespace).
-*
-* @internal
-*/
-const assertClassToken = (className, message) => {
-	if (typeof className !== "string" || className.length === 0 || CLASS_TOKEN_WHITESPACE.test(className)) throw new Error(message);
-};
-//#endregion
-//#region src/dom.ts
-/**
-* Applies the active theme configuration, class/attribute updates, and CSS Custom Properties to the DOM.
-*
-* @param resolvedClasses - Pre-computed class strings for all configured themes. Callers must supply
-*   this value; computing it on each activation is the caller's responsibility (see `ThemeImpl`).
-* @param nextClass - Pre-computed class string for the active theme, or `null` when class application is disabled.
-* @internal
-*/
-const applyTheme = (args) => {
-	const { theme, options, activeTokens, resolvedClasses, nextClass } = args;
-	if (typeof document === "undefined") return;
-	const root = document.documentElement;
-	root.setAttribute(options.attribute, theme.name);
-	root.style.colorScheme = theme.colorScheme;
-	for (const configuredClass of resolvedClasses) if (configuredClass !== nextClass) root.classList.remove(configuredClass);
-	if (nextClass !== null) root.classList.add(nextClass);
-	if (options.isTailwindCss) root.classList.toggle(DARK_CLASS, theme.colorScheme === "dark");
-	if (options.tokenSchema) {
-		const schema = options.tokenSchema;
-		const mergedTokens = {
-			...theme.tokens,
-			...activeTokens
-		};
-		for (const key of Object.keys(schema)) {
-			const cssVarName = schema[key];
-			const tokenValue = mergedTokens[key];
-			if (tokenValue !== void 0 && tokenValue !== null) root.style.setProperty(cssVarName, tokenValue);
-			else root.style.removeProperty(cssVarName);
-		}
-	}
-};
-/**
-* Resolves any missing CSS variables from the computed style of the root DOM element.
-*
-* @internal
-*/
-const readComputedTokens = (args) => {
-	const { theme, options, activeTokens } = args;
-	const computedTokens = {};
-	if (typeof window === "undefined" || typeof window.getComputedStyle !== "function" || typeof document === "undefined" || !options.tokenSchema) return computedTokens;
-	const root = document.documentElement;
-	try {
-		const schema = options.tokenSchema;
-		const mergedTokens = {
-			...theme.tokens,
-			...activeTokens
-		};
-		if (!Object.keys(schema).some((key) => mergedTokens[key] === void 0)) return computedTokens;
-		const style = window.getComputedStyle(root);
-		for (const key of Object.keys(schema)) if (mergedTokens[key] === void 0) {
-			const val = style.getPropertyValue(schema[key]).trim();
-			if (val) computedTokens[key] = val;
-		}
-	} catch (error) {
-		console.error("[theme] Failed to read computed token styles:", error);
-	}
-	return computedTokens;
-};
-/**
-* Dispatches a custom `themechange` event on the window.
-*
-* @internal
-*/
-const emitThemeEvent = (detail) => {
-	if (typeof window === "undefined" || typeof window.dispatchEvent !== "function" || typeof window.CustomEvent !== "function") return;
-	window.dispatchEvent(new CustomEvent(THEME_CHANGE_EVENT, { detail }));
-};
-//#endregion
-//#region src/storage.ts
-/**
-* Reads and validates the user's stored theme preference from `localStorage`.
-* Returns the theme name if it exists and matches a configured theme; otherwise `null`.
-*
-* @internal
-*/
-const readStorage = (storageKey, themes) => {
-	if (typeof window === "undefined") return null;
-	try {
-		const storedName = window.localStorage.getItem(storageKey);
-		if (storedName === null) return null;
-		return themes.some((t) => t.name === storedName) ? storedName : null;
-	} catch (error) {
-		console.error("[theme] Failed to read from localStorage:", error);
-		return null;
-	}
-};
-/**
-* Writes the explicit theme preference to `localStorage`.
-*
-* @internal
-*/
-const writeStorage = (storageKey, themeName) => {
-	if (typeof window === "undefined") return;
-	try {
-		window.localStorage.setItem(storageKey, themeName);
-	} catch (error) {
-		console.error("[theme] Failed to write to localStorage:", error);
-	}
-};
-/**
-* Removes the explicit theme preference from `localStorage`.
-*
-* @internal
-*/
-const removeStorage = (storageKey) => {
-	if (typeof window === "undefined") return;
-	try {
-		window.localStorage.removeItem(storageKey);
-	} catch (error) {
-		console.error("[theme] Failed to remove from localStorage:", error);
-	}
-};
-//#endregion
-//#region src/system.ts
-/**
-* Resolves the configured theme that matches the active OS color-scheme preference.
-*
-* @internal
-*/
-const readSystemTheme = (options) => {
-	const { defaultTheme, systemTheme, themes } = options;
-	const getTheme = (name) => {
-		const theme = themes.find((candidate) => candidate.name === name);
-		if (theme === void 0)
- // c8 ignore next
-		throw new Error(`Theme is not configured: ${name}.`);
-		return theme;
-	};
-	if (typeof window === "undefined" || typeof window.matchMedia !== "function") return getTheme(defaultTheme);
-	try {
-		return getTheme(window.matchMedia("(prefers-color-scheme: dark)").matches ? systemTheme.dark : systemTheme.light);
-	} catch {
-		return getTheme(defaultTheme);
-	}
-};
-/**
-* Registers a media query listener for system color-scheme changes and returns a cleanup function.
-*
-* @internal
-*/
-const registerSystemListener = (handler) => {
-	if (typeof window === "undefined" || typeof window.matchMedia !== "function") return () => {};
-	const mql = (() => {
-		try {
-			return window.matchMedia(PREFERS_DARK_QUERY);
-		} catch {
-			return null;
-		}
-	})();
-	if (mql) try {
-		mql.addEventListener("change", handler);
-	} catch {}
-	return () => {
-		if (mql === null) return;
-		try {
-			mql.removeEventListener("change", handler);
-		} catch {}
-	};
-};
-/**
-* Registers a listener for local storage changes across tabs and returns a cleanup function.
-*
-* @internal
-*/
-const registerStorageListener = (handler) => {
-	if (typeof window === "undefined" || typeof window.addEventListener !== "function") return () => {};
-	window.addEventListener("storage", handler);
-	return () => {
-		window.removeEventListener("storage", handler);
-	};
-};
-//#endregion
-//#region src/validation.ts
-/**
-* Validates the resolved theme configuration, throwing descriptive errors on misconfiguration.
-*
-* @internal
-*/
-const assertThemeConfig = (options) => {
-	if (typeof options.attribute !== "string" || options.attribute.trim().length === 0) throw new Error("Theme attribute option must be a non-empty string.");
-	if (/[\s"'/>=]/.test(options.attribute)) throw new Error("Theme attribute option must be a valid HTML attribute name.");
-	if (typeof options.storageKey !== "string" || options.storageKey.trim().length === 0) throw new Error("Theme storageKey option must be a non-empty string.");
-	if (!Array.isArray(options.themes)) throw new Error("Theme options.themes must be an array.");
-	const names = /* @__PURE__ */ new Set();
-	if (options.tokenSchema) {
-		for (const [key, value] of Object.entries(options.tokenSchema)) if (typeof value !== "string" || !value.startsWith("--")) throw new Error(`Token schema key "${key}" must map to a CSS custom property starting with "--". Received: "${value}".`);
-	}
-	for (const theme of options.themes) {
-		if (typeof theme !== "object" || theme === null) throw new Error("Theme definitions must be objects.");
-		if (typeof theme.name !== "string" || theme.name.trim().length === 0) throw new Error("Theme names must be non-empty strings.");
-		if (theme.colorScheme !== "light" && theme.colorScheme !== "dark") throw new Error(`Theme "${theme.name}" has an invalid colorScheme: ${theme.colorScheme}. Must be "light" or "dark".`);
-		if (names.has(theme.name)) throw new Error(`Duplicate theme name: ${theme.name}.`);
-		names.add(theme.name);
-		if (typeof options.shouldApplyClass !== "function") getThemeClass(theme, options.shouldApplyClass);
-		if (theme.tokens) {
-			if (!options.tokenSchema) throw new Error(`Theme "${theme.name}" defines tokens but no tokenSchema is configured.`);
-			for (const tokenKey of Object.keys(theme.tokens)) if (!Object.hasOwn(options.tokenSchema, tokenKey)) throw new Error(`Theme "${theme.name}" defines token "${tokenKey}" which is not present in tokenSchema.`);
-		}
-	}
-	if (!names.has(options.defaultTheme)) throw new Error(`Default theme is not configured: ${options.defaultTheme}.`);
-	if (!names.has(options.systemTheme.light)) throw new Error(`System light theme is not configured: ${options.systemTheme.light}.`);
-	if (!names.has(options.systemTheme.dark)) throw new Error(`System dark theme is not configured: ${options.systemTheme.dark}.`);
-};
-/**
-* Validates runtime token overrides against the configured token schema.
-*
-* @internal
-*/
-const assertRuntimeTokens = (tokens, tokenSchema) => {
-	if (tokens === void 0 || tokens === null) return;
-	if (typeof tokens !== "object" || Array.isArray(tokens)) throw new Error("Runtime tokens must be an object.");
-	if (tokenSchema === void 0) throw new Error("Runtime tokens provided but no tokenSchema is configured.");
-	for (const tokenKey of Object.keys(tokens)) if (!Object.hasOwn(tokenSchema, tokenKey)) throw new Error(`Runtime token override "${tokenKey}" is not present in tokenSchema.`);
-};
-//#endregion
-//#region src/theme.ts
-var ThemeImpl = class {
-	#options;
-	#activeName;
-	#activeTokens = {};
-	#listeners = /* @__PURE__ */ new Set();
-	#systemListenerCleanup = null;
-	#storageListenerCleanup = null;
-	#isInitialized = false;
-	#resolvedClasses = null;
-	#getResolvedClasses() {
-		if (this.#resolvedClasses === null) {
-			this.#resolvedClasses = /* @__PURE__ */ new Map();
-			for (const t of this.#options.themes) this.#resolvedClasses.set(t.name, getThemeClass(t, this.#options.shouldApplyClass));
-		}
-		return this.#resolvedClasses;
-	}
-	#handleSystemChange = (event) => {
-		if (readStorage(this.#options.storageKey, this.#options.themes) !== null) return;
-		const name = event.matches ? this.#options.systemTheme.dark : this.#options.systemTheme.light;
-		if (this.#activeName !== name) this.#activate(name, {
-			source: "system",
-			shouldStore: false
-		});
-	};
-	#handleStorageChange = (event) => {
-		if (event.key !== this.#options.storageKey) return;
-		if (event.newValue === null) {
-			const systemTheme = this.getSystem().name;
-			this.#activate(systemTheme, {
-				source: "clearPreference",
-				shouldStore: false
-			});
-		} else if (this.#options.themes.some((t) => t.name === event.newValue) && this.#activeName !== event.newValue) this.#activate(event.newValue, {
-			source: "set",
-			shouldStore: false
-		});
-	};
-	constructor(options = {}) {
-		this.#options = {
-			...DEFAULT_OPTIONS,
-			...options,
-			systemTheme: {
-				...DEFAULT_OPTIONS.systemTheme,
-				...options.systemTheme
-			}
-		};
-		assertThemeConfig(this.#options);
-		this.#activeName = this.#options.defaultTheme;
-	}
-	init(tokens) {
-		if (this.#isInitialized) return this;
-		this.#systemListenerCleanup = registerSystemListener(this.#handleSystemChange);
-		this.#storageListenerCleanup = registerStorageListener(this.#handleStorageChange);
-		this.#activate(readStorage(this.#options.storageKey, this.#options.themes) ?? this.getSystem().name, {
-			source: "init",
-			shouldStore: false,
-			tokens
-		});
-		this.#isInitialized = true;
-		return this;
-	}
-	get() {
-		const baseTheme = this.#getTheme(this.#activeName);
-		const computedTokens = readComputedTokens({
-			theme: baseTheme,
-			options: this.#options,
-			activeTokens: this.#activeTokens
-		});
-		return {
-			...baseTheme,
-			tokens: {
-				...computedTokens,
-				...baseTheme.tokens,
-				...this.#activeTokens
-			}
-		};
-	}
-	set(name, tokens) {
-		return this.#activate(name, {
-			source: "set",
-			shouldStore: true,
-			tokens
-		});
-	}
-	toggle(tokens) {
-		const nextName = this.#getTheme(this.#activeName).colorScheme === "dark" ? this.#options.systemTheme.light : this.#options.systemTheme.dark;
-		return this.#activate(nextName, {
-			source: "toggle",
-			shouldStore: true,
-			tokens
-		});
-	}
-	clearPreference() {
-		removeStorage(this.#options.storageKey);
-		return this.#activate(this.getSystem().name, {
-			source: "clearPreference",
-			shouldStore: false
-		});
-	}
-	getStored() {
-		return readStorage(this.#options.storageKey, this.#options.themes);
-	}
-	getSystem() {
-		return readSystemTheme({
-			defaultTheme: this.#options.defaultTheme,
-			systemTheme: this.#options.systemTheme,
-			themes: this.#options.themes
-		});
-	}
-	subscribe(listener) {
-		this.#listeners.add(listener);
-		return () => {
-			this.#listeners.delete(listener);
-		};
-	}
-	destroy() {
-		if (this.#systemListenerCleanup) {
-			this.#systemListenerCleanup();
-			this.#systemListenerCleanup = null;
-		}
-		if (this.#storageListenerCleanup) {
-			this.#storageListenerCleanup();
-			this.#storageListenerCleanup = null;
-		}
-		this.#listeners.clear();
-		this.#activeTokens = {};
-		this.#activeName = this.#options.defaultTheme;
-		this.#resolvedClasses = null;
-		this.#isInitialized = false;
-	}
-	#activate(name, options) {
-		assertRuntimeTokens(options.tokens, this.#options.tokenSchema);
-		const theme = this.#getTheme(name);
-		this.#activeName = theme.name;
-		if (options.tokens !== void 0) this.#activeTokens = options.tokens;
-		if (options.shouldStore) writeStorage(this.#options.storageKey, theme.name);
-		const resolved = this.#getResolvedClasses();
-		applyTheme({
-			theme,
-			options: this.#options,
-			activeTokens: this.#activeTokens,
-			resolvedClasses: Array.from(resolved.values()).filter((c) => c !== null),
-			nextClass: resolved.get(theme.name) ?? null
-		});
-		const activeTheme = this.get();
-		this.#emit({
-			name: activeTheme.name,
-			theme: activeTheme,
-			source: options.source
-		});
-		return activeTheme;
-	}
-	#emit(detail) {
-		for (const listener of this.#listeners) try {
-			listener(detail);
-		} catch (error) {
-			console.error("Error in theme change listener:", error);
-		}
-		emitThemeEvent(detail);
-	}
-	#getTheme(name) {
-		const theme = this.#options.themes.find((candidate) => candidate.name === name);
-		if (theme === void 0) throw new Error(`Theme is not configured: ${name}.`);
-		return theme;
-	}
-};
-/**
-* Factory function that creates and returns a `Theme` instance.
-*
-* @param options - Configuration options for theme definitions, persistence keys, DOM attributes, custom class resolvers, and dynamic token schemas.
-* @returns A `Theme` instance.
-* @throws {Error} If configured theme names are empty, duplicated, invalid for CSS class application, or if the default/system themes are not present in the configured list.
-*/
-function createTheme(options = {}) {
-	return new ThemeImpl(options);
-}
-//#endregion
-export { DARK_THEME, LIGHT_THEME, THEME_CHANGE_EVENT, createTheme };
+const e=`themechange`,t=`dark`,n=/\s/,r=Object.freeze({name:`light`,colorScheme:`light`}),i=Object.freeze({name:`dark`,colorScheme:`dark`}),a=Object.freeze({themes:Object.freeze([r,i]),defaultTheme:r.name,systemTheme:Object.freeze({light:r.name,dark:i.name}),storageKey:`app-theme-preference`,attribute:`data-theme`,isTailwindCss:!1,shouldApplyClass:!0}),o=(e,t)=>{if(t===!1)return null;if(typeof t==`function`){let n=t(e);return s(n,`Theme class resolver returned an invalid class for theme: ${e.name}.`),n}let n=`theme-${e.name}`;return s(n,`Theme name cannot be used as a default theme class: ${e.name}.`),n},s=(e,t)=>{if(typeof e!=`string`||e.length===0||n.test(e))throw Error(t)},c=e=>{let{theme:n,options:r,activeTokens:i,resolvedClasses:a,nextClass:o}=e;if(typeof document>`u`)return;let s=document.documentElement;s.setAttribute(r.attribute,n.name),s.style.colorScheme=n.colorScheme;for(let e of a)e!==o&&s.classList.remove(e);if(o!==null&&s.classList.add(o),r.isTailwindCss&&s.classList.toggle(t,n.colorScheme===`dark`),r.tokenSchema){let e=r.tokenSchema,t={...n.tokens,...i};for(let n of Object.keys(e)){let r=e[n],i=t[n];i==null?s.style.removeProperty(r):s.style.setProperty(r,i)}}},l=e=>{let{theme:t,options:n,activeTokens:r,skipComputed:i}=e,a={};if(i||typeof window>`u`||typeof window.getComputedStyle!=`function`||typeof document>`u`||!n.tokenSchema)return a;let o=document.documentElement;try{let e=n.tokenSchema,i={...t.tokens,...r};if(!Object.keys(e).some(e=>i[e]===void 0))return a;let s=window.getComputedStyle(o);if(!s)return a;for(let t of Object.keys(e))if(i[t]===void 0){let n=s.getPropertyValue(e[t]).trim();n&&(a[t]=n)}}catch(e){console.error(`[theme] Failed to read computed token styles:`,e)}return a},u=t=>{typeof window>`u`||typeof window.dispatchEvent!=`function`||typeof window.CustomEvent!=`function`||window.dispatchEvent(new CustomEvent(e,{detail:t}))},d=e=>{let{options:n,resolvedClasses:r}=e;if(typeof document>`u`)return;let i=document.documentElement;i.removeAttribute(n.attribute),i.style.removeProperty(`color-scheme`);for(let e of r)i.classList.remove(e);if(n.isTailwindCss&&i.classList.remove(t),n.tokenSchema)for(let e of Object.values(n.tokenSchema))i.style.removeProperty(e)};function f(e={}){let t={...a,...e,systemTheme:{...a.systemTheme,...e.systemTheme}},n=t.themes||a.themes,r={};for(let e of n){let n=o(e,t.shouldApplyClass),i;if(t.tokenSchema&&e.tokens)for(let[n,r]of Object.entries(t.tokenSchema)){let t=e.tokens[n];t!=null&&(i??={},i[r]=t)}r[e.name]={colorScheme:e.colorScheme,className:n,...i?{vars:i}:{}}}return`!(function(){try{var k=${JSON.stringify(t.storageKey)},a=${JSON.stringify(t.attribute)},d=${JSON.stringify(t.defaultTheme)},sl=${JSON.stringify(t.systemTheme.light)},sd=${JSON.stringify(t.systemTheme.dark)},tm=${JSON.stringify(r)},tw=${JSON.stringify(t.isTailwindCss)},s=localStorage.getItem(k),m=window.matchMedia("(prefers-color-scheme: dark)").matches,n=(s&&tm[s])?s:(m?sd:sl);if(!tm[n])n=d;var t=tm[n],r=document.documentElement;r.setAttribute(a,n);if(t&&t.colorScheme)r.style.colorScheme=t.colorScheme;if(t&&t.className)r.classList.add(t.className);if(tw)r.classList.toggle("dark",t&&t.colorScheme==="dark");if(t&&t.vars)for(var v in t.vars)r.style.setProperty(v,t.vars[v])}catch(e){}})()`}const p=(e,t)=>{if(typeof window>`u`)return null;try{let n=window.localStorage.getItem(e);return n===null?null:t.some(e=>e.name===n)?n:null}catch(e){return console.error(`[theme] Failed to read from localStorage:`,e),null}},m=(e,t)=>{if(!(typeof window>`u`))try{window.localStorage.setItem(e,t)}catch(e){console.error(`[theme] Failed to write to localStorage:`,e)}},h=e=>{if(!(typeof window>`u`))try{window.localStorage.removeItem(e)}catch(e){console.error(`[theme] Failed to remove from localStorage:`,e)}},g=e=>{let{defaultTheme:t,systemTheme:n,themes:r}=e,i=e=>{let t=r.find(t=>t.name===e);if(t===void 0)throw Error(`Theme is not configured: ${e}.`);return t};if(typeof window>`u`||typeof window.matchMedia!=`function`)return i(t);try{return i(window.matchMedia(`(prefers-color-scheme: dark)`).matches?n.dark:n.light)}catch{return i(t)}},_=e=>{if(typeof window>`u`||typeof window.matchMedia!=`function`)return()=>{};let t=(()=>{try{return window.matchMedia(`(prefers-color-scheme: dark)`)}catch{return null}})(),n=!1;if(t)try{typeof t.addEventListener==`function`?t.addEventListener(`change`,e):typeof t.addListener==`function`&&(n=!0,t.addListener(e))}catch{}return()=>{if(t!==null)try{n&&typeof t.removeListener==`function`?t.removeListener(e):typeof t.removeEventListener==`function`&&t.removeEventListener(`change`,e)}catch{}}},v=e=>typeof window>`u`||typeof window.addEventListener!=`function`?()=>{}:(window.addEventListener(`storage`,e),()=>{window.removeEventListener(`storage`,e)}),y=e=>{if(typeof e.attribute!=`string`||e.attribute.trim().length===0)throw Error(`Theme attribute option must be a non-empty string.`);if(/[\s"'/>=]/.test(e.attribute))throw Error(`Theme attribute option must be a valid HTML attribute name.`);if(typeof e.storageKey!=`string`||e.storageKey.trim().length===0)throw Error(`Theme storageKey option must be a non-empty string.`);if(!Array.isArray(e.themes))throw Error(`Theme options.themes must be an array.`);let t=new Set;if(e.tokenSchema){for(let[t,n]of Object.entries(e.tokenSchema))if(typeof n!=`string`||!n.startsWith(`--`))throw Error(`Token schema key "${t}" must map to a CSS custom property starting with "--". Received: "${n}".`)}for(let n of e.themes){if(typeof n!=`object`||!n)throw Error(`Theme definitions must be objects.`);if(typeof n.name!=`string`||n.name.trim().length===0)throw Error(`Theme names must be non-empty strings.`);if(n.colorScheme!==`light`&&n.colorScheme!==`dark`)throw Error(`Theme "${n.name}" has an invalid colorScheme: ${n.colorScheme}. Must be "light" or "dark".`);if(n.pairedTheme!==void 0&&(typeof n.pairedTheme!=`string`||n.pairedTheme.trim().length===0))throw Error(`Theme "${n.name}" pairedTheme must be a non-empty string.`);if(t.has(n.name))throw Error(`Duplicate theme name: ${n.name}.`);if(t.add(n.name),typeof e.shouldApplyClass!=`function`&&o(n,e.shouldApplyClass),n.tokens){if(!e.tokenSchema)throw Error(`Theme "${n.name}" defines tokens but no tokenSchema is configured.`);for(let t of Object.keys(n.tokens))if(!Object.hasOwn(e.tokenSchema,t))throw Error(`Theme "${n.name}" defines token "${t}" which is not present in tokenSchema.`)}}for(let n of e.themes)if(n.pairedTheme!==void 0&&!t.has(n.pairedTheme))throw Error(`Theme "${n.name}" references unconfigured pairedTheme: ${n.pairedTheme}.`);if(!t.has(e.defaultTheme))throw Error(`Default theme is not configured: ${e.defaultTheme}.`);if(!t.has(e.systemTheme.light))throw Error(`System light theme is not configured: ${e.systemTheme.light}.`);if(!t.has(e.systemTheme.dark))throw Error(`System dark theme is not configured: ${e.systemTheme.dark}.`)},b=(e,t)=>{if(e!=null){if(typeof e!=`object`||Array.isArray(e))throw Error(`Runtime tokens must be an object.`);if(t===void 0)throw Error(`Runtime tokens provided but no tokenSchema is configured.`);for(let n of Object.keys(e))if(!Object.hasOwn(t,n))throw Error(`Runtime token override "${n}" is not present in tokenSchema.`)}};var x=class{#e;#t;#n={};#r=new Set;#i=null;#a=null;#o=!1;#s=null;#c=null;#l(){if(this.#s===null){this.#s=new Map;for(let e of this.#e.themes)this.#s.set(e.name,o(e,this.#e.shouldApplyClass))}return this.#s}#u(){if(this.#c===null){let e=this.#l();this.#c=Array.from(e.values()).filter(e=>e!==null)}return this.#c}#d=e=>{if(p(this.#e.storageKey,this.#e.themes)!==null)return;let t=e.matches?this.#e.systemTheme.dark:this.#e.systemTheme.light;this.#t!==t&&this.#p(t,{source:`system`,shouldStore:!1})};#f=e=>{if(e.key===this.#e.storageKey)if(e.newValue===null){let e=this.getSystem().name;this.#p(e,{source:`clearPreference`,shouldStore:!1})}else this.#e.themes.some(t=>t.name===e.newValue)&&this.#t!==e.newValue&&this.#p(e.newValue,{source:`set`,shouldStore:!1})};constructor(e={}){this.#e={...a,...e,systemTheme:{...a.systemTheme,...e.systemTheme}},y(this.#e),this.#t=this.#e.defaultTheme}init(e){return this.#o?this:(this.#i=_(this.#d),this.#a=v(this.#f),this.#p(p(this.#e.storageKey,this.#e.themes)??this.getSystem().name,{source:`init`,shouldStore:!1,tokens:e}),this.#o=!0,this)}get(e){let t=this.#h(this.#t),n=this.#e,r=this.#n,i=e?.skipComputed,a=null;return{...t,get tokens(){return a===null&&(a={...l({theme:t,options:n,activeTokens:r,skipComputed:i}),...t.tokens,...r}),a}}}set(e,t){return this.#p(e,{source:`set`,shouldStore:!0,tokens:t})}toggle(e){let t=this.#h(this.#t),n;return n=t.pairedTheme!==void 0&&this.#e.themes.some(e=>e.name===t.pairedTheme)?t.pairedTheme:t.colorScheme===`dark`?this.#e.systemTheme.light:this.#e.systemTheme.dark,this.#p(n,{source:`toggle`,shouldStore:!0,tokens:e})}clearPreference(){return h(this.#e.storageKey),this.#p(this.getSystem().name,{source:`clearPreference`,shouldStore:!1})}getStored(){return p(this.#e.storageKey,this.#e.themes)}getSystem(){return g({defaultTheme:this.#e.defaultTheme,systemTheme:this.#e.systemTheme,themes:this.#e.themes})}subscribe(e){return this.#r.add(e),()=>{this.#r.delete(e)}}getPrePaintScript(){return f(this.#e)}destroy(e){e?.revertDom&&d({options:this.#e,resolvedClasses:this.#u()}),this.#i&&=(this.#i(),null),this.#a&&=(this.#a(),null),this.#r.clear(),this.#n={},this.#t=this.#e.defaultTheme,this.#s=null,this.#c=null,this.#o=!1}#p(e,t){b(t.tokens,this.#e.tokenSchema);let n=this.#h(e);this.#t=n.name,t.tokens!==void 0&&(this.#n=t.tokens),t.shouldStore&&m(this.#e.storageKey,n.name);let r=this.#l();c({theme:n,options:this.#e,activeTokens:this.#n,resolvedClasses:this.#u(),nextClass:r.get(n.name)??null});let i=this.get();return this.#m({name:i.name,theme:i,source:t.source}),i}#m(e){for(let t of this.#r)try{t(e)}catch(e){console.error(`Error in theme change listener:`,e)}u(e)}#h(e){let t=this.#e.themes.find(t=>t.name===e);if(t===void 0)throw Error(`Theme is not configured: ${e}.`);return t}};function S(e={}){return new x(e)}export{i as DARK_THEME,r as LIGHT_THEME,e as THEME_CHANGE_EVENT,S as createTheme,f as getPrePaintScript};

package/docs/index.md

@@ -0,0 +1,52 @@
+---
+title: Overview
+---
+
+# Manage Browser Themes
+
+`@codenhub/theme` resolves stored and system theme preferences, applies theme
+state to the document root, synchronizes browser tabs, exposes change events,
+and maps typed tokens to CSS custom properties.
+
+It fits browser applications that need one owner for theme preference and DOM
+synchronization while keeping selectors, visual design, and CSS 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");
+```
+
+Call `destroy()` when the manager's owner is removed. The package persists an
+explicit preference and follows system preference when appropriate.
+
+## Requirements
+
+- Browser integration uses `document.documentElement`, `localStorage`,
+  `matchMedia`, `storage` events, and `CustomEvent`.
+- SSR is supported by skipping unavailable browser work and using the configured
+  default theme.
+- Consumers provide CSS selectors, variables, visual tokens, and any pre-paint
+  script needed to prevent a theme flash.
+
+The package cannot produce server HTML attributes or prevent a flash before
+initialization. Applications that need pre-paint consistency must apply matching
+theme logic before rendering.
+
+## Next steps
+
+- [API, persistence, DOM, and SSR behavior](reference.md): Complete exports,
+  configuration, tokens, browser synchronization, validation, pre-paint
+  concerns, and cleanup.

package/docs/reference.md

@@ -0,0 +1,104 @@
+---
+title: Reference
+---
+
+# Theme API, Persistence, DOM, and SSR Behavior
+
+## Create and Initialize
+
+`createTheme<TSchema>(options?): Theme<TSchema>` validates configuration and
+creates a manager. `ThemeOptions` contains:
+
+- `themes`: definitions, defaulting to `LIGHT_THEME` and `DARK_THEME`.
+- `defaultTheme`: pre-init and SSR fallback, default `"light"`.
+- `systemTheme`: configured names for light/dark OS preference.
+- `storageKey`: `localStorage` key, default `"app-theme-preference"`.
+- `attribute`: document-root attribute, default `"data-theme"`.
+- `isTailwindCss`: toggle the root `dark` class, default `false`.
+- `shouldApplyClass`: add `theme-${name}` by default, disable classes, or return
+  one custom class token with a `ThemeClassResolver`.
+- `tokenSchema`: maps typed token names to CSS custom-property names.
+
+`ThemeDefinition` has a unique `name`, `colorScheme` (`light` or `dark`),
+optional static tokens, and optional `pairedTheme` target for `toggle()`.
+`SystemThemeMap` maps OS light and dark preferences.
+
+`init(tokens?)` is idempotent until `destroy()`. It registers media-query and
+cross-tab storage listeners, selects valid stored preference before system
+preference, applies the theme, and emits an `"init"` change.
+
+## Theme Operations
+
+- `get(options?)` returns the active definition. Tokens merge computed CSS values,
+  static theme values, then runtime overrides. Reading computed values can force
+  style calculation; pass `{ skipComputed: true }` to bypass reading computed DOM styles.
+- `set(name, tokens?)` applies and persists a configured theme; unknown names
+  throw.
+- `toggle(tokens?)` switches to `pairedTheme` if defined on the active theme, or
+  otherwise by active `colorScheme` between the names in `systemTheme`, then
+  persists the choice.
+- `clearPreference()` removes storage and applies the current system theme.
+- `getStored()` returns a valid configured stored name or `null`.
+- `getSystem()` returns the mapped system theme, or `defaultTheme` when media
+  queries are unavailable.
+- `getPrePaintScript()` returns a synchronous inline IIFE script string to inject
+  into document `<head>` to prevent flash of unstyled content (FOUC). Supports custom
+  class resolvers and static token custom properties. Also available as standalone export
+  `getPrePaintScript(options?)`.
+
+Runtime token overrides persist across theme changes. Passing a new object,
+including `{}`, replaces them. Tokens require a schema and unknown token keys
+throw.
+
+## DOM, Persistence, and Events
+
+Applying a theme sets the configured root attribute and
+`document.documentElement.style.colorScheme`, updates configured theme classes,
+toggles Tailwind's `dark` class when enabled, and writes mapped token values as
+CSS custom properties. The package supplies no CSS or token values beyond the
+built-in light/dark definitions.
+
+Explicit preferences use `localStorage`. `storage` events synchronize valid
+changes from other tabs. OS preference changes apply only while no valid stored
+preference exists. Storage read/write/remove failures are logged with
+`console.error` and treated as unavailable.
+
+`subscribe(ThemeChangeListener)` returns an unsubscribe function. Subscribers
+receive `ThemeChangeDetail` with `name`, `theme`, and `ThemeChangeSource`:
+`"init"`, `"set"`, `"toggle"`, `"clearPreference"`, or `"system"`. Subscriber
+errors are logged and do not stop later listeners. Browsers also receive a
+window `CustomEvent` named by `THEME_CHANGE_EVENT` (`"themechange"`).
+
+## Validation and Cleanup
+
+Creation throws for invalid attributes/storage keys, malformed or duplicate
+themes, invalid color schemes/classes/token schemas, and missing default/system
+theme names. Applying a custom class resolver can throw if it returns an empty
+or whitespace-containing class. Runtime token calls throw without a matching
+schema.
+
+`destroy(options?)` removes media-query and storage listeners, clears
+in-process subscribers and runtime tokens, and resets internal active state.
+By default, it does not remove persisted preference or revert attributes,
+classes, custom properties, or `colorScheme` already applied to the document;
+pass `{ revertDom: true }` to remove configured DOM attributes, classes, and
+CSS custom properties from `document.documentElement`.
+
+## SSR and Pre-Paint Behavior
+
+Without browser APIs, storage, DOM, events, and listeners are skipped;
+`getSystem()` uses `defaultTheme`. Calls remain usable but cannot produce server
+HTML attributes. To avoid a flash, applications must apply equivalent validated
+storage/system logic in a blocking pre-paint script or render matching server
+markup. Keep that logic aligned with custom names, mappings, storage key,
+attribute, classes, and color scheme. Note that `getPrePaintScript()` serializes
+static tokens defined on configured theme definitions (`ThemeDefinition.tokens`);
+runtime token overrides passed to `init(tokens)` or `set(name, tokens)` are applied
+during client-side execution after hydration.
+
+## Public Exports
+
+The root exports `createTheme`, `getPrePaintScript`, `THEME_CHANGE_EVENT`,
+`LIGHT_THEME`, and `DARK_THEME`, plus `Theme`, `ThemeDefinition`, `SystemThemeMap`,
+`ThemeClassResolver`, `ThemeChangeSource`, `ThemeChangeDetail`,
+`ThemeChangeListener`, and `ThemeOptions` types.