Skip to content
Tier

Question batch

Pro

A batch of questions an agent asks as it works, shown one at a time, that grows as earlier answers land. Pass items in the order asked and append as the agent asks more. Each settled question is drawn as its receipt in its place, keyed by id, so a receipt never moves as the batch grows; Change reopens a question where it sits. The open question shown is a QuestionCard; the other open ones aren't drawn, but are counted, and Back and Next move among them. A question that arrives never moves focus or changes the question shown; a screen reader hears one polite announcement for questions that arrive close together: "Planning agent asked 2 more questions. 6 open."

Under the heading, the counts come from items: "8 asked so far · 2 answered · 6 open". Each card's position reads "Question 3 of the 8 asked so far" until the app says the agent has asked everything (complete), then "Question 3 of 8". With nothing open, a line says the agent may ask more as it works; only with complete does it say every question is settled. Before the first question arrives, only the heading is drawn. The kit never predicts how many questions there will be.

With onAcceptRecommended or onSkipAssumed, the person can settle several questions in one step: "Accept 4 recommendations", "Skip 3 and use their assumptions". Each takes only open questions the app says spend no money and can be undone (spendsMoney: false and irreversible: false, each said outright), never one where either isn't stated, that the agent has gone ahead on, or that the person has started answering with a file, and says in words how many it leaves and why. Neither is ever the primary action or focused. Pressing one opens a review that lists every question it covers, with the answer, or the assumption and what it means, that will be recorded; focus moves to the review's heading. If a listed question changes or settles, or a new one arrives, the list is redrawn, says so, and its confirm is locked until the person says they have checked it. Confirm calls back with exactly the ids listed. Record each as its own receipt with bulk: a recommendation accepted this way is an answer, a skip an assumption, and every receipt keeps Change. Once every question in the step is recorded so, a screen reader hears "2 answers accepted."; a step recorded otherwise, or only in part, isn't said. When your server can undo the whole step, pass bulkUndo for an UndoWindow; the kit claims no undo your server can't make.

The questions, recommendations, assumptions and the app's title are drawn as text.

Markdown

Preview

Loading the preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/question-batch

Brings in: answer-receipt, bidi, button, chat, heading-level, heading-scope, locale, locked, question-card, tokens, undo-window, use-announcer, utils

Usage

TSX · The example above
"use client"

import * as React from "react"
import type { AgentIdentity } from "@/lib/candor/chat"
import { QuestionBatch, type QuestionBatchItem, type QuestionBatchUndo } from "@/components/candor/question-batch"
import type { QuestionCardSettled } from "@/components/candor/question-card"

const agent: AgentIdentity = { id: "a-launch", name: "Launch agent", role: "planner" }
const dana = { kind: "person" as const, name: "Dana Reyes" }

// The questions the agent asks, and the ones it asks once earlier answers land. Your app says what each answer
// costs: `spendsMoney: false` with `irreversible: false`, each said outright, lets a question be settled in one step
// with others.
const first: QuestionBatchItem[] = [
  {
    id: "regions",
    question: {
      text: "Which regions does the launch cover?",
      recommended: "North America and the UK",
      assumption: "North America only",
      implication: "The UK page and its pricing wait for a later launch.",
    },
    spendsMoney: false,
    irreversible: false,
  },
  {
    id: "budget",
    question: { text: "How much can the launch ads spend in the first month?", recommended: "$4,000", why: "The ad accounts need a monthly cap before they go live." },
    // Answering spends money: never settled in one step, and nothing is filled in.
    spendsMoney: true,
    neededBefore: "the ads go live",
  },
  {
    id: "guide",
    question: { text: "Is there a brand guide the copy must follow?", recommended: "", assumption: "No brand guide", implication: "The copy follows the current site’s voice." },
    spendsMoney: false,
    irreversible: false,
  },
]
// Asked after the first answer lands.
const later: QuestionBatchItem[] = [
  {
    id: "email",
    question: { text: "Should the launch email go to trial users?", recommended: "Yes, as a separate send", assumption: "Customers only", implication: "Trial users hear about it in the product." },
    spendsMoney: false,
    irreversible: false,
  },
  {
    id: "date",
    question: { text: "Which day should the pages go live?", recommended: "Tuesday 1 December", assumption: "Tuesday 1 December", implication: "The pages publish at 9:00 that morning." },
    spendsMoney: false,
    irreversible: false,
  },
]

