@leavepulse/ui 0.12.0

package/src/theme/useTheme.ts

@@ -0,0 +1,288 @@
+/*
+ * Theme engine. A theme is a TokenSet (plain JSON); applyTheme() writes it to
+ * CSS variables at runtime so every kit component re-skins live. Includes an
+ * anti-flash bootstrap (paint the cached theme before mount) and JSON
+ * serialize/parse with validation.
+ */
+import { computed, readonly, shallowRef, type ComputedRef, type DeepReadonly, type Ref } from "vue"
+import {
+  COLOR_VARS,
+  DEFAULT_SURFACE,
+  DENSITY_VARS,
+  FONT_VARS,
+  SHAPE_VARS,
+  SURFACE_VARS,
+  type ColorTokens,
+  type DensityTokens,
+  type FontTokens,
+  type ShapeTokens,
+  type SurfaceTokens,
+  type TokenSet,
+} from "./tokens"
+
+const CACHE_KEY = "leavepulse-ui-theme"
+
+// ── 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.
+const _current = shallowRef<TokenSet | 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
+  try {
+    const cached = localStorage.getItem(CACHE_KEY)
+    if (cached) {
+      _current.value = parseTheme(cached)
+      applyTheme(_current.value)
+      return
+    }
+  } catch {
+    /* ignore — fall through to fallback */
+  }
+  if (_fallback) {
+    _current.value = _fallback
+    applyTheme(_fallback)
+  }
+}
+
+export function applyTheme(theme: TokenSet, root: HTMLElement = document.documentElement): void {
+  for (const [key, cssVar] of Object.entries(COLOR_VARS)) {
+    root.style.setProperty(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`)
+  }
+  for (const [key, cssVar] of Object.entries(DENSITY_VARS)) {
+    root.style.setProperty(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])
+  }
+  // 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])
+  }
+  root.dataset.themeMode = theme.mode
+  root.style.colorScheme = theme.mode
+}
+
+/** Point a circular theme reveal expands from (viewport px). */
+export interface RevealOrigin {
+  x: number
+  y: number
+}
+
+type ViewTransitionDocument = Document & {
+  startViewTransition?: (cb: () => void) => { ready: Promise<void>; finished: Promise<void> }
+}
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true
+  )
+}
+
+/*
+ * Apply a theme with the "circular reveal" transition — a clip-path circle
+ * grows from `origin` (usually the toggle button's centre), repainting the page
+ * underneath. Uses the View Transitions API; falls back to a plain applyTheme
+ * when it's unsupported or the user prefers reduced motion (so behaviour is
+ * identical, just without the animation). The actual token write still happens
+ * through applyTheme, so this stays a thin wrapper — no duplicated var logic.
+ */
+export function applyThemeWithTransition(
+  theme: TokenSet,
+  origin?: RevealOrigin,
+  root: HTMLElement = document.documentElement,
+  durationMs = 480,
+): void {
+  const doc = document as ViewTransitionDocument
+  if (typeof doc.startViewTransition !== "function" || prefersReducedMotion()) {
+    applyTheme(theme, root)
+    return
+  }
+
+  // Centre of the viewport is the default origin if no click point is given.
+  const x = origin?.x ?? window.innerWidth / 2
+  const y = origin?.y ?? window.innerHeight / 2
+  // Radius that reaches the farthest viewport corner from the origin.
+  const endRadius = Math.hypot(
+    Math.max(x, window.innerWidth - x),
+    Math.max(y, window.innerHeight - y),
+  )
+
+  const transition = doc.startViewTransition(() => applyTheme(theme, root))
+  transition.ready.then(() => {
+    // Animate the OLD snapshot shrinking to a point, revealing the (already
+    // repainted) live page underneath through the growing hole. Clipping the
+    // old layer — not growing the new one — avoids a one-frame flash of the new
+    // theme before the circle starts, which read as the theme "changing twice".
+    root.animate(
+      {
+        clipPath: [`circle(${endRadius}px at ${x}px ${y}px)`, `circle(0px at ${x}px ${y}px)`],
+      },
+      {
+        duration: durationMs,
+        easing: "cubic-bezier(0.2, 0, 0, 1)",
+        // Hold the fully-shrunk circle after the keyframes end. Without it the
+        // old snapshot snaps back to its default (un-clipped) state for the one
+        // frame between animation-end and the browser tearing down the
+        // view-transition pseudo-elements — that flash is the old theme
+        // "blinking" at the very end.
+        fill: "forwards",
+        pseudoElement: "::view-transition-old(root)",
+      },
+    )
+  })
+}
+
+export function serializeTheme(theme: TokenSet): string {
+  return JSON.stringify(theme)
+}
+
+/*
+ * Render a theme as CSS custom-property declarations (the body of a rule, e.g.
+ * `--color-brand: #00bcff; …`). Same var mapping as applyTheme, so a server can
+ * inline the theme into a <style> for the first paint while the client uses
+ * 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("; ")
+}
+
+/** Render a theme as a complete CSS rule (default selector `:root`). */
+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',
+}
+
+/** Parse + shallow-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
+}
+
+// ── 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)
+  return theme
+}
+
+export function cacheTheme(theme: TokenSet): void {
+  try {
+    localStorage.setItem(CACHE_KEY, serializeTheme(theme))
+  } catch {
+    /* storage unavailable — non-fatal */
+  }
+}
+
+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. */
+  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. */
+  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. */
+  init: (fallback: TokenSet) => TokenSet
+  apply: (theme: TokenSet) => void
+  applyWithTransition: (theme: TokenSet, origin?: RevealOrigin) => void
+  serialize: typeof serializeTheme
+  parse: typeof parseTheme
+  bootstrap: typeof bootstrapTheme
+}
+
+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)
+    cacheTheme(theme)
+    _current.value = theme
+  }
+
+  return {
+    current: readonly(_current),
+    currentName: computed(() => _current.value?.name ?? ""),
+    setTheme,
+    init: (fallback: TokenSet) => {
+      _fallback = fallback
+      if (!_hydrated) hydrateOnce()
+      if (!_current.value) {
+        _current.value = bootstrapTheme(fallback)
+      }
+      return _current.value
+    },
+    apply: (theme: TokenSet) => {
+      applyTheme(theme)
+      cacheTheme(theme)
+      _current.value = 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
+    },
+    serialize: serializeTheme,
+    parse: parseTheme,
+    bootstrap: bootstrapTheme,
+  }
+}

