@adea-ai/ui 0.123.1 → 0.124.0

package/dist/r/src/lib/themes.ts

@@ -57,6 +57,7 @@ import {
   type ContrastFinding,
 } from '@adea-ai/themes'
 import { shadcnVariables } from '@adea-ai/themes/adapters/shadcn'
+import { oklchToHex, parseColor } from '@adea-ai/themes/oklch'
 import { isThemeAccentId } from './theme-accents'
 
 export { isThemeAccentId } from './theme-accents'
@@ -179,10 +180,24 @@ export type ThemeVariant = {
   /** The categorical series, in order. */
   chart: readonly string[]
   provenance: ThemeProvenance
+  /**
+   * Custom properties written verbatim over {@link themeCssVariables}, last.
+   *
+   * For a variant a host built from data it does not control the derivation of —
+   * an imported theme whose painted colours must stay exactly what the user
+   * imported. The catalogue's own variants never carry it, so the derived roles
+   * stay the only source of truth for them.
+   */
+  tokens?: Readonly<Record<string, string>>
 }
 
-/** Builds the design system's view of one catalogue entry. */
-function toVariant(theme: AdeaThemeRecord): ThemeVariant {
+/**
+ * The shadcn-vocabulary roles of one catalogue entry.
+ *
+ * The expensive half of a variant: `shadcnVariables` projects the whole palette
+ * (about 4 ms a theme), which is why {@link lazyVariant} defers it.
+ */
+function colorsOf(theme: AdeaThemeRecord): ThemeColors {
   const projected = shadcnVariables(theme)
   const token = (name: string): string => {
     const value = projected[`--${name}`]
@@ -190,7 +205,7 @@ function toVariant(theme: AdeaThemeRecord): ThemeVariant {
     return value
   }
   const destructiveAction = shadcnDestructiveProjection(theme)
-  const colors: ThemeColors = {
+  return {
     background: token('background'),
     foreground: token('foreground'),
     card: token('card'),
@@ -231,8 +246,62 @@ function toVariant(theme: AdeaThemeRecord): ThemeVariant {
     sidebarBorder: token('sidebar-border'),
     sidebarMutedForeground: token('sidebar-muted-foreground'),
   }
+}
+
+// The embedded terminal uses the theme's own canvas rather than a palette of its
+// own. The ANSI colours came from the palette that produced the canvas, so they
+// were chosen against it; a terminal on a different background would be the one
+// surface in the application not lit by the active theme.
+function terminalOf(theme: AdeaThemeRecord): ThemeTerminalPalette {
+  return {
+    background: theme.colors.background,
+    foreground: theme.colors.foreground,
+    cursor: theme.cursor,
+    selection: theme.selection,
+    ...theme.ansi,
+  }
+}
+
+function editorOf(theme: AdeaThemeRecord): ThemeEditorPalette {
   const syntax = syntaxRoles(theme)
+  return {
+    keyword: syntax.keyword,
+    string: syntax.string,
+    number: syntax.number,
+    comment: syntax.comment,
+    function: syntax.function,
+    variable: syntax.variable,
+    type: syntax.type,
+    tag: syntax.tag,
+    attribute: syntax.attribute,
+    operator: syntax.operator,
+    heading: syntax.heading,
+    link: syntax.link,
+    diffAdd: syntax.diffAdd,
+    diffDelete: syntax.diffDelete,
+    diffHunk: syntax.diffHunk,
+    searchMatch: syntax.searchMatch,
+  }
+}
 
+function provenanceOf(theme: AdeaThemeRecord): ThemeProvenance {
+  return {
+    source: theme.provenance.project,
+    url: theme.provenance.url,
+    license: theme.provenance.license,
+  }
+}
+
+/**
+ * The design system's view of one catalogue record, built in full and at once.
+ *
+ * For a host that holds a record the catalogue does not — an imported theme, a
+ * reconstruction from stored data — and wants a variant it can hand to
+ * `ThemeProvider`'s `themes`. It throws for a record the shadcn projection cannot
+ * map, here and now, rather than on first paint. The catalogue itself goes through
+ * {@link lazyVariant} instead.
+ */
+export function variantFromRecord(theme: AdeaThemeRecord): ThemeVariant {
   return {
     id: theme.id,
     family: theme.family,
@@ -240,45 +309,62 @@ function toVariant(theme: AdeaThemeRecord): ThemeVariant {
     label: theme.label,
     appearance: theme.appearance,
     description: theme.description,
-    colors,
-    terminal: {
-      // The embedded terminal uses the theme's own canvas rather than a palette of its
-      // own. The ANSI colours came from the palette that produced the canvas, so they
-      // were chosen against it; a terminal on a different background would be the one
-      // surface in the application not lit by the active theme.
-      background: theme.colors.background,
-      foreground: theme.colors.foreground,
-      cursor: theme.cursor,
-      selection: theme.selection,
-      ...theme.ansi,
-    },
-    editor: {
-      keyword: syntax.keyword,
-      string: syntax.string,
-      number: syntax.number,
-      comment: syntax.comment,
-      function: syntax.function,
-      variable: syntax.variable,
-      type: syntax.type,
-      tag: syntax.tag,
-      attribute: syntax.attribute,
-      operator: syntax.operator,
-      heading: syntax.heading,
-      link: syntax.link,
-      diffAdd: syntax.diffAdd,
-      diffDelete: syntax.diffDelete,
-      diffHunk: syntax.diffHunk,
-      searchMatch: syntax.searchMatch,
-    },
+    colors: colorsOf(theme),
+    terminal: terminalOf(theme),
+    editor: editorOf(theme),
     chart: chartSeries(theme),
-    provenance: {
-      source: theme.provenance.project,
-      url: theme.provenance.url,
-      license: theme.provenance.license,
-    },
+    provenance: provenanceOf(theme),
+  }
+}
+
+/** Runs `build` on first call and returns that value from then on. A throw is not cached. */
+function once<T>(build: () => T): () => T {
+  let built = false
+  let value: T
+  return () => {
+    if (!built) {
+      value = build()
+      built = true
+    }
+    return value
   }
 }
 
+const lazy = <T>(build: () => T): PropertyDescriptor => ({
+  get: once(build),
+  enumerable: true,
+})
+
+/**
+ * {@link variantFromRecord} with the four derived palettes built on first read.
+ *
+ * Evaluating this module used to project all 34 catalogue themes up front, about
+ * 155 ms before a single one was needed, on the hydration path of every consumer.
+ * A page paints one variant, and a picker's labels and appearance are plain
+ * fields, so only a variant whose `colors`, `terminal`, `editor` or `chart` is read
+ * pays for them, once. The properties stay enumerable data-shaped accessors, so
+ * spreading, `Object.entries` and JSON see the same object they always did.
+ */
+function lazyVariant(theme: AdeaThemeRecord): ThemeVariant {
+  return Object.defineProperties(
+    {
+      id: theme.id,
+      family: theme.family,
+      familyLabel: theme.familyLabel,
+      label: theme.label,
+      appearance: theme.appearance,
+      description: theme.description,
+      provenance: provenanceOf(theme),
+    },
+    {
+      colors: lazy(() => colorsOf(theme)),
+      terminal: lazy(() => terminalOf(theme)),
+      editor: lazy(() => editorOf(theme)),
+      chart: lazy(() => chartSeries(theme)),
+    }
+  ) as ThemeVariant
+}
+
 /**
  * A variant's `--primary-subtle`: the tint over `var(--primary)` at the strength its
  * catalogue record measures (`primarySubtleAlpha`). A variant that is not in the
@@ -290,13 +376,45 @@ export function primarySubtleFor(theme: Pick<ThemeVariant, 'id' | 'appearance'>)
 }
 
 /** The catalogue, in catalogue order. */
-export const builtinThemes: readonly ThemeVariant[] = Object.freeze(catalogue.map(toVariant))
+export const builtinThemes: readonly ThemeVariant[] = Object.freeze(catalogue.map(lazyVariant))
 
 export function themeById(id: string): ThemeVariant | undefined {
   if (!hasTheme(id)) return undefined
   return builtinThemes.find((theme) => theme.id === id)
 }
 
+/**
+ * The variant a stored id means, or the default of the same appearance.
+ *
+ * An id the registry does not hold — an imported theme that was deleted, a
+ * catalogue entry that was renamed — must still paint *something of the appearance
+ * being shown*. Falling back to whichever variant happens to be first in the
+ * registry painted a dark palette under a light `color-scheme` for a light id, so
+ * the fallback is the appearance's own default, then any variant of that
+ * appearance, then the registry's first entry only when it holds nothing else.
+ *
+ * `registry` is the builtin catalogue plus whatever extras the host supplies; the
+ * stored id is never rewritten, only resolved, so a host that keeps an unknown id
+ * keeps resolving it if the theme comes back.
+ *
+ * The fallback order is translated from Zeron's `ThemeRegistry::resolve` (MIT,
+ * Copyright (c) 2026 Wing); see NOTICE.
+ */
+export function resolveVariant(
+  registry: readonly ThemeVariant[],
+  id: string,
+  appearance: ThemeAppearance
+): ThemeVariant {
+  const found = registry.find((variant) => variant.id === id)
+  if (found) return found
+  const defaultId = appearance === 'dark' ? defaultDarkThemeId : defaultLightThemeId
+  return (
+    registry.find((variant) => variant.id === defaultId) ??
+    registry.find((variant) => variant.appearance === appearance) ??
+    registry[0]!
+  )
+}
+
 /** The variants of one appearance, which is what a picker for that mode shows. */
 export function themesForAppearance(appearance: ThemeAppearance): readonly ThemeVariant[] {
   const ids = new Set(themesByAppearance(appearance).map((theme) => theme.id))
@@ -482,7 +600,7 @@ export function themeCssVariables(theme: ThemeVariant): Record<string, string> {
   const c = theme.colors
   const t = theme.terminal
   const e = theme.editor
-  return {
+  const derived = {
     '--background': c.background,
     '--foreground': c.foreground,
     '--card': c.card,
@@ -587,6 +705,29 @@ export function themeCssVariables(theme: ThemeVariant): Record<string, string> {
     '--chart-5': theme.chart[4] ?? c.destructive,
     '--chart-6': theme.chart[5] ?? c.mutedForeground,
   }
+  return theme.tokens ? { ...derived, ...theme.tokens } : derived
+}
+
+/**
+ * Token values with every `oklch()` colour written as `#rrggbb`.
+ *
+ * For a host whose stylesheet, tests or native shell speak hex: the catalogue's
+ * roles are `oklch()` strings, and this is the one conversion, gamut-mapped by the
+ * catalogue's own `oklchToHex`. A value that is already hex, carries alpha
+ * (`rgba()`), or is not a plain colour (`color-mix()`, `var()`) is left byte for
+ * byte, because converting would either lose the alpha or be a guess. Suitable as
+ * `ThemeProvider`'s `transformTokens`.
+ */
+export function tokensAsHex(tokens: Readonly<Record<string, string>>): Record<string, string> {
+  const converted: Record<string, string> = {}
+  for (const [name, value] of Object.entries(tokens)) {
+    const trimmed = value.trim()
+    // `parseOklch` discards alpha, so a translucent oklch() stays as written.
+    const opaque = trimmed.startsWith('oklch(') && !trimmed.includes('/')
+    const parsed = opaque ? parseColor(trimmed) : undefined
+    converted[name] = parsed ? oklchToHex(parsed) : value
+  }
+  return converted
 }
 
 /* ---------------------------------------------------------------------------

package/dist/r/theming.json

@@ -28,11 +28,26 @@
       "type": "registry:ui",
       "target": "components/theming/index.ts"
     },
+    {
+      "path": "src/components/theme/theme-context.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-context.ts"
+    },
+    {
+      "path": "src/components/theme/theme-document.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-document.ts"
+    },
     {
       "path": "src/components/theme/theme-mode-toggle.tsx",
       "type": "registry:ui",
       "target": "components/theming/theme-mode-toggle.tsx"
     },
+    {
+      "path": "src/components/theme/theme-persistence.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-persistence.ts"
+    },
     {
       "path": "src/components/theme/theme-picker.tsx",
       "type": "registry:ui",
@@ -43,6 +58,11 @@
       "type": "registry:ui",
       "target": "components/theming/theme-provider.tsx"
     },
+    {
+      "path": "src/components/theme/theme-state.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-state.ts"
+    },
     {
       "path": "src/components/theme/theme-toggle.tsx",
       "type": "registry:ui",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.123.1",
+  "version": "0.124.0",
   "description": "The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.",
   "keywords": [
     "adea",

package/registry.json

@@ -2527,11 +2527,26 @@
           "type": "registry:ui",
           "target": "components/theming/index.ts"
         },
+        {
+          "path": "src/components/theme/theme-context.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-context.ts"
+        },
+        {
+          "path": "src/components/theme/theme-document.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-document.ts"
+        },
         {
           "path": "src/components/theme/theme-mode-toggle.tsx",
           "type": "registry:ui",
           "target": "components/theming/theme-mode-toggle.tsx"
         },
+        {
+          "path": "src/components/theme/theme-persistence.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-persistence.ts"
+        },
         {
           "path": "src/components/theme/theme-picker.tsx",
           "type": "registry:ui",
@@ -2542,6 +2557,11 @@
           "type": "registry:ui",
           "target": "components/theming/theme-provider.tsx"
         },
+        {
+          "path": "src/components/theme/theme-state.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-state.ts"
+        },
         {
           "path": "src/components/theme/theme-toggle.tsx",
           "type": "registry:ui",

package/src/components/theme/index.ts

@@ -11,11 +11,14 @@ export {
   ThemeProvider,
   defaultThemeSelection,
   inlineScriptLiteral,
+  localStoragePersistence,
   resolvedDensity,
   themeScript,
+  useOptionalTheme,
   useTheme,
   type ThemeContextValue,
   type ThemeDensity,
+  type ThemePersistence,
   type ThemeProviderProps,
   type ThemeSelection,
 } from './theme-provider'

package/src/components/theme/theme-context.ts

@@ -0,0 +1,43 @@
+import { createContext, useContext, type Context } from 'solid-js'
+import type { ThemeContextValue } from './theme-state'
+
+/**
+ * Where the context object lives: on the global, under a registered symbol.
+ *
+ * A context is an object identity, and a bundle can legitimately load this module
+ * twice — a dev graph where a relative import and a package subpath are distinct
+ * module records, or two copies of the package at different versions. Each copy
+ * would then call `createContext` and own its own object; a provider from one and a
+ * `useOptionalTheme()` from the other would never meet, and the second would return
+ * `undefined` as though no provider were mounted. `Symbol.for` is shared across
+ * every copy in a realm, so they all find the one context the first created.
+ *
+ * Both copies must agree on its shape. The context value only ever grows, which is
+ * why a newer provider under an older reader is safe and the reverse is a missing
+ * member, not a mismatch.
+ */
+const CONTEXT_KEY = Symbol.for('adea.ui.theme')
+
+type ContextHost = { [CONTEXT_KEY]?: Context<ThemeContextValue | undefined> }
+
+export function themeContext(): Context<ThemeContextValue | undefined> {
+  const host = globalThis as ContextHost
+  return (host[CONTEXT_KEY] ??= createContext<ThemeContextValue>())
+}
+
+export function useTheme(): ThemeContextValue {
+  const value = useContext(themeContext())
+  if (!value) throw new Error('useTheme must be called inside a <ThemeProvider>.')
+  return value
+}
+
+/**
+ * The theme context, or `undefined` outside a `ThemeProvider`.
+ *
+ * For a component that can run both ways — a shared control rendered in a harness,
+ * a story, or a host that has not mounted a provider — and would rather degrade
+ * than throw.
+ */
+export function useOptionalTheme(): ThemeContextValue | undefined {
+  return useContext(themeContext())
+}

package/src/components/theme/theme-document.ts

@@ -0,0 +1,168 @@
+import {
+  applyAppearanceFontSettings,
+  normalizeAppearanceEditorFontSettings,
+} from '#lib/appearance-font-settings'
+import {
+  accentVariables,
+  themeCssVariables,
+  type ThemeAppearance,
+  type ThemeVariant,
+} from '#lib/themes'
+import { resolvedDensity, type ThemeSelection } from './theme-state'
+
+/**
+ * The document half of the theme provider: the single writer of `<html>`.
+ *
+ * Written against the few members of an element it uses, so the rules can be tested
+ * on a stand-in and the provider's effect stays a one-line call.
+ */
+export type ThemeRoot = Pick<
+  HTMLElement,
+  'classList' | 'dataset' | 'style' | 'removeAttribute' | 'setAttribute'
+>
+
+export type ThemeDocumentState = {
+  /** What the document shows: the committed selection, or a preview laid over it. */
+  selection: ThemeSelection
+  appearance: ThemeAppearance
+  variant: ThemeVariant
+}
+
+export type ThemeDocumentOptions = {
+  /**
+   * Rewrites the custom properties just before they are written: the variant's
+   * roles with the accent laid over them. It sees every property of the pass and
+   * must return the full map; a name it drops is not written.
+   */
+  transformTokens?: (tokens: Record<string, string>) => Record<string, string>
+}
+
+/**
+ * The custom properties a state paints: the variant's roles, with the accent
+ * selection laid over them, then `transformTokens`.
+ *
+ * The accent is applied *here* rather than left to the `[data-accent]` blocks in
+ * `theme.css`, because the properties are written inline and an inline declaration
+ * outranks every stylesheet selector however specific it is. The blocks still exist
+ * and are still correct — they are what styles the window before this runs — but
+ * they cannot win from here, so leaving the accent to them meant the attribute was
+ * set, the rules were present, and nothing changed on screen.
+ */
+export function themeDocumentTokens(
+  state: ThemeDocumentState,
+  options: ThemeDocumentOptions = {}
+): { tokens: Record<string, string>; accented: boolean } {
+  const properties = { ...themeCssVariables(state.variant) }
+  const accent = accentVariables(state.selection.accent, state.appearance, state.selection)
+  if (accent) Object.assign(properties, accent)
+  return {
+    tokens: options.transformTokens ? options.transformTokens(properties) : properties,
+    accented: accent !== undefined,
+  }
+}
+
+/**
+ * Write a state onto a root and report which custom properties it owns.
+ *
+ * Pass the previous call's return as `previous` and any palette property that pass
+ * wrote and this one does not is removed. For the catalogue the two sets are the
+ * same, so nothing is ever removed; it matters for a host variant that carries
+ * `tokens` the catalogue does not, which would otherwise stay inline, beating the
+ * stylesheet, after the user switched away from it.
+ */
+export function applyThemeToRoot(
+  root: ThemeRoot,
+  state: ThemeDocumentState,
+  options: ThemeDocumentOptions = {},
+  previous?: ReadonlySet<string>
+): ReadonlySet<string> {
+  const { tokens, accented } = themeDocumentTokens(state, options)
+
+  for (const [name, value] of Object.entries(tokens)) {
+    root.style.setProperty(name, value)
+  }
+  if (previous) {
+    for (const name of previous) {
+      if (!(name in tokens)) root.style.removeProperty(name)
+    }
+  }
+
+  root.classList.toggle('dark', state.appearance === 'dark')
+  root.dataset['theme'] = state.variant.id
+  root.dataset['appearance'] = state.appearance
+  root.style.colorScheme = state.appearance
+
+  if (!accented) root.removeAttribute('data-accent')
+  else root.dataset['accent'] = state.selection.accent
+
+  applyAppearanceFontSettings(
+    root,
+    normalizeAppearanceEditorFontSettings(state.selection.fonts, state.selection.font).settings
+  )
+
+  // Density is a pure token shift, so unlike the colour axes there is nothing to
+  // compute: the attribute selects a block in `theme.css`. It is applied here for
+  // the same reason as the others — this is the one place that knows what the
+  // current selection is, and it is the only writer of these attributes.
+  if (resolvedDensity(state.selection) === 'comfortable') root.removeAttribute('data-density')
+  else root.dataset['density'] = resolvedDensity(state.selection)
+
+  return new Set(Object.keys(tokens))
+}
+
+/** What {@link applyWithoutTransitions} needs of a document. */
+export type TransitionDocument = {
+  head: { appendChild(node: unknown): unknown }
+  createElement(tag: 'style'): {
+    textContent: string | null
+    offsetHeight?: number
+    remove(): void
+  }
+}
+
+/**
+ * Run `apply` with every CSS transition switched off for the frame that carries
+ * it, so a theme switch cannot animate page-wide.
+ *
+ * Without this, flipping the custom properties on `<html>` starts a transition on
+ * every element that declares one, and each fades from the old palette to the new
+ * over its own duration: a theme change that looks like a rendering fault. The
+ * rule is removed two frames later, after the browser has committed the new styles
+ * with transitions off, and `restore` runs it early (the provider calls it when it
+ * is disposed mid-switch).
+ *
+ * `schedule` is the frame source; it defaults to `requestAnimationFrame` and falls
+ * back to running at once where there is none, which leaves transitions on rather
+ * than off.
+ */
+export function applyWithoutTransitions(
+  doc: TransitionDocument,
+  apply: () => void,
+  schedule: (callback: () => void) => void = defaultSchedule
+): () => void {
+  const style = doc.createElement('style')
+  style.textContent = '*{transition:none !important}'
+  doc.head.appendChild(style)
+  // Reading a layout property forces the browser to commit the rule before the
+  // properties change; without it the two can be batched into one style recalc.
+  void style.offsetHeight
+  let removed = false
+  const restore = () => {
+    if (removed) return
+    removed = true
+    style.remove()
+  }
+  try {
+    apply()
+  } catch (error) {
+    restore()
+    throw error
+  }
+  schedule(() => schedule(restore))
+  return restore
+}
+
+function defaultSchedule(callback: () => void): void {
+  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(callback)
+  else callback()
+}