@adea-ai/ui 0.128.2 → 0.128.4

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

@@ -17,7 +17,6 @@
  * token exists" a property the build enforces rather than a promise.
  */
 
-import { ACCENTS } from '@adea-ai/themes'
 export { fontOptions } from './font-catalog'
 export type { FontOption } from './font-catalog'
 
@@ -705,40 +704,7 @@ export const zIndexTokens: TokenDefinition[] = [
   },
 ]
 
-/**
- * The accent axis.
- *
- * adea's accent presets, as a selection rather than a constant. `theme` is the
- * default and means "the variant's own primary" — monochrome in adea's palette —
- * and each named preset overrides the interactive roles through the
- * `[data-accent]` blocks in `theme.css`.
- *
- * These are the same six presets `accentPresets` exports in adea's own
- * `appearance.ts`, and the values match. A consumer's appearance picker and the
- * workshop's theme toolbar read this one list, so the two cannot disagree about
- * what a preset is called or what colour it is.
- */
-export type AccentPreset = {
-  /** The `data-accent` value. `theme` is the variant's own primary. */
-  id: string
-  label: string
-  /** What the preset is for, in the gallery and in a picker. */
-  description: string
-  /** The accent as it appears in the light theme. Absent for `theme`. */
-  light?: string
-  /** The accent as it appears in the dark theme. Absent for `theme`. */
-  dark?: string
-}
-
-export const accentPresets: readonly AccentPreset[] = Object.freeze([
-  {
-    id: 'theme',
-    label: 'Theme',
-    description:
-      "The variant's own primary. Neutral in adea's palette, so the interface stays monochrome.",
-  },
-  ...ACCENTS,
-])
+export { accentPresets, type AccentPreset } from './accent-presets'
 
 /** Every token, in gallery order. */
 export const designTokens = {

package/dist/r/theming.json

@@ -28,11 +28,26 @@
       "type": "registry:ui",
       "target": "components/theming/index.ts"
     },
+    {
+      "path": "src/components/theme/lazy.ts",
+      "type": "registry:ui",
+      "target": "components/theming/lazy.ts"
+    },
+    {
+      "path": "src/components/theme/theme-catalogue-source.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-catalogue-source.ts"
+    },
     {
       "path": "src/components/theme/theme-context.ts",
       "type": "registry:ui",
       "target": "components/theming/theme-context.ts"
     },
+    {
+      "path": "src/components/theme/theme-document-core.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-document-core.ts"
+    },
     {
       "path": "src/components/theme/theme-document.ts",
       "type": "registry:ui",
@@ -53,6 +68,21 @@
       "type": "registry:ui",
       "target": "components/theming/theme-picker.tsx"
     },
+    {
+      "path": "src/components/theme/theme-provider-core.tsx",
+      "type": "registry:ui",
+      "target": "components/theming/theme-provider-core.tsx"
+    },
+    {
+      "path": "src/components/theme/theme-provider-lazy.tsx",
+      "type": "registry:ui",
+      "target": "components/theming/theme-provider-lazy.tsx"
+    },
+    {
+      "path": "src/components/theme/theme-provider-value.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-provider-value.ts"
+    },
     {
       "path": "src/components/theme/theme-provider.tsx",
       "type": "registry:ui",
@@ -63,6 +93,11 @@
       "type": "registry:ui",
       "target": "components/theming/theme-script.ts"
     },
