@shadow-js/ui 0.0.0-stage → 1.0.1

package/dist/dev/registry/utils/utils.js

@@ -0,0 +1,26 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+// registry/utils/utils.ts
+/**
+* Joins class names (strings, arrays, `{ name: condition }` objects) and resolves Tailwind
+* conflicts, so the last utility wins: `cn("px-2", props.class)` lets the caller override `px-2`.
+*
+* @param inputs - Any mix of class values; falsy values are skipped.
+* @returns One class string with conflicting Tailwind utilities removed.
+* @example
+* ```ts
+* import { cn } from "@/lib/utils";
+*
+* const active = true;
+* export const classes = cn("px-2 py-1", active && "bg-primary", "px-4");
+* // "py-1 bg-primary px-4"
+* ```
+* @since 1.0.0
+* @see {@link ClassValue}
+*/
+function cn(...inputs) {
+	return twMerge(clsx(...inputs));
+}
+export { cn };
+
+//# sourceMappingURL=utils.js.map

package/dist/dev/registry/utils/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":[],"sources":["../../../../registry/utils/utils.ts"],"sourcesContent":["import { clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * Anything a ShadowJS `class` attribute accepts: strings, numbers, nested (readonly) arrays and\n * `{ name: condition }` objects. Falsy values are skipped.\n * @since 1.0.0\n */\nexport type ClassValue =\n  | string\n  | number\n  | bigint\n  | boolean\n  | null\n  | undefined\n  | readonly ClassValue[]\n  | { readonly [name: string]: unknown };\n\n/**\n * Joins class names (strings, arrays, `{ name: condition }` objects) and resolves Tailwind\n * conflicts, so the last utility wins: `cn(\"px-2\", props.class)` lets the caller override `px-2`.\n *\n * @param inputs - Any mix of class values; falsy values are skipped.\n * @returns One class string with conflicting Tailwind utilities removed.\n * @example\n * ```ts\n * import { cn } from \"@/lib/utils\";\n *\n * const active = true;\n * export const classes = cn(\"px-2 py-1\", active && \"bg-primary\", \"px-4\");\n * // \"py-1 bg-primary px-4\"\n * ```\n * @since 1.0.0\n * @see {@link ClassValue}\n */\nexport function cn(...inputs: ClassValue[]): string {\n  return twMerge(clsx(...(inputs as Parameters<typeof clsx>)));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,GAAG,GAAG,QAA8B;CAClD,OAAO,QAAQ,KAAK,GAAI,MAAkC,CAAC;AAC7D"}

package/dist/dev/theme/theme-logic.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Pure theme logic, shared by the provider and the no-flash script so both agree on what
+ * "system", "light" and "dark" mean. Nothing here touches `window` unless it is handed an object.
+ * @packageDocumentation
+ */
+/**
+ * The theme a user picks: `"light"`, `"dark"`, or `"system"` to follow the operating system.
+ * @since 1.0.0
+ */
+export type Theme = "light" | "dark" | "system";
+/**
+ * The theme that is actually shown: `"light"` or `"dark"`.
+ * @since 1.0.0
+ */
+export type ResolvedTheme = "light" | "dark";
+/**
+ * Where the resolved theme is written on the root element. `"class"` (the default) sets a `light`
+ * or `dark` class, which the generated stylesheet matches for its dark styles (the `dark` variant of
+ * Tailwind is `.dark`). A `data-*` name such as `"data-theme"` sets that attribute to `"light"` or
+ * `"dark"` instead; the stylesheet then has to match that attribute as well.
+ * @since 1.0.0
+ */
+export type ThemeAttribute = "class" | `data-${string}`;
+/**
+ * Options shared by `ThemeProvider` and `themeScript`. Pass the same values to both, or the page can
+ * show one theme before the provider switches to another.
+ * @since 1.0.0
+ */
+export interface ThemeOptions {
+  /**
+   * `localStorage` key that persists the choice. The stored value is `"light"`, `"dark"` or
+   * `"system"`; a missing or invalid value falls back to `defaultTheme`.
+   * @default "shadow-ui-theme"
+   */
+  readonly storageKey?: string | undefined;
+  /**
+   * Theme used before the user chooses one, and when the stored value is missing or invalid.
+   * @default "system"
+   */
+  readonly defaultTheme?: Theme | undefined;
+  /**
+   * Where the resolved theme is written: `"class"` for a `light` or `dark` class on `<html>`, or a
+   * `data-*` attribute name such as `"data-theme"` (see {@link ThemeAttribute}).
+   * @default "class"
+   */
+  readonly attribute?: ThemeAttribute | undefined;
+  /**
+   * Follow `prefers-color-scheme` while the theme is `"system"`. When `false`, `"system"` shows light.
+   * @default true
+   */
+  readonly enableSystem?: boolean | undefined;
+}
+/**
+ * The `localStorage` key that holds the theme choice when `storageKey` is not given.
+ * @example
+ * import { DEFAULT_STORAGE_KEY } from "@shadow-js/ui";
+ *
+ * window.localStorage.getItem(DEFAULT_STORAGE_KEY);
+ * @since 1.0.0
+ */
+export declare const DEFAULT_STORAGE_KEY = "shadow-ui-theme";
+/**
+ * Narrows an unknown value to a {@link Theme}. Use it on anything read from storage or from an event
+ * before trusting it.
+ *
+ * @param value Anything, such as a value read from storage.
+ * @returns `true` for `"light"`, `"dark"` and `"system"`, and `false` for everything else.
+ * @example
+ * import { DEFAULT_STORAGE_KEY, isTheme } from "@shadow-js/ui";
+ *
+ * isTheme(window.localStorage.getItem(DEFAULT_STORAGE_KEY)); // false when nothing is stored
+ * @since 1.0.0
+ */
+export declare function isTheme(value: unknown): value is Theme;
+/**
+ * Turns a theme choice into the theme to show. Only `"system"` depends on the operating system.
+ *
+ * @param theme The user's choice.
+ * @param systemPrefersDark Whether the operating system prefers a dark scheme.
+ * @param enableSystem When `false`, `"system"` resolves to light. Default `true`.
+ * @returns `"light"` or `"dark"`.
+ * @example
+ * import { resolveTheme } from "@shadow-js/ui";
+ *
+ * resolveTheme("system", true); // "dark"
+ * @since 1.0.0
+ */
+export declare function resolveTheme(theme: Theme, systemPrefersDark: boolean, enableSystem?: boolean): ResolvedTheme;
+/**
+ * Writes the resolved theme to the root element: sets the `light` or `dark` class (removing the
+ * other) or the `data-*` attribute, and sets `color-scheme` so form controls and scrollbars follow.
+ *
+ * @param root The element to write to, usually `document.documentElement`.
+ * @param resolved The theme to show.
+ * @param attribute Where to write it: `"class"` (the default) or a `data-*` attribute name.
+ * @example
+ * import { applyTheme } from "@shadow-js/ui";
+ *
+ * applyTheme(document.documentElement, "dark");
+ * @since 1.0.0
+ */
+export declare function applyTheme(root: HTMLElement, resolved: ResolvedTheme, attribute?: ThemeAttribute): void;
+/**
+ * Reads the stored theme. A missing or invalid value gives `undefined`. A storage the browser
+ * blocks (private windows, disabled site data) or has run out of room for also gives `undefined`:
+ * those raise a `SecurityError`, `NotAllowedError` or `QuotaExceededError` `DOMException`.
+ *
+ * @param storage The storage to read, usually `window.localStorage`.
+ * @param key The storage key, such as {@link DEFAULT_STORAGE_KEY}.
+ * @returns The stored theme, or `undefined` when it is missing, invalid or unavailable.
+ * @throws The original error when it is not one of the storage errors above, because that is a bug.
+ * @example
+ * import { DEFAULT_STORAGE_KEY, readStoredTheme } from "@shadow-js/ui";
+ *
+ * readStoredTheme(window.localStorage, DEFAULT_STORAGE_KEY);
+ * @since 1.0.0
+ */
+export declare function readStoredTheme(storage: Storage, key: string): Theme | undefined;
+/**
+ * Stores the theme under the key. A storage that is blocked or full does not throw: the function
+ * returns `false` instead.
+ *
+ * @param storage The storage to write, usually `window.localStorage`.
+ * @param key The storage key, such as {@link DEFAULT_STORAGE_KEY}.
+ * @param theme The theme to store.
+ * @returns `true` when the value was written, `false` when the storage refused it.
+ * @throws The original error when it is not one of the storage errors listed in {@link readStoredTheme}.
+ * @example
+ * import { DEFAULT_STORAGE_KEY, writeStoredTheme } from "@shadow-js/ui";
+ *
+ * writeStoredTheme(window.localStorage, DEFAULT_STORAGE_KEY, "dark");
+ * @since 1.0.0
+ */
+export declare function writeStoredTheme(storage: Storage, key: string, theme: Theme): boolean;
+/**
+ * The inline script that applies the stored theme before the first paint, so a dark-mode user does
+ * not see a flash of the light theme. Put the returned text in a `<script>` in the document
+ * `<head>`: a `<script>` in `index.html`, or the `document.head` option of Dusk's `createHandler`.
+ * An inline script in the head runs before the body is rendered. Pass the same options to
+ * `ThemeProvider`.
+ *
+ * The script is plain ES5 with no dependencies. It reads the stored theme, falls back to
+ * `defaultTheme` when the value is missing or invalid or when storage is blocked, and writes the same
+ * class or attribute and `color-scheme` as {@link applyTheme}. The function returns text only, so you
+ * place the tag yourself. {@link themeScriptTag} returns the same script in a tag with a CSP `nonce`.
+ *
+ * @param options Must match the `ThemeProvider` options.
+ * @returns JavaScript source text, without `<script>` tags.
+ * @example
+ * import { themeScript } from "@shadow-js/ui";
+ *
+ * const html = `<script>${themeScript({ defaultTheme: "dark" })}<\/script>`;
+ * @see {@link themeScriptTag}
+ * @since 1.0.0
+ */
+export declare function themeScript(options?: ThemeOptions): string;
+/**
+ * {@link themeScript} wrapped in a `<script>` element, as an HTML string, for a server that builds the
+ * document. Pass the page's CSP nonce so the inline script is allowed by a policy that uses nonces. In
+ * Dusk, the nonce of each response is `event.nonce`, available in the `document.head` function.
+ * Only base64 characters (`A-Z`, `a-z`, `0-9`, `+`, `/`, `=`, `_`, `-`) are kept from the nonce.
+ *
+ * @param options The theme options plus the CSP `nonce` of the page. Without a nonce the tag has no
+ *   `nonce` attribute.
+ * @returns A `<script>` element as HTML text.
+ * @example
+ * import { createHandler, type DuskRuntimeManifest } from "@shadow-js/dusk/server";
+ * import { pages } from "@shadow-js/dusk/features/pages";
+ * import { themeScriptTag } from "@shadow-js/ui";
+ *
+ * declare const manifest: DuskRuntimeManifest;
+ *
+ * export const handler = createHandler({
+ *   features: [pages()],
+ *   manifest,
+ *   security: { csp: {} },
+ *   document: { head: (event) => themeScriptTag({ nonce: event.nonce }) },
+ * });
+ * @see {@link themeScript}
+ * @since 1.0.0
+ */
+export declare function themeScriptTag(options?: ThemeOptions & {
+  readonly nonce?: string | undefined;
+}): string;
+//# sourceMappingURL=theme-logic.d.ts.map

package/dist/dev/theme/theme-logic.js

@@ -0,0 +1,183 @@
+// src/theme/theme-logic.ts
+/**
+* The `localStorage` key that holds the theme choice when `storageKey` is not given.
+* @example
+* import { DEFAULT_STORAGE_KEY } from "@shadow-js/ui";
+*
+* window.localStorage.getItem(DEFAULT_STORAGE_KEY);
+* @since 1.0.0
+*/
+const DEFAULT_STORAGE_KEY = "shadow-ui-theme";
+/**
+* Narrows an unknown value to a {@link Theme}. Use it on anything read from storage or from an event
+* before trusting it.
+*
+* @param value Anything, such as a value read from storage.
+* @returns `true` for `"light"`, `"dark"` and `"system"`, and `false` for everything else.
+* @example
+* import { DEFAULT_STORAGE_KEY, isTheme } from "@shadow-js/ui";
+*
+* isTheme(window.localStorage.getItem(DEFAULT_STORAGE_KEY)); // false when nothing is stored
+* @since 1.0.0
+*/
+function isTheme(value) {
+	return value === "light" || value === "dark" || value === "system";
+}
+/**
+* Turns a theme choice into the theme to show. Only `"system"` depends on the operating system.
+*
+* @param theme The user's choice.
+* @param systemPrefersDark Whether the operating system prefers a dark scheme.
+* @param enableSystem When `false`, `"system"` resolves to light. Default `true`.
+* @returns `"light"` or `"dark"`.
+* @example
+* import { resolveTheme } from "@shadow-js/ui";
+*
+* resolveTheme("system", true); // "dark"
+* @since 1.0.0
+*/
+function resolveTheme(theme, systemPrefersDark, enableSystem = true) {
+	if (theme === "system") return enableSystem && systemPrefersDark ? "dark" : "light";
+	return theme;
+}
+/**
+* Writes the resolved theme to the root element: sets the `light` or `dark` class (removing the
+* other) or the `data-*` attribute, and sets `color-scheme` so form controls and scrollbars follow.
+*
+* @param root The element to write to, usually `document.documentElement`.
+* @param resolved The theme to show.
+* @param attribute Where to write it: `"class"` (the default) or a `data-*` attribute name.
+* @example
+* import { applyTheme } from "@shadow-js/ui";
+*
+* applyTheme(document.documentElement, "dark");
+* @since 1.0.0
+*/
+function applyTheme(root, resolved, attribute = "class") {
+	if (attribute === "class") {
+		root.classList.remove("light", "dark");
+		root.classList.add(resolved);
+	} else root.setAttribute(attribute, resolved);
+	root.style.colorScheme = resolved;
+}
+/** The storage error names a locked-down browser raises; anything else is a bug and propagates. */
+function isStorageUnavailable(error) {
+	return error instanceof DOMException && (error.name === "SecurityError" || error.name === "QuotaExceededError" || error.name === "NotAllowedError");
+}
+/**
+* Reads the stored theme. A missing or invalid value gives `undefined`. A storage the browser
+* blocks (private windows, disabled site data) or has run out of room for also gives `undefined`:
+* those raise a `SecurityError`, `NotAllowedError` or `QuotaExceededError` `DOMException`.
+*
+* @param storage The storage to read, usually `window.localStorage`.
+* @param key The storage key, such as {@link DEFAULT_STORAGE_KEY}.
+* @returns The stored theme, or `undefined` when it is missing, invalid or unavailable.
+* @throws The original error when it is not one of the storage errors above, because that is a bug.
+* @example
+* import { DEFAULT_STORAGE_KEY, readStoredTheme } from "@shadow-js/ui";
+*
+* readStoredTheme(window.localStorage, DEFAULT_STORAGE_KEY);
+* @since 1.0.0
+*/
+function readStoredTheme(storage, key) {
+	try {
+		const value = storage.getItem(key);
+		return isTheme(value) ? value : void 0;
+	} catch (error) {
+		if (isStorageUnavailable(error)) return void 0;
+		throw error;
+	}
+}
+/**
+* Stores the theme under the key. A storage that is blocked or full does not throw: the function
+* returns `false` instead.
+*
+* @param storage The storage to write, usually `window.localStorage`.
+* @param key The storage key, such as {@link DEFAULT_STORAGE_KEY}.
+* @param theme The theme to store.
+* @returns `true` when the value was written, `false` when the storage refused it.
+* @throws The original error when it is not one of the storage errors listed in {@link readStoredTheme}.
+* @example
+* import { DEFAULT_STORAGE_KEY, writeStoredTheme } from "@shadow-js/ui";
+*
+* writeStoredTheme(window.localStorage, DEFAULT_STORAGE_KEY, "dark");
+* @since 1.0.0
+*/
+function writeStoredTheme(storage, key, theme) {
+	try {
+		storage.setItem(key, theme);
+		return true;
+	} catch (error) {
+		if (isStorageUnavailable(error)) return false;
+		throw error;
+	}
+}
+/**
+* The inline script that applies the stored theme before the first paint, so a dark-mode user does
+* not see a flash of the light theme. Put the returned text in a `<script>` in the document
+* `<head>`: a `<script>` in `index.html`, or the `document.head` option of Dusk's `createHandler`.
+* An inline script in the head runs before the body is rendered. Pass the same options to
+* `ThemeProvider`.
+*
+* The script is plain ES5 with no dependencies. It reads the stored theme, falls back to
+* `defaultTheme` when the value is missing or invalid or when storage is blocked, and writes the same
+* class or attribute and `color-scheme` as {@link applyTheme}. The function returns text only, so you
+* place the tag yourself. {@link themeScriptTag} returns the same script in a tag with a CSP `nonce`.
+*
+* @param options Must match the `ThemeProvider` options.
+* @returns JavaScript source text, without `<script>` tags.
+* @example
+* import { themeScript } from "@shadow-js/ui";
+*
+* const html = `<script>${themeScript({ defaultTheme: "dark" })}<\/script>`;
+* @see {@link themeScriptTag}
+* @since 1.0.0
+*/
+function themeScript(options = {}) {
+	const key = options.storageKey ?? "shadow-ui-theme";
+	const fallback = options.defaultTheme ?? "system";
+	const attribute = options.attribute ?? "class";
+	const system = options.enableSystem ?? true;
+	const literal = (value) => JSON.stringify(value).replace(/</g, "\\u003c");
+	return [
+		"(function(){",
+		`var k=${literal(key)},f=${literal(fallback)},a=${literal(attribute)},s=${literal(system)};`,
+		"var r=document.documentElement;",
+		"function p(t){if(t==='system')return s&&window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';return t}",
+		"function w(m){if(a==='class'){r.classList.remove('light','dark');r.classList.add(m)}else{r.setAttribute(a,m)}r.style.colorScheme=m}",
+		"try{var t=localStorage.getItem(k);if(t!=='light'&&t!=='dark'&&t!=='system')t=f;w(p(t))}",
+		"catch(e){w(p(f))}",
+		"})();"
+	].join("");
+}
+/**
+* {@link themeScript} wrapped in a `<script>` element, as an HTML string, for a server that builds the
+* document. Pass the page's CSP nonce so the inline script is allowed by a policy that uses nonces. In
+* Dusk, the nonce of each response is `event.nonce`, available in the `document.head` function.
+* Only base64 characters (`A-Z`, `a-z`, `0-9`, `+`, `/`, `=`, `_`, `-`) are kept from the nonce.
+*
+* @param options The theme options plus the CSP `nonce` of the page. Without a nonce the tag has no
+*   `nonce` attribute.
+* @returns A `<script>` element as HTML text.
+* @example
+* import { createHandler, type DuskRuntimeManifest } from "@shadow-js/dusk/server";
+* import { pages } from "@shadow-js/dusk/features/pages";
+* import { themeScriptTag } from "@shadow-js/ui";
+*
+* declare const manifest: DuskRuntimeManifest;
+*
+* export const handler = createHandler({
+*   features: [pages()],
+*   manifest,
+*   security: { csp: {} },
+*   document: { head: (event) => themeScriptTag({ nonce: event.nonce }) },
+* });
+* @see {@link themeScript}
+* @since 1.0.0
+*/
+function themeScriptTag(options = {}) {
+	return `<script${options.nonce === void 0 ? "" : ` nonce="${options.nonce.replace(/[^A-Za-z0-9+/=_-]/g, "")}"`}>${themeScript(options)}<\/script>`;
+}
+export { DEFAULT_STORAGE_KEY, applyTheme, isTheme, readStoredTheme, resolveTheme, themeScript, themeScriptTag, writeStoredTheme };
+
+//# sourceMappingURL=theme-logic.js.map

package/dist/dev/theme/theme-logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-logic.js","names":[],"sources":["../../../src/theme/theme-logic.ts"],"sourcesContent":["/**\n * Pure theme logic, shared by the provider and the no-flash script so both agree on what\n * \"system\", \"light\" and \"dark\" mean. Nothing here touches `window` unless it is handed an object.\n * @packageDocumentation\n */\n\n/**\n * The theme a user picks: `\"light\"`, `\"dark\"`, or `\"system\"` to follow the operating system.\n * @since 1.0.0\n */\nexport type Theme = \"light\" | \"dark\" | \"system\";\n\n/**\n * The theme that is actually shown: `\"light\"` or `\"dark\"`.\n * @since 1.0.0\n */\nexport type ResolvedTheme = \"light\" | \"dark\";\n\n/**\n * Where the resolved theme is written on the root element. `\"class\"` (the default) sets a `light`\n * or `dark` class, which the generated stylesheet matches for its dark styles (the `dark` variant of\n * Tailwind is `.dark`). A `data-*` name such as `\"data-theme\"` sets that attribute to `\"light\"` or\n * `\"dark\"` instead; the stylesheet then has to match that attribute as well.\n * @since 1.0.0\n */\nexport type ThemeAttribute = \"class\" | `data-${string}`;\n\n/**\n * Options shared by `ThemeProvider` and `themeScript`. Pass the same values to both, or the page can\n * show one theme before the provider switches to another.\n * @since 1.0.0\n */\nexport interface ThemeOptions {\n  /**\n   * `localStorage` key that persists the choice. The stored value is `\"light\"`, `\"dark\"` or\n   * `\"system\"`; a missing or invalid value falls back to `defaultTheme`.\n   * @default \"shadow-ui-theme\"\n   */\n  readonly storageKey?: string | undefined;\n  /**\n   * Theme used before the user chooses one, and when the stored value is missing or invalid.\n   * @default \"system\"\n   */\n  readonly defaultTheme?: Theme | undefined;\n  /**\n   * Where the resolved theme is written: `\"class\"` for a `light` or `dark` class on `<html>`, or a\n   * `data-*` attribute name such as `\"data-theme\"` (see {@link ThemeAttribute}).\n   * @default \"class\"\n   */\n  readonly attribute?: ThemeAttribute | undefined;\n  /**\n   * Follow `prefers-color-scheme` while the theme is `\"system\"`. When `false`, `\"system\"` shows light.\n   * @default true\n   */\n  readonly enableSystem?: boolean | undefined;\n}\n\n/**\n * The `localStorage` key that holds the theme choice when `storageKey` is not given.\n * @example\n * import { DEFAULT_STORAGE_KEY } from \"@shadow-js/ui\";\n *\n * window.localStorage.getItem(DEFAULT_STORAGE_KEY);\n * @since 1.0.0\n */\nexport const DEFAULT_STORAGE_KEY = \"shadow-ui-theme\";\n\n/**\n * Narrows an unknown value to a {@link Theme}. Use it on anything read from storage or from an event\n * before trusting it.\n *\n * @param value Anything, such as a value read from storage.\n * @returns `true` for `\"light\"`, `\"dark\"` and `\"system\"`, and `false` for everything else.\n * @example\n * import { DEFAULT_STORAGE_KEY, isTheme } from \"@shadow-js/ui\";\n *\n * isTheme(window.localStorage.getItem(DEFAULT_STORAGE_KEY)); // false when nothing is stored\n * @since 1.0.0\n */\nexport function isTheme(value: unknown): value is Theme {\n  return value === \"light\" || value === \"dark\" || value === \"system\";\n}\n\n/**\n * Turns a theme choice into the theme to show. Only `\"system\"` depends on the operating system.\n *\n * @param theme The user's choice.\n * @param systemPrefersDark Whether the operating system prefers a dark scheme.\n * @param enableSystem When `false`, `\"system\"` resolves to light. Default `true`.\n * @returns `\"light\"` or `\"dark\"`.\n * @example\n * import { resolveTheme } from \"@shadow-js/ui\";\n *\n * resolveTheme(\"system\", true); // \"dark\"\n * @since 1.0.0\n */\nexport function resolveTheme(\n  theme: Theme,\n  systemPrefersDark: boolean,\n  enableSystem = true,\n): ResolvedTheme {\n  if (theme === \"system\") return enableSystem && systemPrefersDark ? \"dark\" : \"light\";\n  return theme;\n}\n\n/**\n * Writes the resolved theme to the root element: sets the `light` or `dark` class (removing the\n * other) or the `data-*` attribute, and sets `color-scheme` so form controls and scrollbars follow.\n *\n * @param root The element to write to, usually `document.documentElement`.\n * @param resolved The theme to show.\n * @param attribute Where to write it: `\"class\"` (the default) or a `data-*` attribute name.\n * @example\n * import { applyTheme } from \"@shadow-js/ui\";\n *\n * applyTheme(document.documentElement, \"dark\");\n * @since 1.0.0\n */\nexport function applyTheme(\n  root: HTMLElement,\n  resolved: ResolvedTheme,\n  attribute: ThemeAttribute = \"class\",\n): void {\n  if (attribute === \"class\") {\n    root.classList.remove(\"light\", \"dark\");\n    root.classList.add(resolved);\n  } else {\n    root.setAttribute(attribute, resolved);\n  }\n  root.style.colorScheme = resolved;\n}\n\n/** The storage error names a locked-down browser raises; anything else is a bug and propagates. */\nfunction isStorageUnavailable(error: unknown): boolean {\n  return (\n    error instanceof DOMException &&\n    (error.name === \"SecurityError\" ||\n      error.name === \"QuotaExceededError\" ||\n      error.name === \"NotAllowedError\")\n  );\n}\n\n/**\n * Reads the stored theme. A missing or invalid value gives `undefined`. A storage the browser\n * blocks (private windows, disabled site data) or has run out of room for also gives `undefined`:\n * those raise a `SecurityError`, `NotAllowedError` or `QuotaExceededError` `DOMException`.\n *\n * @param storage The storage to read, usually `window.localStorage`.\n * @param key The storage key, such as {@link DEFAULT_STORAGE_KEY}.\n * @returns The stored theme, or `undefined` when it is missing, invalid or unavailable.\n * @throws The original error when it is not one of the storage errors above, because that is a bug.\n * @example\n * import { DEFAULT_STORAGE_KEY, readStoredTheme } from \"@shadow-js/ui\";\n *\n * readStoredTheme(window.localStorage, DEFAULT_STORAGE_KEY);\n * @since 1.0.0\n */\nexport function readStoredTheme(storage: Storage, key: string): Theme | undefined {\n  try {\n    const value = storage.getItem(key);\n    return isTheme(value) ? value : undefined;\n  } catch (error) {\n    if (isStorageUnavailable(error)) return undefined;\n    throw error;\n  }\n}\n\n/**\n * Stores the theme under the key. A storage that is blocked or full does not throw: the function\n * returns `false` instead.\n *\n * @param storage The storage to write, usually `window.localStorage`.\n * @param key The storage key, such as {@link DEFAULT_STORAGE_KEY}.\n * @param theme The theme to store.\n * @returns `true` when the value was written, `false` when the storage refused it.\n * @throws The original error when it is not one of the storage errors listed in {@link readStoredTheme}.\n * @example\n * import { DEFAULT_STORAGE_KEY, writeStoredTheme } from \"@shadow-js/ui\";\n *\n * writeStoredTheme(window.localStorage, DEFAULT_STORAGE_KEY, \"dark\");\n * @since 1.0.0\n */\nexport function writeStoredTheme(storage: Storage, key: string, theme: Theme): boolean {\n  try {\n    storage.setItem(key, theme);\n    return true;\n  } catch (error) {\n    if (isStorageUnavailable(error)) return false;\n    throw error;\n  }\n}\n\n/**\n * The inline script that applies the stored theme before the first paint, so a dark-mode user does\n * not see a flash of the light theme. Put the returned text in a `<script>` in the document\n * `<head>`: a `<script>` in `index.html`, or the `document.head` option of Dusk's `createHandler`.\n * An inline script in the head runs before the body is rendered. Pass the same options to\n * `ThemeProvider`.\n *\n * The script is plain ES5 with no dependencies. It reads the stored theme, falls back to\n * `defaultTheme` when the value is missing or invalid or when storage is blocked, and writes the same\n * class or attribute and `color-scheme` as {@link applyTheme}. The function returns text only, so you\n * place the tag yourself. {@link themeScriptTag} returns the same script in a tag with a CSP `nonce`.\n *\n * @param options Must match the `ThemeProvider` options.\n * @returns JavaScript source text, without `<script>` tags.\n * @example\n * import { themeScript } from \"@shadow-js/ui\";\n *\n * const html = `<script>${themeScript({ defaultTheme: \"dark\" })}</script>`;\n * @see {@link themeScriptTag}\n * @since 1.0.0\n */\nexport function themeScript(options: ThemeOptions = {}): string {\n  const key = options.storageKey ?? DEFAULT_STORAGE_KEY;\n  const fallback = options.defaultTheme ?? \"system\";\n  const attribute = options.attribute ?? \"class\";\n  const system = options.enableSystem ?? true;\n  // `<` is escaped so a stored value can never close the surrounding <script> element.\n  const literal = (value: unknown): string => JSON.stringify(value).replace(/</g, \"\\\\u003c\");\n  return [\n    \"(function(){\",\n    `var k=${literal(key)},f=${literal(fallback)},a=${literal(attribute)},s=${literal(system)};`,\n    \"var r=document.documentElement;\",\n    \"function p(t){if(t==='system')return s&&window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';return t}\",\n    \"function w(m){if(a==='class'){r.classList.remove('light','dark');r.classList.add(m)}else{r.setAttribute(a,m)}r.style.colorScheme=m}\",\n    \"try{var t=localStorage.getItem(k);if(t!=='light'&&t!=='dark'&&t!=='system')t=f;w(p(t))}\",\n    \"catch(e){w(p(f))}\",\n    \"})();\",\n  ].join(\"\");\n}\n\n/**\n * {@link themeScript} wrapped in a `<script>` element, as an HTML string, for a server that builds the\n * document. Pass the page's CSP nonce so the inline script is allowed by a policy that uses nonces. In\n * Dusk, the nonce of each response is `event.nonce`, available in the `document.head` function.\n * Only base64 characters (`A-Z`, `a-z`, `0-9`, `+`, `/`, `=`, `_`, `-`) are kept from the nonce.\n *\n * @param options The theme options plus the CSP `nonce` of the page. Without a nonce the tag has no\n *   `nonce` attribute.\n * @returns A `<script>` element as HTML text.\n * @example\n * import { createHandler, type DuskRuntimeManifest } from \"@shadow-js/dusk/server\";\n * import { pages } from \"@shadow-js/dusk/features/pages\";\n * import { themeScriptTag } from \"@shadow-js/ui\";\n *\n * declare const manifest: DuskRuntimeManifest;\n *\n * export const handler = createHandler({\n *   features: [pages()],\n *   manifest,\n *   security: { csp: {} },\n *   document: { head: (event) => themeScriptTag({ nonce: event.nonce }) },\n * });\n * @see {@link themeScript}\n * @since 1.0.0\n */\nexport function themeScriptTag(\n  options: ThemeOptions & { readonly nonce?: string | undefined } = {},\n): string {\n  const nonce =\n    options.nonce === undefined\n      ? \"\"\n      : ` nonce=\"${options.nonce.replace(/[^A-Za-z0-9+/=_-]/g, \"\")}\"`;\n  return `<script${nonce}>${themeScript(options)}</script>`;\n}\n"],"mappings":";;;;;;;;;AAiEA,MAAa,sBAAsB;;;;;;;;;;;;;AAcnC,SAAgB,QAAQ,OAAgC;CACtD,OAAO,UAAU,WAAW,UAAU,UAAU,UAAU;AAC5D;;;;;;;;;;;;;;AAeA,SAAgB,aACd,OACA,mBACA,eAAe,MACA;CACf,IAAI,UAAU,UAAU,OAAO,gBAAgB,oBAAoB,SAAS;CAC5E,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,WACd,MACA,UACA,YAA4B,SACtB;CACN,IAAI,cAAc,SAAS;EACzB,KAAK,UAAU,OAAO,SAAS,MAAM;EACrC,KAAK,UAAU,IAAI,QAAQ;CAC7B,OACE,KAAK,aAAa,WAAW,QAAQ;CAEvC,KAAK,MAAM,cAAc;AAC3B;;AAGA,SAAS,qBAAqB,OAAyB;CACrD,OACE,iBAAiB,iBAChB,MAAM,SAAS,mBACd,MAAM,SAAS,wBACf,MAAM,SAAS;AAErB;;;;;;;;;;;;;;;;AAiBA,SAAgB,gBAAgB,SAAkB,KAAgC;CAChF,IAAI;EACF,MAAM,QAAQ,QAAQ,QAAQ,GAAG;EACjC,OAAO,QAAQ,KAAK,IAAI,QAAQ,KAAA;CAClC,SAAS,OAAO;EACd,IAAI,qBAAqB,KAAK,GAAG,OAAO,KAAA;EACxC,MAAM;CACR;AACF;;;;;;;;;;;;;;;;AAiBA,SAAgB,iBAAiB,SAAkB,KAAa,OAAuB;CACrF,IAAI;EACF,QAAQ,QAAQ,KAAK,KAAK;EAC1B,OAAO;CACT,SAAS,OAAO;EACd,IAAI,qBAAqB,KAAK,GAAG,OAAO;EACxC,MAAM;CACR;AACF;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,YAAY,UAAwB,CAAC,GAAW;CAC9D,MAAM,MAAM,QAAQ,cAAA;CACpB,MAAM,WAAW,QAAQ,gBAAgB;CACzC,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,SAAS,QAAQ,gBAAgB;CAEvC,MAAM,WAAW,UAA2B,KAAK,UAAU,KAAK,CAAC,CAAC,QAAQ,MAAM,SAAS;CACzF,OAAO;EACL;EACA,SAAS,QAAQ,GAAG,EAAE,KAAK,QAAQ,QAAQ,EAAE,KAAK,QAAQ,SAAS,EAAE,KAAK,QAAQ,MAAM,EAAE;EAC1F;EACA;EACA;EACA;EACA;EACA;CACF,CAAC,CAAC,KAAK,EAAE;AACX;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,eACd,UAAkE,CAAC,GAC3D;CAKR,OAAO,UAHL,QAAQ,UAAU,KAAA,IACd,KACA,WAAW,QAAQ,MAAM,QAAQ,sBAAsB,EAAE,EAAE,GAC1C,GAAG,YAAY,OAAO,EAAE;AACjD"}

