@adea-ai/ui 0.123.0 → 0.124.0

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()
+}

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

@@ -0,0 +1,140 @@
+import { accentPresets } from '#lib/tokens'
+import { normalizeAppearanceEditorFontSettings } from '#lib/appearance-font-settings'
+import { defaultDarkThemeId, defaultLightThemeId, isThemeAccentId, themeById } from '#lib/themes'
+import { defaultThemeSelection, resolvedDensity, type ThemeSelection } from './theme-state'
+
+/**
+ * Where a selection is kept between sessions.
+ *
+ * The provider never touches storage itself; it asks a `ThemePersistence`. The
+ * default is {@link localStoragePersistence}, which is what the provider always did.
+ * A host that stores the preference in a different shape, under a versioned
+ * envelope, or somewhere that is not `localStorage` supplies its own and the
+ * resolution and application rules stay the shared ones.
+ *
+ * The contract is deliberately narrow, so that an implementation cannot make the
+ * provider less safe than it was:
+ *
+ *   - `read` is synchronous and runs once, when the provider is created. It may
+ *     repair or quarantine what it finds, and it must not throw: the provider
+ *     treats a throw as "nothing stored" and starts from the defaults.
+ *   - `write` runs only from `setSelection`. Never on mount, never from `preview`,
+ *     never as a side effect of reading, so the first write to a store is always a
+ *     user's decision. A throw is swallowed, because a full or blocked store must
+ *     not break the switch.
+ */
+export type ThemePersistence = {
+  read(): Partial<ThemeSelection> | undefined
+  write(next: ThemeSelection): void
+}
+
+/**
+ * The preference store, or nothing.
+ *
+ * Only ever called inside a `try`: where storage is blocked — a sandboxed iframe, a
+ * privacy mode, a denied site-data permission — merely *reading* the `localStorage`
+ * global throws ("Access is denied", `SecurityError`), so even the `typeof` guard
+ * has to sit inside the `try` rather than in front of it. Without a store the
+ * preference lives only in the provider's signal for the session.
+ */
+function preferenceStore(): Storage | undefined {
+  return typeof localStorage === 'undefined' ? undefined : localStorage
+}
+
+/** The stored preference, validated against the catalogue. */
+function readSelection(storageKey: string): ThemeSelection {
+  try {
+    const raw = preferenceStore()?.getItem(storageKey)
+    if (!raw) return defaultThemeSelection
+    const parsed = JSON.parse(raw) as Partial<ThemeSelection>
+    const fonts = normalizeAppearanceEditorFontSettings(parsed.fonts, parsed.font).settings
+    return {
+      appearance:
+        parsed.appearance === 'light' ||
+        parsed.appearance === 'dark' ||
+        parsed.appearance === 'system'
+          ? parsed.appearance
+          : defaultThemeSelection.appearance,
+      // An unknown id would leave the document with no theme at all, so a stale
+      // preference from an older catalogue falls back rather than applying nothing.
+      lightThemeId:
+        themeById(parsed.lightThemeId ?? '')?.appearance === 'light'
+          ? (parsed.lightThemeId as string)
+          : defaultLightThemeId,
+      darkThemeId:
+        themeById(parsed.darkThemeId ?? '')?.appearance === 'dark'
+          ? (parsed.darkThemeId as string)
+          : defaultDarkThemeId,
+      // A theme accent is kept whenever it names a slot, even one the stored pair
+      // cannot offer: the id is role-shaped so it survives a theme switch, and an
+      // unoffered slot already resolves to the theme's own primary when applied.
+      accent:
+        typeof parsed.accent === 'string' &&
+        (accentPresets.some((preset) => preset.id === parsed.accent) ||
+          isThemeAccentId(parsed.accent))
+          ? parsed.accent
+          : defaultThemeSelection.accent,
+      font: fonts.ui.family,
+      fonts,
+      // Every axis has to be read back here, or it is lost twice: the provider's
+      // document effect removes the `data-density` that `themeScript` set for the first paint, and
+      // the next `setSelection` rewrites the store without it.
+      density: resolvedDensity(parsed as ThemeSelection),
+    }
+  } catch {
+    return defaultThemeSelection
+  }
+}
+
+/**
+ * The default persistence: one JSON document in `localStorage` under `key`.
+ *
+ * `read` is the provider's original `readSelection`, moved here unchanged — every
+ * stored id is validated against the catalogue, so a stale preference falls back to
+ * a default rather than reaching the document. `key` may be a function so a
+ * provider whose `storageKey` prop changes writes to the key it is now given.
+ *
+ * Blocked, full or absent storage is survivable in both directions: a read answers
+ * with the defaults and a write is dropped, so the preference simply lasts the
+ * session.
+ */
+export function localStoragePersistence(key: string | (() => string)): ThemePersistence {
+  const keyOf = () => (typeof key === 'function' ? key() : key)
+  return {
+    read: () => readSelection(keyOf()),
+    write(next) {
+      try {
+        preferenceStore()?.setItem(keyOf(), JSON.stringify(next))
+      } catch {
+        // A full, blocked or unavailable store must not break the switch: the
+        // preference simply does not survive the reload.
+      }
+    },
+  }
+}
+
+/**
+ * What a persistence knows, or nothing.
+ *
+ * The seam's `read` must not throw, and the provider does not rely on that: a host
+ * persistence is code the design system has not seen, and a theme provider that
+ * fails to mount because a store misbehaved has turned a lost preference into a
+ * blank application.
+ */
+export function readPersisted(persistence: ThemePersistence): Partial<ThemeSelection> | undefined {
+  try {
+    return persistence.read()
+  } catch {
+    return undefined
+  }
+}
+
+/** Hand a selection to the store; a store that throws loses the preference, not the switch. */
+export function writePersisted(persistence: ThemePersistence, next: ThemeSelection): void {
+  try {
+    persistence.write(next)
+  } catch {
+    // Same contract as a full or blocked `localStorage`: the choice holds for the
+    // session and does not survive the reload.
+  }
+}