Question card
ProOne question from the agent, in the thread: "Question 3 · 2 answered" (no total), the question, and an answer field. Back and Next revisit answered questions through the app.
By default nothing is filled in or chosen: the agent's recommendation is shown first, marked as the agent's, with its own "Use my recommendation" button, and the empty field and "Send answer" sit under it with the same weight. With emphasis="recommended", and only when the app also says answering spends no money (spendsMoney={false}) and can be undone, the field starts filled in with the recommendation and "Use my recommendation" is the primary action; once the person edits the field, the action reads "Send answer" and sends their words. Left out, whether it spends money isn't known, so the recommendation doesn't lead. When the app marks the question as spending money or as something that can't be undone (irreversible), a line says so. Nothing is ever sent without a press.
In the field, a bidi control in the agent's words shows as its escape (\u202E), and is sent as the character it stands for, so an edited recommendation keeps the agent's characters.
When the question has both an assumption and an implication, it can be skipped: "Skip, and I’ll assume: …", with "That means: …" under it, so the person knows exactly what will be assumed. Otherwise it reads "Needed before …", with the app's words (neededBefore), and offers no skip.
Once the app passes settled, the card collapses to an AnswerReceipt: the answer, or the assumption for a skip. Its Change calls onReopen. With Back or Next, the count and the two buttons stay above the receipt, so the person can move on from a question they came back to. With late, the card is still open after the agent went ahead without an answer, and says so. The question, the recommendation and the assumption are the agent's words, drawn as text.
When the question changes (Back, Next, a new one) or the card settles or reopens, and focus was in it, focus goes to the heading of what is shown now.
Preview
Loading the preview
Install
First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/question-card
Brings in: agent-avatar, answer-receipt, bidi, button, chat, heading-level, heading-scope, locale, locked, textarea, tokens, use-focus-within, work, utils · npm: lucide-react@^1.67.0
Usage
"use client"
import * as React from "react"
import type { AgentIdentity } from "@/lib/candor/chat"
import { QuestionCard, type QuestionCardQuestion, type QuestionCardSettled } from "@/components/candor/question-card"
const agent: AgentIdentity = { id: "a-plan", name: "Planning agent", role: "planner" }
// Your app says what each answer costs: `spendsMoney: false` with `emphasis: "recommended"` lets the recommendation
// lead (filled in, and the primary action). Left out, the card gives every choice the same weight.
const questions: (QuestionCardQuestion & { spendsMoney?: boolean; emphasis?: "equal" | "recommended" })[] = [
{
text: "How often should customers be billed?",
recommended: "Monthly, on the first of the month.",
assumption: "Monthly billing",
implication: "Customers are charged on the first of each month.",
emphasis: "recommended",
spendsMoney: false,
},
// No assumption: it can't be skipped, so the card says what it is needed before. Nothing said about cost: equal weight.
{ text: "Which company name goes on the invoices?", recommended: "Northwind Trading Ltd" },
// Answering buys something: nothing is filled in, and a line says it spends money.
{ text: "Which plan should the team start on?", recommended: "Team, at $40 a month", spendsMoney: true },
]
export default function Example() {
// One card in the thread, moved between questions with Back and Next. A settled question shows its receipt; Change
// reopens it.
const [at, setAt] = React.useState(0)
const [settled, setSettled] = React.useState<Record<number, QuestionCardSettled>>({})
const answered = Object.keys(settled).length
const settle = (s: QuestionCardSettled) => setSettled((all) => ({ ...all, [at]: s }))
const { spendsMoney, emphasis, ...question } = questions[at]!
const last = at === questions.length - 1
return (
<div className="max-w-xl">
<QuestionCard
agent={agent}
question={question}
position={{ number: at + 1, answered }}
emphasis={emphasis}
spendsMoney={spendsMoney}
neededBefore="the first invoice"
settled={settled[at]}
onAnswer={(answer) => settle({ kind: "answered", answer, by: { kind: "person", name: "Dana Reyes" }, at: new Date() })}
onSkip={() => settle({ kind: "skipped", by: { kind: "person", name: "Dana Reyes" }, at: new Date() })}
onReopen={() =>
setSettled((all) => {
const rest = { ...all }
delete rest[at]
return rest
})
}
onBack={() => setAt(at - 1)}
backLocked={at === 0 ? "This is the first question." : null}
onNext={() => setAt(at + 1)}
nextLocked={last ? "This is the last question so far." : settled[at] ? null : "Answer or skip this question first."}
/>
</div>
)
}<QuestionCard>
| Prop | Type | Default | Description |
|---|---|---|---|
| questionrequired | QuestionCardQuestion | — | The question: `{ text, recommended, assumption?, implication? }`, the agent's words. |
| positionrequired | { number: number; answered: number } | — | Where it sits: its `number`, and how many questions are `answered` so far. Drawn as "Question 3 · 2 answered". |
| agentrequired | AgentIdentity | — | The agent asking, named by the app. |
| onAnswerrequired | (answer: string, info: QuestionCardAnswerInfo) => void | — | Called with the answer when the person presses "Use my recommendation" or "Send answer", never before. For the recommendation unchanged, the text is `question.recommended` exactly and `recommended` is true. Pass `settled` once the answer is recorded. |
| onSkip | (() => void) | undefined | — | Shows the skip, when the question has both `assumption` and `implication`; called when it's pressed. |
| neededBefore | string | undefined | — | For a question that can't be skipped: the app's words for what it is needed before ("the contract"). Shown as "Needed before the contract". |
| emphasis | "equal" | "recommended" | undefined | "equal" | "equal" (the default): nothing is filled in, and the recommendation, shown first, has the same weight as writing an answer. "recommended": the field starts filled in with the recommendation and "Use my recommendation" is the primary action, only when `spendsMoney` is `false` and `irreversible` isn't `true`; otherwise it is drawn as "equal". |
| spendsMoney | boolean | undefined | — | Whether answering spends money. `true` adds a line saying so; `false` lets `emphasis="recommended"` lead with the recommendation. Left out, it isn't known, and the recommendation doesn't lead. |
| irreversible | boolean | undefined | — | Answering can't be undone. A line says so, and the recommendation doesn't lead whatever `emphasis` says. |
| late | boolean | undefined | — | The agent has gone ahead without an answer (on the assumption, if there is one). The card stays open for a late answer and says so; there is no skip. |
| settled | QuestionCardSettled | undefined | — | The question is settled: the card collapses to an AnswerReceipt with the answer, or the assumption for a skip. |
| onReopen | (() => void) | undefined | — | Shows Change on the receipt; called when it's pressed. Clear `settled` from here to reopen the card. |
| reopenLocked | string | null | undefined | — | Why the answer can't be changed any more, if it can't: Change stays, locked, and says so. `null` or unset means it can. |
| kind | AnswerReceiptKind | undefined | — | The receipt's kind label once settled, in the app's words ("Question"). Left out, no label. |
| onBack | (() => void) | undefined | — | Shows Back, to the question before; called when it's pressed. |
| backLocked | string | null | undefined | — | Why Back can't be used, if it can't. `null` or unset means it can. |
| onNext | (() => void) | undefined | — | Shows Next, to the question after; called when it's pressed. |
| nextLocked | string | null | undefined | — | Why Next can't be used, if it can't ("Answer this question first."). `null` or unset means it can. |
| className | string | undefined | — | Extra classes for the outer element. |
| headingLevel | HeadingLevel | undefined | — | The level of the card's heading, and the receipt's. Defaults to one below the nearest `HeadingScope`, else 2. |
Strings
The fixed words, in English by default. Change any of them under questionCard in <LocaleProvider strings={{ … }}>; the table is exported as questionCardStrings.
| Key | English |
|---|---|
| position | Question {number} · {answered} answered |
| answerLabel | Your answer |
| prefilled | Filled in with {agent}’s recommendation. Change it if you like: nothing is sent until you press a button. |
| useRecommendation | Use my recommendation |
| send | Send answer |
| lockedEmpty | Write an answer first. |
| recommends | {agent} recommends |
| spends | Answering this spends money, so nothing is filled in or chosen for you. |
| irreversible | Answering this can’t be undone, so nothing is filled in or chosen for you. |
| spendsIrreversible | Answering this spends money and can’t be undone, so nothing is filled in or chosen for you. |
| skip | Skip, and I’ll assume: {assumption} |
| implication | That means: {implication} |
| neededBefore | Needed before {before} |
| needed | Needed before {agent} can go on |
| lateAssumed | {agent} has gone ahead, assuming: {assumption}. You can still answer. |
| late | {agent} has gone ahead without an answer. You can still answer. |
| lateNote | Answered after {agent} had gone ahead |
| back | Back |
| next | Next |
Types
- QuestionCardQuestion
- One question, as the agent asks it.
{ /** The question, in the agent's words. Shown as text. */ text: string; /** The answer the agent recommends, in its words. Empty when it has none. */ recommended: string; /** What the agent will assume if the person skips: "Monthly billing". With `implication`, the question can be skipped. */ assumption?: string | undefined; /** What the assumption means: "Customers are charged on the first of each month." With `assumption`, the question can be skipped. */ implication?: string | undefined; }- QuestionCardSettled
- A question that has been settled: answered, or skipped so the agent's assumption stands.
{ kind: "answered"; /** The answer that was sent. */ answer: string; /** Who answered, from the app. Left out, the receipt names nobody. */ by?: Actor | undefined; /** When. Left out, the receipt shows no time. */ at?: Date | string | undefined; /** The answer came after the agent had gone ahead: the receipt says so. */ late?: boolean | undefined; /** Notes in the app's words, under the receipt: "Replaced in round 2". */ notes?: readonly string[] | undefined; } | { kind: "skipped"; /** Who skipped, from the app. Left out, the receipt names nobody. */ by?: Actor | undefined; /** When. Left out, the receipt shows no time. */ at?: Date | string | undefined; /** Notes in the app's words, under the receipt. */ notes?: readonly string[] | undefined; }- QuestionCardAnswerInfo
- How an answer was given: `recommended` is true when it is the agent's recommendation, unchanged.
{ recommended: boolean }
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; }- 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- Actor from @/lib/candor/work
- Who did something: an agent, named by the app, or a person. An agent is the identity the app gives it (its name is the app's, never the model's); a person is the name the app gives them. Digest, DigestEmail, ChangeList, DecisionReview and the approval items all take it.
{ kind: "agent"; agent: AgentIdentity } | { kind: "person"; name: string }- AgentRole from @/lib/candor/chat
- What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).
string