package/dist/dev/theme/theme-provider.d.ts

@@ -0,0 +1,88 @@
+import { ResolvedTheme, Theme, ThemeOptions } from "./theme-logic.js";
+import { Accessor } from "@shadow-js/core";
+import { JsxChild } from "@shadow-js/web/jsx-runtime";
+/**
+ * What {@link useTheme} returns. Every value is an accessor: call it to read.
+ * @since 1.0.0
+ */
+export interface ThemeContextValue {
+  /** The user's choice: `"light"`, `"dark"` or `"system"`. Call it to read the value. */
+  readonly theme: Accessor<Theme>;
+  /**
+   * The theme that is shown: `"light"` or `"dark"`. `undefined` on the server and until the provider
+   * has mounted, so markup that depends on it hydrates without a mismatch.
+   */
+  readonly resolvedTheme: Accessor<ResolvedTheme | undefined>;
+  /**
+   * The operating system preference: `"light"` or `"dark"`. `undefined` on the server and until the
+   * provider has mounted.
+   */
+  readonly systemTheme: Accessor<ResolvedTheme | undefined>;
+  /**
+   * Chooses a theme, or derives one from the previous choice, and stores it under the provider's
+   * `storageKey`. Throws a `TypeError` for a value that is not `"light"`, `"dark"` or `"system"`.
+   */
+  readonly setTheme: (theme: Theme | ((previous: Theme) => Theme)) => void;
+}
+/**
+ * Props of {@link ThemeProvider}: the {@link ThemeOptions} plus a transition switch and the children.
+ * @since 1.0.0
+ */
+export interface ThemeProviderProps extends ThemeOptions {
+  /**
+   * Stops CSS transitions for one frame while the theme changes, so colors flip at once instead
+   * of fading piecemeal.
+   * @default false
+   */
+  readonly disableTransitionOnChange?: boolean | undefined;
+  /** The app to render inside the theme context. */
+  readonly children?: JsxChild | undefined;
+}
+/**
+ * Provides the color theme to the app: `"light"`, `"dark"` or `"system"`. The choice is persisted in
+ * `localStorage`, applied to `<html>` as a `light` or `dark` class (or a `data-*` attribute), and kept
+ * in sync across tabs and with the operating system. The provider renders no element of its own, and
+ * nothing touches the DOM until it has mounted, so it is safe to render on the server. Pair it with
+ * {@link themeScript} in the document head so the first paint already has the right theme.
+ *
+ * @param props The {@link ThemeProviderProps}: theme options (`storageKey`, `defaultTheme`,
+ *   `attribute`, `enableSystem`), `disableTransitionOnChange` and `children`.
+ * @returns The children inside the theme context.
+ * @example
+ * import { ThemeProvider } from "@shadow-js/ui";
+ *
+ * function App() {
+ *   return <p>Hello</p>;
+ * }
+ *
+ * export const root = (
+ *   <ThemeProvider defaultTheme="system">
+ *     <App />
+ *   </ThemeProvider>
+ * );
+ * @see {@link useTheme}
+ * @since 1.0.0
+ */
+export declare function ThemeProvider(props: ThemeProviderProps): JsxChild;
+/**
+ * Reads the theme and its setter. Call it inside a component rendered under {@link ThemeProvider}.
+ *
+ * @returns The {@link ThemeContextValue}: accessors for the chosen, the resolved and the system
+ *   theme, and `setTheme`.
+ * @throws Error when no `ThemeProvider` is above the caller.
+ * @example
+ * import { useTheme } from "@shadow-js/ui";
+ *
+ * export function ThemeToggle() {
+ *   const { resolvedTheme, setTheme } = useTheme();
+ *   return (
+ *     <button onClick={() => setTheme(resolvedTheme() === "dark" ? "light" : "dark")}>
+ *       Toggle theme
+ *     </button>
+ *   );
+ * }
+ * @see {@link ThemeProvider}
+ * @since 1.0.0
+ */
+export declare function useTheme(): ThemeContextValue;
+//# sourceMappingURL=theme-provider.d.ts.map

