@leavepulse/ui 0.43.4 → 0.44.0

package/src/theme/useTheme.ts

@@ -7,6 +7,7 @@
 import { computed, readonly, shallowRef, type ComputedRef, type DeepReadonly, type Ref } from "vue"
 import { easingToken, prefersReducedMotion } from "../composables/easing"
 import { detectBackdropFilter } from "./backdrop"
+import { dark as darkPreset, light as lightPreset } from "./presets"
 import {
   COLOR_VARS,
   DEFAULT_SURFACE,
@@ -24,57 +25,134 @@ import {
 
 const CACHE_KEY = "leavepulse-ui-theme"
 
+/** A light/dark pair followed by the operating system's colour scheme. */
+export interface SystemThemes {
+  light: TokenSet
+  dark: TokenSet
+}
+
+type Cached = { theme: TokenSet; system?: undefined } | { system: SystemThemes; theme?: undefined }
+
 // ── self-managed theme state (singleton) ─────────────────────────────────
-// The kit owns the active theme — like an i18n locale — so every consumer
-// shares one source of truth instead of each wiring its own ref + bootstrap.
-// Module-level (created once per app), reactive, and lazily hydrated from the
-// cache on the client. SSR-safe: hydration only touches localStorage in a
-// browser; on the server `current` stays null until the client mounts.
+// The kit owns the active theme, like an i18n locale, so every consumer shares
+// one source of truth. Lazily hydrated from the cache on the client; on the
+// server `current` stays null.
 const _current = shallowRef<TokenSet | null>(null)
+const _system = shallowRef<SystemThemes | null>(null)
 let _hydrated = false
-
-// The fallback used when nothing is cached yet. Consumers can override it via
-// initTheme(fallback); defaults to whatever the first apply() sets.
 let _fallback: TokenSet | null = null
 
-function hydrateOnce(): void {
-  if (_hydrated || typeof window === "undefined") return
-  _hydrated = true
+const DARK_QUERY = "(prefers-color-scheme: dark)"
+let _media: MediaQueryList | null = null
+
+/** Whether the OS asks for dark. True where it cannot be asked (server, old engines). */
+export function prefersDarkScheme(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return true
+  return window.matchMedia(DARK_QUERY).matches || !window.matchMedia("(prefers-color-scheme: light)").matches
+}
+
+function pick(system: SystemThemes, dark = prefersDarkScheme()): TokenSet {
+  return dark ? system.dark : system.light
+}
+
+function onSchemeChange(event: MediaQueryListEvent): void {
+  const system = _system.value
+  if (!system) return
+  const theme = pick(system, event.matches)
+  applyTheme(theme)
+  _current.value = theme
+}
+
+function followSystem(system: SystemThemes | null): void {
+  _system.value = system
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return
+  if (system && !_media) {
+    _media = window.matchMedia(DARK_QUERY)
+    _media.addEventListener("change", onSchemeChange)
+  } else if (!system && _media) {
+    _media.removeEventListener("change", onSchemeChange)
+    _media = null
+  }
+}
+
+function readCache(): Cached | null {
   try {
     const cached = localStorage.getItem(CACHE_KEY)
-    if (cached) {
-      _current.value = parseTheme(cached)
-      applyTheme(_current.value)
-      return
+    if (!cached) return null
+    const raw = JSON.parse(cached) as { system?: { light?: unknown; dark?: unknown } }
+    if (raw && typeof raw === "object" && raw.system) {
+      return {
+        system: {
+          light: parseTheme(JSON.stringify(raw.system.light)),
+          dark: parseTheme(JSON.stringify(raw.system.dark)),
+        },
+      }
     }
+    return { theme: parseTheme(cached) }
   } catch {
-    /* ignore — fall through to fallback */
+    return null
   }
-  if (_fallback) {
+}
+
+function hydrateOnce(): void {
+  if (_hydrated || typeof window === "undefined") return
+  _hydrated = true
+  const cached = readCache()
+  if (cached?.system) {
+    followSystem(cached.system)
+    _current.value = pick(cached.system)
+    writeThemeCookie(systemCookieValue(cached.system))
+  } else if (cached?.theme) {
+    _current.value = cached.theme
+    writeThemeCookie(cached.theme.name)
+  } else if (_fallback) {
     _current.value = _fallback
-    applyTheme(_fallback)
+  } else {
+    return
   }
+  applyTheme(_current.value)
 }
 
-export function applyTheme(theme: TokenSet, root: HTMLElement = document.documentElement): void {
+/*
+ * Tokens defined in terms of other tokens. A custom property holding `var()` is
+ * resolved where it is declared, so the stylesheet's `:root` copies only ever
+ * see the root theme. Re-declaring them next to a theme makes a theme applied
+ * to a subtree (applyTheme(theme, el), themeToCssRule(theme, ".x")) carry them.
+ */
+const DERIVED_VARS: readonly (readonly [string, string])[] = [
+  ["--color-surface-overlay", "color-mix(in srgb, var(--color-surface-raised) 94%, transparent)"],
+  ["--color-node-compute", "var(--color-action)"],
+  ["--color-node-transit", "var(--color-accent)"],
+  ["--color-node-edge", "var(--color-brand)"],
+  ["--color-node-unknown", "var(--color-line-strong)"],
+]
+
+/** Every CSS variable a theme sets, in application order. */
+export function themeEntries(input: TokenSet): [string, string][] {
+  const theme = normalizeTheme(input)
+  const out: [string, string][] = []
   for (const [key, cssVar] of Object.entries(COLOR_VARS)) {
-    root.style.setProperty(cssVar, theme.colors[key as keyof ColorTokens])
+    out.push([cssVar, theme.colors[key as keyof ColorTokens]])
   }
   for (const [key, cssVar] of Object.entries(SHAPE_VARS)) {
-    root.style.setProperty(cssVar, `${theme.shape[key as keyof ShapeTokens]}px`)
+    out.push([cssVar, `${theme.shape[key as keyof ShapeTokens]}px`])
   }
   for (const [key, cssVar] of Object.entries(DENSITY_VARS)) {
-    root.style.setProperty(cssVar, `${theme.density[key as keyof DensityTokens]}px`)
+    out.push([cssVar, `${theme.density[key as keyof DensityTokens]}px`])
   }
   for (const [key, cssVar] of Object.entries(FONT_VARS)) {
-    root.style.setProperty(cssVar, theme.font[key as keyof FontTokens])
+    out.push([cssVar, theme.font[key as keyof FontTokens]])
   }
-  // Skin axis is optional; fall back to a flat default so themes saved before
-  // it existed still paint correctly.
   const surface = theme.surface ?? DEFAULT_SURFACE
   for (const [key, cssVar] of Object.entries(SURFACE_VARS)) {
-    root.style.setProperty(cssVar, surface[key as keyof SurfaceTokens])
+    out.push([cssVar, surface[key as keyof SurfaceTokens]])
   }
+  for (const [cssVar, value] of DERIVED_VARS) out.push([cssVar, value])
+  return out
+}
+
+export function applyTheme(theme: TokenSet, root: HTMLElement = document.documentElement): void {
+  for (const [cssVar, value] of themeEntries(theme)) root.style.setProperty(cssVar, value)
   root.dataset.themeMode = theme.mode
   root.style.colorScheme = theme.mode
   // Engine capability, not theme data — but this is the one path every consumer
@@ -157,24 +235,9 @@ export function serializeTheme(theme: TokenSet): string {
  * applyTheme — no duplicated values, the TokenSet stays the single source.
  */
 export function themeToCssVars(theme: TokenSet): string {
-  const decls: string[] = []
-  for (const [key, cssVar] of Object.entries(COLOR_VARS)) {
-    decls.push(`${cssVar}: ${theme.colors[key as keyof ColorTokens]}`)
-  }
-  for (const [key, cssVar] of Object.entries(SHAPE_VARS)) {
-    decls.push(`${cssVar}: ${theme.shape[key as keyof ShapeTokens]}px`)
-  }
-  for (const [key, cssVar] of Object.entries(DENSITY_VARS)) {
-    decls.push(`${cssVar}: ${theme.density[key as keyof DensityTokens]}px`)
-  }
-  for (const [key, cssVar] of Object.entries(FONT_VARS)) {
-    decls.push(`${cssVar}: ${theme.font[key as keyof FontTokens]}`)
-  }
-  const surface = theme.surface ?? DEFAULT_SURFACE
-  for (const [key, cssVar] of Object.entries(SURFACE_VARS)) {
-    decls.push(`${cssVar}: ${surface[key as keyof SurfaceTokens]}`)
-  }
-  return decls.join("; ")
+  return themeEntries(theme)
+    .map(([cssVar, value]) => `${cssVar}: ${value}`)
+    .join("; ")
 }
 
 /** Render a theme as a complete CSS rule (default selector `:root`). */
@@ -182,33 +245,43 @@ export function themeToCssRule(theme: TokenSet, selector = ":root"): string {
   return `${selector} { color-scheme: ${theme.mode}; ${themeToCssVars(theme)}; }`
 }
 
-const DEFAULT_FONT = {
-  sans: '"Inter", "Segoe UI", system-ui, sans-serif',
-  mono: '"JetBrains Mono", "SF Mono", ui-monospace, monospace',
+/*
+ * Fill every axis a theme leaves out from the built-in preset of the same mode.
+ * Themes are stored by consumers and live longer than a kit version: a theme
+ * saved before a token existed would otherwise write `undefined` into that
+ * variable and blank out every utility that reads it.
+ */
+export function normalizeTheme(raw: Partial<TokenSet> & { name?: string }): TokenSet {
+  const mode = raw.mode === "light" ? "light" : "dark"
+  const base = mode === "light" ? lightPreset : darkPreset
+  return {
+    name: typeof raw.name === "string" ? raw.name : base.name,
+    mode,
+    colors: { ...base.colors, ...raw.colors },
+    shape: { ...base.shape, ...raw.shape },
+    density: { ...base.density, ...raw.density },
+    font: { ...base.font, ...raw.font },
+    surface: raw.surface ? { ...DEFAULT_SURFACE, ...raw.surface } : undefined,
+  }
 }
 
-/** Parse + shallow-validate a theme JSON; throws on a malformed shape. */
+/** Parse + validate a theme JSON; throws on a malformed shape. */
 export function parseTheme(json: string): TokenSet {
   const raw = JSON.parse(json) as Partial<TokenSet>
   if (!raw || typeof raw !== "object" || !raw.colors || !raw.shape || !raw.density) {
     throw new Error("Invalid theme: missing colors/shape/density")
   }
-  // font is a newer axis — fill it in for configs saved before it existed.
-  return { ...raw, font: raw.font ?? DEFAULT_FONT } as TokenSet
+  return normalizeTheme(raw)
 }
 
 // ── anti-flash bootstrap ─────────────────────────────────────
 // Call once before mount with your default theme; paints the cached theme (if
 // any) synchronously so the first frame already matches the saved look.
 export function bootstrapTheme(fallback: TokenSet): TokenSet {
-  let theme = fallback
-  try {
-    const cached = localStorage.getItem(CACHE_KEY)
-    if (cached) theme = parseTheme(cached)
-  } catch {
-    /* ignore, use fallback */
-  }
-  applyTheme(theme)
+  const cached = typeof window === "undefined" ? null : readCache()
+  const theme = cached?.system ? pick(cached.system) : (cached?.theme ?? fallback)
+  if (cached?.system) followSystem(cached.system)
+  if (typeof document !== "undefined") applyTheme(theme)
   return theme
 }
 
@@ -216,62 +289,97 @@ export function cacheTheme(theme: TokenSet): void {
   try {
     localStorage.setItem(CACHE_KEY, serializeTheme(theme))
   } catch {
-    /* storage unavailable — non-fatal */
+    /* storage unavailable, non-fatal */
   }
   writeThemeCookie(theme.name)
 }
 
+/** Persist "follow the OS" with the pair it switches between. */
+export function cacheSystemThemes(system: SystemThemes): void {
+  try {
+    localStorage.setItem(CACHE_KEY, JSON.stringify({ system }))
+  } catch {
+    /* storage unavailable, non-fatal */
+  }
+  writeThemeCookie(systemCookieValue(system))
+}
+
 /*
- * SSR handoff. localStorage is invisible to the server, so an SSR app would
- * render the default theme and only repaint after hydration — a visible flash on
- * every reload. The cookie rides along with the request, letting the server
- * inline the user's real theme in the first frame (see themeFromCookie).
- *
- * Only the NAME is stored: a full TokenSet is ~1KB of JSON that would be sent on
- * every request. The server resolves the name against the themes it knows, and
- * localStorage stays the client's source of truth for the full token values.
+ * SSR handoff. localStorage is invisible to the server, so the theme NAME rides
+ * along in a cookie and the server resolves it against the themes it knows
+ * (see themeFromCookie). "Follow the OS" is stored as `system:<light>|<dark>`.
  */
 export const THEME_COOKIE = "lp-theme"
+const SYSTEM_PREFIX = "system:"
 
 const COOKIE_MAX_AGE = 60 * 60 * 24 * 365
 
-function writeThemeCookie(name: string): void {
+function systemCookieValue(system: SystemThemes): string {
+  return `${SYSTEM_PREFIX}${system.light.name}|${system.dark.name}`
+}
+
+function writeThemeCookie(value: string): void {
   if (typeof document === "undefined") return
-  // lax: the theme must survive a top-level navigation (which is what SSR
-  // renders) without riding cross-site subrequests.
   document.cookie =
-    `${THEME_COOKIE}=${encodeURIComponent(name)}` +
+    `${THEME_COOKIE}=${encodeURIComponent(value)}` +
     `; path=/; max-age=${COOKIE_MAX_AGE}; samesite=lax`
 }
 
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
 /**
  * Resolve a theme name (as read from the `lp-theme` cookie) against a set of
  * known themes. Returns `null` when the name is absent or unknown, so the caller
  * can fall back to its own default.
  *
- * Server-side counterpart to `cacheTheme`: pair it with `themeToCssRule` to
- * inline the right variables into `<head>` during SSR.
+ * Accepts both a raw and an already-decoded value: frameworks differ on whether
+ * their cookie helpers decode, and a name containing `%` must not throw.
+ * A "follow the OS" cookie resolves to its dark member unless `prefersDark` is
+ * false (pass it from the `Sec-CH-Prefers-Color-Scheme` request header).
  */
 export function themeFromCookie(
   cookieValue: string | null | undefined,
   themes: readonly TokenSet[],
+  options: { prefersDark?: boolean } = {},
 ): TokenSet | null {
   if (!cookieValue) return null
-  const name = decodeURIComponent(cookieValue)
-  return themes.find((theme) => theme.name === name) ?? null
+  const find = (name: string) => themes.find((theme) => theme.name === name) ?? null
+  for (const value of [cookieValue, safeDecode(cookieValue)]) {
+    if (value.startsWith(SYSTEM_PREFIX)) {
+      const [lightName = "", darkName = ""] = value.slice(SYSTEM_PREFIX.length).split("|")
+      const wanted = options.prefersDark === false ? lightName : darkName
+      const found = find(wanted)
+      if (found) return found
+      continue
+    }
+    const found = find(value)
+    if (found) return found
+  }
+  return null
 }
 
 export interface UseTheme {
   /** The active theme, kept in sync by the kit. Null until hydrated (SSR/first
-   *  paint) — reactive, so a switcher binds straight to it. */
+   *  paint), reactive, so a switcher binds straight to it. */
   current: DeepReadonly<Ref<TokenSet | null>>
   /** The active theme's name (""="not yet hydrated"). */
   currentName: ComputedRef<string>
-  /** Set + persist a theme (with the circular reveal if `origin`/transition).
-   *  This is the one call a switcher needs — it updates `current` too. */
+  /** True while the theme follows the OS colour scheme (see setSystem). */
+  system: ComputedRef<boolean>
+  /** Set + persist a theme (with the circular reveal). Stops following the OS. */
   setTheme: (theme: TokenSet, origin?: RevealOrigin) => void
-  /** Seed the fallback (used when nothing is cached) and hydrate now. Call once
-   *  at app start (client) — optional; the first useTheme() hydrates anyway. */
+  /**
+   * Follow the OS colour scheme, switching between `themes.light` and
+   * `themes.dark` as it changes. Persisted like any other choice.
+   */
+  setSystem: (themes: SystemThemes, origin?: RevealOrigin) => void
+  /** Seed the fallback (used when nothing is cached) and hydrate now. */
   init: (fallback: TokenSet) => TokenSet
   apply: (theme: TokenSet) => void
   applyWithTransition: (theme: TokenSet, origin?: RevealOrigin) => void
@@ -281,14 +389,10 @@ export interface UseTheme {
 }
 
 export function useTheme(): UseTheme {
-  // Lazily hydrate the singleton the first time anyone asks (client only).
   hydrateOnce()
 
-  // The single "set a theme" path the kit owns: apply, cache, and update the
-  // shared reactive state so every consumer + switcher reflects it.
-  const setTheme = (theme: TokenSet, origin?: RevealOrigin) => {
-    if (origin) applyThemeWithTransition(theme, origin)
-    else applyThemeWithTransition(theme)
+  const commit = (theme: TokenSet) => {
+    followSystem(null)
     cacheTheme(theme)
     _current.value = theme
   }
@@ -296,29 +400,31 @@ export function useTheme(): UseTheme {
   return {
     current: readonly(_current),
     currentName: computed(() => _current.value?.name ?? ""),
-    setTheme,
+    system: computed(() => _system.value !== null),
+    setTheme: (theme, origin) => {
+      applyThemeWithTransition(theme, origin)
+      commit(theme)
+    },
+    setSystem: (themes, origin) => {
+      const theme = pick(themes)
+      applyThemeWithTransition(theme, origin)
+      followSystem(themes)
+      cacheSystemThemes(themes)
+      _current.value = theme
+    },
     init: (fallback: TokenSet) => {
       _fallback = fallback
-      if (!_hydrated) hydrateOnce()
-      if (!_current.value) {
-        _current.value = bootstrapTheme(fallback)
-      }
+      hydrateOnce()
+      if (!_current.value) _current.value = bootstrapTheme(fallback)
       return _current.value
     },
     apply: (theme: TokenSet) => {
       applyTheme(theme)
-      cacheTheme(theme)
-      _current.value = theme
+      commit(theme)
     },
-    /**
-     * Apply + cache a theme with the circular reveal animation. Pass the click
-     * point (e.g. from a toggle's `event`) as `origin` so the circle grows from
-     * the button; omit it to reveal from the viewport centre.
-     */
     applyWithTransition: (theme: TokenSet, origin?: RevealOrigin) => {
       applyThemeWithTransition(theme, origin)
-      cacheTheme(theme)
-      _current.value = theme
+      commit(theme)
     },
     serialize: serializeTheme,
     parse: parseTheme,

package/dist/chunks/LpBreadcrumbs-p4jHe_V-.js

@@ -1,62 +0,0 @@
-import { defineComponent, openBlock, createElementBlock, mergeProps, unref, Fragment, renderList, createBlock, createCommentVNode, resolveDynamicComponent, withCtx, createTextVNode, toDisplayString, normalizeClass } from "vue";
-import { _ as _sfc_main$1 } from "./LpIcon-CCnX5_2j.js";
-import { useMergedAttrs } from "../composables/useMergedClass.js";
-const __default__ = { inheritAttrs: false };
-const _sfc_main = /* @__PURE__ */ defineComponent({
-  ...__default__,
-  __name: "LpBreadcrumbs",
-  props: {
-    items: {},
-    as: { default: "a" }
-  },
-  emits: ["navigate"],
-  setup(__props) {
-    const { class: rootClass, attrs: rest } = useMergedAttrs(
-      "flex items-center gap-1.5 text-sm"
-    );
-    return (_ctx, _cache) => {
-      return openBlock(), createElementBlock("nav", mergeProps({ class: unref(rootClass) }, unref(rest), { "aria-label": "Breadcrumb" }), [
-        (openBlock(true), createElementBlock(Fragment, null, renderList(__props.items, (item, i) => {
-          return openBlock(), createElementBlock(Fragment, { key: i }, [
-            i > 0 ? (openBlock(), createBlock(_sfc_main$1, {
-              key: 0,
-              name: "lucide:chevron-right",
-              size: 14,
-              class: "text-muted"
-            })) : createCommentVNode("", true),
-            (item.href || item.to) && i < __props.items.length - 1 ? (openBlock(), createBlock(resolveDynamicComponent(__props.as), {
-              key: 1,
-              href: __props.as === "a" ? item.href : void 0,
-              to: __props.as === "a" ? void 0 : item.to,
-              class: "inline-flex items-center gap-1.5 rounded-xs text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring",
-              onClick: ($event) => _ctx.$emit("navigate", item, i)
-            }, {
-              default: withCtx(() => [
-                item.icon ? (openBlock(), createBlock(_sfc_main$1, {
-                  key: 0,
-                  name: item.icon,
-                  size: 14
-                }, null, 8, ["name"])) : createCommentVNode("", true),
-                createTextVNode(" " + toDisplayString(item.label), 1)
-              ]),
-              _: 2
-            }, 1032, ["href", "to", "onClick"])) : (openBlock(), createElementBlock("span", {
-              key: 2,
-              class: normalizeClass(["inline-flex items-center gap-1.5", i === __props.items.length - 1 ? "text-ink" : "text-muted"])
-            }, [
-              item.icon ? (openBlock(), createBlock(_sfc_main$1, {
-                key: 0,
-                name: item.icon,
-                size: 14
-              }, null, 8, ["name"])) : createCommentVNode("", true),
-              createTextVNode(" " + toDisplayString(item.label), 1)
-            ], 2))
-          ], 64);
-        }), 128))
-      ], 16);
-    };
-  }
-});
-export {
-  _sfc_main as _
-};