{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"clarifying-question","type":"registry:component","title":"Clarifying question","description":"The agent pauses to ask. Pick with a click or a number key, or type your own; it folds into a one-line receipt.","author":"Hairline UI","dependencies":["lucide-react"],"registryDependencies":["https://hairlineui.com/r/number-roll.json","https://hairlineui.com/r/text-morph.json"],"files":[{"path":"registry/clarifying-question.tsx","type":"registry:component","content":"\"use client\";\n\nimport * as React from \"react\";\nimport { ArrowUp } from \"lucide-react\";\nimport { NumberRoll } from \"./number-roll\";\nimport { TextMorph } from \"./text-morph\";\n\n/* ─────────────────────────────────────────────────────────\n * CLARIFYING QUESTION: the agent pauses to ask\n *\n * asking the question and its options; press 1–9 or click\n * other \"Something else\" turns into a field in place\n * multiple options toggle (their checks draw themselves), then\n * \"Continue · 3\", the count rolling as you pick\n * answered the same card folds into one line: the options close,\n * \"Needs your answer\" lifts away and the question and\n * your answer slide into its place as a check draws\n * skipped \"Skipped, the agent will decide\"\n *\n * Pair it with a client-side tool that has no execute: render it\n * for the tool's input and send the answer back as the output.\n * ───────────────────────────────────────────────────────── */\n\nexport interface QuestionOption {\n id: string;\n label: string;\n description?: string;\n}\n\nexport interface QuestionAnswer {\n ids: string[];\n labels: string[];\n /** What they typed under \"Something else\". */\n other?: string;\n}\n\nexport interface ClarifyingQuestionProps extends Omit, \"onSubmit\"> {\n question: string;\n detail?: string;\n options: QuestionOption[];\n /** Allow several answers, confirmed with Continue. */\n multiple?: boolean;\n /** Offer \"Something else\" with a field. */\n allowOther?: boolean;\n otherLabel?: string;\n /** The answer once given, e.g. the tool's output; shows the folded line. */\n answer?: QuestionAnswer | null;\n onAnswer: (answer: QuestionAnswer) => void;\n /** Shows Skip; the agent continues with its own choice. */\n onSkip?: () => void;\n skipped?: boolean;\n skippedText?: string;\n autoFocus?: boolean;\n}\n\nconst OTHER = \"__other__\";\nconst EASE = \"cubic-bezier(0.23,1,0.32,1)\";\nconst MORPH = \"cubic-bezier(0.16,1,0.3,1)\";\nconst FOCUS = \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40\";\n\nconst reducedQuery = \"(prefers-reduced-motion: reduce)\";\nconst subscribeReduced = (onChange: () => void) => {\n const query = window.matchMedia(reducedQuery);\n query.addEventListener(\"change\", onChange);\n return () => query.removeEventListener(\"change\", onChange);\n};\nconst useReducedMotion = () =>\n React.useSyncExternalStore(subscribeReduced, () => window.matchMedia(reducedQuery).matches, () => false);\n\n/** Icons trade places through a blur: the old one shrinks away as the new one grows in. */\nconst swap = (on: boolean, reduced: boolean): React.CSSProperties => ({\n opacity: on ? 1 : 0,\n transform: on ? \"none\" : \"scale(0.6)\",\n filter: on ? \"none\" : \"blur(3px)\",\n transition: reduced ? \"none\" : `opacity 260ms ${MORPH}, transform 380ms ${MORPH}, filter 260ms ${MORPH}`,\n});\n\n/** A piece of a line that opens out of nothing and folds back into it. */\nfunction Reveal({ show, reduced, className = \"\", children }: { show: boolean; reduced: boolean; className?: string; children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n\nfunction DrawnCheck({ drawn, reduced, className = \"size-3\" }: { drawn: boolean; reduced: boolean; className?: string }) {\n return (\n \n \n \n );\n}\n\nexport function ClarifyingQuestion({\n question,\n detail,\n options,\n multiple = false,\n allowOther = true,\n otherLabel = \"Something else\",\n answer,\n onAnswer,\n onSkip,\n skipped = false,\n skippedText = \"the agent will decide\",\n autoFocus = false,\n className = \"\",\n ...props\n}: ClarifyingQuestionProps) {\n const id = React.useId();\n const reduced = useReducedMotion();\n const [own, setOwn] = React.useState(null);\n const [ownSkipped, setOwnSkipped] = React.useState(false);\n const [picked, setPicked] = React.useState([]);\n const [otherOpen, setOtherOpen] = React.useState(false);\n const [otherText, setOtherText] = React.useState(\"\");\n const [active, setActive] = React.useState(0);\n const [highlight, setHighlight] = React.useState({ top: 0, height: 0, ready: false });\n\n const surfaceRef = React.useRef(null);\n const rowRefs = React.useRef<(HTMLButtonElement | HTMLDivElement | null)[]>([]);\n const otherRef = React.useRef(null);\n\n const final = answer ?? own;\n const isSkipped = skipped || ownSkipped;\n const done = Boolean(final) || isSkipped;\n const rows = allowOther ? [...options, { id: OTHER, label: otherLabel }] : options;\n\n // The options are about to fold away: keep focus on the card instead of dropping it on the page.\n const fold = () => {\n if (surfaceRef.current?.contains(document.activeElement)) surfaceRef.current.focus({ preventScroll: true });\n };\n\n React.useEffect(() => {\n if (autoFocus && !done) (rowRefs.current[0] as HTMLElement | null)?.focus({ preventScroll: true });\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, []);\n\n React.useEffect(() => {\n if (otherOpen) otherRef.current?.focus({ preventScroll: true });\n }, [otherOpen]);\n\n // Digits also answer when nothing else has focus (never while typing in a field).\n const chooseRef = React.useRef<(i: number) => void>(() => {});\n React.useEffect(() => {\n if (done) return;\n const onKey = (e: KeyboardEvent) => {\n const focused = document.activeElement;\n if ((focused && focused !== document.body) || e.metaKey || e.ctrlKey || e.altKey || !/^[1-9]$/.test(e.key)) return;\n if (Number(e.key) > rows.length) return;\n e.preventDefault();\n chooseRef.current(Number(e.key) - 1);\n };\n document.addEventListener(\"keydown\", onKey);\n return () => document.removeEventListener(\"keydown\", onKey);\n }, [done, rows.length]);\n\n // The highlight slides to the active row and takes its height.\n React.useLayoutEffect(() => {\n const row = rowRefs.current[active];\n if (!row || done) return;\n const top = row.offsetTop;\n const height = row.offsetHeight;\n setHighlight((h) => (h.top === top && h.height === height && h.ready ? h : { top, height, ready: h.height > 0 }));\n }, [active, otherOpen, done, rows.length]);\n\n const submit = (picks: string[], other?: string) => {\n const order = (x: string) => options.findIndex((o) => o.id === x);\n const ids = [...picks].sort((a, b) => order(a) - order(b));\n const next: QuestionAnswer = {\n ids,\n labels: ids.map((i) => options.find((o) => o.id === i)?.label ?? i),\n ...(other ? { other } : {}),\n };\n fold();\n if (answer === undefined) setOwn(next);\n onAnswer(next);\n };\n\n const skip = () => {\n fold();\n setOwnSkipped(true);\n onSkip?.();\n };\n\n const choose = (i: number) => {\n const row = rows[i];\n if (!row) return;\n setActive(i);\n if (row.id === OTHER) {\n setOtherOpen((o) => (multiple ? !o : true));\n return;\n }\n if (multiple) setPicked((p) => (p.includes(row.id) ? p.filter((x) => x !== row.id) : [...p, row.id]));\n else submit([row.id]);\n };\n\n React.useLayoutEffect(() => {\n chooseRef.current = choose;\n });\n\n const submitOther = () => {\n const text = otherText.trim();\n if (!text) return;\n if (multiple) submit(picked, text);\n else submit([], text);\n };\n\n const onListKey = (e: React.KeyboardEvent) => {\n if (e.target instanceof HTMLInputElement) return;\n if (/^[1-9]$/.test(e.key) && Number(e.key) <= rows.length) {\n e.preventDefault();\n choose(Number(e.key) - 1);\n (rowRefs.current[Number(e.key) - 1] as HTMLElement | null)?.focus();\n } else if (e.key === \"ArrowDown\" || e.key === \"ArrowUp\") {\n e.preventDefault();\n const next = (active + (e.key === \"ArrowDown\" ? 1 : -1) + rows.length) % rows.length;\n setActive(next);\n (rowRefs.current[next] as HTMLElement | null)?.focus();\n }\n };\n\n const summary = final ? [...final.labels, final.other].filter(Boolean).join(\", \") : \"\";\n const receipt = isSkipped && !final ? `Skipped, ${skippedText}` : summary;\n const count = picked.length + (otherOpen && otherText.trim() ? 1 : 0);\n const canContinue = count > 0;\n\n return (\n
\n {/* The header stays put; once answered it becomes the whole card: question · answer. */}\n \n \n \n \n \n \n \n \n \n \n \n \n \n {done ? \"\" : \"Needs your answer\"}\n \n \n \n {question}\n \n \n \n \n ·\n \n \n {receipt}\n \n \n
\n \n {done ? `${question}: ${receipt}` : \"\"}\n \n\n {/* Everything else folds shut once it's answered. */}\n \n
\n
\n
\n

\n {question}\n

\n {detail &&

{detail}

}\n
\n\n
\n \n {rows.map((row, i) => {\n const isOther = row.id === OTHER;\n const checked = isOther ? otherOpen : picked.includes(row.id);\n const description = \"description\" in row ? row.description : undefined;\n const marker = multiple ? (\n \n \n \n ) : (\n \n {i + 1}\n \n );\n\n if (isOther && otherOpen) {\n return (\n {\n rowRefs.current[i] = el;\n }}\n className=\"relative flex min-h-11 items-center gap-3 rounded-[14px] px-2.5\"\n >\n {marker}\n setOtherText(e.target.value)}\n onFocus={() => setActive(i)}\n onKeyDown={(e) => {\n if (e.nativeEvent.isComposing) return;\n if (e.key === \"Enter\") {\n e.preventDefault();\n submitOther();\n } else if (e.key === \"Escape\") {\n e.preventDefault();\n setOtherOpen(false);\n requestAnimationFrame(() => (rowRefs.current[i] as HTMLElement | null)?.focus());\n }\n }}\n placeholder=\"Type your answer\"\n aria-label={otherLabel}\n className=\"h-8 min-w-0 flex-1 bg-transparent text-[13.5px] text-foreground outline-none placeholder:text-muted-foreground animate-[ui-fade-in_200ms_ease-out_both] motion-reduce:animate-none\"\n />\n {!multiple && (\n \n \n \n )}\n
\n );\n }\n\n return (\n {\n rowRefs.current[i] = el;\n }}\n type=\"button\"\n role={multiple ? \"checkbox\" : \"radio\"}\n aria-checked={multiple ? checked : false}\n tabIndex={i === active ? 0 : -1}\n onClick={() => choose(i)}\n onPointerMove={() => i !== active && setActive(i)}\n onFocus={() => setActive(i)}\n className=\"relative flex min-h-11 w-full items-center gap-3 rounded-[14px] px-2.5 py-2 text-left outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring/30\"\n >\n {marker}\n \n {isOther ? `${row.label}…` : row.label}\n {description && {description}}\n \n \n );\n })}\n
\n\n {(onSkip || multiple) && (\n
\n {onSkip ? (\n \n Skip\n \n ) : (\n \n )}\n {multiple && (\n submit(picked, otherOpen && otherText.trim() ? otherText.trim() : undefined)}\n className={`inline-flex h-8 items-center rounded-full bg-primary px-3.5 text-[12.5px] font-medium text-primary-foreground transition-[opacity,transform] duration-300 active:scale-[0.96] disabled:opacity-35 ${FOCUS}`}\n >\n Continue\n {/* \" · 3\" opens beside it with the first pick and rolls as you pick more. */}\n 0 ? \"1fr\" : \"0fr\",\n opacity: count > 0 ? 1 : 0,\n transition: reduced ? \"none\" : `grid-template-columns 380ms ${MORPH}, opacity 260ms ${MORPH}`,\n }}\n >\n \n  · \n \n \n \n {count > 0 && , {count} selected}\n \n )}\n
\n )}\n
\n \n \n \n );\n}\n"}],"css":{"@keyframes ui-fade-in":{"from":{"opacity":"0"},"to":{"opacity":"1"}},"@keyframes ui-ping":{"from":{"transform":"scale(1)","opacity":"0.55"},"to":{"transform":"scale(2.6)","opacity":"0"}}},"docs":"Docs and live preview: https://hairlineui.com/ui/clarifying-question"}