# Acceptance list

What the work said it would do, and how each was checked: a list of criteria, each met, not met, not delivered or not checked yet (AcceptanceItem). By default they are grouped under a heading for each status, with how many are in it: not met first, then not delivered, not checked yet and met. Under the list's heading, how many are met of all of them.

A criterion shows as met, in green, only when the app reports the check passed, and always says how it was checked and who checked it, with the evidence; the type requires all three. A check by reading is the checker's judgement and says so. The app's own nouns for a criterion ("promise", "requirement") go in LocaleProvider's strings.

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

## Install

```bash
npx candor-ui@4 add acceptance-list
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/acceptance-list`.
It brings in: agent-avatar, bidi, button, chat, evidence-image, heading-level, heading-scope, link, locale, tokens, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { AcceptanceList, type AcceptanceCriterion } from "@/components/candor/acceptance-list"
import { Button } from "@/components/candor/ui/button"

const checker = { id: "check", name: "Checking agent", role: "reviewer" }

/*
 * What the work said it would do, and how each was checked. Met only where the app reports the check passed, with the
 * method, the checker and the evidence; the read check says it was read, not run. Screenshots are the app's own copies.
 */
const criteria: AcceptanceCriterion[] = [
  {
    id: "inbox",
    status: "met",
    text: "Requests wait in the inbox until a person answers them.",
    method: { kind: "ran", label: "by running it in the test copy" },
    checker: { agent: checker },
    what: "Sent a request and saw it wait in the inbox.",
    evidence: [
      {
        kind: "screenshot",
        image: { id: "inbox", src: "/examples/screenshots/approvals-inbox-light-desktop.jpg", alt: "The approvals inbox with the request waiting", shows: "The request waits, unanswered.", describedBy: checker, signedInAs: "Dana Whitfield", where: "The test copy" },
      },
      { kind: "log", id: "log", label: "Run log, 14:03", href: "#run-log" },
    ],
    steps: ["Sign in as Dana Whitfield.", "Start a run that needs an approval.", "Open the inbox."],
  },
  {
    id: "words",
    status: "met",
    text: "The approval names what it changes.",
    method: { kind: "read" },
    checker: { agent: checker },
    what: "Read the request; it names the record and the field.",
    evidence: [{ kind: "quote", id: "quote", label: "The request’s summary", onOpen: () => {} }],
  },
  {
    id: "email",
    status: "notMet",
    text: "Approving sends the requester an email.",
    reason: "No email arrived in the test inbox within five minutes.",
    method: { kind: "test", label: "by the email test" },
    checker: { agent: checker },
    wouldProve: "An email in the test inbox within a minute of approving.",
    checkYourself: ["Approve a request in the test copy.", "Open the test inbox."],
    action: (
      <Button size="sm" variant="outline">
        Ask for a fix
      </Button>
    ),
  },
  { id: "export", status: "notDelivered", text: "Export the inbox to a spreadsheet.", reason: "Left out of this round, as agreed." },
  { id: "phone", status: "unchecked", text: "The inbox works on a phone." },
]

