@adea-ai/ui 0.123.1 → 0.124.0

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

@@ -0,0 +1,225 @@
+import {
+  DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS,
+  normalizeAppearanceEditorFontSettings,
+  type AppearanceEditorFontSettings,
+} from '#lib/appearance-font-settings'
+import type { AccentPreset } from '@adea-ai/themes'
+import {
+  defaultDarkThemeId,
+  defaultLightThemeId,
+  resolveVariant,
+  type ThemeAppearance,
+  type ThemeVariant,
+} from '#lib/themes'
+
+/**
+ * The pure half of the theme provider: what a selection is, how two selections
+ * merge, and what a selection resolves to.
+ *
+ * Nothing here touches the document, storage or a signal, so each rule can be
+ * tested by calling it. `ThemeProvider` owns the reactivity and wires these to it;
+ * `theme-document.ts` owns the writes; `theme-persistence.ts` owns the store.
+ */
+
+/**
+ * Four independent choices, and keeping them independent is the point:
+ *
+ *   - **appearance** — light, dark, or follow the system.
+ *   - **a theme per appearance** — so a user can run Catppuccin Mocha by night and
+ *     Solarized Light by day without re-choosing when the system flips.
+ *   - **an accent** — adea's six presets, or one of the accents the selected theme
+ *     pair carries itself (`ansi-blue`…), which re-colour the interactive roles on
+ *     top of whichever theme is active.
+ *   - **fonts** — separate family and size choices for UI, content and code.
+ */
+export type ThemeSelection = {
+  /** `system` follows `prefers-color-scheme` and updates when it changes. */
+  appearance: ThemeAppearance | 'system'
+  /** The variant to use when the resolved appearance is light. */
+  lightThemeId: string
+  /** The variant to use when the resolved appearance is dark. */
+  darkThemeId: string
+  /**
+   * An `accentPresets` id, a theme accent id from `themeAccents()` (`ansi-blue`…),
+   * or `theme` for the variant's own primary. A theme accent the current pair does
+   * not offer falls back to the variant's own primary.
+   */
+  accent: string
+  /** UI-family alias for consumers of the original single-font preference. */
+  font: string
+  /** UI, content and code font settings. Omitted legacy records are migrated from `font`. */
+  fonts?: AppearanceEditorFontSettings
+  /**
+   * `comfortable` is the system's default geometry; `compact` moves the control
+   * ladder down one rung.
+   *
+   * Optional, and defaulted on read, so a preference stored before density existed
+   * keeps working and `ThemeSelection` stays assignable without it.
+   */
+  density?: ThemeDensity
+}
+
+/**
+ * The two density rungs.
+ *
+ * `comfortable` is the geometry in `theme.css`, so it is the absence of an
+ * attribute rather than a value: a document that ships no `data-density` at all
+ * renders correctly, which is what keeps this additive.
+ */
+export type ThemeDensity = 'comfortable' | 'compact'
+
+/**
+ * Deliberately lists only the fields every consumer has always had. A field added
+ * to {@link ThemeSelection} later gets no default here: `JSON.stringify` drops an
+ * `undefined`, so a store written by a consumer that never sets the field stays
+ * byte-identical to what it was before the field existed.
+ */
+export const defaultThemeSelection: ThemeSelection = {
+  appearance: 'system',
+  lightThemeId: defaultLightThemeId,
+  darkThemeId: defaultDarkThemeId,
+  accent: 'theme',
+  font: 'system',
+  fonts: DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS,
+  density: 'comfortable',
+}
+
+/**
+ * A stored selection's density, defaulted.
+ *
+ * The stored value is read through here rather than trusted, because a preference
+ * written before density existed has no `density` key and a hand-edited store may
+ * hold anything.
+ */
+export function resolvedDensity(selection: ThemeSelection): ThemeDensity {
+  return selection.density === 'compact' ? 'compact' : 'comfortable'
+}
+
+export type ThemeContextValue = {
+  /** The preference as stored. A {@link ThemeContextValue.preview} does not change it. */
+  selection: () => ThemeSelection
+  /** What the preference resolves to right now, after `system`. */
+  resolvedAppearance: () => ThemeAppearance
+  /** The variant in use. */
+  variant: () => ThemeVariant
+  /** Update part of the preference. */
+  setSelection: (patch: Partial<ThemeSelection>) => void
+  /**
+   * The built-in catalogue, so a picker does not import it separately. A plain
+   * array: {@link ThemeContextValue.allThemes} is the one that follows a host's
+   * extra themes.
+   */
+  themes: readonly ThemeVariant[]
+  /**
+   * The accents the selected light/dark pair carries, offered beside the presets.
+   * Follows the selection: a different theme pair may offer different slots.
+   */
+  themeAccents: () => readonly AccentPreset[]
+  /**
+   * The built-in catalogue followed by the provider's `themes` prop. Reactive when
+   * that prop is a function that reads signals.
+   */
+  allThemes: () => readonly ThemeVariant[]
+  /**
+   * Paint the document from `draft` laid over the stored selection, without
+   * persisting it or changing what {@link ThemeContextValue.selection} returns.
+   * `undefined` ends the preview. A {@link ThemeContextValue.setSelection} ends it
+   * too, because the committed selection is then what should be showing.
+   */
+  preview: (draft: Partial<ThemeSelection> | undefined) => void
+  /** True while a {@link ThemeContextValue.preview} draft is on the document. */
+  previewing: () => boolean
+}
+
+/** A selection with the `undefined` keys of a patch left out. */
+function definedOnly<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined)
+  ) as Partial<T>
+}
+
+/** Keep the deprecated single-font view synchronized with the UI axis. */
+export function mergeThemeSelection(
+  base: ThemeSelection,
+  patch: Partial<ThemeSelection>
+): ThemeSelection {
+  const merged = { ...base, ...patch }
+  let fonts: AppearanceEditorFontSettings
+
+  if (patch.fonts !== undefined) {
+    fonts = normalizeAppearanceEditorFontSettings(patch.fonts).settings
+  } else if (patch.font !== undefined) {
+    const currentFonts = normalizeAppearanceEditorFontSettings(base.fonts, base.font).settings
+    fonts = normalizeAppearanceEditorFontSettings({
+      ...currentFonts,
+      ui: { ...currentFonts.ui, family: patch.font },
+    }).settings
+  } else {
+    fonts = normalizeAppearanceEditorFontSettings(merged.fonts, merged.font).settings
+  }
+
+  return { ...merged, fonts, font: fonts.ui.family }
+}
+
+/**
+ * The selection a provider starts from: the defaults, then whatever the store
+ * returned, then `initial`.
+ *
+ * `initial` wins over the store on every mount. That precedence is part of the
+ * contract Cortana relies on (its `initial` pins `appearance` and `font`), and it
+ * is why the store's answer is only the middle layer. A store that returned
+ * nothing, or threw, or answered with explicit `undefined`s, leaves the defaults
+ * standing for those fields.
+ */
+export function initialThemeSelection(
+  stored: Partial<ThemeSelection> | undefined,
+  initial: Partial<ThemeSelection> | undefined
+): ThemeSelection {
+  const base = mergeThemeSelection(defaultThemeSelection, definedOnly(stored ?? {}))
+  return mergeThemeSelection(base, initial ?? {})
+}
+
+/** `system` resolved against what the operating system reports. */
+export function resolveAppearance(
+  preference: ThemeSelection['appearance'],
+  system: ThemeAppearance
+): ThemeAppearance {
+  return preference === 'system' ? system : preference
+}
+
+/** The theme id the selection names for a resolved appearance. */
+export function selectedThemeId(selection: ThemeSelection, appearance: ThemeAppearance): string {
+  return appearance === 'dark' ? selection.darkThemeId : selection.lightThemeId
+}
+
+/**
+ * What a selection paints: the resolved appearance and the variant for it.
+ *
+ * An id the registry does not hold resolves to the appearance's default rather than
+ * being rewritten (see `resolveVariant`), so the selection a host stores is never
+ * changed by being unresolvable.
+ */
+export function resolveThemeState(
+  selection: ThemeSelection,
+  system: ThemeAppearance,
+  registry: readonly ThemeVariant[]
+): { appearance: ThemeAppearance; variant: ThemeVariant } {
+  const appearance = resolveAppearance(selection.appearance, system)
+  return {
+    appearance,
+    variant: resolveVariant(registry, selectedThemeId(selection, appearance), appearance),
+  }
+}
+
+/**
+ * The registry a provider resolves against: the catalogue, then the host's extras.
+ *
+ * The catalogue wins an id collision, because it is listed first and `resolveVariant`
+ * takes the first match: a host's variant can add a theme but cannot shadow one.
+ */
+export function mergeRegistry(
+  builtin: readonly ThemeVariant[],
+  extra: readonly ThemeVariant[] | undefined
+): readonly ThemeVariant[] {
+  return extra && extra.length > 0 ? [...builtin, ...extra] : builtin
+}

package/src/index.ts

@@ -135,6 +135,7 @@ export {
   defaultLightThemeId,
   isThemeAccentId,
   resolveAccentPreset,
+  resolveVariant,
   themeAccentsFor,
   themeById,
   themeCssVariables,
@@ -142,8 +143,10 @@ export {
   themeRecordById,
   themeRecords,
   themesForAppearance,
+  tokensAsHex,
   validateTheme,
   validateThemeRegistry,
+  variantFromRecord,
   withAccent,
   type ThemeAppearance,
   type ThemeColors,

package/src/lib/appearance-font-settings.ts

@@ -181,7 +181,7 @@ export function normalizeAppearanceEditorFontSettings(
  * stylesheet and survives CSS import reordering.
  */
 export function applyAppearanceFontSettings(
-  root: HTMLElement,
+  root: Pick<HTMLElement, 'removeAttribute' | 'setAttribute' | 'style'>,
   value: unknown
 ): NormalizedAppearanceEditorFontSettings {
   const normalized = normalizeAppearanceEditorFontSettings(value)

package/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
 }
 
 /* ---------------------------------------------------------------------------