export default function Example() {
  const [items, setItems] = React.useState(first)
  const [complete, setComplete] = React.useState(false)
  const [undo, setUndo] = React.useState<QuestionBatchUndo | undefined>(undefined)
  const settle = (ids: readonly string[], record: (item: QuestionBatchItem) => QuestionCardSettled | undefined) =>
    setItems((all) => all.map((item) => (ids.includes(item.id) ? { ...item, settled: record(item) } : item)))
  // Stands in for the agent: it asks two more once the first answer lands, then says it has asked everything.
  const agentReads = () => {
    if (items.length > first.length) return
    window.setTimeout(() => setItems((all) => [...all, ...later]), 800)
    window.setTimeout(() => setComplete(true), 4000)
  }

  return (
    <div className="flex max-w-xl flex-col gap-6">
      <QuestionBatch
        agent={agent}
        items={items}
        // Leave it out while the agent may ask more: positions read "of the 3 asked so far", never a predicted total.
        complete={complete}
        onAnswer={(id, answer, info) => {
          settle([id], () => ({ kind: "answered", answer, files: info.files, edited: info.edited, by: dana, at: new Date() }))
          agentReads()
        }}
        onSkip={(id) => {
          settle([id], () => ({ kind: "skipped", by: dana, at: new Date() }))
          agentReads()
        }}
        // Change clears the record, and the question opens again in its place.
        onReopen={(id) => settle([id], () => undefined)}
        // Opt-in: the person reviews every answer before it is recorded. A recommendation accepted this way is an
        // answer; `bulk` is how many the step settled, and each receipt says so.
        onAcceptRecommended={(ids) => {
          settle(ids, (item) => ({ kind: "answered", answer: item.question.recommended, bulk: ids.length, by: dana, at: new Date() }))
          // Your server says whether, and for how long, it can undo the step as one.
          setUndo({
            id: crypto.randomUUID(),
            act: "accepted",
            count: ids.length,
            seconds: 30,
            onUndo: async () => settle(ids, () => undefined),
            onClose: () => setUndo(undefined),
          })
          agentReads()
        }}
        onSkipAssumed={(ids) => {
          settle(ids, () => ({ kind: "skipped", bulk: ids.length, by: dana, at: new Date() }))
          setUndo(undefined)
          agentReads()
        }}
        bulkUndo={undo}
      />
    </div>
  )
}

<QuestionBatch>

