# Stat Cards (Lumen Halo): prompt.md (v1.2.0) - id: `glass-stat-cards` · version 1.2.0 · component · free - category: Charts - build: Base UI (one set of files; its dependencies follow the build) - install (this build): `npx shadcn@latest add https://beautiful-ui.dev/r/glass-stat-cards.json` - npm dependencies: @web-kits/audio@^0.2 - registry dependencies: https://beautiful-ui.dev/r/beautiful-ui.json - docs: https://beautiful-ui.dev/components/glass-stat-cards - The install command carries everything this item needs (files, CSS, tokens, npm and registry dependencies). Prefer it to copying source by hand. Liquid-glass KPI cards in dark and light, in hero, default and compact sizes: the number, whether the change is good or bad, and whether the data can be trusted, with a headline that names what moved the wrong way, period tabs, rolling digits, cell trends and a drill-in. ## Build it - Stack: React 19 (`ref` is a plain prop), TypeScript, Tailwind CSS v4 utilities, a shadcn-initialised project with the `@/*` alias. - Packages: `@web-kits/audio`. - Source: `components/beautiful-ui/glass-stat-cards.tsx`, shared code in `lib/beautiful-ui/`. - Exports to keep: `GlassStatCards`, `GlassStatCard`, and every exported type. - CSS: none to add. Themes, tokens and keyframes are inlined by the component (a deduped ` onOpen() : undefined} /> ); } // --------------------------------------------------------------------------------------------- // GlassStatCards // --------------------------------------------------------------------------------------------- const STAGGER = 60; const TAB_W = 58; /** The KPI row: headline, period tabs, hero, default and compact cards, and the drill-in panel. */ export function GlassStatCards({ metrics, periods = defaultGlassStatPeriods, period, defaultPeriod, onPeriodChange, hero, sizes = ["hero", "default", "compact"], eyebrow = "WORKSPACE · PULSE", openId: openIdProp, defaultOpenId = null, onOpenChange, formatValue, locale, currency, formatDate, labels, now, motion = "full", layout = "auto", theme = "system", sound = true, className, style, ref, ...rest }: GlassStatCardsProps) { const level = useLevel(motion); const sfx = useGlassSound(sound); const L = React.useMemo(() => mergeLabels(defaultGlassStatCardsLabels, labels), [labels]); const ctx: StatCtx = { L, formatDate: formatDate ?? formatGlassStatDate }; const tx = mkTx(level); const list = React.useMemo(() => (Array.isArray(metrics) ? metrics : defaultGlassStatMetrics).filter((m) => m && typeof m.id === "string"), [metrics]); // The designed data carries its own clock, so it always reads "Updated 2 min ago". const clock = useNow(now ?? (metrics === undefined ? GLASS_STAT_DEMO_NOW : undefined)); const hydrated = useHydrated(); const pers = React.useMemo( () => (Array.isArray(periods) && periods.length ? periods : [...new Set(list.flatMap((m) => Object.keys(m.data ?? {})))]) .map((p) => (typeof p === "string" ? { id: p } : p)) .filter((p): p is GlassStatPeriod => !!p && typeof p.id === "string") .map((p) => ({ id: p.id, label: p.label ?? p.id, name: p.name ?? L.periodName(p.label ?? p.id) })), [periods, list, L], ); const [inner, setInner] = React.useState(() => defaultPeriod ?? (pers.some((p) => p.id === "30D") ? "30D" : pers[0]?.id ?? "")); const want = period ?? inner; const cur = pers.find((p) => p.id === want) ?? pers[0] ?? { id: "", label: "", name: "" }; const pi = Math.max(0, pers.indexOf(cur as (typeof pers)[number])); const rootRef = React.useRef(null); const setRoot = React.useCallback( (el: HTMLDivElement | null) => { rootRef.current = el; if (typeof ref === "function") return ref(el); if (ref) ref.current = el; }, [ref], ); const seen = useSeenOnce(rootRef); const shown = seen || level === "off"; // The entrance staggers cards (and their cells) once; later period switches ripple together. const [introDone, setIntroDone] = React.useState(false); React.useEffect(() => { if (!shown || introDone) return; const t = window.setTimeout(() => setIntroDone(true), 1800); return () => window.clearTimeout(t); }, [shown, introDone]); const statsFor = (per: (typeof pers)[number]) => list.map((m) => { const d = m.data?.[per.id]; return { m, s: statModel( { label: m.label, value: d?.value ?? null, previous: d?.previous, unit: m.unit, format: m.format ?? (formatValue ? (v: number) => formatValue(v, m) : undefined), suffix: m.suffix, locale, currency, goodDirection: m.goodDirection, periodLabel: per.label, periodName: per.name, trend: d?.trend, goal: d?.goal, updatedAt: d?.updatedAt ?? m.updatedAt, trackingSince: m.trackingSince, staleAfterMs: m.staleAfterMs, }, clock, hydrated, ctx, ), }; }); const stats = statsFor(cur); const nameOf = (m: GlassStatMetric) => m.name ?? sentenceCase(m.label); const headFor = (st: typeof stats, per: (typeof pers)[number]) => glassStatHeadline(st.map((x) => ({ name: nameOf(x.m), tone: x.s.tone, missing: x.s.missing })), per.name, L); const [headA, headB] = headFor(stats, cur); const heroId = hero === null ? null : (hero ?? (list.find((m) => Object.values(m.data ?? {}).some((d) => isNum(d?.goal))) ?? list[0])?.id ?? null); const heroStat = heroId != null ? stats.find((x) => x.m.id === heroId) : undefined; const show = (k: GlassStatSize) => sizes.includes(k); // --- drill-in --- const [innerOpen, setInnerOpen] = React.useState(defaultOpenId); const controlledOpen = openIdProp !== undefined; const wanted = controlledOpen ? openIdProp : innerOpen; // An id that is not (or no longer) in the data reads as closed. const openId = wanted != null && list.some((m) => m.id === wanted) ? wanted : null; const setOpenId = (id: string | null) => { if (!controlledOpen) setInnerOpen(id); }; const [lastId, setLastId] = React.useState(null); if (openId && openId !== lastId) setLastId(openId); // The open metric went away with new data: forget it (adjusted during render). if (!controlledOpen && innerOpen && !openId) setInnerOpen(null); const [armed, setArmed] = React.useState(false); if (!openId && armed) setArmed(false); React.useEffect(() => { if (!openId) return; // Two frames: the cells render empty first, so they ripple in. let r2 = 0; const r1 = requestAnimationFrame(() => (r2 = requestAnimationFrame(() => setArmed(true)))); return () => { cancelAnimationFrame(r1); cancelAnimationFrame(r2); }; }, [openId]); const opener = React.useRef(null); const panelRef = React.useRef(null); const wantFocus = React.useRef(false); const uid = React.useId(); const panelId = `${uid}-drill`; const titleId = `${uid}-drill-title`; const toggle = (id: string, el: HTMLElement) => { const next = openId === id ? null : id; opener.current = el; wantFocus.current = next != null; setOpenId(next); onOpenChange?.(next); }; const close = () => { if (!openId) return; setOpenId(null); onOpenChange?.(null); const el = opener.current; if (el?.isConnected) el.focus(); }; React.useEffect(() => { if (!openId || !wantFocus.current) return; wantFocus.current = false; const p = panelRef.current; if (!p) return; p.focus({ preventScroll: true }); // Once grown, bring the panel into view if it opened below the fold. const instant = level === "off" || level === "reduced"; const t = window.setTimeout( () => { if (p.isConnected && p.getBoundingClientRect().bottom > window.innerHeight) p.scrollIntoView({ block: "nearest", behavior: instant ? "auto" : "smooth" }); }, instant ? 0 : 620, ); return () => window.clearTimeout(t); }, [openId, level]); const drillStat = stats.find((x) => x.m.id === (openId ?? lastId)); // --- period --- const [said, setSaid] = React.useState(""); const pick = (i: number) => { const p = pers[i]; if (!p || p.id === cur.id) return; if (period === undefined) setInner(p.id); onPeriodChange?.(p.id); const [a, b] = headFor(statsFor(p), p); setSaid(`${cap1(p.name)}. ${a} ${b}`); }; const tabW = Math.max(TAB_W, ...pers.map((p) => Math.ceil(p.label.length * 7.4 + 22))); const onTabKey = (ev: React.KeyboardEvent) => { const n = pers.length; if (!n) return; let k = -1; if (ev.key === "ArrowRight") k = (pi + 1) % n; else if (ev.key === "ArrowLeft") k = (pi + n - 1) % n; else if (ev.key === "Home") k = 0; else if (ev.key === "End") k = n - 1; if (k < 0) return; ev.preventDefault(); if (k !== pi) sfx.play("select", { index: k }); pick(k); ev.currentTarget.querySelectorAll("[role=tab]")[k]?.focus(); }; const { "aria-label": ariaLabel, ...rootRest } = rest; // Entrance order: hero, then the row, then the compact row, 60ms apart. let order = 0; const introAt = (): Intro => ({ shown, delay: introDone ? 0 : order++ * STAGGER }); return (
{ rootRest.onKeyDown?.(e); if (e.defaultPrevented) return; if (e.key === "Escape" && openId) { e.preventDefault(); sfx.play("close"); close(); } }} >
{/* Header */}
{eyebrow}

