# Decision row

A decision as one compact row, for a list of what needs the person: a kind tile, the title, a meta line (what it is about, what is paused, how long it has waited, what the agent recommends) and the answers inline on one line, with "Answer differently…" after them opening the app's own flow. Inbox's rows are single buttons, so a row with its own actions is this part, not an Inbox prop; for one decision with its facts, use DecisionCard.

The answers keep the app's order and the same weight, the recommended one marked "Agent’s pick". With `emphasis="recommended"`, the recommended answer leads, first and as the primary button, only when the app says taking it spends nothing (`spends: false`) and it isn't `destructive`; otherwise nothing moves. This is DecisionCard's rule, through the same helpers (`leadingChoice` and `arrangedChoices`). None is focused or pre-selected and no key answers it. A destructive answer is drawn in the destructive tone with the app's words for what can and can't be undone tied to its button, and an answer that ends unfinished work says what. A choice's `detail` isn't drawn in a row: open the decision for it.

The row is a group named by its title, the title its own link (`href`) or button (`onOpen`) and the answers its siblings, never nested in it. In a list, put each row in an `<li>` of the app's `<ul>`. The kind is drawn as an icon in a tile and the kind's word in the meta line, never colour alone.

- Registry name: `decision-row` (`@candor/decision-row`)
- 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/decision-row

## Install

```bash
npx candor-ui@4 add decision-row
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/decision-row`.
It brings in: bidi, button, chat, decision-review, link, locale, locked, relative-time, tokens, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import * as React from "react"
import { CircleDollarSign, KeyRound } from "lucide-react"
import { DecisionRow } from "@/components/candor/decision-row"

const kinds = {
  money: { label: "Spend", icon: CircleDollarSign, tone: "warning" as const },
  access: { label: "Access", icon: KeyRound, tone: "accent" as const },
}
const agent = { id: "builder", name: "Builder", role: "dev" }
const hoursAgo = (h: number) => new Date(Date.now() - h * 3_600_000).toISOString()

/**
 * Two rows in a list. The first answer that spends nothing may lead with emphasis="recommended"; the second row's
 * pick spends, so its answers keep the app's order and the same weight, the pick only marked.
 */
export default function Example() {
  const [answered, setAnswered] = React.useState<Record<string, string>>({})
  const choose = (row: string) => (choice: string) => setAnswered((was) => ({ ...was, [row]: choice }))
  return (
    <ul className="max-w-2xl divide-y rounded-xl border bg-card">
      <li>
        <DecisionRow
          title="Reconnect the test account?"
          href="#reconnect"
          kind="access"
          kinds={kinds}
          subject="Renewal board"
          paused="the deploy"
          since={hoursAgo(1)}
          agent={agent}
          choices={[
            { id: "later", label: "Later" },
            { id: "reconnect", label: "Reconnect…", spends: false },
          ]}
          recommended="reconnect"
          emphasis="recommended"
          pending={answered.access ?? null}
          onChoose={choose("access")}
          onAnswerDifferently={() => {}}
        />
      </li>
      <li>
        <DecisionRow
          title="The build reached its $20 budget"
          href="#budget"
          kind="money"
          kinds={kinds}
          subject="Renewal board"
          paused="the build"
          since={hoursAgo(3)}
          agent={agent}
          choices={[
            { id: "stop", label: "Finish with what’s done", spends: false },
            { id: "raise", label: "Raise to $40", spends: true },
          ]}
          recommended="raise"
          emphasis="recommended"
          pending={answered.money ?? null}
          onChoose={choose("money")}
          onAnswerDifferently={() => {}}
        />
      </li>
    </ul>
  )
}
```

## <DecisionRow>

Props:

- `title: string`: What is to be decided, in the app's words: "Raise the build's budget to $40?". Drawn as text.
- `href?: string | undefined`: Where the title opens the decision, the app's own address. With it, the title is a link.
- `onOpen?: (() => void) | undefined`: Called when the title is pressed, when there is no `href`. With it, the title is a button.
- `kind?: string | undefined`: Which kind of decision it is: a key of `kinds`. A kind with no entry shows this key as it is.
- `kinds?: Readonly<Record<string, DecisionReviewKind>> | undefined`: The app's kinds, by key: each one's word, icon and tone, as DecisionCard's.
- `subject?: string | undefined`: What it is about, in the app's words ("Renewal board"): the meta line's first part.
- `paused?: string | undefined`: What it has paused, in the app's words ("the deploy"), drawn as "Paused: the deploy".
- `since?: string | undefined`: When it was asked, as an ISO time: "Asked 2 hours ago".
- `agent?: AgentIdentity | undefined`: The agent whose pick `recommended` is, named by the app: "{agent} recommends: …".
- `choices: readonly DecisionCardChoice[]`: The answers, in the order to show them. Only a recommended answer that may lead (see `emphasis`) moves first.
- `recommended?: string | undefined`: The id of the agent's recommended answer: marked, named in the meta line, never pre-selected.
- `emphasis?: "equal" | "recommended" | undefined` (default `"equal"`): How the recommended answer is drawn. "equal" (the default): the app's order, every answer with the same weight, the recommended one marked. "recommended": it leads, first and as the primary button, only when it says `spends: false` and isn't `destructive`; otherwise as "equal".
- `onChoose?: ((choiceId: string) => void) | undefined`: Called with the chosen answer's id.
- `onAnswerDifferently?: (() => void) | undefined`: Shows "Answer differently…" after the answers; called when it's pressed. Open the app's own flow from here.
- `pending?: string | null | undefined`: The id of the answer being recorded: its button is busy and every answer is locked until the app clears it.
- `locked?: string | null | undefined`: Why the viewer can't answer here, if they can't; shown on every answer. `null` or left out: unlocked.
- `className?: string | undefined`: Classes, merged with Candor's.

## Strings (`decisionRow`)

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

- `paused`: Paused: {what}
- `since`: Asked {time}
- `recommends`: {agent} recommends: {choice}
- `recommendsUnnamed`: Recommended: {choice}
- `agentsPick`: Agent’s pick
- `answerDifferently`: Answer differently…
- `recording`: Recording your answer
- `undoable`: {choice}: {undoable}
- `ends`: {choice} ends these unfinished: {items}

## 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;
}
```

### 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`.
