# Question batch

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.

- Registry name: `question-batch` (`@candor/question-batch`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/question-batch

## Install

```bash
npx candor-ui@4 add question-batch
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/question-batch`.
It brings in: answer-receipt, bidi, button, chat, heading-level, heading-scope, locale, locked, question-card, tokens, undo-window, use-announcer, utils.

## Example

```tsx
"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>

Props:

- `items: readonly QuestionBatchItem[]`: The questions, in the order the agent asked them. Append as it asks more; never reorder.
- `agent: AgentIdentity`: The agent asking, named by the app.
- `onAnswer: (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.
- `current?: string | 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.
- `complete?: boolean | 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.
- `bulkUndo?: QuestionBatchUndo | 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.
- `accept?: string | 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.
- `title?: string | undefined`: The batch's heading, in the app's words. Left out, "Questions from {agent}".
- `className?: string | undefined`
- `headingLevel?: HeadingLevel | undefined`: The level of the batch's heading; each question's sits one below. Defaults to one below the nearest `HeadingScope`, else 2.

## Strings (`questionBatch`)

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

- `title`: Questions 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" }
- `listLabel`: Questions, 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." }
- `firstOpen`: This is the first open question.
- `lastOpenSoFar`: This is the last open question so far.
- `lastOpen`: This is the last open question.
- `toOpen`: Go to the next open question
- `bulkLabel`: Settle 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?" }
- `reviewAcceptIntro`: Each answer is recorded as it reads here, noted as accepted in one step. You can change any of them afterwards.
- `reviewSkipIntro`: Each assumption is recorded as it reads here, noted as skipped in one step. You can change any of them afterwards.
- `answerIs`: Answer: {answer}
- `assumes`: {agent} will assume: {assumption}
- `implication`: That means: {implication}
- `confirmAccept`: { one: "Accept this one", other: "Accept these {count}" }
- `confirmSkip`: { one: "Skip this one", other: "Skip these {count}" }
- `cancel`: Cancel
- `reviewChanged`: The questions changed. Check the list again.
- `reviewSeen`: I’ve checked the list
- `lockedChanged`: The list changed: check it again first.
- `lockedEmpty`: None 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.

```ts
{
  /** 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.

```ts
{
  /** 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

Import: `import type { AgentIdentity } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

```ts
{
  id: string;
  /** The displayed name, e.g. "Architect agent". Never derived from model output. */
  name: string;
  role: AgentRole;
  specialty?: string | undefined;
}
```

### Attachment

Import: `import type { Attachment } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

```ts
{
  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

Import: `import type { HeadingLevel } from "@/lib/candor/heading-level"` (item `heading-level`, https://candor.themethodic.com/docs/heading-level.md)

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.

```ts
1 | 2 | 3 | 4 | 5 | 6
```

### AgentRole

Import: `import type { AgentRole } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).

```ts
string
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
