Skip to content
Tier

Question card

Pro

One 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.

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-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

TSX · The example above
"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>

PropTypeDefaultDescription
questionrequiredQuestionCardQuestion—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".
agentrequiredAgentIdentity—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.
neededBeforestring | 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".
spendsMoneyboolean | 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.
irreversibleboolean | undefined—Answering can't be undone. A line says so, and the recommendation doesn't lead whatever `emphasis` says.
lateboolean | 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.
settledQuestionCardSettled | 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.
reopenLockedstring | 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.
kindAnswerReceiptKind | 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.
backLockedstring | 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.
nextLockedstring | null | undefined—Why Next can't be used, if it can't ("Answer this question first."). `null` or unset means it can.
classNamestring | undefined—Extra classes for the outer element.
headingLevelHeadingLevel | 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.

KeyEnglish
positionQuestion {number} · {answered} answered
answerLabelYour answer
prefilledFilled in with {agent}’s recommendation. Change it if you like: nothing is sent until you press a button.
useRecommendationUse my recommendation
sendSend answer
lockedEmptyWrite an answer first.
recommends{agent} recommends
spendsAnswering this spends money, so nothing is filled in or chosen for you.
irreversibleAnswering this can’t be undone, so nothing is filled in or chosen for you.
spendsIrreversibleAnswering this spends money and can’t be undone, so nothing is filled in or chosen for you.
skipSkip, and I’ll assume: {assumption}
implicationThat means: {implication}
neededBeforeNeeded before {before}
neededNeeded 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.
lateNoteAnswered after {agent} had gone ahead
backBack
nextNext

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