{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "citation-chips", "title": "Citation chips", "description": "Citation chips is a production-ready ai component from BJORK UI, packaged for shadcn registries.", "dependencies": [ "clsx", "framer-motion", "lucide-react", "next-themes", "tailwind-merge" ], "files": [ { "path": "components/bjork-ui/ai/citation-chips.tsx", "content": "\"use client\";\n\nimport {\n createContext,\n useContext,\n useEffect,\n useId,\n useLayoutEffect,\n useMemo,\n useRef,\n useState,\n type PointerEvent as ReactPointerEvent,\n type ReactNode,\n type Ref,\n} from \"react\";\nimport { motion } from \"framer-motion\";\nimport { ArrowUpRight } from \"lucide-react\";\nimport { springs } from \"@/components/bjork-ui/_core/motion\";\nimport { FOCUS_RING, PRESS, useAiTone, useReduceMotion, type BjorkTone } from \"@/components/bjork-ui/ai/_shared\";\nimport { cn } from \"@/lib/utils\";\n\nexport interface CitationSource {\n id: string;\n title: string;\n url: string;\n /** Shown in mono, such as \"fieldnotes.dev\". */\n domain: string;\n snippet: string;\n /** A passage inside `snippet` that the answer relies on. Highlighted in the preview. */\n quote?: string;\n /** ISO date, such as \"2026-03-14\". */\n publishedAt?: string;\n}\n\n/** Plain text, or a citation of one or more sources by id. */\nexport type CitationSegment = string | { cite: string | string[] };\n\nexport interface CitedTextProps {\n sources: CitationSource[];\n /** Text with numbered markers such as \"[1]\" or \"[2][3]\", numbered from 1 in `sources` order. */\n text?: string;\n /** Pre-split content. Used instead of `text` when given. */\n segments?: CitationSegment[];\n onOpenSource?: (source: CitationSource) => void;\n /** Demo/preview only: opens the card of this marker (0-based, in reading order) on mount. */\n defaultOpenIndex?: number;\n tone?: BjorkTone;\n className?: string;\n}\n\nexport interface SourceListProps {\n sources: CitationSource[];\n /** Chips shown before \"+N more\". Default 4. */\n visibleCount?: number;\n onOpenSource?: (source: CitationSource) => void;\n /** Heading above the chips. Default \"Sources\". Pass null to hide it. */\n label?: string | null;\n tone?: BjorkTone;\n className?: string;\n}\n\nexport const SAMPLE_SOURCES: CitationSource[] = [\n {\n id: \"s1\",\n title: \"Why cities stay hot after dark\",\n url: \"https://fieldnotes.dev/notes/urban-heat-at-night\",\n domain: \"fieldnotes.dev\",\n snippet:\n \"Most people picture the heat island at noon. The measurements say otherwise: asphalt, brick and concrete bank heat all day and give it back slowly overnight, so the gap with the countryside peaks a few hours after sunset.\",\n quote: \"the gap with the countryside peaks a few hours after sunset\",\n publishedAt: \"2026-06-02\",\n },\n {\n id: \"s2\",\n title: \"Street canyons and the sky view factor\",\n url: \"https://quarrylab.org/papers/sky-view-factor\",\n domain: \"quarrylab.org\",\n snippet:\n \"In narrow streets lined with tall buildings, surfaces see less open sky. Less of their stored heat radiates upward, and more is exchanged between facing walls, which keeps the canyon warm long into the night.\",\n quote: \"Less of their stored heat radiates upward\",\n publishedAt: \"2025-11-19\",\n },\n {\n id: \"s3\",\n title: \"Canopy versus cool roofs: a street-level comparison\",\n url: \"https://civic-ledger.net/reports/canopy-cool-roofs\",\n domain: \"civic-ledger.net\",\n snippet:\n \"Reflective roofs lower rooftop temperatures sharply, but pedestrians feel the canopy more. Blocks with mature street trees ran up to 2 °C cooler at night than matched blocks without them.\",\n quote: \"up to 2 °C cooler at night\",\n publishedAt: \"2026-04-27\",\n },\n {\n id: \"s4\",\n title: \"Warm nights and heat-wave health risk\",\n url: \"https://tidewaterpost.com/health/warm-nights\",\n domain: \"tidewaterpost.com\",\n snippet:\n \"Hospital admissions track night-time lows more closely than daytime highs. When nights stay warm, the body never gets the recovery window it needs between hot days.\",\n quote: \"the body never gets the recovery window it needs\",\n publishedAt: \"2026-07-30\",\n },\n {\n id: \"s5\",\n title: \"Mapping a city's thermal footprint by bicycle\",\n url: \"https://openharbor.io/blog/thermal-bike-map\",\n domain: \"openharbor.io\",\n snippet: \"Volunteers rode fixed routes at 9pm with clip-on sensors, producing a block-by-block night temperature map.\",\n publishedAt: \"2025-08-12\",\n },\n {\n id: \"s6\",\n title: \"Materials that release heat faster\",\n url: \"https://lowtide.science/articles/emissive-pavements\",\n domain: \"lowtide.science\",\n snippet: \"High-emissivity coatings let pavements shed stored heat earlier in the evening.\",\n publishedAt: \"2026-01-08\",\n },\n {\n id: \"s7\",\n title: \"A short history of the urban heat island\",\n url: \"https://marginalia.press/essays/heat-island-history\",\n domain: \"marginalia.press\",\n snippet: \"The effect was first described in 1818, from thermometer readings taken inside and outside London.\",\n publishedAt: \"2024-12-03\",\n },\n];\n\nexport const SAMPLE_CITED_ANSWER =\n \"Urban heat islands are strongest after sunset, not at noon: asphalt and brick store heat all day and release it slowly overnight [1]. Dense blocks trap that warmth too, because narrow streets limit how much heat can radiate back to the sky [2]. At street level, trees do more than reflective roofs, cutting night-time temperatures by up to 2 °C [3]. The effect compounds in heat waves, when warm nights leave no time to recover [4].\";\n\nconst OPEN_DELAY = 150;\nconst EDGE = 12;\nconst MONTHS = [\"Jan\", \"Feb\", \"Mar\", \"Apr\", \"May\", \"Jun\", \"Jul\", \"Aug\", \"Sep\", \"Oct\", \"Nov\", \"Dec\"];\n\nfunction formatDate(iso?: string): string {\n if (!iso) return \"\";\n const m = /^(\\d{4})-(\\d{2})-(\\d{2})/.exec(iso);\n if (!m) return iso;\n return `${MONTHS[Number(m[2]) - 1]} ${Number(m[3])}, ${m[1]}`;\n}\n\n// Deterministic favicon tile: the same domain always gets the same tone.\nconst TILE_TONES = [\n \"bg-[color:var(--bjork-accent-soft)] text-[color:var(--bjork-accent-ink)]\",\n \"bg-[color:var(--bjork-surface-active)] text-[color:var(--bjork-text-medium)]\",\n \"bg-[color:var(--bjork-text)] text-[color:var(--bjork-ring-offset)]\",\n \"bg-[color:var(--bjork-hair)] text-[color:var(--bjork-text)]\",\n];\n\nfunction hash(s: string): number {\n return s.split(\"\").reduce((h, c) => (h * 31 + c.charCodeAt(0)) >>> 0, 7);\n}\n\nfunction FaviconTile({ domain, size = 16 }: { domain: string; size?: number }) {\n return (\n \n {domain.replace(/^www\\./, \"\")[0]}\n \n );\n}\n\n/* Shared highlight between inline markers and source chips. */\n\ninterface CitationCtx {\n hot: string | null;\n setHot: (id: string | null) => void;\n}\nconst Ctx = createContext(null);\n\n/** Wrap a CitedText and SourceList so hovering either highlights the matching chips in the other. */\nexport function CitationGroup({ children, defaultHighlighted = null }: { children: ReactNode; defaultHighlighted?: string | null }) {\n const [hot, setHot] = useState(defaultHighlighted);\n const value = useMemo(() => ({ hot, setHot }), [hot]);\n return {children};\n}\n\nfunction useHot(): CitationCtx {\n const shared = useContext(Ctx);\n const [hot, setHot] = useState(null);\n return shared ?? { hot, setHot };\n}\n\n/* Inline text with markers. */\n\nfunction parse(text: string, sources: CitationSource[]): CitationSegment[] {\n const parts = text.split(/((?:\\s*\\[\\d+\\])+)/g).filter((p) => p !== \"\");\n return parts.map((p) => {\n const nums = [...p.matchAll(/\\[(\\d+)\\]/g)].map((m) => Number(m[1]));\n if (nums.length === 0) return p;\n const ids = nums.map((n) => sources[n - 1]?.id).filter((id): id is string => Boolean(id));\n return { cite: ids };\n });\n}\n\n/**\n * Answer text with numbered citation chips. Each chip previews its source on hover or focus, and highlights the\n * matching chip in a SourceList inside the same CitationGroup.\n */\nexport function CitedText({\n sources,\n text = \"\",\n segments,\n onOpenSource,\n defaultOpenIndex,\n tone: toneProp,\n className,\n}: CitedTextProps) {\n const { style } = useAiTone(toneProp);\n const { hot, setHot } = useHot();\n const content = useMemo(() => segments ?? parse(text, sources), [segments, text, sources]);\n const indexOf = (id: string) => sources.findIndex((s) => s.id === id);\n\n // Marker order in reading order, so `defaultOpenIndex` can address one.\n const markers = content.flatMap((seg, si) =>\n typeof seg === \"string\" ? [] : [seg.cite].flat().map((id, ci) => ({ key: `${si}-${ci}`, id })),\n );\n\n return (\n

\n {content.map((seg, si) => {\n if (typeof seg === \"string\") return {seg};\n const ids = [seg.cite].flat();\n return (\n \n {ids.map((id, ci) => {\n const source = sources.find((s) => s.id === id);\n if (!source) return null;\n const key = `${si}-${ci}`;\n const order = markers.findIndex((m) => m.key === key);\n return (\n \n );\n })}\n \n );\n })}\n

\n );\n}\n\n/** Source chips under an answer, with \"+N more\" for the rest. */\nexport function SourceList({\n sources,\n visibleCount = 4,\n onOpenSource,\n label = \"Sources\",\n tone: toneProp,\n className,\n}: SourceListProps) {\n const { style } = useAiTone(toneProp);\n const reduce = useReduceMotion();\n const { hot, setHot } = useHot();\n const [expanded, setExpanded] = useState(false);\n const headingId = useId();\n const shown = expanded ? sources : sources.slice(0, visibleCount);\n const hidden = sources.length - shown.length;\n\n return (\n \n {label && (\n

\n {label} · {sources.length}\n

\n )}\n
    \n {shown.map((source, i) => (\n = visibleCount && !reduce ? { opacity: 0, y: 4, filter: \"blur(4px)\" } : false}\n animate={{ opacity: 1, y: 0, filter: \"blur(0px)\" }}\n transition={reduce ? { duration: 0 } : { ...springs.blurIn, delay: Math.max(0, i - visibleCount) * 0.03 }}\n >\n \n \n ))}\n {sources.length > visibleCount && (\n
  • \n setExpanded((v) => !v)}\n className={cn(\n \"h-8 cursor-pointer rounded-full px-3 font-mono text-[11px] tabular-nums text-[color:var(--bjork-text-muted)] transition-colors duration-150 hover:bg-[color:var(--bjork-surface-active)] hover:text-[color:var(--bjork-text)]\",\n FOCUS_RING,\n PRESS,\n )}\n >\n {expanded ? \"Show less\" : `+${hidden} more`}\n \n
    • \n )}\n
\n \n );\n}\n\n/* One chip and its preview card. */\n\ninterface ChipProps {\n source: CitationSource;\n number: number;\n inline?: boolean;\n hot: boolean;\n setHot: (id: string | null) => void;\n onOpenSource?: (source: CitationSource) => void;\n defaultOpen?: boolean;\n}\n\ntype OpenReason = \"hover\" | \"focus\" | \"press\";\n\nfunction CitationChip({ source, number, inline = false, hot, setHot, onOpenSource, defaultOpen = false }: ChipProps) {\n const [openBy, setOpenBy] = useState(defaultOpen ? \"press\" : null);\n const open = openBy !== null;\n const wrapRef = useRef(null);\n const cardRef = useRef(null);\n const timer = useRef(undefined);\n const cardId = useId();\n\n const cancel = () => window.clearTimeout(timer.current);\n const openLater = (reason: OpenReason) => {\n cancel();\n timer.current = window.setTimeout(() => setOpenBy((cur) => cur ?? reason), OPEN_DELAY);\n };\n useEffect(() => () => window.clearTimeout(timer.current), []);\n\n // Escape closes; a press outside closes a pressed card (touch).\n useEffect(() => {\n if (!open) return;\n const shut = () => {\n window.clearTimeout(timer.current);\n setOpenBy(null);\n };\n const onKey = (e: KeyboardEvent) => {\n if (e.key === \"Escape\") shut();\n };\n const onDown = (e: PointerEvent) => {\n if (wrapRef.current && !wrapRef.current.contains(e.target as Node)) shut();\n };\n document.addEventListener(\"keydown\", onKey);\n document.addEventListener(\"pointerdown\", onDown);\n return () => {\n document.removeEventListener(\"keydown\", onKey);\n document.removeEventListener(\"pointerdown\", onDown);\n };\n }, [open]);\n\n // Flip above or below by available room, then keep the card inside the viewport horizontally.\n useLayoutEffect(() => {\n const wrap = wrapRef.current;\n const card = cardRef.current;\n if (!open || !wrap || !card) return;\n const place = () => {\n const r = wrap.getBoundingClientRect();\n const h = card.offsetHeight;\n const w = card.offsetWidth;\n const below = window.innerHeight - r.bottom;\n const placeBelow = below >= h || below >= r.top;\n card.style.top = placeBelow ? \"100%\" : \"auto\";\n card.style.bottom = placeBelow ? \"auto\" : \"100%\";\n card.dataset.side = placeBelow ? \"bottom\" : \"top\";\n const want = r.left + r.width / 2 - w / 2;\n const left = Math.min(Math.max(EDGE, want), Math.max(EDGE, window.innerWidth - EDGE - w));\n card.style.left = `${left - r.left}px`;\n };\n place();\n window.addEventListener(\"resize\", place);\n window.addEventListener(\"scroll\", place, true);\n return () => {\n window.removeEventListener(\"resize\", place);\n window.removeEventListener(\"scroll\", place, true);\n };\n }, [open]);\n\n const isMouse = (e: ReactPointerEvent) => e.pointerType === \"mouse\" || e.pointerType === \"pen\";\n\n return (\n {\n if (!isMouse(e)) return;\n setHot(source.id);\n openLater(\"hover\");\n }}\n onPointerLeave={(e) => {\n if (!isMouse(e)) return;\n setHot(null);\n cancel();\n // Instant out, unless keyboard or a press opened it.\n setOpenBy((cur) => (cur === \"hover\" ? null : cur));\n }}\n onBlur={(e) => {\n if (wrapRef.current?.contains(e.relatedTarget as Node)) return;\n setHot(null);\n cancel();\n setOpenBy((cur) => (cur === \"hover\" ? cur : null));\n }}\n >\n {\n setHot(source.id);\n if (e.currentTarget.matches(\":focus-visible\")) openLater(\"focus\");\n }}\n onClick={() => {\n cancel();\n setOpenBy((cur) => (cur === null || cur === \"hover\" ? \"press\" : null));\n }}\n className={cn(\n \"cursor-pointer transition-[background-color,color,border-color] duration-150\",\n FOCUS_RING,\n inline\n ? cn(\n // 16px chip with a 28px hit area from the pseudo-element. ml nudges it off the preceding word.\n \"relative ml-[3px] inline-flex h-4 min-w-4 -translate-y-[1px] items-center justify-center rounded-[5px] px-[3px] align-baseline font-mono text-[11px] font-medium leading-none tabular-nums before:absolute before:-inset-x-1.5 before:-inset-y-1.5 before:content-['']\",\n hot || open\n ? \"bg-[color:var(--bjork-accent)] text-[color:var(--bjork-accent-foreground)]\"\n : \"bg-[color:var(--bjork-surface-active)] text-[color:var(--bjork-text-muted)] hover:text-[color:var(--bjork-text)]\",\n )\n : cn(\n \"flex h-8 min-w-0 max-w-full items-center gap-2 rounded-full border pl-1.5 pr-3 text-left\",\n PRESS,\n hot || open\n ? \"border-[color:var(--bjork-accent-muted)] bg-[color:var(--bjork-accent-soft)]\"\n : \"border-[color:var(--bjork-border)] hover:bg-[color:var(--bjork-surface-active)]\",\n ),\n )}\n >\n {inline ? (\n number\n ) : (\n <>\n {number}\n \n {source.title}\n \n {source.domain}\n \n \n )}\n \n\n \n \n );\n}\n\nfunction highlight(snippet: string, quote?: string): ReactNode {\n const at = quote ? snippet.indexOf(quote) : -1;\n if (!quote || at < 0) return snippet;\n return (\n <>\n {snippet.slice(0, at)}\n \n {quote}\n \n {snippet.slice(at + quote.length)}\n \n );\n}\n\nfunction PreviewCard({\n ref,\n id,\n source,\n open,\n onOpenSource,\n}: {\n ref: Ref;\n id: string;\n source: CitationSource;\n open: boolean;\n onOpenSource?: (source: CitationSource) => void;\n}) {\n const reduce = useReduceMotion();\n return (\n \n \n \n \n \n \n {source.domain}\n \n {source.publishedAt && (\n \n {formatDate(source.publishedAt)}\n \n )}\n \n \n {source.title}\n \n \n {highlight(source.snippet, source.quote)}\n \n \n {\n if (!onOpenSource) return;\n e.preventDefault();\n onOpenSource(source);\n }}\n className={cn(\n \"-ml-1 inline-flex h-7 items-center gap-1 rounded-[6px] px-1 text-[12.5px] font-medium text-[color:var(--bjork-accent-ink)] hover:underline hover:underline-offset-2\",\n FOCUS_RING,\n )}\n >\n Open source\n \n \n \n \n \n );\n}\n", "type": "registry:component", "target": "@components/bjork-ui/ai/citation-chips.tsx" }, { "path": "components/bjork-ui/_core/motion.ts", "content": "// Shared springs, easings and durations. Components import these instead of inventing values.\n\nexport const springs = {\n press: { type: \"spring\", stiffness: 500, damping: 30, mass: 0.6 },\n snappy: { type: \"spring\", stiffness: 400, damping: 25, mass: 1 },\n standard: { type: \"spring\", stiffness: 300, damping: 30, mass: 0.8 },\n soft: { type: \"spring\", stiffness: 200, damping: 25, mass: 1.2 },\n settle: { type: \"spring\", stiffness: 380, damping: 30, mass: 0.8 },\n blurIn: { type: \"spring\", stiffness: 400, damping: 28, mass: 0.6 },\n} as const;\n\nexport const ease = {\n out: [0.23, 1, 0.32, 1],\n inOut: [0.77, 0, 0.175, 1],\n drawer: [0.32, 0.72, 0, 1],\n} as const;\n\nexport const easeCss = {\n out: \"cubic-bezier(0.23,1,0.32,1)\",\n inOut: \"cubic-bezier(0.77,0,0.175,1)\",\n drawer: \"cubic-bezier(0.32,0.72,0,1)\",\n} as const;\n\nexport const durations = { press: 140, tooltip: 160, menu: 200, panel: 280 } as const; // ms\n\n// Cubic bezier easing for canvas and rAF code. Returns progress y for input x in [0, 1].\nexport function cubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {\n const cx = 3 * x1;\n const bx = 3 * (x2 - x1) - cx;\n const ax = 1 - cx - bx;\n const cy = 3 * y1;\n const by = 3 * (y2 - y1) - cy;\n const ay = 1 - cy - by;\n const sampleX = (s: number) => ((ax * s + bx) * s + cx) * s;\n const sampleY = (s: number) => ((ay * s + by) * s + cy) * s;\n const sampleDX = (s: number) => (3 * ax * s + 2 * bx) * s + cx;\n\n const solveX = (x: number) => {\n let s = x;\n for (let i = 0; i < 8; i++) {\n const err = sampleX(s) - x;\n if (Math.abs(err) < 1e-6) return s;\n const d = sampleDX(s);\n if (Math.abs(d) < 1e-6) break;\n s -= err / d;\n }\n let lo = 0;\n let hi = 1;\n s = x;\n while (lo < hi) {\n const v = sampleX(s);\n if (Math.abs(v - x) < 1e-6) return s;\n if (x > v) lo = s;\n else hi = s;\n s = (lo + hi) / 2;\n if (hi - lo < 1e-7) break;\n }\n return s;\n };\n\n return (t: number) => {\n if (t <= 0) return 0;\n if (t >= 1) return 1;\n return sampleY(solveX(t));\n };\n}\n", "type": "registry:component", "target": "@components/bjork-ui/_core/motion.ts" }, { "path": "components/bjork-ui/ai/_shared.ts", "content": "\"use client\";\n\n// Shared plumbing for the bjork-ui AI components: tone tokens, reduced motion, controllable state and\n// number formatting. Every AI component imports from here so they read as one family.\n\nimport {\n useCallback,\n useLayoutEffect,\n useRef,\n useState,\n useSyncExternalStore,\n type CSSProperties,\n} from \"react\";\nimport { useReducedMotion } from \"framer-motion\";\nimport { BJORK_PALETTE, type BjorkTone } from \"@/components/bjork-ui/_core/palette\";\nimport { useBjorkTone } from \"@/components/bjork-ui/_core/tone\";\nimport { surfaceVars } from \"@/components/bjork-ui/_core/surface\";\n\nexport type { BjorkTone };\nexport type BjorkPalette = (typeof BJORK_PALETTE)[BjorkTone];\n\nconst noopSubscribe = () => () => {};\n\n/** False on the server and the first client render, true after hydration. */\nexport function useHydrated(): boolean {\n return useSyncExternalStore(\n noopSubscribe,\n () => true,\n () => false,\n );\n}\n\n/** Hydration-safe reduced motion: both sides report \"not reduced\" until mount, then the real value applies. */\nexport function useReduceMotion(): boolean {\n const hydrated = useHydrated();\n const reduced = useReducedMotion();\n return hydrated && reduced === true;\n}\n\n/**\n * Resolves the tone and returns the CSS custom properties for it. Spread `style` on the component root so an\n * explicit `tone` prop wins over the page theme, and status colours (success, warning, error) are always defined.\n */\nexport function useAiTone(toneProp?: BjorkTone) {\n const tone = useBjorkTone(toneProp);\n const pal = BJORK_PALETTE[tone];\n const style = {\n ...surfaceVars(tone),\n \"--bjork-text\": pal.text,\n \"--bjork-text-medium\": pal.textMedium,\n \"--bjork-text-muted\": pal.textMuted,\n \"--bjork-text-soft\": pal.textSoft,\n \"--bjork-text-faint\": pal.textFaint,\n \"--bjork-hair\": pal.hair,\n \"--bjork-border\": pal.border,\n \"--bjork-border-strong\": pal.borderStrong,\n \"--bjork-surface\": pal.surface,\n \"--bjork-raised\": pal.raised,\n \"--bjork-surface-active\": pal.active,\n \"--bjork-accent\": pal.accent,\n \"--bjork-accent-ink\": pal.accentInk,\n \"--bjork-accent-fill\": pal.accentFill,\n \"--bjork-accent-soft\": pal.accentSoft,\n \"--bjork-accent-muted\": pal.accentMuted,\n \"--bjork-accent-foreground\": pal.accentFg,\n \"--bjork-success\": pal.success,\n \"--bjork-warning\": pal.warning,\n \"--bjork-error\": pal.error,\n \"--bjork-ring-offset\": pal.bg,\n colorScheme: tone,\n } as CSSProperties;\n return { tone, pal, style };\n}\n\n/** Classes for the shared keyboard focus ring. */\nexport const FOCUS_RING =\n \"outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--bjork-accent)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--bjork-ring-offset)]\";\n\n/** Classes for the shared press feedback. */\nexport const PRESS = \"transition-transform duration-150 ease-out active:scale-[0.97] motion-reduce:transition-none\";\n\n/**\n * Controlled-or-uncontrolled state. Pass `value` to control it; `onChange` fires for every change either way.\n */\nexport function useControllable(\n value: T | undefined,\n defaultValue: T,\n onChange?: (next: T) => void,\n): [T, (next: T) => void] {\n const controlled = value !== undefined;\n const [inner, setInner] = useState(defaultValue);\n const current = controlled ? value : inner;\n const onChangeRef = useRef(onChange);\n useLayoutEffect(() => {\n onChangeRef.current = onChange;\n });\n const set = useCallback(\n (next: T) => {\n if (!controlled) setInner(next);\n onChangeRef.current?.(next);\n },\n [controlled],\n );\n return [current, set];\n}\n\n/** 1234 -> \"1,234\", 18400 -> \"18.4k\", 1_200_000 -> \"1.2M\". */\nexport function formatTokens(n: number): string {\n if (n < 10_000) return Math.round(n).toLocaleString(\"en-US\");\n if (n < 1_000_000) return `${(n / 1000).toFixed(n < 100_000 ? 1 : 0).replace(/\\.0$/, \"\")}k`;\n return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 2 : 1).replace(/\\.?0+$/, \"\")}M`;\n}\n\n/** US dollars with sub-cent precision when it matters: 0.0042 -> \"$0.0042\", 12.5 -> \"$12.50\". */\nexport function formatCost(usd: number): string {\n if (usd === 0) return \"$0.00\";\n if (Math.abs(usd) < 0.01) return `$${usd.toFixed(4)}`;\n if (Math.abs(usd) < 1) return `$${usd.toFixed(3)}`;\n return `$${usd.toLocaleString(\"en-US\", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;\n}\n\n/** 640 -> \"640ms\", 4200 -> \"4.2s\", 95000 -> \"1m 35s\". */\nexport function formatDuration(ms: number): string {\n if (ms < 1000) return `${Math.round(ms)}ms`;\n if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;\n const m = Math.floor(ms / 60_000);\n const s = Math.round((ms % 60_000) / 1000);\n return `${m}m ${s}s`;\n}\n\n/** 2_400_000 bytes -> \"2.4 MB\". */\nexport function formatBytes(bytes: number): string {\n if (bytes < 1024) return `${bytes} B`;\n const units = [\"KB\", \"MB\", \"GB\"];\n let v = bytes / 1024;\n let i = 0;\n while (v >= 1024 && i < units.length - 1) {\n v /= 1024;\n i++;\n }\n return `${v.toFixed(v < 10 ? 1 : 0)} ${units[i]}`;\n}\n\n/** Shimmer keyframes for \"working\" text. Mount once with