PropTypeDefaultDescription
itemsrequiredreadonly QuestionBatchItem[]—The questions, in the order the agent asked them. Append as it asks more; never reorder.
agentrequiredAgentIdentity—The agent asking, named by the app.
onAnswerrequired(id: string, answer: string, info: QuestionCardAnswerInfo) => void—Called with a question's id and its answer, as QuestionCard's `onAnswer`. Pass the question's `settled` once recorded.
onSkip((id: string) => void) | undefined—Shows the skip on questions with both an assumption and what it means; called with the question's id.
onReopen((id: string) => void) | undefined—Shows Change on each receipt; called with the question's id. Clear its `settled` to reopen it in its place.
currentstring | undefined—The id of the open question shown. Left out, the batch keeps its own: the first open question, then, as each is settled, the next open one after it. If you pass it, pass the ids `onCurrentChange` gives you.
onCurrentChange((id: string) => void) | undefined—Called with the id of the question shown when it changes: the first one shown, Back, Next, Change, or the next open one after a question settles.
completeboolean | undefined—The app says the agent has asked everything: counts read "of 8" in place of "of the 8 asked so far".
onAcceptRecommended((ids: string[]) => void) | undefined—Offers to accept, in one step, the recommendation of every open question your app says spends no money and can be undone (`spendsMoney: false`, `irreversible: false`), after a review that lists each answer. Called with exactly the ids listed.
onSkipAssumed((ids: string[]) => void) | undefined—Offers to skip, in one step, every open question that has an assumption and what it means and that your app says spends no money and can be undone (`spendsMoney: false`, `irreversible: false`), after a review that lists each assumption. Called with exactly the ids listed.
bulkUndoQuestionBatchUndo | undefined—After a step that settled several questions, when your server can undo it as one: drawn as an UndoWindow.
onAttach((id: string, files: File[]) => void) | undefined—Lets files be (part of) an answer, as QuestionCard's `onAttach`; called with the question's id and the files.
onRemoveAttachment((id: string, fileId: string) => void) | undefined—Shows a remove button on each file; called with the question's id and the file's id.
acceptstring | undefined—Which files the picker offers, as for `<input accept>`.
onOpenFile((file: Attachment) => void) | undefined—Makes each file on a receipt a button; called with the file.
titlestring | undefined—The batch's heading, in the app's words. Left out, "Questions from {agent}".
classNamestring | undefined—Extra classes for the outer element.
headingLevelHeadingLevel | undefined—The level of the batch's heading; each question's sits one below. Defaults to one below the nearest `HeadingScope`, else 2.

Strings

The fixed words, in English by default. Change any of them under questionBatch in <LocaleProvider strings={{ … }}>; the table is exported as questionBatchStrings.

KeyEnglish
titleQuestions from {agent}
askedSoFar{ one: "{count} asked so far", other: "{count} asked so far" }
questions{ one: "{count} question", other: "{count} questions" }
answered{ one: "{count} answered", other: "{count} answered" }
open{ one: "{count} open", other: "{count} open" }
listLabelQuestions, in the order asked
mayAskMore{agent} may ask more as it works.
allSettled{ one: "The {count} question is settled.", other: "All {count} questions are settled." }
added{ one: "{agent} asked {count} more question. {open} open.", other: "{agent} asked {count} more questions. {open} open." }
firstOpenThis is the first open question.
lastOpenSoFarThis is the last open question so far.
lastOpenThis is the last open question.
toOpenGo to the next open question
bulkLabelSettle several in one step
acceptRecommended{ one: "Accept {count} recommendation", other: "Accept {count} recommendations" }
skipAssumed{ one: "Skip {count} and use its assumption", other: "Skip {count} and use their assumptions" }
leftFor{ one: "Leaves {count} question for you to settle yourself:", other: "Leaves {count} questions for you to settle yourself:" }
reasonStakes{ one: "{count} spends money, can’t be undone, or doesn’t say", other: "{count} spend money, can’t be undone, or don’t say" }
reasonNoRecommendation{ one: "{count} has no recommendation", other: "{count} have no recommendation" }
reasonNotSkippable{ one: "{count} can’t be skipped", other: "{count} can’t be skipped" }
reasonHasFiles{ one: "{count} has a file you attached", other: "{count} have files you attached" }
reasonLate{ one: "{agent} has already gone ahead on {count}", other: "{agent} has already gone ahead on {count}" }
reviewAccept{ one: "Accept this recommendation?", other: "Accept these {count} recommendations?" }
reviewSkip{ one: "Skip this question and use its assumption?", other: "Skip these {count} questions and use their assumptions?" }
reviewAcceptIntroEach answer is recorded as it reads here, noted as accepted in one step. You can change any of them afterwards.
reviewSkipIntroEach assumption is recorded as it reads here, noted as skipped in one step. You can change any of them afterwards.
answerIsAnswer: {answer}
assumes{agent} will assume: {assumption}
implicationThat means: {implication}
confirmAccept{ one: "Accept this one", other: "Accept these {count}" }
confirmSkip{ one: "Skip this one", other: "Skip these {count}" }
cancelCancel
reviewChangedThe questions changed. Check the list again.
reviewSeenI’ve checked the list
lockedChangedThe list changed: check it again first.
lockedEmptyNone of these can be settled in one step now.
accepted{ one: "{count} answer accepted.", other: "{count} answers accepted." }
skipped{ one: "{count} question skipped.", other: "{count} questions skipped." }
undoAccepted{ one: "Accepted {count} recommendation", other: "Accepted {count} recommendations" }
undoSkipped{ one: "Skipped {count} question", other: "Skipped {count} questions" }