package/dist/dev/theme/theme-provider.js

@@ -0,0 +1,149 @@
+import { applyTheme, isTheme, readStoredTheme, resolveTheme, writeStoredTheme } from "./theme-logic.js";
+import { batch, createContext, onCleanup, onMount, untrack, useContext, useEffect, useMemo, useSignal } from "@shadow-js/core";
+// src/theme/theme-provider.ts
+const MISSING = {
+	theme: () => "system",
+	resolvedTheme: () => void 0,
+	systemTheme: () => void 0,
+	setTheme: () => void 0
+};
+const ThemeContext = createContext(MISSING, { name: "ShadowUITheme" });
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+/** Disables transitions until the next frame; returns nothing, cleans itself up. */
+function suppressTransitions() {
+	const style = document.createElement("style");
+	style.textContent = "*,*::before,*::after{transition:none!important;animation-duration:0s!important}";
+	document.head.append(style);
+	window.getComputedStyle(document.body).getPropertyValue("opacity");
+	window.setTimeout(() => style.remove(), 1);
+}
+/**
+* The page's `localStorage`, or `undefined` when the browser blocks it: reading the property
+* itself throws a `DOMException` in some sandboxed and locked-down contexts.
+*/
+function localStorageOrUndefined() {
+	try {
+		return window.localStorage;
+	} catch (error) {
+		if (error instanceof DOMException) return void 0;
+		throw error;
+	}
+}
+/**
+* Provides the color theme to the app: `"light"`, `"dark"` or `"system"`. The choice is persisted in
+* `localStorage`, applied to `<html>` as a `light` or `dark` class (or a `data-*` attribute), and kept
+* in sync across tabs and with the operating system. The provider renders no element of its own, and
+* nothing touches the DOM until it has mounted, so it is safe to render on the server. Pair it with
+* {@link themeScript} in the document head so the first paint already has the right theme.
+*
+* @param props The {@link ThemeProviderProps}: theme options (`storageKey`, `defaultTheme`,
+*   `attribute`, `enableSystem`), `disableTransitionOnChange` and `children`.
+* @returns The children inside the theme context.
+* @example
+* import { ThemeProvider } from "@shadow-js/ui";
+*
+* function App() {
+*   return <p>Hello</p>;
+* }
+*
+* export const root = (
+*   <ThemeProvider defaultTheme="system">
+*     <App />
+*   </ThemeProvider>
+* );
+* @see {@link useTheme}
+* @since 1.0.0
+*/
+function ThemeProvider(props) {
+	const storageKey = () => props.storageKey ?? "shadow-ui-theme";
+	const defaultTheme = () => props.defaultTheme ?? "system";
+	const attribute = () => props.attribute ?? "class";
+	const enableSystem = () => props.enableSystem ?? true;
+	const [theme, setThemeState] = useSignal(untrack(defaultTheme));
+	const [systemDark, setSystemDark] = useSignal(void 0);
+	const resolved = useMemo(() => {
+		const dark = systemDark();
+		if (dark === void 0) return void 0;
+		return resolveTheme(theme(), dark, enableSystem());
+	});
+	const system = useMemo(() => {
+		const dark = systemDark();
+		return dark === void 0 ? void 0 : dark ? "dark" : "light";
+	});
+	onMount(() => {
+		const query = window.matchMedia(DARK_QUERY);
+		batch(() => {
+			const storage = localStorageOrUndefined();
+			const stored = storage === void 0 ? void 0 : readStoredTheme(storage, storageKey());
+			if (stored !== void 0) setThemeState(stored);
+			setSystemDark(query.matches);
+		});
+		const onSystemChange = (event) => {
+			setSystemDark(event.matches);
+		};
+		const onStorage = (event) => {
+			if (event.key !== storageKey()) return;
+			setThemeState(isTheme(event.newValue) ? event.newValue : defaultTheme());
+		};
+		query.addEventListener("change", onSystemChange);
+		window.addEventListener("storage", onStorage);
+		onCleanup(() => {
+			query.removeEventListener("change", onSystemChange);
+			window.removeEventListener("storage", onStorage);
+		});
+	});
+	useEffect(() => {
+		const value = resolved();
+		if (value === void 0) return;
+		const attributeName = attribute();
+		const current = document.documentElement;
+		if (props.disableTransitionOnChange === true) suppressTransitions();
+		applyTheme(current, value, attributeName);
+	});
+	const value = {
+		theme,
+		resolvedTheme: resolved,
+		systemTheme: system,
+		setTheme(next) {
+			const chosen = typeof next === "function" ? next(untrack(theme)) : next;
+			if (!isTheme(chosen)) throw new TypeError(`setTheme: expected "light", "dark" or "system", received ${String(chosen)}`);
+			setThemeState(chosen);
+			const storage = localStorageOrUndefined();
+			if (storage !== void 0) writeStoredTheme(storage, untrack(storageKey), chosen);
+		}
+	};
+	return ThemeContext.Provider({
+		value,
+		get children() {
+			return props.children;
+		}
+	});
+}
+/**
+* Reads the theme and its setter. Call it inside a component rendered under {@link ThemeProvider}.
+*
+* @returns The {@link ThemeContextValue}: accessors for the chosen, the resolved and the system
+*   theme, and `setTheme`.
+* @throws Error when no `ThemeProvider` is above the caller.
+* @example
+* import { useTheme } from "@shadow-js/ui";
+*
+* export function ThemeToggle() {
+*   const { resolvedTheme, setTheme } = useTheme();
+*   return (
+*     <button onClick={() => setTheme(resolvedTheme() === "dark" ? "light" : "dark")}>
+*       Toggle theme
+*     </button>
+*   );
+* }
+* @see {@link ThemeProvider}
+* @since 1.0.0
+*/
+function useTheme() {
+	const value = useContext(ThemeContext);
+	if (value === MISSING) throw new Error("useTheme() must be used within <ThemeProvider>");
+	return value;
+}
+export { ThemeProvider, useTheme };
+
+//# sourceMappingURL=theme-provider.js.map