package/src/tokens/scrollbar.css

@@ -0,0 +1,138 @@
+/*
+ * Native scrollbar skin — opt-in. Styles the browser's OWN scrollbars (the
+ * window scroll and any `overflow:auto/scroll` element) to match LpScrollArea:
+ * a thin, rounded, brand-tinted thumb on a transparent track. Use this when you
+ * want the kit look on scroll that LpScrollArea can't own — the page itself,
+ * sticky panels, code blocks — without wrapping everything in a component.
+ *
+ * It does NOT replace the native scroll mechanism (no container, no JS), so
+ * sticky positioning, scroll restoration, anchor jumps and IntersectionObserver
+ * keep working. It's purely cosmetic.
+ *
+ * Reads --color-brand (kit token), so import it AFTER the tokens:
+ *   @import "@leavepulse/ui";
+ *   @import "@leavepulse/ui/scrollbar";
+ *
+ * Falls back to a neutral tint if --color-brand is absent.
+ */
+
+:root {
+  --lp-scrollbar-size: 10px;
+  --lp-scrollbar-thumb: color-mix(
+    in oklab,
+    var(--color-brand, #7a8a84) 40%,
+    transparent
+  );
+  --lp-scrollbar-thumb-hover: var(--color-brand, #c7d2cc);
+}
+
+/* Firefox — Chrome ignores ::-webkit-* once scrollbar-width is set, so scope it. */
+@supports (-moz-appearance: none) {
+  html {
+    scrollbar-width: thin;
+    scrollbar-color: var(--lp-scrollbar-thumb) transparent;
+  }
+}
+
+*::-webkit-scrollbar {
+  width: var(--lp-scrollbar-size);
+  height: var(--lp-scrollbar-size);
+  background: transparent;
+}
+
+*::-webkit-scrollbar-track,
+*::-webkit-scrollbar-track-piece {
+  background: transparent;
+  border: none;
+  box-shadow: none;
+}
+
+*::-webkit-scrollbar-thumb {
+  background-color: var(--lp-scrollbar-thumb);
+  border-radius: 9999px;
+  /* Transparent border + padding-box clip = a slim thumb floating in a wider
+     hit area, the way LpScrollArea's overlay bar reads. */
+  border: 3px solid transparent;
+  background-clip: padding-box;
+  min-height: 40px;
+  transition: background-color var(--duration-fast, 120ms) ease;
+}
+
+*::-webkit-scrollbar-thumb:hover {
+  background-color: var(--lp-scrollbar-thumb-hover);
+  background-clip: padding-box;
+}
+
+*::-webkit-scrollbar-corner {
+  background: transparent;
+}
+
+*::-webkit-scrollbar-button {
+  display: none;
+  width: 0;
+  height: 0;
+}
+
+/* Chrome reads the root scrollbar from body, not html/*, so repeat for body. */
+body::-webkit-scrollbar {
+  width: var(--lp-scrollbar-size);
+  height: var(--lp-scrollbar-size);
+  background: transparent;
+}
+
+body::-webkit-scrollbar-track,
+body::-webkit-scrollbar-track-piece {
+  background: transparent;
+  border: none;
+  box-shadow: none;
+}
+
+body::-webkit-scrollbar-thumb {
+  background-color: var(--lp-scrollbar-thumb);
+  border-radius: 9999px;
+  border: 3px solid transparent;
+  background-clip: padding-box;
+  min-height: 40px;
+}
+
+body::-webkit-scrollbar-thumb:hover {
+  background-color: var(--lp-scrollbar-thumb-hover);
+  background-clip: padding-box;
+}
+
+body::-webkit-scrollbar-corner {
+  background: transparent;
+}
+
+body::-webkit-scrollbar-button {
+  display: none;
+  width: 0;
+  height: 0;
+}
+
+/*
+ * Per-element opt-out (hide the bar entirely — carousels, the CodeBlock editor,
+ * etc.) lives in utilities.css as `.lp-scrollbar-none`, shipped with the main
+ * import so it's available even without this opt-in skin.
+ */
+
+/*
+ * GLOBAL opt-in: drop the native scrollbar from the layout flow site-wide so it
+ * never reserves viewport width (the page still scrolls — bar is just hidden).
+ * Add the class to <html> at the app root:
+ *   <html class="lp-scroll-hide">
+ * Pair with LpScrollArea (or the skin above) for any region that should still
+ * show a bar. This only hides the document's own bar; nested overflow elements
+ * keep theirs unless they also carry .lp-scrollbar-none.
+ */
+html.lp-scroll-hide {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+
+html.lp-scroll-hide::-webkit-scrollbar,
+html.lp-scroll-hide body::-webkit-scrollbar {
+  display: none;
+  width: 0;
+  height: 0;
+}