+    {
+      "path": "src/components/theme/theme-state-core.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-state-core.ts"
+    },
     {
       "path": "src/components/theme/theme-state.ts",
       "type": "registry:ui",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.128.2",
+  "version": "0.128.4",
   "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",
@@ -74,6 +74,12 @@
     "./fonts.css": "./src/styles/fonts.css",
     "./registry.json": "./registry.json",
     "./package.json": "./package.json",
+    "./components/theme/lazy": {
+      "types": "./dist/components/theme/lazy.d.ts",
+      "solid": "./src/components/theme/lazy.ts",
+      "development": "./src/components/theme/lazy.ts",
+      "import": "./dist/components/theme/lazy.js"
+    },
     "./components/layout/split-layout/model": {
       "types": "./dist/components/layout/split-layout/model.d.ts",
       "solid": "./src/components/layout/split-layout/model.ts",
@@ -111,9 +117,11 @@
     "registry:validate": "bun run cn:check && bun scripts/validate-registry.ts",
     "pack:check": "bun scripts/check-pack.ts && bun scripts/check-lib-exports.ts",
     "check:lib-exports": "bun scripts/check-lib-exports.ts",
-    "check:tree-shaking": "bun scripts/check-tree-shaking.ts",
+    "check:tree-shaking": "bun scripts/check-tree-shaking.ts && bun scripts/check-theme-startup.ts",
+    "check:theme-startup": "bun scripts/check-theme-startup.ts",
     "theme:build": "bun scripts/build-default-theme.ts",
     "theme:check": "bun scripts/build-default-theme.ts --check",
+    "theme:defaults": "bun scripts/build-theme-defaults.ts",
     "design-system:build": "bun scripts/design-system/build.ts",
     "check:packed-layout": "node --test scripts/check-packed-layout-process.test.mjs && node scripts/check-packed-layout.mjs && node scripts/check-packed-layout-tree.mjs",
     "check:packed-lint": "node scripts/check-packed-lint.mjs",

package/registry.json

@@ -2527,11 +2527,26 @@
           "type": "registry:ui",
           "target": "components/theming/index.ts"
         },
+        {
+          "path": "src/components/theme/lazy.ts",
+          "type": "registry:ui",
+          "target": "components/theming/lazy.ts"
+        },
+        {
+          "path": "src/components/theme/theme-catalogue-source.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-catalogue-source.ts"
+        },
         {
           "path": "src/components/theme/theme-context.ts",
           "type": "registry:ui",
           "target": "components/theming/theme-context.ts"
         },
+        {
+          "path": "src/components/theme/theme-document-core.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-document-core.ts"
+        },
         {
           "path": "src/components/theme/theme-document.ts",
           "type": "registry:ui",
@@ -2552,6 +2567,21 @@
           "type": "registry:ui",
           "target": "components/theming/theme-picker.tsx"
         },
+        {
+          "path": "src/components/theme/theme-provider-core.tsx",
+          "type": "registry:ui",
+          "target": "components/theming/theme-provider-core.tsx"
+        },
+        {
+          "path": "src/components/theme/theme-provider-lazy.tsx",
+          "type": "registry:ui",
+          "target": "components/theming/theme-provider-lazy.tsx"
+        },
+        {
+          "path": "src/components/theme/theme-provider-value.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-provider-value.ts"
+        },
         {
           "path": "src/components/theme/theme-provider.tsx",
           "type": "registry:ui",
@@ -2562,6 +2592,11 @@
           "type": "registry:ui",
           "target": "components/theming/theme-script.ts"
         },
+        {
+          "path": "src/components/theme/theme-state-core.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-state-core.ts"
+        },
         {
           "path": "src/components/theme/theme-state.ts",
           "type": "registry:ui",
@@ -2654,6 +2689,11 @@
       ],
       "registryDependencies": [],
       "files": [
+        {
+          "path": "src/lib/accent-presets.ts",
+          "type": "registry:lib",
+          "target": "lib/accent-presets.ts"
+        },
         {
           "path": "src/lib/accent-roles.ts",
           "type": "registry:lib",
@@ -2719,6 +2759,41 @@
           "type": "registry:lib",
           "target": "lib/theme-accents.ts"
         },
+        {
+          "path": "src/lib/theme-catalogue.ts",
+          "type": "registry:lib",
+          "target": "lib/theme-catalogue.ts"
+        },
+        {
+          "path": "src/lib/theme-css.ts",
+          "type": "registry:lib",
+          "target": "lib/theme-css.ts"
+        },
+        {
+          "path": "src/lib/theme-defaults.generated.ts",
+          "type": "registry:lib",
+          "target": "lib/theme-defaults.generated.ts"
+        },
+        {
+          "path": "src/lib/theme-defaults.ts",
+          "type": "registry:lib",
+          "target": "lib/theme-defaults.ts"
+        },
+        {
+          "path": "src/lib/theme-engine-light.ts",
+          "type": "registry:lib",
+          "target": "lib/theme-engine-light.ts"
+        },
+        {
+          "path": "src/lib/theme-engine.ts",
+          "type": "registry:lib",
+          "target": "lib/theme-engine.ts"
+        },
+        {
+          "path": "src/lib/theme-records.ts",
+          "type": "registry:lib",
+          "target": "lib/theme-records.ts"
+        },
         {
           "path": "src/lib/theme-surface.ts",
           "type": "registry:lib",

package/src/components/theme/lazy.ts

@@ -0,0 +1,35 @@
+/**
+ * The theme provider with the catalogue out of the start-up path.
+ *
+ * Everything here is free of the 34-theme catalogue: `import` this entry instead of
+ * `@adea-ai/ui/components/theme` in a host that paints its theme from a stylesheet.
+ * The catalogue loads, in a chunk of its own, the first time a stored or previewed
+ * theme needs it. See {@link ThemeProvider} for the rules and `docs/consumption.md`
+ * for the setup.
+ */
+export { loadThemeCatalogue } from './theme-catalogue-source'
+export { ThemeProvider } from './theme-provider-lazy'
+export {
+  createVersionedPersistence,
+  defaultThemeSelection,
+  inlineScriptLiteral,
+  localStoragePersistence,
+  resolvedDensity,
+  themeScript,
+  useOptionalTheme,
+  useTheme,
+  type EditorRolesMode,
+  type ThemeCatalogueSource,
+  type ThemeContextValue,
+  type ThemeDensity,
+  type ThemePersistence,
+  type ThemeProviderProps,
+  type ThemeScriptOptions,
+  type ThemeSelection,
+  type ThemeStorageSchema,
+  type ThemeSurface,
+  type VersionedCodec,
+  type VersionedPersistenceOptions,
+} from './theme-provider-core'
+export { ThemeToggle, type ThemeToggleProps } from './theme-toggle'
+export { ThemeModeToggle, type ThemeModeToggleProps } from './theme-mode-toggle'

package/src/components/theme/theme-catalogue-source.ts

@@ -0,0 +1,59 @@
+import { createSignal } from 'solid-js'
+import type { ThemeEngine } from '#lib/theme-engine'
+import { lightThemeEngine } from '#lib/theme-engine-light'
+import type { ThemeCatalogueSource } from './theme-provider-value'
+
+/**
+ * The full catalogue engine once something has asked for it, shared by every lazy
+ * provider and every caller of {@link loadThemeCatalogue} in the page. A provider
+ * created after the load starts with it already in hand.
+ */
+let loadedEngine: ThemeEngine | undefined
+let loading: Promise<ThemeEngine> | undefined
+
+/**
+ * Load the whole theme catalogue (about 129 KB raw, 34 KB gzipped) and resolve to the
+ * engine backed by it. Idempotent: every call shares one import, and a failed import is
+ * forgotten so the next call retries.
+ *
+ * The lazy provider calls this itself the moment a selection needs a theme beyond the
+ * default pair. Call it earlier — when a settings page mounts, or on hover of its
+ * entry — to have the picker ready by the time it opens.
+ */
+export function loadThemeCatalogue(): Promise<ThemeEngine> {
+  if (loadedEngine) return Promise.resolve(loadedEngine)
+  loading ??= import('#lib/theme-catalogue').then(
+    (module) => {
+      loadedEngine = module.catalogueThemeEngine
+      return loadedEngine
+    },
+    (error: unknown) => {
+      loading = undefined
+      throw error
+    }
+  )
+  return loading
+}
+
+/** A catalogue source for one provider: the shipped defaults until the load resolves. */
+export function createLazyCatalogue(): ThemeCatalogueSource {
+  const [full, setFull] = createSignal<ThemeEngine | undefined>(loadedEngine)
+  const [failed, setFailed] = createSignal(false)
+  const load = () =>
+    loadThemeCatalogue().then(
+      (loaded) => {
+        setFailed(false)
+        setFull(() => loaded)
+      },
+      () => {
+        // The theme the stylesheet painted stays; the next request retries.
+        setFailed(true)
+      }
+    )
+  return {
+    engine: () => full() ?? lightThemeEngine,
+    loaded: () => full() !== undefined,
+    failed,
+    load,
+  }
+}

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

@@ -0,0 +1,262 @@
+import {
+  applyAppearanceFontSettings,
+  normalizeAppearanceEditorFontSettings,
+} from '#lib/appearance-font-settings'
+import { terminalCssVariables } from '#lib/theme-css'
+import type { ThemeEngine } from '#lib/theme-engine'
+import type { EditorRolesMode, ThemeAppearance, ThemeVariant } from '#lib/themes'
+import { isCustomAccent } from '#lib/accent-roles'
+import { surfaceAlpha, type SurfaceState } from '#lib/theme-surface'
+import { resolvedDensity, type ThemeSelection } from './theme-state-core'
+
+/**
+ * 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.
+ *
+ * This is the engine-parameterised half: every question the catalogue answers goes
+ * through the {@link ThemeEngine} it is given, so it imports no catalogue code or data.
+ * `theme-document.ts` binds the full catalogue and keeps the signatures the eager
+ * provider and the tests have always used.
+ */
+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
+  /**
+   * The variant whose terminal palette is pinned over the interface variant's.
+   * Absent, the terminal follows the interface theme.
+   */
+  terminalVariant?: ThemeVariant
+  /**
+   * The resolved surface axis. Absent, the axis is off: no attribute and no
+   * `--surface-alpha` is written, and any this writer wrote before is removed.
+   */
+  surface?: SurfaceState
+}
+
+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 contrast an accent is held to against the variant's background. Absent, a
+   * preset is painted verbatim (the catalogue measured it for its own themes) and
+   * only a custom `#rrggbb` is held to the default floor of 3:1.
+   */
+  accentContrastFloor?: number
+  /**
+   * Where a catalogue variant's palette comes from. `inline` (the default) writes
+   * every role onto the root. `stylesheet` writes none for a catalogue variant,
+   * because the host loads a stylesheet that carries a `[data-theme]` block for it;
+   * a variant the catalogue does not hold (a host's imported theme) is still written
+   * inline, since no stylesheet can know it. The accent, the terminal pin, the
+   * surface alpha and the fonts are written the same in both.
+   *
+   * Switching from an imported variant back to a catalogue one removes what the
+   * imported one wrote, so nothing inline outlives it to beat the stylesheet.
+   */
+  palette?: 'inline' | 'stylesheet'
+  /**
+   * The `--editor-*` projection. `syntax` (the default) is the catalogue's quiet
+   * syntax roles, which is what `theme-variants.css` carries; `floor` holds every
+   * editor role to 4.5:1 on the canvas, as hex.
+   *
+   * With `palette: 'stylesheet'`, `floor` is the one palette write a catalogue
+   * variant still gets: the stylesheet is generated for the default projection, so
+   * the sixteen `--editor-*` properties are written inline over it. The rest of the
+   * palette stays in the stylesheet.
+   */
+  editorRoles?: EditorRolesMode
+}
+
+/**
+ * What a catalogue variant still writes inline when its palette is the stylesheet's:
+ * nothing, unless the editor projection is not the one the stylesheet was generated
+ * for.
+ */
+function stylesheetOverrides(
+  engine: ThemeEngine,
+  variant: ThemeVariant,
+  editorRoles: EditorRolesMode | undefined
+): Record<string, string> {
+  if (editorRoles !== 'floor') return {}
+  return Object.fromEntries(
+    Object.entries(engine.themeCssVariables(variant, { editor: 'floor' })).filter(([name]) =>
+      name.startsWith('--editor-')
+    )
+  )
+}
+
+/**
+ * The custom properties a state paints: the variant's roles, with the accent
+ * selection laid over them, the pinned terminal palette over that, the surface
+ * alpha, 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 themeDocumentTokensWith(
+  engine: ThemeEngine,
+  state: ThemeDocumentState,
+  options: ThemeDocumentOptions = {}
+): { tokens: Record<string, string>; accented: boolean } {
+  const fromStylesheet =
+    options.palette === 'stylesheet' && engine.isCatalogueVariant(state.variant)
+  const properties = fromStylesheet
+    ? stylesheetOverrides(engine, state.variant, options.editorRoles)
+    : { ...engine.themeCssVariables(state.variant, { editor: options.editorRoles }) }
+  const accent = engine.accentVariables(state.selection.accent, state.appearance, state.selection, {
+    background: state.variant.colors.background,
+    floor: options.accentContrastFloor,
+    variantId: state.variant.id,
+  })
+  if (accent) Object.assign(properties, accent)
+  // Written after the variant and the accent, so it wins over the interface
+  // variant's own terminal ramp (and over the stylesheet's, which it outranks as an
+  // inline declaration). Dropping the pin needs no removal of its own: the ramp is
+  // then rewritten by the variant, or swept back to the stylesheet.
+  if (state.terminalVariant) Object.assign(properties, terminalCssVariables(state.terminalVariant))
+  if (state.surface) properties['--surface-alpha'] = surfaceAlpha[state.surface.surface]
+  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 applyThemeToRootWith(
+  engine: ThemeEngine,
+  root: ThemeRoot,
+  state: ThemeDocumentState,
+  options: ThemeDocumentOptions = {},
+  previous?: ReadonlySet<string>
+): ReadonlySet<string> {
+  const { tokens, accented } = themeDocumentTokensWith(engine, 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
+
+  // A custom colour has no stylesheet block to select, and its value is the
+  // attribute's worst possible content, so it is reported as `custom`.
+  if (!accented) root.removeAttribute('data-accent')
+  else
+    root.dataset['accent'] = isCustomAccent(state.selection.accent)
+      ? 'custom'
+      : state.selection.accent
+
+  // The surface axis is opt-in, so its absence removes rather than defaults: a host
+  // that never enables it keeps an `<html>` with neither attribute, and one that
+  // turns it off leaves nothing behind. (`--surface-alpha` is swept with the tokens.)
+  if (state.surface) {
+    root.dataset['surface'] = state.surface.surface
+    root.dataset['reduceTransparency'] = state.surface.reduceTransparencyActive ? 'true' : 'false'
+  } else {
+    root.removeAttribute('data-surface')
+    root.removeAttribute('data-reduce-transparency')
+  }
+
+  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()
+}