{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"reasoning-panel","type":"registry:ui","title":"ReasoningPanel","description":"Collapsible reasoning trace that streams while the model thinks, then folds itself into a one-line summary","author":"fancy-ui <https://fancy-ui.rama.app>","categories":["ai-agents"],"registryDependencies":["https://fancy-ui.rama.app/r/internals.json","https://fancy-ui.rama.app/r/internals-dom.json","https://fancy-ui.rama.app/r/sound.json","https://fancy-ui.rama.app/r/utils.json"],"files":[{"path":"react/src/components/reasoning-panel/ReasoningPanel.tsx","content":"\"use client\";\n\nimport { forwardRef, useEffect, useInsertionEffect, useRef, useState } from \"react\";\nimport { cn } from \"../../utils\";\nimport { StreamText } from \"../../internals/StreamText\";\nimport { useAutoscroll } from \"../../internals/use-autoscroll\";\nimport { formatElapsed, useElapsed } from \"../../internals/use-elapsed\";\nimport { useFancyId } from \"../../internals/use-id\";\nimport { useComposedRefs } from \"../../internals/dom/use-composed-refs\";\nimport { useElementRef } from \"../../internals/dom/use-element-ref\";\nimport { useInertAttribute } from \"../../internals/dom/use-inert-attribute\";\nimport { useEventCallback } from \"../../internals/dom/use-event-callback\";\nimport { useLiveRef } from \"../../internals/dom/use-live-ref\";\nimport { useSoundCue } from \"../../sound/use-sound\";\nimport \"./reasoning-panel.css\";\n\n/**\n * Props for ReasoningPanel\n */\nexport interface ReasoningPanelProps {\n\t/** The reasoning trace so far. Hand over a longer string to stream more in. */\n\ttext: string;\n\t/** Whether the trace is still growing. Drives the timer, the shimmer, and autoscroll. */\n\tstreaming?: boolean;\n\t/**\n\t * Whether the trace is expanded. Left alone until either the component or\n\t * the reader changes it — see the open-behaviour contract in the README. A\n\t * changed prop value is adopted as the new state and announced through\n\t * `onToggle`, the counterpart of a consumer writing to the bound variable\n\t * on the Svelte side.\n\t */\n\topen?: boolean;\n\t/** Header text. */\n\tlabel?: string;\n\t/** Epoch ms the current burst started at. Pins the live timer's origin. */\n\tsince?: number;\n\t/** Final duration for the summary line. Falls back to what the timer measured. */\n\tdurationMs?: number;\n\t/** Scroll height of the trace once expanded. */\n\tmaxHeight?: string;\n\t/** Called whenever the panel opens or closes, by click or on its own. */\n\tonToggle?: (open: boolean) => void;\n\t/** Additional CSS classes */\n\tclassName?: string;\n\t/**\n\t * Plays the matching interface cue through the sound controller. Off by\n\t * default; only audible once the user has enabled sound.\n\t */\n\tsound?: boolean;\n}\n\n/** How long a finished trace stays on screen before folding itself away. */\nconst AUTO_COLLAPSE_MS = 600;\n\n/**\n * ReasoningPanel\n */\nexport const ReasoningPanel = forwardRef<HTMLDivElement, ReasoningPanelProps>(\n\tfunction ReasoningPanel(\n\t\t{\n\t\t\ttext,\n\t\t\tstreaming = false,\n\t\t\topen: openProp,\n\t\t\tlabel = \"Reasoning\",\n\t\t\tsince,\n\t\t\tdurationMs,\n\t\t\tmaxHeight = \"12rem\",\n\t\t\tonToggle,\n\t\t\tclassName,\n\t\t\tsound = false,\n\t\t},\n\t\tref\n\t) {\n\t\tconst uid = useFancyId();\n\t\tconst headerId = `${uid}-header`;\n\t\tconst bodyId = `${uid}-body`;\n\n\t\t// `open` stays undefined until something actually decides: `autoOpen`\n\t\t// carries the answer in the meantime, so a consumer that never touches\n\t\t// the prop still gets the automatic behaviour and one that drives it\n\t\t// still owns the value.\n\t\tconst [openState, setOpenState] = useState<boolean | undefined>(openProp);\n\t\tconst [autoOpen, setAutoOpen] = useState(false);\n\t\tconst [measuredMs, setMeasuredMs] = useState(0);\n\n\t\t// A changed `open` prop is a consumer decision: adopt it during render,\n\t\t// the way a write to the bound variable lands on the Svelte side.\n\t\tconst lastOpenProp = useRef(openProp);\n\t\tif (openProp !== lastOpenProp.current) {\n\t\t\tlastOpenProp.current = openProp;\n\t\t\tif (openProp !== openState) setOpenState(openProp);\n\t\t}\n\n\t\tconst isOpen = openState ?? autoOpen;\n\n\t\t// The state the last COMMITTED render published, readable from outside a\n\t\t// render. Written in an insertion effect rather than the render body, so a\n\t\t// render React starts and throws away can never publish a value the\n\t\t// component never showed.\n\t\tconst isOpenRef = useLiveRef(isOpen);\n\t\t// What `commit` last decided, parked here until the render carrying it\n\t\t// lands: React publishes state one render later, and two commits inside a\n\t\t// single batch — a mount effect rehearsed by StrictMode, an effect and a\n\t\t// timer in the same flush — must see the first one's answer rather than\n\t\t// the render's. Cleared on every commit, so it never outlives the render\n\t\t// that carries it.\n\t\tconst decidedOpen = useRef<boolean | undefined>(undefined);\n\t\tuseInsertionEffect(() => {\n\t\t\tdecidedOpen.current = undefined;\n\t\t});\n\n\t\t/** The panel's state as `commit`/`toggle` see it, between renders. */\n\t\tfunction currentOpen(): boolean {\n\t\t\treturn decidedOpen.current ?? isOpenRef.current;\n\t\t}\n\n\t\t// Plain refs: none of these should wake an effect that writes them.\n\t\tconst userToggled = useRef(false);\n\t\tconst wasStreaming = useRef(false);\n\t\tconst collapseTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);\n\t\t// The last value `onToggle` was told about. `commit` keeps it in step\n\t\t// with its own calls, so the effect below only speaks up for changes\n\t\t// that never went through it — a consumer rewriting the `open` prop.\n\t\tconst lastNotifiedOpen = useRef(isOpen);\n\n\t\tconst elapsed = useElapsed();\n\t\tconst elapsedMsRef = useLiveRef(elapsed.ms);\n\t\tconst { start: startElapsed, stop: stopElapsed } = elapsed;\n\n\t\tconst playCue = useSoundCue(sound);\n\n\t\tconst duration = durationMs ?? measuredMs;\n\t\tconst summary = streaming\n\t\t\t? formatElapsed(elapsed.ms)\n\t\t\t: duration > 0\n\t\t\t\t? `Thought for ${formatElapsed(duration)}`\n\t\t\t\t: \"\";\n\n\t\tfunction clearCollapseTimer() {\n\t\t\tif (collapseTimer.current !== undefined) {\n\t\t\t\tclearTimeout(collapseTimer.current);\n\t\t\t\tcollapseTimer.current = undefined;\n\t\t\t}\n\t\t}\n\n\t\tconst commit = useEventCallback((next: boolean) => {\n\t\t\tif (currentOpen() === next) return;\n\t\t\tdecidedOpen.current = next;\n\t\t\tsetOpenState(next);\n\t\t\tsetAutoOpen(next);\n\t\t\tlastNotifiedOpen.current = next;\n\t\t\tonToggle?.(next);\n\t\t});\n\n\t\tfunction toggle() {\n\t\t\t// From here on the reader owns the panel: no more opening or closing\n\t\t\t// on its own behind their back.\n\t\t\tuserToggled.current = true;\n\t\t\tclearCollapseTimer();\n\t\t\tconst next = !currentOpen();\n\t\t\t// Only this click plays a cue — the streaming auto-open and the 600ms\n\t\t\t// auto-collapse both fold through `commit`, and must stay silent, so the\n\t\t\t// play sits here rather than in `commit` or the effect that watches it.\n\t\t\tplayCue(next ? \"open\" : \"close\");\n\t\t\tcommit(next);\n\t\t}\n\n\t\t// Open on the first chunk, fold away a beat after the last one — until\n\t\t// the reader takes over. `userToggled` is a ref so that taking over\n\t\t// does not itself re-run this.\n\t\tuseEffect(() => {\n\t\t\tclearCollapseTimer();\n\t\t\tif (streaming) {\n\t\t\t\twasStreaming.current = true;\n\t\t\t\tif (!userToggled.current) commit(true);\n\t\t\t\treturn clearCollapseTimer;\n\t\t\t}\n\t\t\tif (!wasStreaming.current) return clearCollapseTimer;\n\t\t\twasStreaming.current = false;\n\t\t\tif (userToggled.current) return clearCollapseTimer;\n\t\t\tcollapseTimer.current = setTimeout(() => {\n\t\t\t\tcollapseTimer.current = undefined;\n\t\t\t\tcommit(false);\n\t\t\t}, AUTO_COLLAPSE_MS);\n\t\t\treturn clearCollapseTimer;\n\t\t}, [streaming, commit]);\n\n\t\t// A consumer that rewrites the `open` prop moves the panel without going\n\t\t// through `commit`, so nothing above reports it. The README promises\n\t\t// every change is announced, whichever side caused it.\n\t\tconst notifyToggle = useEventCallback(onToggle);\n\t\tuseEffect(() => {\n\t\t\tif (isOpen === lastNotifiedOpen.current) return;\n\t\t\tlastNotifiedOpen.current = isOpen;\n\t\t\tnotifyToggle(isOpen);\n\t\t}, [isOpen, notifyToggle]);\n\n\t\t// The timer only exists while the trace grows; its last reading survives\n\t\t// as the summary duration.\n\t\tuseEffect(() => {\n\t\t\tif (!streaming) return;\n\t\t\tstartElapsed(since ?? Date.now());\n\t\t\treturn () => {\n\t\t\t\tsetMeasuredMs(elapsedMsRef.current);\n\t\t\t\tstopElapsed();\n\t\t\t};\n\t\t}, [streaming, since, startElapsed, stopElapsed]);\n\n\t\tconst [bodyEl, bodyRef] = useElementRef<HTMLDivElement>();\n\t\tconst inertRef = useInertAttribute<HTMLDivElement>(!isOpen);\n\t\tconst composedBodyRef = useComposedRefs<HTMLDivElement>(bodyRef, inertRef);\n\t\tuseAutoscroll(bodyEl, { enabled: streaming && isOpen, pinOnConnect: true });\n\n\t\treturn (\n\t\t\t<div\n\t\t\t\tref={ref}\n\t\t\t\tclassName={cn(\n\t\t\t\t\t\"fancy-reasoning-panel border-border bg-card/50 w-full rounded-lg border text-sm\",\n\t\t\t\t\tclassName\n\t\t\t\t)}\n\t\t\t>\n\t\t\t\t<button\n\t\t\t\t\ttype=\"button\"\n\t\t\t\t\tid={headerId}\n\t\t\t\t\tclassName=\"text-muted-foreground hover:text-foreground flex w-full items-center gap-2 rounded-lg px-3 py-2 text-left transition-colors\"\n\t\t\t\t\taria-expanded={isOpen}\n\t\t\t\t\taria-controls={bodyId}\n\t\t\t\t\tonClick={toggle}\n\t\t\t\t>\n\t\t\t\t\t<svg\n\t\t\t\t\t\tclassName={cn(\"ft-chevron size-3.5 shrink-0\", isOpen && \"ft-open\")}\n\t\t\t\t\t\tviewBox=\"0 0 24 24\"\n\t\t\t\t\t\tfill=\"none\"\n\t\t\t\t\t\tstroke=\"currentColor\"\n\t\t\t\t\t\tstrokeWidth=\"2.5\"\n\t\t\t\t\t\tstrokeLinecap=\"round\"\n\t\t\t\t\t\tstrokeLinejoin=\"round\"\n\t\t\t\t\t\taria-hidden=\"true\"\n\t\t\t\t\t>\n\t\t\t\t\t\t<path d=\"m9 6 6 6-6 6\" />\n\t\t\t\t\t</svg>\n\t\t\t\t\t<span className={cn(\"text-foreground font-medium\", streaming && \"ft-shimmer\")}>\n\t\t\t\t\t\t{label}\n\t\t\t\t\t</span>\n\t\t\t\t\t{summary ? <span className=\"ml-auto text-xs tabular-nums\">{summary}</span> : null}\n\t\t\t\t</button>\n\n\t\t\t\t<div className={cn(\"ft-body\", isOpen && \"ft-open\")}>\n\t\t\t\t\t<div className=\"overflow-hidden\">\n\t\t\t\t\t\t{/*\n\t\t\t\t\t\t\t`inert` goes straight to the node through `useInertAttribute`, never\n\t\t\t\t\t\t\tas a JSX prop: React 18 drops `inert={true}` and React 19 rejects\n\t\t\t\t\t\t\t`inert=\"\"`, so no single prop spelling covers this package's peer\n\t\t\t\t\t\t\trange. The hook emits the same attribute on both.\n\t\t\t\t\t\t*/}\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tref={composedBodyRef}\n\t\t\t\t\t\t\tid={bodyId}\n\t\t\t\t\t\t\trole=\"group\"\n\t\t\t\t\t\t\taria-labelledby={headerId}\n\t\t\t\t\t\t\tclassName=\"text-muted-foreground overflow-y-auto px-3 pb-3 leading-relaxed\"\n\t\t\t\t\t\t\tstyle={{ maxHeight }}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<StreamText text={text} />\n\t\t\t\t\t\t</div>\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t);\n\t}\n);\n","type":"registry:ui","target":"@ui/fancy/components/reasoning-panel/ReasoningPanel.tsx"},{"path":"react/src/components/reasoning-panel/index.ts","content":"\"use client\";\n\nexport { ReasoningPanel } from \"./ReasoningPanel\";\nexport type { ReasoningPanelProps } from \"./ReasoningPanel\";\n","type":"registry:ui","target":"@ui/fancy/components/reasoning-panel/index.ts"},{"path":"react/src/components/reasoning-panel/reasoning-panel.css","content":"/*\n * `.fancy-reasoning-panel` is a PORT-ADDED anchor (PORTING.md, styling rule 2).\n * The source's <style> block was compiler-scoped and had no root class; plain\n * CSS is global, so every rule here stays anchored under the root to keep\n * names like `.ft-body` from leaking into every consumer's page. The anchor is\n * the first token of the root `cn()` call.\n */\n\n/*\n * 0fr → 1fr on a one-row grid is the only way to transition \"auto\" height\n * without measuring anything. The inner wrapper does the clipping.\n */\n.fancy-reasoning-panel .ft-body {\n\tdisplay: grid;\n\tgrid-template-rows: 0fr;\n}\n\n.fancy-reasoning-panel .ft-body.ft-open {\n\tgrid-template-rows: 1fr;\n}\n\n.fancy-reasoning-panel .ft-chevron.ft-open {\n\ttransform: rotate(90deg);\n}\n\n/*\n * Everything that moves lives behind the query, so reduced motion gets the\n * same three states with nothing to shorten or fall back from.\n */\n@media (prefers-reduced-motion: no-preference) {\n\t.fancy-reasoning-panel .ft-body {\n\t\ttransition: grid-template-rows 260ms cubic-bezier(0.4, 0, 0.2, 1);\n\t}\n\n\t.fancy-reasoning-panel .ft-chevron {\n\t\ttransition: transform 220ms cubic-bezier(0.4, 0, 0.2, 1);\n\t}\n\n\t.fancy-reasoning-panel .ft-shimmer {\n\t\tbackground-image: linear-gradient(\n\t\t\t100deg,\n\t\t\tcurrentColor 40%,\n\t\t\tvar(--ft-reasoning-shimmer, color-mix(in oklab, currentColor 35%, transparent)) 50%,\n\t\t\tcurrentColor 60%\n\t\t);\n\t\tbackground-size: 250% 100%;\n\t\tbackground-clip: text;\n\t\t/* Keep `color` intact: the gradient stops resolve currentColor at this\n\t\t   element, so `color: transparent` would blank every stop. Only the glyph\n\t\t   fill goes transparent; the clipped gradient supplies the visible text. */\n\t\t-webkit-text-fill-color: transparent;\n\t\tanimation: ft-reasoning-shimmer 1.9s linear infinite;\n\t}\n\n\t@keyframes ft-reasoning-shimmer {\n\t\tfrom {\n\t\t\tbackground-position: 150% 0;\n\t\t}\n\t\tto {\n\t\t\tbackground-position: -50% 0;\n\t\t}\n\t}\n}\n","type":"registry:ui","target":"@ui/fancy/components/reasoning-panel/reasoning-panel.css"}],"meta":{"license":"MIT","package":"fancy-ui-react","version":"0.7.0","source":"https://fancy-ui.rama.app/docs/components/reasoning-panel?framework=react"}}