export default function Example() {
  return <AcceptanceList criteria={criteria} title="What the work said it would do" className="max-w-2xl" />
}
```

## <AcceptanceList>

Props:

- `criteria: AcceptanceCriterion[]`: The criteria, in the app's order (kept within each group).
- `title?: string | undefined`: The heading, in the app's words. Defaults to the `title` string, "Acceptance criteria".
- `grouped?: boolean | undefined` (default `true`): Group the criteria under a heading for each status. Defaults to true; false keeps one numbered list in the app's order.
- `headingLevel?: HeadingLevel | undefined`: The level of the heading. Defaults to one below the nearest `HeadingScope`, else 2; the group headings sit one below it.
- `className?: string | undefined`: Classes for the list, merged with Candor's.

## <AcceptanceItem>

One criterion: what the work said it would do and how it stands, said as an icon and a word, never colour alone.

- Met, in green, only as the app reports a passed check, with how it was checked ("Met by running it"), who checked it and the evidence. Given as met without a method the kit knows, a named checker or evidence it can draw, it shows as not checked yet, without the checker's account.
- Checked by reading it, met or not, it adds that it was read and not run: the checker's judgement.
- Not met, in red, with the reason in its details.
- Not delivered, in a dark neutral: it isn't an error.
- Not checked yet, muted.

Each piece of evidence says its kind (screenshot, log, quote, file): a screenshot is an EvidenceImage, whose lightbox walks the criterion's screenshots; the others open through the app's link or its `onOpen`. The checker's one-line account is drawn as their words, with their name. "Details" shows the check as plain steps, the reason, what would prove it, how to check it yourself and the app's next-round action. The work's and the checker's words are drawn as text, never as HTML or a link.

Props:

- `criterion: AcceptanceCriterion`: The criterion, its status and how it was checked.
- `className?: string | undefined`: Classes for the item, merged with Candor's.

## Functions

### shownStatus

```ts
shownStatus(c: AcceptanceCriterion)
```

The status a criterion is drawn with. A `met` is drawn as met only with a method the kit knows (a run, a test or a read), a checker who is named, and at least one piece of evidence it can draw; without them, as data from JSON can be, it is drawn as not checked yet.

## Strings (`acceptanceList`)

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

- `title`: Acceptance criteria
- `summary`: {met} of {total} met
- `met`: Met {method}
- `notMet`: Not met
- `notDelivered`: Not delivered
- `unchecked`: Not checked yet
- `groupMet`: Met ({count})
- `groupNotMet`: Not met ({count})
- `groupNotDelivered`: Not delivered ({count})
- `groupUnchecked`: Not checked yet ({count})
- `methodRan`: by running it
- `methodTest`: by a test
- `methodRead`: by reading it
- `readNote`: Read, not run: this is the checker’s judgement.
- `checkedHow`: Checked {method}
- `checkedBy`: Checked by {checker}
- `what`: {checker}: {what}
- `evidence`: Evidence
- `screenshot`: Screenshot
- `log`: Log
- `quote`: Quote
- `file`: File
- `showDetails`: Details
- `hideDetails`: Hide details
- `steps`: How it was checked
- `reasonNotMet`: Why it isn’t met
- `reasonNotDelivered`: Why it wasn’t delivered
- `wouldProve`: What would prove it
- `checkYourself`: How to check it yourself
- `none`: No criteria.

## Types

### AcceptanceStatus

Where a criterion stands: met (the app reports the check passed), not met, not delivered, or not checked yet.

```ts
"met" | "notMet" | "notDelivered" | "unchecked"
```

### AcceptanceMethod

How a criterion was checked. A run or a test may carry the app's own words for it ("by running it in the test copy"); a read never does. Reading it is the checker's judgement, so it is always said as "by reading it", with a note that it was read and not run.

```ts
{
  /** The work was run and watched. */
  kind: "ran";
  /** How, in the app's words after "Met": "by running it in the test copy". Defaults to "by running it". */
  label?: string | undefined;
} | {
  /** A test passed. */
  kind: "test";
  /** How, in the app's words after "Met": "by the sign-in test". Defaults to "by a test". */
  label?: string | undefined;
} | {
  /** The checker read the work and judged it. */
  kind: "read";
  /** A read takes no words of its own: it is always "by reading it", so it can't read as a run. */
  label?: undefined;
}
```

### AcceptanceChecker

Who checked a criterion, named by the app: an agent or a person.

```ts
{ agent: AgentIdentity } | { person: string }
```

### AcceptanceEvidence

One piece of evidence for a criterion. A screenshot is the app's image; the others open through the app.

```ts
{
  kind: "screenshot";
  /** The app's image, drawn as an EvidenceImage: its own stored copy, never an address from model output. */
  image: EvidenceImageData;
} | {
  kind: "log" | "quote" | "file";
  /** Stable within the criterion. */
  id: string;
  /** What it is, in the app's words: "Run log, 14:03", "error.txt". */
  label: string;
  /** An address in the app to open it at, drawn through the app's link (LinkProvider). Never an address from model output. */
  href?: string | undefined;
  /** Called to open it, when it opens in place rather than at an address. */
  onOpen?: (() => void) | undefined;
}
```

### AcceptanceCriterion

One criterion and how it stands. `met` needs how it was checked (`method`), who checked it (`checker`) and at least one piece of `evidence`: set it only when the app reports the check passed. Drawn without them, it shows as not checked yet. `notMet` needs the `reason`.

```ts
AcceptanceBase & ({
  status: "met";
  /** How it was checked. */
  method: AcceptanceMethod;
  /** Who checked it. */
  checker: AcceptanceChecker;
  /** What shows it, at least one. */
  evidence: [
    AcceptanceEvidence,
    ...AcceptanceEvidence[]
  ];
  reason?: undefined;
} | {
  status: "notMet";
  /** Why it isn't met, shown in the details. */
  reason: string;
  /** How it was checked, if it was. */
  method?: AcceptanceMethod | undefined;
  /** Who checked it, if anyone did. */
  checker?: AcceptanceChecker | undefined;
  /** What shows it isn't met. */
  evidence?: AcceptanceEvidence[] | undefined;
} | {
  status: "notDelivered";
  /** Why it wasn't delivered, shown in the details. */
  reason?: string | undefined;
  method?: undefined;
  checker?: undefined;
  evidence?: AcceptanceEvidence[] | undefined;
} | {
  status: "unchecked";
  reason?: undefined;
  method?: undefined;
  checker?: undefined;
  evidence?: AcceptanceEvidence[] | undefined;
})
```

## Types from other items

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

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

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

## Motion

- **tint** (tint): A piece of evidence that opens has its border darken when the pointer is over it.

Set with `--cd-motion-acceptance-list-<moment>-*` in your brand file; the families are in the design reference.

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