{ "schemaVersion": 1, "name": "questionnaire", "useFor": "Use when an agent or a setup flow needs a few answers in a row (how to route calls, what to include in a summary). Pass the questions as items to Questionnaire, then render a QuestionnaireItem per question with a QuestionnaireTitle, a QuestionnaireDescription, QuestionnaireChoices of QuestionnaireChoice (add QuestionnaireInput for another answer) and a QuestionnaireError; end with QuestionnaireActions holding Previous, Skip, Next and Submit. Mark required questions; set multiple to allow several answers. onSubmit receives the native form event: read the answers with FormData.", "constraints": [ "More than one question on screen", "Animating between questions", "A required question without its error message", "A purple card fill for a chosen answer" ], "documentation": "", "source": "Extrapolated from the Inkbox console (Figma 427:2715): the radio and checks in Create Agent Identity and the Where does this agent run? picker", "exports": [ "Questionnaire", "QuestionnaireActions", "QuestionnaireChoice", "QuestionnaireChoiceDescription", "QuestionnaireChoices", "QuestionnaireDescription", "QuestionnaireError", "QuestionnaireInput", "QuestionnaireItem", "QuestionnaireNext", "QuestionnairePrevious", "QuestionnaireProgress", "QuestionnaireSkip", "QuestionnaireSubmit", "QuestionnaireTitle" ], "client": true, "docsUrl": "https://inkbox-ds.vercel.app/components/questionnaire", "markdownUrl": "https://inkbox-ds.vercel.app/r/questionnaire.md", "examples": [ { "path": "examples/questionnaire.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport {\n Questionnaire,\n QuestionnaireActions,\n QuestionnaireChoice,\n QuestionnaireChoiceDescription,\n QuestionnaireChoices,\n QuestionnaireDescription,\n QuestionnaireError,\n QuestionnaireInput,\n QuestionnaireItem,\n QuestionnaireNext,\n QuestionnairePrevious,\n QuestionnaireProgress,\n QuestionnaireSkip,\n QuestionnaireSubmit,\n QuestionnaireTitle,\n} from \"@/components/ui/questionnaire\";\n\nconst ITEMS = [\n { name: \"channel\", required: true, choices: [{ value: \"email\" }, { value: \"phone\" }, { value: \"imessage\" }] },\n { name: \"include\", multiple: true, choices: [{ value: \"sender\" }, { value: \"summary\" }, { value: \"attachments\" }, { value: \"next-step\" }] },\n { name: \"when\", required: true, choices: [{ value: \"now\" }, { value: \"hourly\" }, { value: \"daily\" }] },\n] as const;\n\nfunction Saved({ answers }: { answers: string }) {\n return (\n

\n Saved. {answers}\n

\n );\n}\n\nexport function Preview() {\n const [saved, setSaved] = React.useState();\n return (\n
\n {\n event.preventDefault();\n const data = new FormData(event.currentTarget);\n setSaved(`Channel: ${data.get(\"channel\")}. Include: ${data.getAll(\"include\").join(\", \") || \"nothing\"}. When: ${data.get(\"when\")}.`);\n }}\n >\n \n \n Where should @acme tell you about new mail?\n Choose a channel, or type another one.\n \n \n Email\n A note to robert@acme.com\n \n \n Phone\n A text from the agent's number\n \n \n iMessage\n Through the shared iMessage line\n \n \n \n \n \n \n What should each note include?\n Choose any, or skip this question.\n \n The sender\n A one-line summary\n Attachments\n The suggested next step\n \n \n \n \n How often?\n Batched notes arrive once per period.\n \n As each email arrives\n Once an hour\n Once a day\n \n \n \n \n \n \n \n Save rule\n \n \n {saved && }\n
\n );\n}\n\nconst PLAN = [{ name: \"line\", required: true, choices: [{ value: \"shared\" }, { value: \"dedicated\" }, { value: \"port\" }] }] as const;\n\nexport function Disabled() {\n return (\n event.preventDefault()}>\n \n Which iMessage line should the agent use?\n No dedicated lines are available to assign right now.\n \n \n Shared\n Assigned when someone connects\n \n \n Dedicated\n None available\n \n \n Port a number\n Bring an existing number\n \n \n \n \n \n Assign line\n \n \n );\n}\n", "exports": [ "Preview", "Disabled" ], "requires": [ "questionnaire" ], "packages": [], "previews": [ { "name": "Preview", "url": "https://inkbox-ds.vercel.app/preview/questionnaire/Preview" }, { "name": "Disabled", "url": "https://inkbox-ds.vercel.app/preview/questionnaire/Disabled" } ] } ], "type": "ui", "title": "Questionnaire", "description": "Questions asked one at a time: white choice cards with the brand's radio or checkbox and a shortcut key, a typed answer, a progress count and Previous, Skip and Next pills.", "surface": "site", "kinds": [], "requires": [ "theme", "button", "input", "kbd", "progress", "utils" ], "packages": [ "@phosphor-icons/react" ], "files": [ { "path": "components/ui/questionnaire.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { CheckIcon } from \"@phosphor-icons/react/ssr\";\n\nimport { Button } from \"@/components/ui/button\";\nimport { Input } from \"@/components/ui/input\";\nimport { Kbd } from \"@/components/ui/kbd\";\nimport { Progress } from \"@/components/ui/progress\";\nimport { cn } from \"@/lib/utils\";\n\n// A short set of questions asked one at a time (extrapolated from the console, Figma 427:2715: Create Agent Identity's\n// choices and the Where does this agent run? picker). A choice is a 44px white card with the field edge and 8px\n// corners, the brand's radio (a thick pink ring when chosen) or checkbox (purple when checked) 14px in, a 14px ink label\n// and its number or letter key at the right; a chosen card takes the purple edge. The question is 16px medium ink with\n// a 14px secondary line under it; progress is a 12px muted count over a thin purple bar. Changing questions is instant:\n// it is driven by the keyboard as often as by the pointer. The answers submit as one native form (FormData), every\n// question's inputs included, so the page owns saving and what happens next.\n\ntype Choice = { readonly value: string; readonly disabled?: boolean };\ntype ItemConfig = { readonly name: string; readonly required?: boolean; readonly multiple?: boolean; readonly choices?: readonly Choice[] };\ntype Shortcuts = \"numbers\" | \"letters\" | \"none\";\n\ntype QuestionnaireContextValue = {\n order: string[];\n active: string | undefined;\n goTo: (name: string) => void;\n shortcuts: Shortcuts;\n answers: Record;\n other: Record;\n errors: Record;\n configs: React.RefObject>;\n register: (config: ItemConfig) => () => void;\n setAnswer: (name: string, value: string, checked: boolean) => void;\n setOther: (name: string, text: string) => void;\n next: () => void;\n previous: () => void;\n skip: () => void;\n};\n\nconst QuestionnaireContext = React.createContext(null);\nconst ItemContext = React.createContext<{ name: string; required: boolean; multiple: boolean; id: string } | null>(null);\n\nfunction useQuestionnaire() {\n const context = React.useContext(QuestionnaireContext);\n if (!context) throw new Error(\"Questionnaire parts must be inside a Questionnaire.\");\n return context;\n}\n\nfunction useItem() {\n const context = React.useContext(ItemContext);\n if (!context) throw new Error(\"This part must be inside a QuestionnaireItem.\");\n return context;\n}\n\nconst shortcutKey = (index: number, shortcuts: Shortcuts) => (shortcuts === \"none\" || index > 8 ? undefined : shortcuts === \"letters\" ? String.fromCharCode(65 + index) : String(index + 1));\n\n/**\n * The questions and their answers. Pass `items` (name, required, multiple, choices) so the order, progress and shortcuts\n * are known on the server; without it the order is the QuestionnaireItems' order. `defaultItem` or a controlled\n * `item` with `onItemChange` picks the question shown. `shortcuts` puts 1 to 9 (or A to I) on the choices.\n */\nfunction Questionnaire({\n items,\n defaultItem,\n item,\n onItemChange,\n shortcuts = \"numbers\",\n className,\n onSubmit,\n onKeyDown,\n children,\n ...props\n}: Omit, \"onSubmit\"> & {\n items?: readonly ItemConfig[];\n defaultItem?: string;\n item?: string;\n onItemChange?: (name: string) => void;\n shortcuts?: Shortcuts;\n onSubmit?: (event: React.FormEvent) => void;\n}) {\n const form = React.useRef(null);\n const configs = React.useRef(new Map(items?.map((i) => [i.name, i])));\n const [registered, setRegistered] = React.useState([]);\n const order = items ? items.map((i) => i.name) : registered;\n const [internal, setInternal] = React.useState(defaultItem ?? items?.[0]?.name);\n const active = item ?? internal ?? order[0];\n const [answers, setAnswers] = React.useState>({});\n const [other, setOtherState] = React.useState>({});\n const [errors, setErrors] = React.useState>({});\n\n const focusItem = React.useCallback((name: string) => {\n requestAnimationFrame(() => {\n const fieldset = form.current?.querySelector(`[data-slot=questionnaire-item][data-name=\"${CSS.escape(name)}\"]`);\n fieldset?.querySelector(\"input:not(:disabled)\")?.focus({ preventScroll: true });\n });\n }, []);\n\n const goTo = React.useCallback(\n (name: string) => {\n if (item === undefined) setInternal(name);\n onItemChange?.(name);\n focusItem(name);\n },\n [item, onItemChange, focusItem],\n );\n\n const register = React.useCallback((config: ItemConfig) => {\n configs.current.set(config.name, { ...configs.current.get(config.name), ...config });\n setRegistered((list) => (list.includes(config.name) ? list : [...list, config.name]));\n return () => setRegistered((list) => list.filter((n) => n !== config.name));\n }, []);\n\n const answered = React.useCallback((name: string) => (answers[name]?.length ?? 0) > 0 || (other[name] ?? \"\").trim() !== \"\", [answers, other]);\n\n const validate = React.useCallback(\n (name: string) => {\n const config = configs.current.get(name);\n const message = config?.required && !answered(name) ? (config.multiple ? \"Choose at least one answer to continue.\" : \"Choose an answer to continue.\") : undefined;\n setErrors((e) => ({ ...e, [name]: message }));\n return !message;\n },\n [answered],\n );\n\n const setAnswer = React.useCallback((name: string, value: string, checked: boolean) => {\n const multiple = configs.current.get(name)?.multiple;\n setAnswers((a) => ({ ...a, [name]: multiple ? (checked ? [...(a[name] ?? []).filter((v) => v !== value), value] : (a[name] ?? []).filter((v) => v !== value)) : checked ? [value] : [] }));\n if (!multiple && checked) setOtherState((o) => ({ ...o, [name]: \"\" }));\n setErrors((e) => ({ ...e, [name]: undefined }));\n }, []);\n\n const setOther = React.useCallback((name: string, text: string) => {\n setOtherState((o) => ({ ...o, [name]: text }));\n if (text && !configs.current.get(name)?.multiple) setAnswers((a) => ({ ...a, [name]: [] }));\n setErrors((e) => ({ ...e, [name]: undefined }));\n }, []);\n\n const index = active ? order.indexOf(active) : -1;\n const next = React.useCallback(() => {\n if (!active || !validate(active)) return focusItem(active ?? \"\");\n const following = order[index + 1];\n if (following) goTo(following);\n }, [active, validate, focusItem, order, index, goTo]);\n const previous = React.useCallback(() => {\n const before = order[index - 1];\n if (before) goTo(before);\n }, [order, index, goTo]);\n const skip = React.useCallback(() => {\n if (!active) return;\n setAnswers((a) => ({ ...a, [active]: [] }));\n setOtherState((o) => ({ ...o, [active]: \"\" }));\n setErrors((e) => ({ ...e, [active]: undefined }));\n const following = order[index + 1];\n if (following) goTo(following);\n }, [active, order, index, goTo]);\n\n const value = React.useMemo(\n () => ({ order, active, goTo, shortcuts, answers, other, errors, configs, register, setAnswer, setOther, next, previous, skip }),\n [order, active, goTo, shortcuts, answers, other, errors, register, setAnswer, setOther, next, previous, skip],\n );\n\n return (\n \n {\n // Every required question must be answered; the first one that is not is shown with its message.\n const missing = order.find((name) => !validate(name));\n if (missing) {\n event.preventDefault();\n goTo(missing);\n return;\n }\n onSubmit?.(event);\n }}\n onKeyDown={(event) => {\n onKeyDown?.(event);\n if (event.defaultPrevented || !active || event.metaKey || event.ctrlKey || event.altKey) return;\n const target = event.target as HTMLElement;\n const typing = target instanceof HTMLInputElement && target.type === \"text\";\n if (event.key === \"Enter\" && !(target instanceof HTMLButtonElement) && !(target instanceof HTMLTextAreaElement)) {\n event.preventDefault();\n if (index < order.length - 1) next();\n else form.current?.requestSubmit();\n return;\n }\n if (typing || shortcuts === \"none\") return;\n const key = event.key.toUpperCase();\n const at = shortcuts === \"letters\" ? key.charCodeAt(0) - 65 : Number(key) - 1;\n if (key.length !== 1 || Number.isNaN(at) || at < 0 || at > 8) return;\n const choice = form.current?.querySelectorAll(`[data-slot=questionnaire-item][data-name=\"${CSS.escape(active)}\"] [data-slot=questionnaire-choice-input]`)[at];\n if (!choice || choice.disabled) return;\n event.preventDefault();\n choice.focus();\n setAnswer(active, choice.value, choice.type === \"checkbox\" ? !choice.checked : true);\n }}\n {...props}\n >\n {children}\n \n \n );\n}\n\n/** Where the person is: \"Question 2 of 3\" in 12px muted medium over a 4px purple bar. */\nfunction QuestionnaireProgress({ className, children, ...props }: React.ComponentProps<\"div\">) {\n const { order, active } = useQuestionnaire();\n const at = active ? order.indexOf(active) + 1 : 0;\n const total = order.length;\n return (\n
\n \n {children ?? (total ? `Question ${at} of ${total}` : \" \")}\n \n \n
\n );\n}\n\n/** One question. Only the current one shows; the others stay in the form so their answers submit with it. */\nfunction QuestionnaireItem({ name, required = false, multiple = false, className, children, ...props }: Omit, \"name\"> & { name: string; required?: boolean; multiple?: boolean }) {\n const { active, register, errors } = useQuestionnaire();\n const id = React.useId();\n React.useLayoutEffect(() => register({ name, required, multiple }), [register, name, required, multiple]);\n const context = React.useMemo(() => ({ name, required, multiple, id }), [name, required, multiple, id]);\n const isActive = active === name;\n return (\n \n \n );\n}\n\nfunction QuestionnaireTitle({ className, ...props }: React.ComponentProps<\"div\">) {\n const { id } = useItem();\n return
;\n}\n\nfunction QuestionnaireDescription({ className, ...props }: React.ComponentProps<\"p\">) {\n const { id } = useItem();\n return

;\n}\n\n/** The choices of a question, 8px apart; each direct QuestionnaireChoice gets its shortcut in order. */\nfunction QuestionnaireChoices({ className, children, ...props }: React.ComponentProps<\"div\">) {\n const { multiple, id } = useItem();\n let index = 0;\n return (\n

\n {React.Children.map(children, (child) => (React.isValidElement<{ index?: number }>(child) && child.type === QuestionnaireChoice ? React.cloneElement(child, { index: index++ }) : child))}\n
\n );\n}\n\nfunction QuestionnaireChoice({ value, disabled = false, index = 0, className, children, ...props }: Omit, \"children\"> & { value: string; disabled?: boolean; index?: number; children?: React.ReactNode }) {\n const { answers, setAnswer, shortcuts } = useQuestionnaire();\n const { name, multiple } = useItem();\n const checked = answers[name]?.includes(value) ?? false;\n const key = shortcutKey(index, shortcuts);\n return (\n \n setAnswer(name, value, event.target.checked)}\n className=\"peer sr-only\"\n />\n \n {multiple && }\n \n \n {children}\n \n {key && (\n \n )}\n \n );\n}\n\n/** A choice's second line: 14px muted. */\nfunction QuestionnaireChoiceDescription({ className, ...props }: React.ComponentProps<\"span\">) {\n return ;\n}\n\n/** A free answer typed instead of a choice (another answer); typing clears a single choice, choosing clears the text. */\nfunction QuestionnaireInput({ className, ...props }: Omit, \"name\" | \"value\" | \"onChange\">) {\n const { other, setOther } = useQuestionnaire();\n const { name } = useItem();\n return (\n
\n setOther(name, event.target.value)} className={cn(\"h-11\", className)} {...props} />\n
\n );\n}\n\n/** Why the question cannot be passed yet: 12px red, read out when it appears. */\nfunction QuestionnaireError({ className, children, ...props }: React.ComponentProps<\"p\">) {\n const { errors } = useQuestionnaire();\n const { name, id } = useItem();\n const message = children ?? errors[name];\n if (!message) return null;\n return (\n

\n {message}\n

\n );\n}\n\n/** The buttons under the question: Previous at the left, then Skip and Next (or Submit on the last question). */\nfunction QuestionnaireActions({ className, ...props }: React.ComponentProps<\"div\">) {\n return
;\n}\n\ntype ActionProps = Omit, \"onClick\" | \"type\"> & { onClick?: React.MouseEventHandler };\n\nfunction QuestionnairePrevious({ children, className, variant = \"secondary\", onClick, ...props }: ActionProps) {\n const { order, active, previous } = useQuestionnaire();\n const first = !active || order.indexOf(active) <= 0;\n return (\n {\n onClick?.(event);\n if (!event.defaultPrevented) previous();\n }}\n {...props}\n >\n {children ?? \"Previous\"}\n \n );\n}\n\nfunction QuestionnaireSkip({ children, className, variant = \"ghost\", onClick, ...props }: ActionProps) {\n const { active, configs, order, skip } = useQuestionnaire();\n const required = active ? configs.current.get(active)?.required : true;\n const last = !active || order.indexOf(active) === order.length - 1;\n if (required || last) return null;\n return (\n {\n onClick?.(event);\n if (!event.defaultPrevented) skip();\n }}\n {...props}\n >\n {children ?? \"Skip\"}\n \n );\n}\n\nfunction QuestionnaireNext({ children, className, variant = \"default\", onClick, ...props }: ActionProps) {\n const { order, active, next } = useQuestionnaire();\n if (!active || order.indexOf(active) >= order.length - 1) return null;\n return (\n {\n onClick?.(event);\n if (!event.defaultPrevented) next();\n }}\n {...props}\n >\n {children ?? \"Next\"}\n \n );\n}\n\nfunction QuestionnaireSubmit({ children, className, variant = \"default\", ...props }: Omit, \"type\">) {\n const { order, active } = useQuestionnaire();\n if (!active || order.indexOf(active) !== order.length - 1) return null;\n return (\n \n );\n}\n\nexport {\n Questionnaire,\n QuestionnaireActions,\n QuestionnaireChoice,\n QuestionnaireChoiceDescription,\n QuestionnaireChoices,\n QuestionnaireDescription,\n QuestionnaireError,\n QuestionnaireInput,\n QuestionnaireItem,\n QuestionnaireNext,\n QuestionnairePrevious,\n QuestionnaireProgress,\n QuestionnaireSkip,\n QuestionnaireSubmit,\n QuestionnaireTitle,\n};\n" } ] }