@askrjs/themes 0.0.25 → 0.0.27

package/dist/components/theme/theme.d.ts

@@ -1,13 +1,18 @@
 import { ButtonNativeProps, PressEvent } from "@askrjs/ui";
 import { JSX } from "@askrjs/askr/jsx-runtime";
 //#region src/components/theme/theme.d.ts
+/** Names of the built-in "cat" theme presets. */
 declare const CAT_THEME_NAMES: readonly ["tabby", "ginger", "tuxedo", "calico", "torty"];
+/** A built-in "cat" theme name, one of {@link CAT_THEME_NAMES}. */
 type CatThemeName = (typeof CAT_THEME_NAMES)[number];
+/** Any theme identifier accepted by {@link ThemeScope}: `"light"`, `"dark"`, `"system"`, a {@link CatThemeName}, or a custom string. */
 type ThemeName = "light" | "dark" | "system" | CatThemeName | (string & {});
+/** A theme choice offered by {@link ThemePicker}/{@link ThemeToggle}: a `value` paired with a display `label`. */
 type ThemeOption = {
   value: ThemeName;
   label: string;
 };
+/** Value read from {@link theme}: the active theme, its resolved system value, a setter, and the available theme options. */
 type ThemeScopeValue = {
   theme: () => ThemeName;
   resolvedSystemTheme: () => "light" | "dark";
@@ -15,20 +20,24 @@ type ThemeScopeValue = {
   themes: readonly ThemeOption[];
   storageKey: string;
 };
+/** Props for the {@link ThemeScope} component. */
 type ThemeScopeProps = {
   children?: unknown;
   defaultTheme?: ThemeName;
   themes?: readonly ThemeOption[];
   storageKey?: string;
 };
+/** Props for the {@link ThemePicker} component. */
 type ThemePickerProps = Omit<JSX.IntrinsicElements["select"], "children" | "value" | "defaultValue" | "onChange"> & {
   themes?: readonly ThemeOption[];
   label?: string;
 };
+/** Render context passed to a function-as-children {@link ThemeToggleProps.children}. */
 type ThemeToggleRenderContext = {
   theme: ThemeName;
   nextTheme: ThemeName;
 };
+/** Props for the {@link ThemeToggle} component. */
 type ThemeToggleProps = Omit<ButtonNativeProps, "children" | "onPress"> & {
   children?: unknown | ((context: ThemeToggleRenderContext) => unknown);
   lightIcon?: unknown;
@@ -37,11 +46,27 @@ type ThemeToggleProps = Omit<ButtonNativeProps, "children" | "onPress"> & {
   themes?: readonly ThemeName[];
   onPress?: (event: PressEvent) => void;
 };
+/** Default light/dark/system theme options used by {@link ThemeScope} and {@link ThemePicker}. */
 declare const DEFAULT_THEME_OPTIONS: readonly ThemeOption[];
+/** Theme options for the built-in "cat" theme presets, keyed to {@link CAT_THEME_NAMES}. */
 declare const CAT_THEME_OPTIONS: readonly ThemeOption[];
+/** Reads the current {@link ThemeScopeValue} from the nearest enclosing {@link ThemeScope}. */
 declare function theme(): ThemeScopeValue;
+/**
+ * Establishes a theme boundary: tracks the active theme (persisted to
+ * `localStorage` under `storageKey` and synced across tabs/scopes), resolves
+ * the OS `"system"` preference, and reflects the choice onto the DOM via
+ * `data-theme`/`data-theme-choice` attributes. Nested scopes cooperate
+ * through a shared coordinator so the deepest explicitly-set scope wins.
+ */
 declare function ThemeScope(props: ThemeScopeProps): JSX.Element;
+/** A `<select>` bound to the current {@link theme}, listing `themes` (defaults to the enclosing scope's options). */
 declare function ThemePicker(props: ThemePickerProps): JSX.Element;
+/**
+ * A button that cycles through `themes` (defaults to `["light", "dark"]`) on
+ * press. Supports icon props per theme, or a function-as-children render
+ * prop receiving {@link ThemeToggleRenderContext}.
+ */
 declare function ThemeToggle(props: ThemeToggleProps): JSX.Element;
 //#endregion
 export { CAT_THEME_NAMES, CAT_THEME_OPTIONS, CatThemeName, DEFAULT_THEME_OPTIONS, ThemeName, ThemeOption, ThemePicker, ThemePickerProps, ThemeScope, ThemeScopeProps, ThemeScopeValue, ThemeToggle, ThemeToggleProps, ThemeToggleRenderContext, theme };

package/dist/components/theme/theme.js

@@ -3,6 +3,7 @@ import { jsx } from "@askrjs/askr/jsx-runtime";
 import { defineScope, getSignal, readScope, state } from "@askrjs/askr";
 import { cloneElement, isElement } from "@askrjs/askr/foundations/structures";
 //#region src/components/theme/theme.tsx
+/** Names of the built-in "cat" theme presets. */
 const CAT_THEME_NAMES = [
 	"tabby",
 	"ginger",
@@ -10,6 +11,7 @@ const CAT_THEME_NAMES = [
 	"calico",
 	"torty"
 ];
+/** Default light/dark/system theme options used by {@link ThemeScope} and {@link ThemePicker}. */
 const DEFAULT_THEME_OPTIONS = [
 	{
 		value: "system",
@@ -24,6 +26,7 @@ const DEFAULT_THEME_OPTIONS = [
 		label: "Dark"
 	}
 ];
+/** Theme options for the built-in "cat" theme presets, keyed to {@link CAT_THEME_NAMES}. */
 const CAT_THEME_OPTIONS = [
 	{
 		value: "tabby",
@@ -58,9 +61,17 @@ const ThemeScopeContext = defineScope({
 	coordinator: null,
 	depth: -1
 });
+/** Reads the current {@link ThemeScopeValue} from the nearest enclosing {@link ThemeScope}. */
 function theme() {
 	return readScope(ThemeScopeContext);
 }
+/**
+* Establishes a theme boundary: tracks the active theme (persisted to
+* `localStorage` under `storageKey` and synced across tabs/scopes), resolves
+* the OS `"system"` preference, and reflects the choice onto the DOM via
+* `data-theme`/`data-theme-choice` attributes. Nested scopes cooperate
+* through a shared coordinator so the deepest explicitly-set scope wins.
+*/
 function ThemeScope(props) {
 	const { children, defaultTheme = "system", themes = DEFAULT_THEME_OPTIONS, storageKey = DEFAULT_STORAGE_KEY } = props;
 	const scopeId = state(Symbol("ThemeScope"))();
@@ -203,6 +214,7 @@ function createThemeCoordinator() {
 		}
 	});
 }
+/** A `<select>` bound to the current {@link theme}, listing `themes` (defaults to the enclosing scope's options). */
 function ThemePicker(props) {
 	const activeTheme = theme();
 	const { themes = activeTheme.themes, label = "Theme", ...rest } = props;
@@ -234,6 +246,11 @@ function getThemePickerTarget(event) {
 	for (const candidate of candidates) if (candidate instanceof HTMLSelectElement) return candidate;
 	return null;
 }
+/**
+* A button that cycles through `themes` (defaults to `["light", "dark"]`) on
+* press. Supports icon props per theme, or a function-as-children render
+* prop receiving {@link ThemeToggleRenderContext}.
+*/
 function ThemeToggle(props) {
 	const activeTheme = theme();
 	const { children, lightIcon, darkIcon, systemIcon, themes = ["light", "dark"], onPress, ...rest } = props;

package/dist/components/theme/theme.js.map

@@ -1 +1 @@
-{"version":3,"file":"theme.js","names":[],"sources":["../../../src/components/theme/theme.tsx"],"sourcesContent":["import type { JSX } from \"@askrjs/askr/jsx-runtime\";\nimport { defineScope, getSignal, readScope, state } from \"@askrjs/askr\";\nimport { cloneElement, isElement, type JSXElement } from \"@askrjs/askr/foundations/structures\";\nimport { Button } from \"@askrjs/ui\";\nimport type { ButtonNativeProps, PressEvent } from \"@askrjs/ui\";\n\nexport const CAT_THEME_NAMES = [\"tabby\", \"ginger\", \"tuxedo\", \"calico\", \"torty\"] as const;\n\nexport type CatThemeName = (typeof CAT_THEME_NAMES)[number];\nexport type ThemeName = \"light\" | \"dark\" | \"system\" | CatThemeName | (string & {});\n\nexport type ThemeOption = {\n  value: ThemeName;\n  label: string;\n};\n\nexport type ThemeScopeValue = {\n  theme: () => ThemeName;\n  resolvedSystemTheme: () => \"light\" | \"dark\";\n  setTheme: (theme: ThemeName) => void;\n  themes: readonly ThemeOption[];\n  storageKey: string;\n};\n\nexport type ThemeScopeProps = {\n  children?: unknown;\n  defaultTheme?: ThemeName;\n  themes?: readonly ThemeOption[];\n  storageKey?: string;\n};\n\nexport type ThemePickerProps = Omit<\n  JSX.IntrinsicElements[\"select\"],\n  \"children\" | \"value\" | \"defaultValue\" | \"onChange\"\n> & {\n  themes?: readonly ThemeOption[];\n  label?: string;\n};\n\nexport type ThemeToggleRenderContext = {\n  theme: ThemeName;\n  nextTheme: ThemeName;\n};\n\nexport type ThemeToggleProps = Omit<ButtonNativeProps, \"children\" | \"onPress\"> & {\n  children?: unknown | ((context: ThemeToggleRenderContext) => unknown);\n  lightIcon?: unknown;\n  darkIcon?: unknown;\n  systemIcon?: unknown;\n  themes?: readonly ThemeName[];\n  onPress?: (event: PressEvent) => void;\n};\n\nexport const DEFAULT_THEME_OPTIONS: readonly ThemeOption[] = [\n  { value: \"system\", label: \"System\" },\n  { value: \"light\", label: \"Light\" },\n  { value: \"dark\", label: \"Dark\" },\n];\n\nexport const CAT_THEME_OPTIONS: readonly ThemeOption[] = [\n  { value: \"tabby\", label: \"Tabby\" },\n  { value: \"ginger\", label: \"Ginger\" },\n  { value: \"tuxedo\", label: \"Tuxedo\" },\n  { value: \"calico\", label: \"Calico\" },\n  { value: \"torty\", label: \"Torty\" },\n];\n\nconst DEFAULT_STORAGE_KEY = \"askr-theme\";\nconst STATIC_CHILDREN = Symbol.for(\"askr.static-children\");\nconst documentThemeCoordinators = new WeakMap<Document, ThemeCoordinator>();\ntype ThemeCoordinator = ReturnType<typeof createThemeCoordinator>;\ntype InternalThemeScopeValue = ThemeScopeValue & {\n  readonly coordinator: ThemeCoordinator | null;\n  readonly depth: number;\n};\n\nconst ThemeScopeContext = defineScope<InternalThemeScopeValue>({\n  theme: () => \"system\",\n  resolvedSystemTheme: () => \"light\",\n  setTheme: () => undefined,\n  themes: DEFAULT_THEME_OPTIONS,\n  storageKey: DEFAULT_STORAGE_KEY,\n  coordinator: null,\n  depth: -1,\n});\n\nexport function theme(): ThemeScopeValue {\n  return readScope(ThemeScopeContext);\n}\n\nexport function ThemeScope(props: ThemeScopeProps): JSX.Element {\n  const {\n    children,\n    defaultTheme = \"system\",\n    themes = DEFAULT_THEME_OPTIONS,\n    storageKey = DEFAULT_STORAGE_KEY,\n  } = props;\n\n  const scopeId = state<symbol>(Symbol(\"ThemeScope\"))();\n  const scopeSignal = getSignal();\n  // The first render must be identical on the server and in the browser.\n  // Browser persistence is adopted from the committed root ref, after Askr's\n  // hydration verifier has accepted the server markup.\n  const themeState = state<ThemeName>(defaultTheme);\n  const localResolvedSystemTheme = state<\"light\" | \"dark\">(\"light\");\n  const persistenceAdoption = state({ complete: false })();\n  const currentTheme = themeState();\n  const parentScope = readScope(ThemeScopeContext);\n  const ownedCoordinator = state<ThemeCoordinator>(getDefaultThemeCoordinator())();\n  const coordinator = parentScope.coordinator ?? ownedCoordinator;\n  const scopeDepth = parentScope.depth + 1;\n  coordinator.register(scopeId, scopeDepth, currentTheme, scopeSignal, (nextTheme) => {\n    if (themeState() !== nextTheme) themeState.set(nextTheme);\n  });\n\n  const setTheme = (nextTheme: ThemeName) => {\n    themeState.set(nextTheme);\n    writeStoredTheme(storageKey, nextTheme);\n    coordinator.activate(scopeId, nextTheme);\n  };\n\n  const resolvedSystemTheme = parentScope.coordinator\n    ? parentScope.resolvedSystemTheme\n    : localResolvedSystemTheme;\n  const value: InternalThemeScopeValue = {\n    theme: themeState,\n    resolvedSystemTheme,\n    setTheme,\n    themes,\n    storageKey,\n    coordinator,\n    depth: scopeDepth,\n  };\n\n  return (\n    <ThemeScopeContext value={value}>\n      <div\n        data-slot=\"theme-scope\"\n        ref={\n          parentScope.coordinator === null\n            ? (element: HTMLElement | null) => {\n                coordinator.attach(\n                  element,\n                  (nextTheme) => localResolvedSystemTheme.set(nextTheme),\n                  scopeSignal,\n                );\n                if (element && typeof window !== \"undefined\") {\n                  const onStorage = (event: StorageEvent) => {\n                    let storageMatches = event.storageArea == null;\n                    try {\n                      storageMatches ||= event.storageArea === window.localStorage;\n                    } catch {\n                      // Locked-down/private contexts may deny access to localStorage.\n                    }\n                    if (!storageMatches || event.key !== storageKey) {\n                      return;\n                    }\n                    const nextTheme = event.newValue as ThemeName | null;\n                    if (!nextTheme) return;\n                    themeState.set(nextTheme);\n                    coordinator.activate(scopeId, nextTheme);\n                  };\n                  window.addEventListener(\"storage\", onStorage);\n                  scopeSignal.addEventListener(\n                    \"abort\",\n                    () => window.removeEventListener(\"storage\", onStorage),\n                    { once: true },\n                  );\n                }\n                if (!element || persistenceAdoption.complete) return;\n                persistenceAdoption.complete = true;\n                const storedTheme = readStoredTheme(storageKey);\n                if (storedTheme && storedTheme !== themeState()) {\n                  themeState.set(storedTheme);\n                  coordinator.activate(scopeId, storedTheme);\n                }\n              }\n            : undefined\n        }\n      >\n        {children}\n      </div>\n    </ThemeScopeContext>\n  );\n}\n\nfunction getDefaultThemeCoordinator(): ThemeCoordinator {\n  if (typeof document === \"undefined\") {\n    return createThemeCoordinator();\n  }\n\n  const existing = documentThemeCoordinators.get(document);\n  if (existing) return existing;\n\n  const coordinator = createThemeCoordinator();\n  documentThemeCoordinators.set(document, coordinator);\n  return coordinator;\n}\n\nfunction removeEmptyGeneratedStyleRegistries(root: Node | null): void {\n  const ownerDocument =\n    root?.nodeType === 9\n      ? (root as Document)\n      : (root?.ownerDocument ?? (typeof document === \"undefined\" ? null : document));\n  if (!ownerDocument) return;\n\n  for (const registry of ownerDocument.querySelectorAll<HTMLStyleElement>(\n    \"style[data-askr-style-registry]\",\n  )) {\n    if (!registry.textContent?.trim()) registry.remove();\n  }\n}\n\nfunction createThemeCoordinator() {\n  const scopes = new Map<\n    symbol,\n    {\n      depth: number;\n      sequence: number;\n      theme: ThemeName;\n      signal: AbortSignal;\n      onThemeChange: (themeName: ThemeName) => void;\n    }\n  >();\n  let nextSequence = 0;\n  let explicitOwner: symbol | undefined;\n  let root: Node | null = null;\n  let scheduled = false;\n\n  const target = (): HTMLElement | null => {\n    if (root?.nodeType === 9) return (root as Document).documentElement;\n    if (root && \"host\" in root) return (root as ShadowRoot).host as HTMLElement;\n    return typeof document === \"undefined\" ? null : document.documentElement;\n  };\n  const syncActive = (): void => {\n    if (explicitOwner !== undefined) return;\n    let candidate: { depth: number; sequence: number; theme: ThemeName } | undefined;\n    for (const scope of scopes.values()) {\n      if (\n        !candidate ||\n        scope.depth > candidate.depth ||\n        (scope.depth === candidate.depth && scope.sequence > candidate.sequence)\n      ) {\n        candidate = scope;\n      }\n    }\n    if (candidate) syncThemeTarget(target(), candidate.theme);\n  };\n  const schedule = (): void => {\n    if (typeof document === \"undefined\" || scheduled) return;\n    scheduled = true;\n    setTimeout(() => {\n      scheduled = false;\n      syncActive();\n      if (scopes.size === 0) removeEmptyGeneratedStyleRegistries(root);\n    }, 0);\n  };\n\n  return Object.freeze({\n    attach(\n      element: HTMLElement | null,\n      onResolvedSystemTheme: (themeName: \"light\" | \"dark\") => void,\n      signal: AbortSignal,\n    ) {\n      if (element) root = element.getRootNode();\n      if (element && typeof window !== \"undefined\" && typeof window.matchMedia === \"function\") {\n        const media = window.matchMedia(\"(prefers-color-scheme: dark)\");\n        const update = () => onResolvedSystemTheme(media.matches ? \"dark\" : \"light\");\n        update();\n        media.addEventListener?.(\"change\", update);\n        signal.addEventListener(\"abort\", () => media.removeEventListener?.(\"change\", update), {\n          once: true,\n        });\n      }\n      schedule();\n    },\n    register(\n      id: symbol,\n      depth: number,\n      themeName: ThemeName,\n      signal: AbortSignal,\n      onThemeChange: (themeName: ThemeName) => void,\n    ) {\n      const existing = scopes.get(id);\n      scopes.set(id, {\n        depth,\n        sequence: existing?.sequence ?? nextSequence++,\n        theme: themeName,\n        signal,\n        onThemeChange,\n      });\n      if (!existing) {\n        signal.addEventListener(\n          \"abort\",\n          () => {\n            scopes.delete(id);\n            if (explicitOwner === id) explicitOwner = undefined;\n            schedule();\n          },\n          { once: true },\n        );\n      }\n      schedule();\n    },\n    activate(id: symbol, themeName: ThemeName) {\n      const scope = scopes.get(id);\n      if (scope) scope.theme = themeName;\n      explicitOwner = id;\n      const ownerDepth = scope?.depth;\n      for (const [scopeId, registered] of scopes) {\n        if (scopeId !== id && registered.depth === ownerDepth) {\n          registered.theme = themeName;\n          registered.onThemeChange(themeName);\n        }\n      }\n      syncThemeTarget(target(), themeName);\n    },\n  });\n}\n\nexport function ThemePicker(props: ThemePickerProps): JSX.Element {\n  const activeTheme = theme();\n  const { themes = activeTheme.themes, label = \"Theme\", ...rest } = props;\n  const currentTheme = activeTheme.theme();\n\n  return (\n    <select\n      {...rest}\n      aria-label={rest[\"aria-label\"] ?? label}\n      data-slot=\"theme-picker\"\n      value={currentTheme}\n      onChange={(event: Event) => {\n        const target = getThemePickerTarget(event);\n        if (target) {\n          activeTheme.setTheme(target.value as ThemeName);\n        }\n      }}\n    >\n      {themes.map((option) => (\n        <option key={option.value} value={option.value} selected={option.value === currentTheme}>\n          {option.label}\n        </option>\n      ))}\n    </select>\n  );\n}\n\nfunction getThemePickerTarget(event: Event): HTMLSelectElement | null {\n  if (typeof HTMLSelectElement === \"undefined\") {\n    return null;\n  }\n\n  const path = typeof event.composedPath === \"function\" ? event.composedPath() : [];\n  const candidates = [event.target, event.currentTarget, ...path];\n\n  for (const candidate of candidates) {\n    if (candidate instanceof HTMLSelectElement) {\n      return candidate;\n    }\n  }\n\n  return null;\n}\n\nexport function ThemeToggle(props: ThemeToggleProps): JSX.Element {\n  const activeTheme = theme();\n  const {\n    children,\n    lightIcon,\n    darkIcon,\n    systemIcon,\n    themes = [\"light\", \"dark\"],\n    onPress,\n    ...rest\n  } = props;\n\n  const currentTheme = activeTheme.theme();\n  const nextTheme = getNextTheme(currentTheme, themes, activeTheme.resolvedSystemTheme());\n  const renderContext = { theme: currentTheme, nextTheme };\n  const ariaLabel = (rest as Record<string, unknown>)[\"aria-label\"];\n  const themedIcon = resolveThemeToggleIcon(currentTheme, nextTheme, {\n    lightIcon,\n    darkIcon,\n    systemIcon,\n  });\n  const renderedIcon = cloneThemeToggleIcon(themedIcon, currentTheme);\n  const renderedIconSlots =\n    renderThemeToggleIconSlots(currentTheme, {\n      lightIcon,\n      darkIcon,\n      systemIcon,\n    }) ?? renderedIcon;\n  const content =\n    typeof children === \"function\" ? children(renderContext) : (children ?? renderedIconSlots);\n\n  return (\n    <Button\n      {...(rest as ButtonNativeProps)}\n      aria-label={typeof ariaLabel === \"string\" ? ariaLabel : `Switch to ${nextTheme} theme`}\n      data-theme-control=\"toggle\"\n      data-theme-choice={currentTheme}\n      data-next-theme={nextTheme}\n      onPress={(event) => {\n        onPress?.(event);\n        if (!event.defaultPrevented && !Object.is(nextTheme, currentTheme)) {\n          activeTheme.setTheme(nextTheme);\n        }\n      }}\n    >\n      <span data-slot=\"theme-toggle-content\">{content}</span>\n    </Button>\n  );\n}\n\nfunction getNextTheme(\n  currentTheme: ThemeName,\n  themes: readonly ThemeName[],\n  resolvedSystemTheme: \"light\" | \"dark\" = \"light\",\n): ThemeName {\n  if (themes.length === 0) return currentTheme;\n  const index = themes.indexOf(currentTheme);\n  if (index < 0 && currentTheme === \"system\") {\n    if (themes.includes(\"light\") && themes.includes(\"dark\")) {\n      return resolvedSystemTheme === \"dark\" ? \"light\" : \"dark\";\n    }\n  }\n  return themes[index >= 0 && index < themes.length - 1 ? index + 1 : 0]!;\n}\n\nfunction getThemeIcon(\n  theme: ThemeName,\n  icons: Pick<ThemeToggleProps, \"lightIcon\" | \"darkIcon\" | \"systemIcon\">,\n): unknown {\n  if (theme === \"light\") return icons.lightIcon;\n  if (theme === \"dark\") return icons.darkIcon;\n  if (theme === \"system\") return icons.systemIcon;\n  return undefined;\n}\n\nexport function resolveThemeToggleIcon(\n  theme: ThemeName,\n  nextTheme: ThemeName,\n  icons: Pick<ThemeToggleProps, \"lightIcon\" | \"darkIcon\" | \"systemIcon\">,\n): unknown {\n  return getThemeIcon(theme, icons) ?? getThemeIcon(nextTheme, icons);\n}\n\nfunction renderThemeToggleIconSlots(\n  theme: ThemeName,\n  icons: Pick<ThemeToggleProps, \"lightIcon\" | \"darkIcon\" | \"systemIcon\">,\n): unknown {\n  if (getThemeIcon(theme, icons) === undefined) {\n    return undefined;\n  }\n\n  const slots = [\n    [\"light\", icons.lightIcon],\n    [\"dark\", icons.darkIcon],\n    [\"system\", icons.systemIcon],\n  ] as const;\n  const availableSlots = slots.filter(([, icon]) => icon !== undefined && icon !== null);\n\n  if (availableSlots.length <= 1) {\n    return undefined;\n  }\n\n  return availableSlots.map(([slotTheme, icon]) => (\n    <span\n      key={slotTheme}\n      data-slot=\"theme-toggle-icon\"\n      data-theme-toggle-icon={slotTheme}\n      hidden={slotTheme === theme ? undefined : true}\n    >\n      {cloneThemeToggleIcon(icon, slotTheme)}\n    </span>\n  ));\n}\n\nfunction cloneThemeToggleIcon(icon: unknown, key?: string): unknown {\n  if (Array.isArray(icon)) {\n    const clonedChildren = icon.map((child) => cloneThemeToggleIcon(child));\n    if ((icon as unknown as Record<symbol, unknown>)[STATIC_CHILDREN] === true) {\n      Object.defineProperty(clonedChildren, STATIC_CHILDREN, {\n        value: true,\n        configurable: true,\n      });\n    }\n    return clonedChildren;\n  }\n\n  if (!isElement(icon)) return icon;\n\n  const props = icon.props as Record<string, unknown> | undefined;\n  const clonedProps = props ? { ...props } : {};\n\n  if (\"children\" in clonedProps) {\n    clonedProps.children = cloneThemeToggleIcon(clonedProps.children);\n  }\n\n  const clonedIcon = cloneElement(icon, clonedProps);\n  return {\n    ...clonedIcon,\n    key: icon.key ?? key ?? null,\n  } satisfies JSXElement;\n}\n\nfunction syncThemeTarget(\n  html: HTMLElement | null,\n  themeChoice: ThemeName | null | undefined,\n): void {\n  if (!html) return;\n\n  if (themeChoice == null) {\n    html.removeAttribute(\"data-theme\");\n    html.removeAttribute(\"data-theme-choice\");\n    return;\n  }\n\n  html.setAttribute(\"data-theme-choice\", themeChoice);\n\n  if (themeChoice === \"system\") {\n    html.removeAttribute(\"data-theme\");\n  } else {\n    html.setAttribute(\"data-theme\", themeChoice);\n  }\n}\n\nfunction readStoredTheme(storageKey: string): ThemeName | undefined {\n  if (typeof window === \"undefined\") return undefined;\n  try {\n    const storedTheme = window.localStorage.getItem(storageKey);\n    return storedTheme ? (storedTheme as ThemeName) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction writeStoredTheme(storageKey: string, theme: ThemeName): void {\n  if (typeof window === \"undefined\") return;\n  try {\n    window.localStorage.setItem(storageKey, theme);\n  } catch {\n    // Storage can be unavailable in private or locked-down browser contexts.\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"theme.js","names":[],"sources":["../../../src/components/theme/theme.tsx"],"sourcesContent":["import type { JSX } from \"@askrjs/askr/jsx-runtime\";\nimport { defineScope, getSignal, readScope, state } from \"@askrjs/askr\";\nimport { cloneElement, isElement, type JSXElement } from \"@askrjs/askr/foundations/structures\";\nimport { Button } from \"@askrjs/ui\";\nimport type { ButtonNativeProps, PressEvent } from \"@askrjs/ui\";\n\n/** Names of the built-in \"cat\" theme presets. */\nexport const CAT_THEME_NAMES = [\"tabby\", \"ginger\", \"tuxedo\", \"calico\", \"torty\"] as const;\n\n/** A built-in \"cat\" theme name, one of {@link CAT_THEME_NAMES}. */\nexport type CatThemeName = (typeof CAT_THEME_NAMES)[number];\n/** Any theme identifier accepted by {@link ThemeScope}: `\"light\"`, `\"dark\"`, `\"system\"`, a {@link CatThemeName}, or a custom string. */\nexport type ThemeName = \"light\" | \"dark\" | \"system\" | CatThemeName | (string & {});\n\n/** A theme choice offered by {@link ThemePicker}/{@link ThemeToggle}: a `value` paired with a display `label`. */\nexport type ThemeOption = {\n  value: ThemeName;\n  label: string;\n};\n\n/** Value read from {@link theme}: the active theme, its resolved system value, a setter, and the available theme options. */\nexport type ThemeScopeValue = {\n  theme: () => ThemeName;\n  resolvedSystemTheme: () => \"light\" | \"dark\";\n  setTheme: (theme: ThemeName) => void;\n  themes: readonly ThemeOption[];\n  storageKey: string;\n};\n\n/** Props for the {@link ThemeScope} component. */\nexport type ThemeScopeProps = {\n  children?: unknown;\n  defaultTheme?: ThemeName;\n  themes?: readonly ThemeOption[];\n  storageKey?: string;\n};\n\n/** Props for the {@link ThemePicker} component. */\nexport type ThemePickerProps = Omit<\n  JSX.IntrinsicElements[\"select\"],\n  \"children\" | \"value\" | \"defaultValue\" | \"onChange\"\n> & {\n  themes?: readonly ThemeOption[];\n  label?: string;\n};\n\n/** Render context passed to a function-as-children {@link ThemeToggleProps.children}. */\nexport type ThemeToggleRenderContext = {\n  theme: ThemeName;\n  nextTheme: ThemeName;\n};\n\n/** Props for the {@link ThemeToggle} component. */\nexport type ThemeToggleProps = Omit<ButtonNativeProps, \"children\" | \"onPress\"> & {\n  children?: unknown | ((context: ThemeToggleRenderContext) => unknown);\n  lightIcon?: unknown;\n  darkIcon?: unknown;\n  systemIcon?: unknown;\n  themes?: readonly ThemeName[];\n  onPress?: (event: PressEvent) => void;\n};\n\n/** Default light/dark/system theme options used by {@link ThemeScope} and {@link ThemePicker}. */\nexport const DEFAULT_THEME_OPTIONS: readonly ThemeOption[] = [\n  { value: \"system\", label: \"System\" },\n  { value: \"light\", label: \"Light\" },\n  { value: \"dark\", label: \"Dark\" },\n];\n\n/** Theme options for the built-in \"cat\" theme presets, keyed to {@link CAT_THEME_NAMES}. */\nexport const CAT_THEME_OPTIONS: readonly ThemeOption[] = [\n  { value: \"tabby\", label: \"Tabby\" },\n  { value: \"ginger\", label: \"Ginger\" },\n  { value: \"tuxedo\", label: \"Tuxedo\" },\n  { value: \"calico\", label: \"Calico\" },\n  { value: \"torty\", label: \"Torty\" },\n];\n\nconst DEFAULT_STORAGE_KEY = \"askr-theme\";\nconst STATIC_CHILDREN = Symbol.for(\"askr.static-children\");\nconst documentThemeCoordinators = new WeakMap<Document, ThemeCoordinator>();\ntype ThemeCoordinator = ReturnType<typeof createThemeCoordinator>;\ntype InternalThemeScopeValue = ThemeScopeValue & {\n  readonly coordinator: ThemeCoordinator | null;\n  readonly depth: number;\n};\n\nconst ThemeScopeContext = defineScope<InternalThemeScopeValue>({\n  theme: () => \"system\",\n  resolvedSystemTheme: () => \"light\",\n  setTheme: () => undefined,\n  themes: DEFAULT_THEME_OPTIONS,\n  storageKey: DEFAULT_STORAGE_KEY,\n  coordinator: null,\n  depth: -1,\n});\n\n/** Reads the current {@link ThemeScopeValue} from the nearest enclosing {@link ThemeScope}. */\nexport function theme(): ThemeScopeValue {\n  return readScope(ThemeScopeContext);\n}\n\n/**\n * Establishes a theme boundary: tracks the active theme (persisted to\n * `localStorage` under `storageKey` and synced across tabs/scopes), resolves\n * the OS `\"system\"` preference, and reflects the choice onto the DOM via\n * `data-theme`/`data-theme-choice` attributes. Nested scopes cooperate\n * through a shared coordinator so the deepest explicitly-set scope wins.\n */\nexport function ThemeScope(props: ThemeScopeProps): JSX.Element {\n  const {\n    children,\n    defaultTheme = \"system\",\n    themes = DEFAULT_THEME_OPTIONS,\n    storageKey = DEFAULT_STORAGE_KEY,\n  } = props;\n\n  const scopeId = state<symbol>(Symbol(\"ThemeScope\"))();\n  const scopeSignal = getSignal();\n  // The first render must be identical on the server and in the browser.\n  // Browser persistence is adopted from the committed root ref, after Askr's\n  // hydration verifier has accepted the server markup.\n  const themeState = state<ThemeName>(defaultTheme);\n  const localResolvedSystemTheme = state<\"light\" | \"dark\">(\"light\");\n  const persistenceAdoption = state({ complete: false })();\n  const currentTheme = themeState();\n  const parentScope = readScope(ThemeScopeContext);\n  const ownedCoordinator = state<ThemeCoordinator>(getDefaultThemeCoordinator())();\n  const coordinator = parentScope.coordinator ?? ownedCoordinator;\n  const scopeDepth = parentScope.depth + 1;\n  coordinator.register(scopeId, scopeDepth, currentTheme, scopeSignal, (nextTheme) => {\n    if (themeState() !== nextTheme) themeState.set(nextTheme);\n  });\n\n  const setTheme = (nextTheme: ThemeName) => {\n    themeState.set(nextTheme);\n    writeStoredTheme(storageKey, nextTheme);\n    coordinator.activate(scopeId, nextTheme);\n  };\n\n  const resolvedSystemTheme = parentScope.coordinator\n    ? parentScope.resolvedSystemTheme\n    : localResolvedSystemTheme;\n  const value: InternalThemeScopeValue = {\n    theme: themeState,\n    resolvedSystemTheme,\n    setTheme,\n    themes,\n    storageKey,\n    coordinator,\n    depth: scopeDepth,\n  };\n\n  return (\n    <ThemeScopeContext value={value}>\n      <div\n        data-slot=\"theme-scope\"\n        ref={\n          parentScope.coordinator === null\n            ? (element: HTMLElement | null) => {\n                coordinator.attach(\n                  element,\n                  (nextTheme) => localResolvedSystemTheme.set(nextTheme),\n                  scopeSignal,\n                );\n                if (element && typeof window !== \"undefined\") {\n                  const onStorage = (event: StorageEvent) => {\n                    let storageMatches = event.storageArea == null;\n                    try {\n                      storageMatches ||= event.storageArea === window.localStorage;\n                    } catch {\n                      // Locked-down/private contexts may deny access to localStorage.\n                    }\n                    if (!storageMatches || event.key !== storageKey) {\n                      return;\n                    }\n                    const nextTheme = event.newValue as ThemeName | null;\n                    if (!nextTheme) return;\n                    themeState.set(nextTheme);\n                    coordinator.activate(scopeId, nextTheme);\n                  };\n                  window.addEventListener(\"storage\", onStorage);\n                  scopeSignal.addEventListener(\n                    \"abort\",\n                    () => window.removeEventListener(\"storage\", onStorage),\n                    { once: true },\n                  );\n                }\n                if (!element || persistenceAdoption.complete) return;\n                persistenceAdoption.complete = true;\n                const storedTheme = readStoredTheme(storageKey);\n                if (storedTheme && storedTheme !== themeState()) {\n                  themeState.set(storedTheme);\n                  coordinator.activate(scopeId, storedTheme);\n                }\n              }\n            : undefined\n        }\n      >\n        {children}\n      </div>\n    </ThemeScopeContext>\n  );\n}\n\nfunction getDefaultThemeCoordinator(): ThemeCoordinator {\n  if (typeof document === \"undefined\") {\n    return createThemeCoordinator();\n  }\n\n  const existing = documentThemeCoordinators.get(document);\n  if (existing) return existing;\n\n  const coordinator = createThemeCoordinator();\n  documentThemeCoordinators.set(document, coordinator);\n  return coordinator;\n}\n\nfunction removeEmptyGeneratedStyleRegistries(root: Node | null): void {\n  const ownerDocument =\n    root?.nodeType === 9\n      ? (root as Document)\n      : (root?.ownerDocument ?? (typeof document === \"undefined\" ? null : document));\n  if (!ownerDocument) return;\n\n  for (const registry of ownerDocument.querySelectorAll<HTMLStyleElement>(\n    \"style[data-askr-style-registry]\",\n  )) {\n    if (!registry.textContent?.trim()) registry.remove();\n  }\n}\n\nfunction createThemeCoordinator() {\n  const scopes = new Map<\n    symbol,\n    {\n      depth: number;\n      sequence: number;\n      theme: ThemeName;\n      signal: AbortSignal;\n      onThemeChange: (themeName: ThemeName) => void;\n    }\n  >();\n  let nextSequence = 0;\n  let explicitOwner: symbol | undefined;\n  let root: Node | null = null;\n  let scheduled = false;\n\n  const target = (): HTMLElement | null => {\n    if (root?.nodeType === 9) return (root as Document).documentElement;\n    if (root && \"host\" in root) return (root as ShadowRoot).host as HTMLElement;\n    return typeof document === \"undefined\" ? null : document.documentElement;\n  };\n  const syncActive = (): void => {\n    if (explicitOwner !== undefined) return;\n    let candidate: { depth: number; sequence: number; theme: ThemeName } | undefined;\n    for (const scope of scopes.values()) {\n      if (\n        !candidate ||\n        scope.depth > candidate.depth ||\n        (scope.depth === candidate.depth && scope.sequence > candidate.sequence)\n      ) {\n        candidate = scope;\n      }\n    }\n    if (candidate) syncThemeTarget(target(), candidate.theme);\n  };\n  const schedule = (): void => {\n    if (typeof document === \"undefined\" || scheduled) return;\n    scheduled = true;\n    setTimeout(() => {\n      scheduled = false;\n      syncActive();\n      if (scopes.size === 0) removeEmptyGeneratedStyleRegistries(root);\n    }, 0);\n  };\n\n  return Object.freeze({\n    attach(\n      element: HTMLElement | null,\n      onResolvedSystemTheme: (themeName: \"light\" | \"dark\") => void,\n      signal: AbortSignal,\n    ) {\n      if (element) root = element.getRootNode();\n      if (element && typeof window !== \"undefined\" && typeof window.matchMedia === \"function\") {\n        const media = window.matchMedia(\"(prefers-color-scheme: dark)\");\n        const update = () => onResolvedSystemTheme(media.matches ? \"dark\" : \"light\");\n        update();\n        media.addEventListener?.(\"change\", update);\n        signal.addEventListener(\"abort\", () => media.removeEventListener?.(\"change\", update), {\n          once: true,\n        });\n      }\n      schedule();\n    },\n    register(\n      id: symbol,\n      depth: number,\n      themeName: ThemeName,\n      signal: AbortSignal,\n      onThemeChange: (themeName: ThemeName) => void,\n    ) {\n      const existing = scopes.get(id);\n      scopes.set(id, {\n        depth,\n        sequence: existing?.sequence ?? nextSequence++,\n        theme: themeName,\n        signal,\n        onThemeChange,\n      });\n      if (!existing) {\n        signal.addEventListener(\n          \"abort\",\n          () => {\n            scopes.delete(id);\n            if (explicitOwner === id) explicitOwner = undefined;\n            schedule();\n          },\n          { once: true },\n        );\n      }\n      schedule();\n    },\n    activate(id: symbol, themeName: ThemeName) {\n      const scope = scopes.get(id);\n      if (scope) scope.theme = themeName;\n      explicitOwner = id;\n      const ownerDepth = scope?.depth;\n      for (const [scopeId, registered] of scopes) {\n        if (scopeId !== id && registered.depth === ownerDepth) {\n          registered.theme = themeName;\n          registered.onThemeChange(themeName);\n        }\n      }\n      syncThemeTarget(target(), themeName);\n    },\n  });\n}\n\n/** A `<select>` bound to the current {@link theme}, listing `themes` (defaults to the enclosing scope's options). */\nexport function ThemePicker(props: ThemePickerProps): JSX.Element {\n  const activeTheme = theme();\n  const { themes = activeTheme.themes, label = \"Theme\", ...rest } = props;\n  const currentTheme = activeTheme.theme();\n\n  return (\n    <select\n      {...rest}\n      aria-label={rest[\"aria-label\"] ?? label}\n      data-slot=\"theme-picker\"\n      value={currentTheme}\n      onChange={(event: Event) => {\n        const target = getThemePickerTarget(event);\n        if (target) {\n          activeTheme.setTheme(target.value as ThemeName);\n        }\n      }}\n    >\n      {themes.map((option) => (\n        <option key={option.value} value={option.value} selected={option.value === currentTheme}>\n          {option.label}\n        </option>\n      ))}\n    </select>\n  );\n}\n\nfunction getThemePickerTarget(event: Event): HTMLSelectElement | null {\n  if (typeof HTMLSelectElement === \"undefined\") {\n    return null;\n  }\n\n  const path = typeof event.composedPath === \"function\" ? event.composedPath() : [];\n  const candidates = [event.target, event.currentTarget, ...path];\n\n  for (const candidate of candidates) {\n    if (candidate instanceof HTMLSelectElement) {\n      return candidate;\n    }\n  }\n\n  return null;\n}\n\n/**\n * A button that cycles through `themes` (defaults to `[\"light\", \"dark\"]`) on\n * press. Supports icon props per theme, or a function-as-children render\n * prop receiving {@link ThemeToggleRenderContext}.\n */\nexport function ThemeToggle(props: ThemeToggleProps): JSX.Element {\n  const activeTheme = theme();\n  const {\n    children,\n    lightIcon,\n    darkIcon,\n    systemIcon,\n    themes = [\"light\", \"dark\"],\n    onPress,\n    ...rest\n  } = props;\n\n  const currentTheme = activeTheme.theme();\n  const nextTheme = getNextTheme(currentTheme, themes, activeTheme.resolvedSystemTheme());\n  const renderContext = { theme: currentTheme, nextTheme };\n  const ariaLabel = (rest as Record<string, unknown>)[\"aria-label\"];\n  const themedIcon = resolveThemeToggleIcon(currentTheme, nextTheme, {\n    lightIcon,\n    darkIcon,\n    systemIcon,\n  });\n  const renderedIcon = cloneThemeToggleIcon(themedIcon, currentTheme);\n  const renderedIconSlots =\n    renderThemeToggleIconSlots(currentTheme, {\n      lightIcon,\n      darkIcon,\n      systemIcon,\n    }) ?? renderedIcon;\n  const content =\n    typeof children === \"function\" ? children(renderContext) : (children ?? renderedIconSlots);\n\n  return (\n    <Button\n      {...(rest as ButtonNativeProps)}\n      aria-label={typeof ariaLabel === \"string\" ? ariaLabel : `Switch to ${nextTheme} theme`}\n      data-theme-control=\"toggle\"\n      data-theme-choice={currentTheme}\n      data-next-theme={nextTheme}\n      onPress={(event) => {\n        onPress?.(event);\n        if (!event.defaultPrevented && !Object.is(nextTheme, currentTheme)) {\n          activeTheme.setTheme(nextTheme);\n        }\n      }}\n    >\n      <span data-slot=\"theme-toggle-content\">{content}</span>\n    </Button>\n  );\n}\n\nfunction getNextTheme(\n  currentTheme: ThemeName,\n  themes: readonly ThemeName[],\n  resolvedSystemTheme: \"light\" | \"dark\" = \"light\",\n): ThemeName {\n  if (themes.length === 0) return currentTheme;\n  const index = themes.indexOf(currentTheme);\n  if (index < 0 && currentTheme === \"system\") {\n    if (themes.includes(\"light\") && themes.includes(\"dark\")) {\n      return resolvedSystemTheme === \"dark\" ? \"light\" : \"dark\";\n    }\n  }\n  return themes[index >= 0 && index < themes.length - 1 ? index + 1 : 0]!;\n}\n\nfunction getThemeIcon(\n  theme: ThemeName,\n  icons: Pick<ThemeToggleProps, \"lightIcon\" | \"darkIcon\" | \"systemIcon\">,\n): unknown {\n  if (theme === \"light\") return icons.lightIcon;\n  if (theme === \"dark\") return icons.darkIcon;\n  if (theme === \"system\") return icons.systemIcon;\n  return undefined;\n}\n\nexport function resolveThemeToggleIcon(\n  theme: ThemeName,\n  nextTheme: ThemeName,\n  icons: Pick<ThemeToggleProps, \"lightIcon\" | \"darkIcon\" | \"systemIcon\">,\n): unknown {\n  return getThemeIcon(theme, icons) ?? getThemeIcon(nextTheme, icons);\n}\n\nfunction renderThemeToggleIconSlots(\n  theme: ThemeName,\n  icons: Pick<ThemeToggleProps, \"lightIcon\" | \"darkIcon\" | \"systemIcon\">,\n): unknown {\n  if (getThemeIcon(theme, icons) === undefined) {\n    return undefined;\n  }\n\n  const slots = [\n    [\"light\", icons.lightIcon],\n    [\"dark\", icons.darkIcon],\n    [\"system\", icons.systemIcon],\n  ] as const;\n  const availableSlots = slots.filter(([, icon]) => icon !== undefined && icon !== null);\n\n  if (availableSlots.length <= 1) {\n    return undefined;\n  }\n\n  return availableSlots.map(([slotTheme, icon]) => (\n    <span\n      key={slotTheme}\n      data-slot=\"theme-toggle-icon\"\n      data-theme-toggle-icon={slotTheme}\n      hidden={slotTheme === theme ? undefined : true}\n    >\n      {cloneThemeToggleIcon(icon, slotTheme)}\n    </span>\n  ));\n}\n\nfunction cloneThemeToggleIcon(icon: unknown, key?: string): unknown {\n  if (Array.isArray(icon)) {\n    const clonedChildren = icon.map((child) => cloneThemeToggleIcon(child));\n    if ((icon as unknown as Record<symbol, unknown>)[STATIC_CHILDREN] === true) {\n      Object.defineProperty(clonedChildren, STATIC_CHILDREN, {\n        value: true,\n        configurable: true,\n      });\n    }\n    return clonedChildren;\n  }\n\n  if (!isElement(icon)) return icon;\n\n  const props = icon.props as Record<string, unknown> | undefined;\n  const clonedProps = props ? { ...props } : {};\n\n  if (\"children\" in clonedProps) {\n    clonedProps.children = cloneThemeToggleIcon(clonedProps.children);\n  }\n\n  const clonedIcon = cloneElement(icon, clonedProps);\n  return {\n    ...clonedIcon,\n    key: icon.key ?? key ?? null,\n  } satisfies JSXElement;\n}\n\nfunction syncThemeTarget(\n  html: HTMLElement | null,\n  themeChoice: ThemeName | null | undefined,\n): void {\n  if (!html) return;\n\n  if (themeChoice == null) {\n    html.removeAttribute(\"data-theme\");\n    html.removeAttribute(\"data-theme-choice\");\n    return;\n  }\n\n  html.setAttribute(\"data-theme-choice\", themeChoice);\n\n  if (themeChoice === \"system\") {\n    html.removeAttribute(\"data-theme\");\n  } else {\n    html.setAttribute(\"data-theme\", themeChoice);\n  }\n}\n\nfunction readStoredTheme(storageKey: string): ThemeName | undefined {\n  if (typeof window === \"undefined\") return undefined;\n  try {\n    const storedTheme = window.localStorage.getItem(storageKey);\n    return storedTheme ? (storedTheme as ThemeName) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction writeStoredTheme(storageKey: string, theme: ThemeName): void {\n  if (typeof window === \"undefined\") return;\n  try {\n    window.localStorage.setItem(storageKey, theme);\n  } catch {\n    // Storage can be unavailable in private or locked-down browser contexts.\n  }\n}\n"],"mappings":"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"}

package/dist/components/toolbar/toolbar.d.ts

@@ -1,6 +1,7 @@
 import { ToolbarProps } from "./toolbar.types.js";
 import { JSX } from "@askrjs/askr/jsx-runtime";
 //#region src/components/toolbar/toolbar.d.ts
+/** Titled toolbar row with an actions area, wrapping to a new line on small screens. */
 declare function Toolbar(props: ToolbarProps): JSX.Element;
 //#endregion
 export { Toolbar };

package/dist/components/toolbar/toolbar.js

@@ -1,6 +1,7 @@
 import { Block } from "../block/block.js";
 import { jsx, jsxs } from "@askrjs/askr/jsx-runtime";
 //#region src/components/toolbar/toolbar.tsx
+/** Titled toolbar row with an actions area, wrapping to a new line on small screens. */
 function Toolbar(props) {
 	const { title, actions, ...rest } = props;
 	return /* @__PURE__ */ jsxs(Block, {

package/dist/components/toolbar/toolbar.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolbar.js","names":[],"sources":["../../../src/components/toolbar/toolbar.tsx"],"sourcesContent":["import type { JSX } from \"@askrjs/askr/jsx-runtime\";\nimport { Block } from \"../block\";\nimport type { ToolbarProps } from \"./toolbar.types\";\n\nexport function Toolbar(props: ToolbarProps): JSX.Element {\n  const { title, actions, ...rest } = props;\n\n  return (\n    <Block\n      rowFrom=\"md\"\n      align={{ base: \"start\", md: \"center\" }}\n      justify=\"between\"\n      gap=\"md\"\n      {...rest}\n      data-slot=\"toolbar\"\n    >\n      <h2 data-slot=\"toolbar-title\">{title}</h2>\n      {actions !== undefined ? (\n        <Block direction=\"row\" gap=\"sm\" data-slot=\"toolbar-actions\">\n          {actions}\n        </Block>\n      ) : null}\n    </Block>\n  );\n}\n"],"mappings":";;;AAIA,SAAgB,QAAQ,OAAkC;CACxD,MAAM,EAAE,OAAO,SAAS,GAAG,SAAS;CAEpC,OACE,qBAAC,OAAD;EACE,SAAQ;EACR,OAAO;GAAE,MAAM;GAAS,IAAI;EAAS;EACrC,SAAQ;EACR,KAAI;EACJ,GAAI;EACJ,aAAU;EANZ,UAAA,CAQE,oBAAC,MAAD;GAAI,aAAU;GAAiB,UAAA;EAAU,CAAA,GACxC,YAAY,KAAA,IACX,oBAAC,OAAD;GAAO,WAAU;GAAM,KAAI;GAAK,aAAU;GACvC,UAAA;EACI,CAAA,IACL,IACC;;AAEX"}
+{"version":3,"file":"toolbar.js","names":[],"sources":["../../../src/components/toolbar/toolbar.tsx"],"sourcesContent":["import type { JSX } from \"@askrjs/askr/jsx-runtime\";\nimport { Block } from \"../block\";\nimport type { ToolbarProps } from \"./toolbar.types\";\n\n/** Titled toolbar row with an actions area, wrapping to a new line on small screens. */\nexport function Toolbar(props: ToolbarProps): JSX.Element {\n  const { title, actions, ...rest } = props;\n\n  return (\n    <Block\n      rowFrom=\"md\"\n      align={{ base: \"start\", md: \"center\" }}\n      justify=\"between\"\n      gap=\"md\"\n      {...rest}\n      data-slot=\"toolbar\"\n    >\n      <h2 data-slot=\"toolbar-title\">{title}</h2>\n      {actions !== undefined ? (\n        <Block direction=\"row\" gap=\"sm\" data-slot=\"toolbar-actions\">\n          {actions}\n        </Block>\n      ) : null}\n    </Block>\n  );\n}\n"],"mappings":";;;;AAKA,SAAgB,QAAQ,OAAkC;CACxD,MAAM,EAAE,OAAO,SAAS,GAAG,SAAS;CAEpC,OACE,qBAAC,OAAD;EACE,SAAQ;EACR,OAAO;GAAE,MAAM;GAAS,IAAI;EAAS;EACrC,SAAQ;EACR,KAAI;EACJ,GAAI;EACJ,aAAU;EANZ,UAAA,CAQE,oBAAC,MAAD;GAAI,aAAU;GAAiB,UAAA;EAAU,CAAA,GACxC,YAAY,KAAA,IACX,oBAAC,OAAD;GAAO,WAAU;GAAM,KAAI;GAAK,aAAU;GACvC,UAAA;EACI,CAAA,IACL,IACC;;AAEX"}

package/dist/components/toolbar/toolbar.types.d.ts

@@ -1,6 +1,7 @@
 import { BlockDivProps } from "../block/block.types.js";
 import "../block/index.js";
 //#region src/components/toolbar/toolbar.types.d.ts
+/** Props for the {@link Toolbar} component. */
 type ToolbarProps = BlockDivProps & {
   title: unknown;
   actions?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/themes",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Default theme tokens, styles, and component presets for Askr apps.",
   "keywords": [
     "askr",

package/src/components/_internal/style.ts

@@ -4,6 +4,7 @@ const cssPropertyNameCache = new Map<string, string>();
 const MAX_PROPERTY_CACHE = 256;
 
 const CSS_UNSAFE_RE = /[{}<>\\]/;
+const CSS_COMMENT_DELIMITER_RE = /\/\*|\*\//;
 const CSS_URI_SCHEME_RE = /(?:^|[\s(,])([a-z][a-z0-9+.-]*):/i;
 const CSS_FUNCTION_NAME_RE = /([a-z-][a-z0-9-]*)\s*\(/gi;
 const CSS_ALLOWED_FUNCTIONS = new Set([
@@ -57,7 +58,13 @@ function isSafeCssPropertyName(name: string): boolean {
 }
 
 function isSafeCssValue(value: string): boolean {
-  if (CSS_UNSAFE_RE.test(value) || CSS_URI_SCHEME_RE.test(value)) return false;
+  if (
+    CSS_UNSAFE_RE.test(value) ||
+    CSS_COMMENT_DELIMITER_RE.test(value) ||
+    CSS_URI_SCHEME_RE.test(value)
+  ) {
+    return false;
+  }
 
   for (const match of value.matchAll(CSS_FUNCTION_NAME_RE)) {
     if (!CSS_ALLOWED_FUNCTIONS.has(match[1]!.toLowerCase())) return false;

package/src/components/alert/alert.tsx

@@ -11,6 +11,11 @@ function resolveAlertRole(variant: AlertProps["variant"] | undefined): "alert" |
   return "status";
 }
 
+/**
+ * Renders an alert/status banner with an optional icon, title, description,
+ * actions, and a dismiss button. Automatically picks an "alert" or "status"
+ * ARIA role from `variant` unless `role` is set explicitly.
+ */
 export function Alert(props: AlertProps): JSX.Element {
   const {
     actions,

package/src/components/alert/alert.types.ts

@@ -1,11 +1,14 @@
 import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Visual tone of an {@link AlertProps} alert; `"danger"`/`"warning"` render with `role="alert"`. */
 export type AlertVariant = "default" | "info" | "success" | "warning" | "danger";
+/** Heading tag allowed for an alert's title via `titleAs`. */
 export type AlertHeadingTag = "h2" | "h3" | "h4" | "h5" | "h6";
 
 type DivProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref">;
 
+/** Props for the {@link Alert} component. */
 export type AlertProps = DivProps & {
   actions?: unknown;
   children?: unknown;

package/src/components/aside/aside.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { Block } from "../block";
 import type { AsideProps } from "./aside.types";
 
+/** Renders a `<aside>`-element {@link Block} tagged with `data-slot="aside"`. */
 export function Aside(props: AsideProps): JSX.Element {
   const { children, ...rest } = props;
 

package/src/components/aside/aside.types.ts

@@ -1,3 +1,4 @@
 import type { BlockElementProps } from "../block";
 
+/** Props for the {@link Aside} component. */
 export type AsideProps = Omit<BlockElementProps<"aside">, "as">;

package/src/components/aspect-ratio/aspect-ratio.tsx

@@ -6,6 +6,11 @@ import { styleDeclarationsToClass } from "../_internal/style";
 import { intrinsicElement } from "../_internal/jsx";
 import type { AspectRatioAsChildProps, AspectRatioProps } from "./aspect-ratio.types";
 
+/**
+ * Constrains its content to a fixed width/height ratio (defaults to `1`)
+ * using a computed `aspect-ratio` style, rendering as a `<div>` or, with
+ * `asChild`, merging its layout into the single child element.
+ */
 export function AspectRatio(props: AspectRatioProps): JSX.Element;
 export function AspectRatio(props: AspectRatioAsChildProps): JSX.Element;
 export function AspectRatio(props: AspectRatioProps | AspectRatioAsChildProps) {

package/src/components/aspect-ratio/aspect-ratio.types.ts

@@ -2,18 +2,21 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { JSXElement } from "@askrjs/askr/foundations";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Props shared by both {@link AspectRatio} call signatures. */
 export type AspectRatioOwnProps = {
   children?: unknown;
   ratio?: number | string;
   style?: unknown;
 };
 
+/** Props for {@link AspectRatio} rendered as its default `<div>` element. */
 export type AspectRatioProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref"> &
   AspectRatioOwnProps & {
     asChild?: false;
     ref?: Ref<HTMLDivElement>;
   };
 
+/** Props for {@link AspectRatio} rendered with `asChild`, merging layout onto a single child element. */
 export type AspectRatioAsChildProps = AspectRatioOwnProps & {
   asChild: true;
   children: JSXElement;

package/src/components/badge/badge.tsx

@@ -9,6 +9,7 @@ function normalizeBadgeVariant(variant: BadgeProps["variant"] | undefined) {
   return variant && variant !== "default" ? `badge-${variant}` : undefined;
 }
 
+/** Renders a small status/label badge, defaulting to a `<span>` (or merging onto a child via `asChild`), with a `variant` color modifier. */
 export function Badge(props: BadgeProps): JSX.Element;
 export function Badge(props: BadgeAsChildProps): JSX.Element;
 export function Badge(props: BadgeProps | BadgeAsChildProps) {

package/src/components/badge/badge.types.ts

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { JSXElement } from "@askrjs/askr/foundations";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Visual tone of a {@link BadgeProps} badge. */
 export type BadgeVariant =
   | "default"
   | "secondary"
@@ -11,17 +12,20 @@ export type BadgeVariant =
   | "danger"
   | "info";
 
+/** Props shared by both {@link Badge} call signatures. */
 export type BadgeOwnProps = {
   children?: unknown;
   variant?: BadgeVariant;
 };
 
+/** Props for {@link Badge} rendered as its default `<span>` element. */
 export type BadgeProps = Omit<JSX.IntrinsicElements["span"], "children" | "ref"> &
   BadgeOwnProps & {
     asChild?: false;
     ref?: Ref<HTMLSpanElement>;
   };
 
+/** Props for {@link Badge} rendered with `asChild`, merging its attributes onto a single child element. */
 export type BadgeAsChildProps = BadgeOwnProps & {
   asChild: true;
   children: JSXElement;

package/src/components/block/block.tsx

@@ -13,6 +13,12 @@ import type { BlockAsChildProps, BlockNativeProps } from "./block.types";
 
 const DEFAULT_ELEMENT = "div";
 
+/**
+ * Low-level layout primitive: renders any element in {@link BlockElement}
+ * (default `<div>`) and turns layout-only props (spacing, alignment,
+ * direction, sizing, etc.) into a generated utility class. With `asChild`,
+ * the layout is merged onto a single child element instead of a wrapper.
+ */
 export function Block(props: BlockNativeProps): JSX.Element;
 export function Block(props: BlockAsChildProps): JSX.Element;
 export function Block(props: BlockNativeProps | BlockAsChildProps) {

package/src/components/block/block.types.ts

@@ -32,6 +32,7 @@ export type {
   ResponsiveValue as BlockResponsiveValue,
 };
 
+/** Element tags {@link Block} can render as via its `as` prop. */
 export type BlockElement =
   | "div"
   | "span"
@@ -48,12 +49,14 @@ export type BlockElement =
   | "form"
   | "article";
 
+/** Layout and structural props accepted by {@link Block}, independent of the rendered element. */
 export type BlockOwnProps = BlockLayoutProps & {
   as?: BlockElement;
   children?: unknown;
   className?: string;
 };
 
+/** {@link Block} props specialized for a given {@link BlockElement} tag `TElement`. */
 export type BlockElementProps<TElement extends BlockElement> = Omit<
   JSX.IntrinsicElements[TElement],
   "children" | "ref"
@@ -64,16 +67,21 @@ export type BlockElementProps<TElement extends BlockElement> = Omit<
     ref?: Ref<unknown>;
   };
 
+/** Union of {@link BlockElementProps} across every {@link BlockElement}, used for {@link Block}'s native (non-`asChild`) overload. */
 export type BlockNativeProps = {
   [TElement in BlockElement]: BlockElementProps<TElement>;
 }[BlockElement];
 
+/** Props for {@link Block} rendered with `asChild`, merging layout onto a single child element. */
 export type BlockAsChildProps = Omit<BlockOwnProps, "as"> & {
   asChild: true;
   children: JSXElement;
   ref?: Ref<unknown>;
 };
 
+/** {@link Block} props specialized for a `<div>` element. */
 export type BlockDivProps = BlockElementProps<"div">;
+/** {@link Block} props specialized for a `<span>` element. */
 export type BlockSpanProps = BlockElementProps<"span">;
+/** Union of all prop shapes accepted by {@link Block}. */
 export type BlockProps = BlockNativeProps | BlockAsChildProps;

package/src/components/brand/brand.tsx

@@ -13,6 +13,7 @@ import type {
 
 const DEFAULT_ELEMENT = "div";
 
+/** Renders a brand/logo wrapper, defaulting to a `<div>` (or `<a>`/`<span>` via `as`), or merges onto a single child via `asChild`. */
 export function Brand<TElement extends "div" | "a" | "span" = "div">(
   props: BrandProps<TElement>,
 ): JSX.Element {
@@ -42,6 +43,7 @@ export function Brand<TElement extends "div" | "a" | "span" = "div">(
   return intrinsicElement(as ?? DEFAULT_ELEMENT, finalProps, children);
 }
 
+/** Renders the icon/mark portion of a {@link Brand}. */
 export function BrandMark(props: BrandMarkProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -53,6 +55,7 @@ export function BrandMark(props: BrandMarkProps): JSX.Element {
   return <span {...finalProps}>{children}</span>;
 }
 
+/** Renders the text label portion of a {@link Brand}. */
 export function BrandLabel(props: BrandLabelProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {

package/src/components/brand/brand.types.ts

@@ -1,6 +1,7 @@
 import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Element tags {@link Brand} can render as via its `as` prop. */
 export type BrandElement = "div" | "a" | "span";
 
 type BrandIntrinsicProps<TElement extends BrandElement> = Omit<
@@ -9,6 +10,7 @@ type BrandIntrinsicProps<TElement extends BrandElement> = Omit<
 >;
 type SpanProps = Omit<JSX.IntrinsicElements["span"], "children" | "ref">;
 
+/** {@link Brand} props for its native (non-`asChild`) rendering, specialized for a given {@link BrandElement} `TElement`. */
 export type BrandNativeProps<TElement extends BrandElement = "div"> =
   BrandIntrinsicProps<TElement> & {
     as?: TElement;
@@ -17,6 +19,7 @@ export type BrandNativeProps<TElement extends BrandElement = "div"> =
     ref?: Ref<HTMLElement>;
   };
 
+/** Props for {@link Brand} rendered with `asChild`, merging its attributes onto a single child element. */
 export type BrandAsChildProps = {
   asChild: true;
   children: JSX.Element;
@@ -25,15 +28,18 @@ export type BrandAsChildProps = {
   ref?: Ref<HTMLElement>;
 };
 
+/** Union of all prop shapes accepted by {@link Brand}. */
 export type BrandProps<TElement extends BrandElement = "div"> =
   | BrandNativeProps<TElement>
   | BrandAsChildProps;
 
+/** Props for the {@link BrandMark} component. */
 export type BrandMarkProps = SpanProps & {
   children?: unknown;
   ref?: Ref<HTMLSpanElement>;
 };
 
+/** Props for the {@link BrandLabel} component. */
 export type BrandLabelProps = SpanProps & {
   children?: unknown;
   ref?: Ref<HTMLSpanElement>;

package/src/components/button-group/button-group.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { classes } from "../_internal/classes";
 import { ButtonGroupProps } from "./button-group.types";
 
+/** Groups related buttons together, optionally visually attached, with a horizontal or vertical orientation and `role="group"` by default. */
 export function ButtonGroup(props: ButtonGroupProps): JSX.Element {
   const {
     attached = true,

package/src/components/button-group/button-group.types.ts

@@ -1,10 +1,12 @@
 import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Layout direction of a {@link ButtonGroup}. */
 export type ButtonGroupOrientation = "horizontal" | "vertical";
 
 type DivProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref">;
 
+/** Props for the {@link ButtonGroup} component. */
 export type ButtonGroupProps = DivProps & {
   children?: unknown;
   attached?: boolean;