{headA} {headB && ( <> {" "} {headB} )}

{pers.length > 1 && ( // Tabs keep their designed 58px and share the width when a narrow container can't fit them.
{pers.map((p, i) => ( ))}
)}
{/* The cards: the tabs' panel (same flex column and gap as the shell) */}
1 ? "tabpanel" : undefined} aria-labelledby={pers.length > 1 ? `${uid}-tab-${pi}` : undefined} data-gsc-body="" className="relative flex flex-col" style={{ gap: 22 }}> {/* Hero */} {show("hero") && heroStat && ( toggle(heroStat.m.id, el)} /> )} {/* Default row */} {show("default") && stats.length > 0 && (
{stats.map(({ m, s }) => ( toggle(m.id, el)} /> ))}
)} {/* Drill-in */}
{drillStat && }
{/* Compact row */} {show("compact") && stats.length > 0 && (
{stats.map(({ m, s }) => ( toggle(m.id, el)} /> ))}
)}
{said}
); } /** The drill-in: 12 intervals as 12-row cell columns, the first and last labelled (hover a column for its value). */ function Drill({ s, name, live, tx, titleId, onClose }: { s: Stat; name: string; live: boolean; tx: Tx; titleId: string; onClose: () => void }) { const t = s.trend; const n = t ? glassStatCells(t, 12) : []; const firstI = t ? t.findIndex((v) => v != null) : -1; const count = t ? t.length - firstI : 0; return (
{name} {`· ${s.perName}, ${s.L.intervals(count)}`}
{t ? ( <>
{t.map((v, i) => { const last = i === t.length - 1; const first = i === firstI; return (
{v != null ? formatGlassStatValue(v, s.unit, s.fo) : NBSP}
{Array.from({ length: 12 }, (_, j) => ( ))}
{v == null ? NBSP : last ? s.L.now : String(i - firstI + 1)}
); })}
    {t.map((v, i) => (v != null ?
  1. {`${i === t.length - 1 ? s.L.now : s.L.interval(i - firstI + 1)}: ${formatGlassStatValue(v, s.unit, s.fo)}`}
    2. : null))}
) : (
{s.L.noIntervals}
)}
); } export default GlassStatCards; ``` ### lib/beautiful-ui/glass-sound.tsx ```tsx "use client"; /* * Lumen sound: the voice of the glass family. A thin layer over a Web Audio synthesiser * (@web-kits/audio today). Components never import the engine; they call play(cue) or mark * elements with data-sound, and this file decides what that sounds like. * * - No provider, no sound: play() is a silent no-op and the engine is never loaded. * - Nothing plays, and no AudioContext exists, before the first user gesture. * - Mute persists in localStorage ("beautiful-ui-sound"), SSR safe, never throws. * - The click layer: inside the provider every click on something interactive answers with a * cue. data-sound="" picks a richer one, data-sound="none" means the element plays its * own, data-sound="off" silences a whole subtree. * * The voice: sine glints with a quiet inharmonic partial (×2.756, a struck glass bar), 2ms * attacks, no reverb, all in D major pentatonic around D6. Short, soft, never harsh. */ import * as React from "react"; import type { Layer, PlayOptions, SoundDefinition } from "@web-kits/audio"; import { GLASS_FOCUS, GlassThemeStyle, mergeLabels, type GlassLabels, type GlassTheme } from "@/lib/beautiful-ui/glass"; // --------------------------------------------------------------------------------------------- // Vocabulary // --------------------------------------------------------------------------------------------- /** Every cue in the Lumen vocabulary, grouped as they are documented. */ export const GLASS_SOUND_GROUPS = { presses: ["tap", "select", "destructive"], toggles: ["toggleOn", "toggleOff"], surfaces: ["open", "close", "swoosh"], values: ["tick", "sliderTick", "key"], outcomes: ["success", "error", "warning"], named: ["copy", "notification", "chirp", "command", "blocked", "lock", "halt"], } as const; export type GlassSoundGroup = keyof typeof GLASS_SOUND_GROUPS; export type GlassSoundCue = (typeof GLASS_SOUND_GROUPS)[GlassSoundGroup][number]; export const GLASS_SOUND_CUES = Object.values(GLASS_SOUND_GROUPS).flat() as GlassSoundCue[]; export function isGlassSoundCue(value: unknown): value is GlassSoundCue { return typeof value === "string" && (GLASS_SOUND_CUES as string[]).includes(value); } /** One sound, as the engine describes it (layers, envelope, filters). */ export type GlassSoundDefinition = SoundDefinition; /** What a cue can be told when it plays. */ export interface GlassSoundPlayOptions { /** Position in a group (tabs, options, OTP digits): select and key step up D major pentatonic. */ index?: number; /** Pitch shift in semitones (can be fractional). */ pitch?: number; /** Volume multiplier, 0–1. */ volume?: number; /** Stereo position, −1 (left) to 1 (right). */ pan?: number; /** Skip the per-cue throttle (for sequences you schedule yourself). */ force?: boolean; /** Which theme's patch plays the cue. Default "lumen"; the click layer reads data-sound-voice. */ voice?: GlassSoundVoice; } /** * A theme's voice: the same cue vocabulary, patched in that theme's sound. Components mark their * root with data-sound-voice, so one provider plays each theme in its own voice. */ export type GlassSoundVoice = "lumen" | "analogue"; export const GLASS_SOUND_VOICES: readonly GlassSoundVoice[] = ["lumen", "analogue"]; export const isGlassSoundVoice = (value: unknown): value is GlassSoundVoice => value === "lumen" || value === "analogue"; /** A component's `sound` prop: true (default) plays when a provider enables sound, false never, "subtle" at 55%. */ export type GlassSoundProp = boolean | "subtle"; // --------------------------------------------------------------------------------------------- // The Lumen voice // --------------------------------------------------------------------------------------------- const GLASS_RATIO = 2.756; // first overtone of a free glass bar: what makes a sine sound struck type Freq = number | { start: number; end: number }; const scale = (f: Freq, k: number): Freq => (typeof f === "number" ? f * k : { start: f.start * k, end: f.end * k }); /** A struck glass note: the fundamental and a quiet, faster-fading overtone. */ function glint(freq: Freq, decay: number, gain: number, { delay = 0, attack = 0.002, ring = 0.16 } = {}): Layer[] { const layers: Layer[] = [{ source: { type: "sine", frequency: freq }, envelope: { attack, decay }, gain, delay }]; if (ring > 0) layers.push({ source: { type: "sine", frequency: scale(freq, GLASS_RATIO) }, envelope: { attack, decay: decay * 0.42 }, gain: gain * ring, delay }); return layers; } /** A breath of filtered noise: the air a surface moves. */ function air(from: number, to: number, attack: number, decay: number, gain: number, delay = 0): Layer { return { source: { type: "noise", color: "pink" }, filter: { type: "bandpass", frequency: from, resonance: 1.1, envelope: { attack, peak: to, decay } }, envelope: { attack, decay }, gain, delay, }; } /** A soft, rounded low tone (errors, blocked, destructive): triangle through a lowpass. */ function knock(freq: Freq, decay: number, gain: number, delay = 0, cutoff = 1500): Layer { return { source: { type: "triangle", frequency: freq }, filter: { type: "lowpass", frequency: cutoff, resonance: 0.4 }, envelope: { attack: 0.003, decay }, gain, delay }; } // D major pentatonic around D6: the key every Lumen cue lives in. const D5 = 587.33, E5 = 659.26, A5 = 880, B5 = 987.77, D6 = 1174.66, E6 = 1318.51, Fs6 = 1479.98, A6 = 1760, D7 = 2349.32, E7 = 2637.02; /** The designed Lumen patch. Levels are before the provider volume (default 0.8). */ export const GLASS_SOUND_PATCH: Record = { // Presses tap: { layers: [...glint({ start: 1540, end: Fs6 }, 0.034, 0.05, { ring: 0.12 }), { source: { type: "noise", color: "white" }, filter: { type: "highpass", frequency: 6000 }, envelope: { attack: 0.001, decay: 0.006 }, gain: 0.006 }] }, select: { layers: glint(D6, 0.055, 0.045, { ring: 0.2 }) }, destructive: { layers: [knock({ start: E5, end: D5 }, 0.1, 0.07), ...glint(A5 / 2, 0.08, 0.03, { ring: 0 })] }, // Toggles toggleOn: { layers: [...glint(B5, 0.038, 0.04), ...glint(E6, 0.07, 0.045, { delay: 0.048 })] }, toggleOff: { layers: [...glint(E6, 0.038, 0.04), ...glint(B5, 0.07, 0.04, { delay: 0.048 })] }, // Surfaces open: { layers: [{ source: { type: "sine", frequency: { start: 740, end: D6 } }, envelope: { attack: 0.012, decay: 0.11 }, gain: 0.035 }, air(2200, 5200, 0.02, 0.09, 0.012)] }, close: { layers: [{ source: { type: "sine", frequency: { start: D6, end: 700 } }, envelope: { attack: 0.006, decay: 0.09 }, gain: 0.03 }, air(3600, 1600, 0.008, 0.08, 0.01)] }, swoosh: { layers: [air(900, 4200, 0.05, 0.17, 0.045), ...glint(A6, 0.09, 0.012, { delay: 0.07, ring: 0 })] }, // Values tick: { layers: glint(D7, 0.012, 0.016, { ring: 0 }) }, sliderTick: { layers: glint(E7, 0.008, 0.009, { ring: 0 }) }, key: { layers: glint(A5 * 1.5, 0.035, 0.03, { ring: 0.12 }) }, // Outcomes success: { layers: [...glint(D6, 0.12, 0.04), ...glint(A6, 0.26, 0.045, { delay: 0.075, ring: 0.22 })] }, error: { layers: [knock(E5, 0.09, 0.05, 0, 1600), knock(D5 * 0.89, 0.15, 0.05, 0.085, 1400)] }, warning: { layers: [...glint(A5, 0.06, 0.04), ...glint(A5, 0.08, 0.035, { delay: 0.1 })] }, // Named copy: { layers: [...glint(A6, 0.045, 0.035), ...glint(D7, 0.09, 0.03, { delay: 0.035 })] }, notification: { layers: [...glint(D6, 0.5, 0.028, { attack: 0.004 }), ...glint(Fs6, 0.45, 0.02, { delay: 0.02, attack: 0.004 }), ...glint(A6, 0.5, 0.018, { delay: 0.04, attack: 0.004 })] }, chirp: { layers: [{ source: { type: "sine", frequency: { start: 1300, end: 2200 } }, envelope: { attack: 0.004, decay: 0.05 }, gain: 0.028 }] }, command: { layers: [...glint(A5, 0.08, 0.035), ...glint(E6, 0.08, 0.025, { ring: 0 }), ...glint(A6, 0.14, 0.032, { delay: 0.045 })] }, blocked: { layers: [knock(330, 0.05, 0.055, 0, 900), knock(330, 0.06, 0.04, 0.07, 900)] }, // A mechanical seat (Analogue plate presses) and a stopped run (Analogue signal outcomes), in glass. lock: { layers: [...glint(Fs6, 0.02, 0.04, { ring: 0 }), ...glint(A5, 0.04, 0.04, { delay: 0.02, ring: 0.1 })] }, halt: { layers: [knock(D5 / 2, 0.06, 0.06, 0, 1000), knock(D5 / 2.2, 0.07, 0.05, 0.07, 1000)] }, }; // --------------------------------------------------------------------------------------------- // The Analogue voice: dry, mechanical, single partials. Sine sweeps and 10ms noise ticks with a 3ms // linear attack and an exponential release, peaking at −18 dBFS (the Analogue Button handoff). // --------------------------------------------------------------------------------------------- const sweep = (from: number, to: number, len: number, gain: number, delay = 0): Layer => ({ source: { type: "sine", frequency: from === to ? from : { start: from, end: to } }, envelope: { attack: 0.003, decay: len }, gain, delay, }); const noiseTick = (gain: number, delay = 0): Layer => ({ source: { type: "noise", color: "white" }, filter: { type: "highpass", frequency: 3200 }, envelope: { attack: 0.001, decay: 0.01 }, gain, delay, }); /** The Analogue patch. Cues it does not define fall back to the Lumen patch. */ export const ANALOGUE_SOUND_PATCH: Partial> = { // tap: 1200→1150 Hz, 25ms. tick: 10ms noise through a 3.2 kHz highpass. tap: { layers: [sweep(1200, 1150, 0.025, 0.1)] }, select: { layers: [noiseTick(0.28)] }, tick: { layers: [noiseTick(0.28)] }, sliderTick: { layers: [noiseTick(0.16)] }, key: { layers: [noiseTick(0.22)] }, // low tap: 520→440 Hz, 45ms (stop and destroy). destructive: { layers: [sweep(520, 440, 0.045, 0.12)] }, // click-lock: 1.4 kHz for 12ms, then 900 Hz for 20ms at +20ms (the plate seating). lock: { layers: [sweep(1400, 1300, 0.012, 0.08), sweep(900, 880, 0.02, 0.08, 0.02)] }, toggleOn: { layers: [sweep(900, 880, 0.02, 0.07), sweep(1400, 1300, 0.012, 0.07, 0.02)] }, toggleOff: { layers: [sweep(1400, 1300, 0.012, 0.07), sweep(900, 880, 0.02, 0.07, 0.02)] }, // rise: 330→990 Hz, 120ms (work finished). success: { layers: [sweep(330, 990, 0.12, 0.05)] }, // low double: 196→180 Hz, 50ms, twice, 70ms apart (a run stopped, something failed). halt: { layers: [sweep(196, 180, 0.05, 0.12), sweep(196, 180, 0.05, 0.12, 0.07)] }, error: { layers: [sweep(196, 180, 0.05, 0.12), sweep(196, 180, 0.05, 0.12, 0.07)] }, blocked: { layers: [sweep(260, 240, 0.03, 0.07)] }, // pulse: 523 then 784 Hz, 50ms each (a message arrived). notification: { layers: [sweep(523, 523, 0.05, 0.06), sweep(784, 784, 0.05, 0.06, 0.06)] }, }; /** Minimum gap between two plays of the same cue (ms). Repeats inside it are dropped. */ export const GLASS_SOUND_THROTTLE: Record = { tap: 35, select: 35, destructive: 80, toggleOn: 60, toggleOff: 60, open: 80, close: 80, swoosh: 120, tick: 40, sliderTick: 45, key: 25, success: 150, error: 150, warning: 150, copy: 80, notification: 200, chirp: 60, command: 100, blocked: 90, lock: 40, halt: 150, }; /** Tiny per-play variation so repeats never feel mechanical: [cents, volume]. */ const JITTER: Partial> = { tap: [40, 0.08], select: [8, 0.06], tick: [14, 0.1], sliderTick: [14, 0.1], key: [6, 0.06], chirp: [20, 0.05], }; const PENTATONIC = [0, 2, 4, 7, 9]; // semitones: D E F# A B /** Semitones for the nth step of the pentatonic scale (wraps up an octave every 5, max two octaves). */ export function glassPentatonicStep(index: number): number { const i = Math.max(0, Math.min(10, Math.floor(Number.isFinite(index) ? index : 0))); return PENTATONIC[i % 5] + 12 * Math.floor(i / 5); } /** The engine call a cue resolves to: definition, detune (cents), volume and pan. Pure, for tests. */ export function resolveGlassCue( cue: GlassSoundCue, opts: GlassSoundPlayOptions = {}, { overrides, volume = 0.8 }: { overrides?: GlassSoundOverrides; volume?: number } = {}, ): { definition: GlassSoundDefinition; options: PlayOptions } | null { const override = overrides?.[cue]; if (override === false) return null; const analogue = opts.voice === "analogue"; const definition = override ?? (analogue ? ANALOGUE_SOUND_PATCH[cue] : undefined) ?? GLASS_SOUND_PATCH[cue]; if (!definition) return null; let cents = (opts.pitch ?? 0) * 100; // Analogue is mechanical: no pentatonic steps and no jitter. if (!analogue && opts.index !== undefined && (cue === "select" || cue === "key")) cents += glassPentatonicStep(opts.index) * 100; const v = clamp01(volume) * clamp01(opts.volume ?? 1); const jitter = analogue ? undefined : JITTER[cue]; const options: PlayOptions = { volume: v }; if (cents) options.detune = cents; if (opts.pan) options.pan = Math.max(-1, Math.min(1, opts.pan)); if (jitter) options.jitter = { detune: jitter[0], volume: jitter[1] }; return { definition, options }; } const clamp01 = (n: number) => (Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : 1); // --------------------------------------------------------------------------------------------- // Engine: lazily loaded, swappable // --------------------------------------------------------------------------------------------- /** The audio backend. Swap it (tests, another synth) through the provider's `engine` prop. */ export interface GlassSoundEngine { /** Start loading code (no audio). Called when the page is idle. */ preload?(): void; /** Create or resume the audio context. Only ever called inside a user gesture. */ unlock(): void; /** Play a definition. Must not throw. */ play(definition: GlassSoundDefinition, options: PlayOptions): void; } type WebKits = typeof import("@web-kits/audio"); /** The default engine: @web-kits/audio, imported on demand so pages without sound never load it. */ export function createWebKitsEngine(): GlassSoundEngine { let mod: WebKits | null = null; let loading: Promise | null = null; let unlocked = false; // The first cue can arrive before the engine has loaded: keep the latest one and play it when ready. let pending: [GlassSoundDefinition, PlayOptions] | null = null; const players = new WeakMap unknown>(); const playNow = (m: WebKits, definition: GlassSoundDefinition, options: PlayOptions) => { try { let p = players.get(definition); if (!p) { p = m.defineSound(definition); players.set(definition, p); } p(options); } catch {} }; const flush = (m: WebKits) => { const next = pending; pending = null; if (next) playNow(m, next[0], next[1]); }; const load = () => (loading ??= import("@web-kits/audio") .then((m) => (mod = m)) .catch(() => null)); const ready = (m: WebKits) => { try { m.ensureReady().catch(() => {}); } catch {} }; return { preload() { if (hasWebAudio()) void load(); }, unlock() { if (unlocked || !hasWebAudio()) return; unlocked = true; if (mod) ready(mod); else void load().then((m) => m && ready(m)); }, play(definition, options) { if (!unlocked) return; if (!mod) { pending = [definition, options]; void load().then((m) => { if (!m) return; try { m.ensureReady().then(() => flush(m), () => flush(m)); } catch { flush(m); } }); return; } playNow(mod, definition, options); }, }; } export function hasWebAudio(): boolean { try { return typeof window !== "undefined" && typeof window.AudioContext === "function"; } catch { return false; } } // --------------------------------------------------------------------------------------------- // Controller: gesture gate, throttle, rapid-fire damping. Framework free, for tests. // --------------------------------------------------------------------------------------------- export interface GlassSoundControllerOptions { engine: GlassSoundEngine; now?: () => number; } export interface GlassSoundController { /** Call from a user gesture: unlocks the engine. Plays before it are dropped. */ unlock(): void; readonly unlocked: boolean; play(cue: GlassSoundCue, opts?: GlassSoundPlayOptions, config?: { overrides?: GlassSoundOverrides; volume?: number }): boolean; } export function createGlassSoundController({ engine, now = () => Date.now() }: GlassSoundControllerOptions): GlassSoundController { let unlocked = false; const last = new Map(); const recent: number[] = []; return { get unlocked() { return unlocked; }, unlock() { if (unlocked) return; unlocked = true; try { engine.unlock(); } catch {} }, play(cue, opts = {}, config = {}) { if (!unlocked || !isGlassSoundCue(cue)) return false; const t = now(); const key = opts.index === undefined ? cue : `${cue}:${opts.index}`; if (!opts.force && t - (last.get(key) ?? -Infinity) < GLASS_SOUND_THROTTLE[cue]) return false; last.set(key, t); // Rapid sequences get quieter: every play in the last 600ms takes 12% off, down to 45%. while (recent.length && t - recent[0] > 600) recent.shift(); const damp = Math.max(0.45, 1 - 0.12 * recent.length); recent.push(t); const resolved = resolveGlassCue(cue, { ...opts, volume: (opts.volume ?? 1) * damp }, config); if (!resolved) return false; try { engine.play(resolved.definition, resolved.options); } catch {} return true; }, }; } // --------------------------------------------------------------------------------------------- // Mute persistence // --------------------------------------------------------------------------------------------- export const GLASS_SOUND_STORAGE_KEY = "beautiful-ui-sound"; const muteListeners = new Set<() => void>(); /** The saved choice: true (muted), false (on) or null (never chosen). Never throws. */ export function readGlassSoundMuted(key: string | null = GLASS_SOUND_STORAGE_KEY): boolean | null { if (!key) return null; try { const v = globalThis.localStorage?.getItem(key); return v === "off" ? true : v === "on" ? false : null; } catch { return null; } } /** Saves the choice ("on" / "off") and tells every provider on the page. Never throws. */ export function writeGlassSoundMuted(muted: boolean, key: string | null = GLASS_SOUND_STORAGE_KEY) { if (key) { try { globalThis.localStorage?.setItem(key, muted ? "off" : "on"); } catch {} } for (const l of muteListeners) l(); } function subscribeMuted(listener: () => void, key: string | null = GLASS_SOUND_STORAGE_KEY) { muteListeners.add(listener); // Another tab changed this provider's key (or cleared storage). const onStorage = (e: StorageEvent) => { if (!e.key || e.key === key) listener(); }; try { window.addEventListener("storage", onStorage); } catch {} return () => { muteListeners.delete(listener); try { window.removeEventListener("storage", onStorage); } catch {} }; } // --------------------------------------------------------------------------------------------- // The click layer // --------------------------------------------------------------------------------------------- /** What the click layer treats as pressable. Anything with data-sound counts too. */ export const GLASS_SOUND_INTERACTIVE = 'button,a[href],summary,input[type="checkbox"],input[type="radio"],input[type="button"],input[type="submit"],input[type="reset"],select,[role="button"],[role="tab"],[role="option"],[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"],[role="checkbox"],[role="switch"],[role="radio"],[role="link"],[role="gridcell"][tabindex],[data-sound]'; /** "all": every interactive element; "components": only inside Lumen components; "off": only cues components play. */ export type GlassSoundClicks = "all" | "components" | "off"; /** * The cue a press on `target` should play, or null. Pure DOM reads, for tests and custom layers. * data-sound="off" on an ancestor silences, "none" means the element plays its own cue, * data-sound-index gives select / key their pitch. */ export function glassSoundForElement( target: Element | null, clicks: GlassSoundClicks = "all", ): { cue: GlassSoundCue; index?: number; el: Element; subtle: boolean; voice?: GlassSoundVoice } | null { if (!target || clicks === "off" || typeof target.closest !== "function") return null; if (target.closest('[data-sound="off"]')) return null; const el = target.closest(GLASS_SOUND_INTERACTIVE); if (!el) return null; // Hidden proxy inputs (Base UI and Radix click one for form state after the visible control) never // sound: the control the person pressed already did. if (el.matches('input[aria-hidden="true"]')) return null; if (clicks === "components" && !el.closest("[data-lumen],[data-analogue],[data-sound]")) return null; const subtle = Boolean(el.closest('[data-sound-level="subtle"]')); const voiceAttr = el.closest("[data-sound-voice]")?.getAttribute("data-sound-voice"); const voice = isGlassSoundVoice(voiceAttr) ? voiceAttr : undefined; const marked = el.getAttribute("data-sound"); if (marked === "off") return null; // A disabled control answers "blocked" even when it normally plays its own cue (a radio disabled by its group). const disabled = el.matches(":disabled") || el.getAttribute("aria-disabled") === "true" || el.hasAttribute("data-disabled"); if (disabled) return { cue: "blocked", el, subtle, voice }; if (marked === "none") return null; // A busy button ignores the press, so it stays silent too. if (el.getAttribute("aria-busy") === "true" || el.hasAttribute("data-inert")) return null; if (marked && isGlassSoundCue(marked)) { const idx = Number(el.getAttribute("data-sound-index")); return { cue: marked, index: el.hasAttribute("data-sound-index") && Number.isFinite(idx) ? idx : undefined, el, subtle, voice }; } // Text fields and selects answer to typing, not to being clicked into. if (el.matches("select")) return null; return { cue: "tap", el, subtle, voice }; } /** Attributes for a component root: data-sound="off" when sound={false}, the subtle level when "subtle". */ export function glassSoundRootAttrs(sound: GlassSoundProp | undefined): Record { if (sound === false) return { "data-sound": "off" }; if (sound === "subtle") return { "data-sound-level": "subtle" }; return {}; } // --------------------------------------------------------------------------------------------- // React // --------------------------------------------------------------------------------------------- /** Replace any cue with your own definition, or silence it with false. */ export type GlassSoundOverrides = Partial>; interface GlassSoundContextValue { play: (cue: GlassSoundCue, opts?: GlassSoundPlayOptions) => boolean; /** Unlock inside a gesture and play even while muted (the toggle's own answer). */ confirm: (cue: GlassSoundCue) => void; muted: boolean; enabled: boolean; setMuted: (muted: boolean) => void; } const GlassSoundContext = React.createContext(null); export interface GlassSoundProviderProps { children?: React.ReactNode; /** Master switch. false: nothing plays and the engine never loads. Default true. */ enabled?: boolean; /** 0–1. Default 0.8. */ volume?: number; /** Controlled mute (with onMutedChange). Uncontrolled, the saved choice or defaultMuted is used. */ muted?: boolean; /** Muted until the visitor turns sound on. Default false. */ defaultMuted?: boolean; onMutedChange?: (muted: boolean) => void; /** localStorage key for the mute choice. null: don't persist. Default "beautiful-ui-sound". */ storageKey?: string | null; /** Replace or silence cues: { tap: myDefinition, tick: false }. */ cues?: GlassSoundOverrides; /** The click layer: "all" (every button, link, tab… inside), "components" (only inside Lumen components) or "off". Default "all". */ clicks?: GlassSoundClicks; /** Pan clicks slightly toward where they happened on screen (±0.25). Default true. */ spatial?: boolean; /** Swap the audio backend. Default: @web-kits/audio, loaded on idle. */ engine?: GlassSoundEngine; } /** * Turns sound on for everything inside. Renders one `display: contents` element to scope the * click layer, so layout is untouched. */ export function GlassSoundProvider({ children, enabled = true, volume = 0.8, muted: mutedProp, defaultMuted = false, onMutedChange, storageKey = GLASS_SOUND_STORAGE_KEY, cues, clicks = "all", spatial = true, engine: engineProp, }: GlassSoundProviderProps) { const [controller] = React.useState(() => { const engine = engineProp ?? createWebKitsEngine(); return { engine, ctl: createGlassSoundController({ engine }) }; }); const subscribe = React.useCallback((l: () => void) => subscribeMuted(l, storageKey), [storageKey]); const stored = React.useSyncExternalStore( subscribe, () => readGlassSoundMuted(storageKey), () => null, ); // Without a storage key the choice lives here (uncontrolled), so the toggle still works. const [own, setOwn] = React.useState(null); const muted = mutedProp ?? (storageKey ? stored : own) ?? defaultMuted; const active = enabled && !muted; const config = React.useRef({ cues, volume, active, clicks, spatial }); React.useEffect(() => { config.current = { cues, volume, active, clicks, spatial }; }); // Unlock on the first gesture anywhere on the page; preload the engine when idle. React.useEffect(() => { if (!active || typeof window === "undefined") return; const { ctl, engine } = controller; let idle: number | undefined; try { const ric = (window as Window & { requestIdleCallback?: (cb: () => void, o?: { timeout: number }) => number }).requestIdleCallback; idle = ric ? ric(() => engine.preload?.(), { timeout: 3000 }) : window.setTimeout(() => engine.preload?.(), 1200); } catch {} if (ctl.unlocked) return; const events = ["pointerdown", "keydown", "touchend"] as const; const onGesture = (e: Event) => { if (!e.isTrusted) return; ctl.unlock(); for (const ev of events) window.removeEventListener(ev, onGesture, true); }; for (const ev of events) window.addEventListener(ev, onGesture, true); return () => { for (const ev of events) window.removeEventListener(ev, onGesture, true); try { const cic = (window as Window & { cancelIdleCallback?: (id: number) => void }).cancelIdleCallback; if (idle !== undefined) (cic ?? window.clearTimeout)(idle); } catch {} }; }, [active, controller]); const play = React.useCallback( (cue: GlassSoundCue, opts?: GlassSoundPlayOptions) => { const c = config.current; if (!c.active) return false; try { if (typeof document !== "undefined" && document.visibilityState === "hidden") return false; return controller.ctl.play(cue, opts, { overrides: c.cues, volume: c.volume }); } catch { return false; } }, [controller], ); const setMuted = React.useCallback( (next: boolean) => { // Controlled: the parent owns it. Uncontrolled: persist it, or keep it here without a key. if (mutedProp === undefined) { if (storageKey) writeGlassSoundMuted(next, storageKey); else setOwn(next); } onMutedChange?.(next); }, [mutedProp, storageKey, onMutedChange], ); const confirm = React.useCallback( (cue: GlassSoundCue) => { const c = config.current; if (!enabled) return; try { controller.ctl.unlock(); controller.ctl.play(cue, { force: true }, { overrides: c.cues, volume: c.volume }); } catch {} }, [controller, enabled], ); const value = React.useMemo(() => ({ play, confirm, muted, enabled, setMuted }), [play, confirm, muted, enabled, setMuted]); // The click layer. Mouse and pen answer on press (tactile, no latency); touch waits for the // click so scrolling stays silent; keyboard activation (click with detail 0) answers too. const pressed = React.useRef(null); const wrap = React.useRef(null); // Nested providers: the innermost one around the target answers (a portal outside every // provider's DOM goes to the first that sees it). The event is marked so nothing plays twice. const owns = (e: React.SyntheticEvent) => { const ne = e.nativeEvent as Event & { __glassSound?: boolean }; const t = e.target as Element | null; const nearest = t && typeof t.closest === "function" ? t.closest("[data-glass-sound]") : null; if ((nearest && nearest !== wrap.current) || ne.__glassSound) return false; ne.__glassSound = true; return true; }; const fire = (target: EventTarget | null, x?: number) => { const c = config.current; if (!c.active || c.clicks === "off") return; const hit = glassSoundForElement(target as Element | null, c.clicks); if (!hit) return; let pan: number | undefined; if (c.spatial && typeof window !== "undefined") { try { const cx = x ?? (() => { const r = hit.el.getBoundingClientRect(); return r.left + r.width / 2; })(); pan = ((cx / Math.max(1, window.innerWidth)) * 2 - 1) * 0.25; } catch {} } play(hit.cue, { index: hit.index, pan, volume: hit.subtle ? 0.55 : 1, voice: hit.voice }); }; // Outcome cues from components without audio code: they dispatch a bubbling `beautiful-ui:sound` // event ({ cue }) and the provider around them plays it, in the voice their root declares. React.useEffect(() => { const el = wrap.current; if (!el) return; const onCue = (e: Event) => { const ev = e as CustomEvent<{ cue?: unknown; index?: unknown }> & { __glassSound?: boolean }; const target = e.target as Element | null; const nearest = target && typeof target.closest === "function" ? target.closest("[data-glass-sound]") : null; if ((nearest && nearest !== el) || ev.__glassSound) return; ev.__glassSound = true; const cue = ev.detail?.cue; if (!isGlassSoundCue(cue) || !target || target.closest('[data-sound="off"]')) return; const voiceAttr = target.closest("[data-sound-voice]")?.getAttribute("data-sound-voice"); const subtle = Boolean(target.closest('[data-sound-level="subtle"]')); // index pitches "select" and "key" by position (a radio's option, a list's row). const index = typeof ev.detail?.index === "number" && Number.isFinite(ev.detail.index) ? ev.detail.index : undefined; play(cue, { voice: isGlassSoundVoice(voiceAttr) ? voiceAttr : undefined, volume: subtle ? 0.55 : 1, index }); }; el.addEventListener("beautiful-ui:sound", onCue); // A component portalled outside every provider (a dialog, a popover) still sounds: the first // mounted provider answers events whose target has no provider around it. ORPHAN_OWNERS.push(el); const onOrphan = (e: Event) => { const target = e.target as Element | null; if (ORPHAN_OWNERS[0] !== el || !target || typeof target.closest !== "function" || target.closest("[data-glass-sound]")) return; onCue(e); }; document.addEventListener("beautiful-ui:sound", onOrphan); return () => { el.removeEventListener("beautiful-ui:sound", onCue); document.removeEventListener("beautiful-ui:sound", onOrphan); const i = ORPHAN_OWNERS.indexOf(el); if (i >= 0) ORPHAN_OWNERS.splice(i, 1); }; }, [play]); return (
{ pressed.current = null; if (e.pointerType === "touch" || e.button !== 0 || !config.current.active || !owns(e)) return; controller.ctl.unlock(); pressed.current = e.target as Element; fire(e.target, e.clientX); }} onClickCapture={(e) => { const wasPressed = pressed.current !== null; pressed.current = null; // Mouse clicks already sounded on press. Touch taps (detail 1, no press) and keyboard (detail 0) sound here. if ((wasPressed && e.detail > 0) || !owns(e)) return; fire(e.target, e.detail > 0 ? e.clientX : undefined); }} > {children}
); } const NOOP = () => false; /** Mounted providers in mount order: the first answers cues from portalled components. */ const ORPHAN_OWNERS: HTMLElement[] = []; /** * Play Lumen cues from a component. Without a provider (or with sound off, muted, or * `sound={false}`) play() is a silent no-op. * * @example * const sfx = useGlassSound(sound); * sfx.play("success"); * sfx.play("select", { index: 2 }); */ export function useGlassSound(sound: GlassSoundProp = true, voice?: GlassSoundVoice) { const ctx = React.useContext(GlassSoundContext); const playCtx = ctx?.play; const play = React.useMemo(() => { if (!playCtx || sound === false) return NOOP as (cue: GlassSoundCue, opts?: GlassSoundPlayOptions) => boolean; const k = sound === "subtle" ? 0.55 : 1; return (cue: GlassSoundCue, opts?: GlassSoundPlayOptions) => playCtx(cue, { voice, ...opts, ...(k === 1 ? null : { volume: (opts?.volume ?? 1) * k }) }); }, [playCtx, sound, voice]); return { play, /** A provider is present. */ available: ctx !== null, /** Sound would play right now (provider enabled, not muted, this instance not silenced). */ enabled: Boolean(ctx?.enabled && !ctx.muted && sound !== false), muted: ctx?.muted ?? true, setMuted: ctx?.setMuted ?? (() => {}), }; } /** * Plays `cue` when `value` changes to something that matches (not on mount). For outcomes that * arrive from props: an error message, a success status. */ export function useGlassSoundOnChange( value: T, cue: GlassSoundCue | ((next: T, prev: T) => GlassSoundCue | null), sound: GlassSoundProp = true, voice?: GlassSoundVoice, ) { const { play } = useGlassSound(sound, voice); const prev = React.useRef(value); React.useEffect(() => { if (Object.is(prev.current, value)) return; const before = prev.current; prev.current = value; const c = typeof cue === "function" ? cue(value, before) : cue; if (c) play(c); }, [value, cue, play]); } // --------------------------------------------------------------------------------------------- // The toggle // --------------------------------------------------------------------------------------------- export interface GlassSoundToggleLabels { /** The button's accessible name (it is a toggle: aria-pressed says whether sound is on). */ sound: string; on: string; off: string; } export const defaultGlassSoundToggleLabels: GlassSoundToggleLabels = { sound: "Sound effects", on: "Sound on", off: "Sound off" }; export interface GlassSoundToggleState { muted: boolean; toggle: () => void; /** A provider is present and enabled. */ available: boolean; } export interface GlassSoundToggleProps extends Omit, "children"> { /** Render your own control. Gets { muted, toggle, available }. */ render?: (state: GlassSoundToggleState) => React.ReactNode; /** Diameter in px. Default 32. */ size?: number; theme?: GlassTheme; labels?: GlassLabels; ref?: React.Ref; } const TOGGLE_CSS = ".gsnd{position:relative;display:inline-grid;place-items:center;flex:none;border:0;padding:0;margin:0;border-radius:999px;cursor:pointer;color:var(--lg-strong);background:var(--lg-cardBg);box-shadow:var(--lg-cardShadow);transition:color .2s,background .2s,transform .35s cubic-bezier(.34,1.5,.64,1);-webkit-tap-highlight-color:transparent}" + ".gsnd:hover{color:var(--lg-active)}.gsnd:active{transform:scale(.94)}" + ".gsnd .gsnd-w{transition:opacity .3s cubic-bezier(.22,1,.36,1),transform .3s cubic-bezier(.22,1,.36,1);transform-origin:6px 8px}" + ".gsnd[aria-pressed=false] .gsnd-w{opacity:0;transform:scale(.6)}.gsnd .gsnd-x{transition:opacity .25s;opacity:0}.gsnd[aria-pressed=false] .gsnd-x{opacity:1}" + "@media (prefers-reduced-motion:reduce){.gsnd,.gsnd .gsnd-w,.gsnd .gsnd-x{transition:none}}"; /** The speaker: cell body, two waves when on, a small cross when off. 16px grid, currentColor. */ export function GlassSoundIcon({ muted, size = 16 }: { muted: boolean; size?: number }) { const st = { stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round", fill: "none" } as const; return ( ); } /** * The mute button, in glass. Renders nothing without a provider (there is nothing to toggle). * Turning sound on answers with a swoosh; turning it off is silent. */ export function GlassSoundToggle({ render, size = 32, theme = "system", labels, className, style, onClick, ref, ...rest }: GlassSoundToggleProps) { const ctx = React.useContext(GlassSoundContext); const L = React.useMemo(() => mergeLabels(defaultGlassSoundToggleLabels, labels), [labels]); const muted = ctx?.muted ?? true; const available = Boolean(ctx?.enabled); const setMuted = ctx?.setMuted; const confirm = ctx?.confirm; const toggle = React.useCallback(() => { if (!setMuted) return; const next = !muted; setMuted(next); if (!next) confirm?.("swoosh"); }, [muted, setMuted, confirm]); if (!ctx) return null; if (render) return <>{render({ muted, toggle, available })}; return ( ); } ```