# Read back

An inline receipt for something the agent saved: a record's name, a field, a setting. It shows the value the service read back after the save, not the value that was sent, so it never claims more than the service confirms.

- `pending`: it says it is checking. It never says saved before the read-back arrives. Its sentence may name the value that was sent (`sent`, as `{sent}`), never as saved.
- `saved`: the value as the service read it back, in the app's sentence ("I named it {value}"), marked saved, with an optional action such as Rename. Set it only from the service's read-back. Without a `value`, it says the value read back isn't known rather than showing one.
- `failed`: what is still true ("I couldn’t save the name; it’s still Untitled"), with the service's reason when the app has one. When the app doesn't know the value now, it says that rather than guessing.

Each state has its own icon and words, not a colour alone. Values are drawn as plain text in an isolate (`<bdi>`), with bidi controls marked, since a model may have written them. The sentence sits in one status region for the receipt's life, so a change of state is announced once, politely; nothing is announced when it first appears. The action sits outside the region, and is hidden while pending.

Follows SettlingCard's model: pending, then settled or failed, only on the service's word.

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

## Install

```bash
npx candor-ui@4 add read-back
```

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

## Example

```tsx
"use client"

import * as React from "react"
import { ReadBack, type ReadBackState } from "@/components/candor/read-back"
import { Button } from "@/components/candor/ui/button"

/** `value` is what the service read back after the save, not what was sent. */
export default function Example() {
  const [state, setState] = React.useState<ReadBackState>("pending")
  return (
    <div className="flex max-w-lg flex-col gap-3">
      <ReadBack
        state={state}
        field="name"
        value="Renewal Risk Board"
        previous="Untitled"
        failure="A board with that name already exists."
        messages={{ saved: "I named it {value}", failed: "I couldn’t save the name; it’s still {previous}" }}
        action={{ label: "Rename", onAction: () => {} }}
      />
      <div className="flex gap-2">
        {(["pending", "saved", "failed"] as const).map((s) => (
          <Button key={s} size="xs" variant="outline" aria-pressed={state === s} onClick={() => setState(s)}>
            {s}
          </Button>
        ))}
      </div>
    </div>
  )
}
```

## <ReadBack>

Props:

- `state: ReadBackState`: Where it stands: "pending" until the service reads the value back, "saved" once it has, "failed" if it wasn't saved.
- `field: string`: What was saved, in the app's words, lower case for the middle of a sentence: "name", "stage".
- `value?: string | null | undefined`: The value as the service read it back, not as it was sent. Shown when saved; `null` or "" reads "(empty)", and left out, the receipt says the value read back isn't known. Ignored while pending, so a value sent but not yet read back is never shown as saved: name that one with `sent`.
- `sent?: string | null | undefined`: The value that was sent, for the pending sentence's `{sent}` only ("Renaming it to {sent}…"). Never shown once saved or failed, and never as the saved value.
- `previous?: string | null | undefined`: What the value still is after a failure, as the service last read it. Left out, the failure says the current value isn't known; `null` or "" reads "(empty)".
- `failure?: string | undefined`: Why the save failed, in the service's own words; shown after the failure sentence.
- `messages?: ReadBackMessages | undefined`: The app's own sentences for this receipt, in place of the defaults: `{ saved: "I named it {value}" }`.
- `action?: ReadBackAction | undefined`: A button beside the receipt once it has settled, such as Rename. Hidden while pending.
- `className?: string | undefined`: Classes, merged with Candor's.

## Strings (`readBack`)

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

- `pending`: Checking that the {field} was saved…
- `saved`: The {field} is now {value}
- `savedUnknown`: The {field} was saved, but the value read back isn’t known
- `savedMark`: (saved)
- `failed`: Couldn’t save the {field}; it’s still {previous}
- `failedUnknown`: Couldn’t save the {field}. What it is now isn’t known.
- `reason`: Reason: {reason}
- `empty`: (empty)

## Types

### ReadBackState

Where a saved value stands: sent and not yet read back, read back by the service, or not saved.

```ts
"pending" | "saved" | "failed"
```

### ReadBackMessages

The app's own sentences for one receipt, each with `{field}`, and `{value}` (the read-back) or `{previous}` where they go. `pending` takes `{sent}` instead: the value sent, never the read-back.

```ts
{
  /** In place of "The {field} is now {value}": "I named it {value}". */
  saved?: string | undefined;
  /** In place of "Couldn’t save the {field}; it’s still {previous}": "I couldn’t save the name; it’s still {previous}". */
  failed?: string | undefined;
  /** In place of "Couldn’t save the {field}. What it is now isn’t known.", used when `previous` is left out. */
  failedUnknown?: string | undefined;
  /** In place of "The {field} was saved, but the value read back isn’t known", used when `value` is left out. */
  savedUnknown?: string | undefined;
  /**
   * In place of "Checking that the {field} was saved…". It may hold `{sent}`, the value that was sent and not yet
   * read back ("Renaming it to {sent}…"); `{value}` isn't filled while pending.
   */
  pending?: string | undefined;
}
```

### ReadBackAction

A button beside the receipt, such as Rename, in the app's words.

```ts
{
  /** The button's words: "Rename". */
  label: string;
  /** Called when it's pressed. */
  onAction: () => void;
  /** Why it can't be used right now, if it can't. The button stays and says why. */
  locked?: string | null | undefined;
}
```

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