Types

QuestionBatchItem
One question in the batch, with what the app knows about it.
{ /** The app's id for the question: the list is keyed by it, so a receipt stays where it is as the batch grows. */ id: string; /** The question: `{ text, recommended, assumption?, implication?, why? }`, the agent's words. */ question: QuestionCardQuestion; /** * The kind of question, in the app's words: a tag beside the heading while open, and the receipt's label once * settled. */ kind?: AnswerReceiptKind | undefined; /** * Whether answering spends money. `false` lets `emphasis="recommended"` lead and, with `irreversible: false`, lets * the question be settled in one step with others. Left out, it isn't known, and neither happens. */ spendsMoney?: boolean | undefined; /** * Whether answering can't be undone. `true`: the recommendation doesn't lead. Only `false`, said outright, lets the * question be settled in one step with others; left out, it isn't known, and the question is left for the person. */ irreversible?: boolean | undefined; /** * As QuestionCard's `emphasis`: "recommended" fills in the recommendation only when it spends nothing and can be * undone. */ emphasis?: "equal" | "recommended" | undefined; /** For a question that can't be skipped: the app's words for what it is needed before ("the contract"). */ neededBefore?: string | undefined; /** * The agent has gone ahead without an answer. The card says so, and the question is never settled in one step with * others. */ late?: boolean | undefined; /** * The question is settled, as your app recorded it: drawn as its receipt, in its place. For a recommendation accepted * with others in one step, record `{ kind: "answered", answer: question.recommended, bulk }`; for a question skipped * with others, `{ kind: "skipped", bulk }`, where `bulk` is how many the step settled. */ settled?: QuestionCardSettled | undefined; /** Why the answer can't be changed any more, if it can't: Change stays, locked, and says so. */ reopenLocked?: string | null | undefined; /** * Files attached to this question's answer, as your app tracks them (QuestionCard's `attachments`). A question with * any is never settled in one step with others: the person has started an answer of their own. */ attachments?: readonly Attachment[] | undefined; }
QuestionBatchUndo
A step that settled several questions, which your server can undo as one for a while: drawn as an UndoWindow.
{ /** The app's id for the step: a new id starts a new window. */ id: string; /** What the step did: accepted recommendations, or skipped questions. */ act: "accepted" | "skipped"; /** How many questions it settled. */ count: number; /** When the window closes, as an ISO timestamp from your server. */ until?: string | undefined; /** How many seconds your server granted, counted from when the notice appears. */ seconds?: number | undefined; /** Undoes the whole step. Clear the questions' `settled` once it has. */ onUndo: () => Promise<void>; /** Called once, when the window closes without an undo. */ onClose?: (() => void) | undefined; }

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

AgentIdentity from @/lib/candor/chat
{ id: string; /** The displayed name, e.g. "Architect agent". Never derived from model output. */ name: string; role: AgentRole; specialty?: string | undefined; }
Attachment from @/lib/candor/chat
{ id: string; name: string; /** In bytes. */ size?: number | undefined; /** e.g. "image/png", "application/pdf": picks the icon, and allows an image preview. */ mediaType?: string | undefined; /** A thumbnail your app serves (or a blob: URL), shown for images. Never a URL from model output. */ previewUrl?: string | undefined; /** 0–1 while uploading; absent when done. */ progress?: number | undefined; error?: string | undefined; }
HeadingLevel from @/lib/candor/heading-level
A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.
1 | 2 | 3 | 4 | 5 | 6
AgentRole from @/lib/candor/chat
What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).
string