# Status Text

> Status as colored text with no background, with an optional quickest fix and a peek behind it.

- Name: `status-text`
- Status: beta
- Categories: data, display
- File: the install writes `status-text.tsx` to your `ui` alias, `@/components/ui` by default.
- Other registry items: `@arbokui/motion`, `@arbokui/hover-card`, `@arbokui/peek-card`, `@arbokui/tool-button`, `@arbokui/tooltip`. The install adds them.
- Gallery: https://arbokui.com/components/status-text
- Registry item: https://arbokui.com/r/status-text.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/status-text
   ```

## Use it for

- Drawing a status anywhere: rows, tables, receipts, files, and sync lines. Status is colored text, not a chip.
- Map your own statuses to a tone, like ok → success, warn → warning, bad → danger, info → brand, muted → neutral, overdue → danger. Overdue shares danger's red, so its word, Overdue, must always show.
- fix ends the status with its quickest fix as an icon in the same color, named in its tooltip: Couldn't save, then a retry arrow.
- Give fix a result, like { label: 'Reminded' }. The icon slips to a check and its tooltip says so. With onUndo, coming back shows Undo for 8 seconds, and ⌘Z undoes it too. Send the change in onCommit.
- Return a promise from onClick, and give the result failed words. The fix waits while it runs, and turns into a red Retry arrow if it fails.
- detail opens the story behind the status on hover, focus, or tap. Pass PeekCard props, or a node.
- Set stream when the words change in place, like Reply to Sent, so the new words slip in.

## Avoid it for

- A chip or badge for a status. Use StatusText.
- An icon for a fix that does not say the action on sight. Leave fix out, and put the action in the row.
- Color alone. The words must say the status, since color is only a hint.

## Props

- `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. Color role. neutral is muted.
- `icon`: `ReactNode`. An icon before the words, in their color.
- `fix`: `{ label: string; icon?: ReactNode; onClick?; result?: ActionResult }`. The quickest fix: an icon after the words, named by label in its tooltip. The default icon is a turn arrow, for retry.
- `stream`: `boolean`. Default `false`. When the words change, the new ones slip in. The first words just show.
- `detail`: `PeekCardProps | ReactNode`. The story behind the status, in a peek on hover, focus, or tap. The words get a dotted underline.
- `children`: `ReactNode`. The words, like "Going" or "Couldn't save". Required, since tones share colors: Overdue and Couldn't save are both danger red.
- `className`: `string`. Extra classes on the status. Later classes win.

## Accessibility

- The words carry the status, so color is never the only signal.
- A fix is a 24px button named by its label, which shows in its tooltip. Once pressed, its name follows its state: the result, with "Press to undo." while a press undoes, then the record. A fix that failed is named "Retry:" and what failed.
- A fix says its result once, through the page's one polite live region, and its tooltip shows it for a moment after the press.
- With detail, the words are a button that opens the peek, named by its PeekCard title, or else by the words.
- stream only moves the words. To have a change read out, put role="status" on it.

## Examples

### Each tone, in words

```tsx
<StatusText tone="success">Going</StatusText>
<StatusText tone="warning">Maybe</StatusText>
<StatusText>No reply</StatusText>
```

### With its quickest fix

```tsx
<StatusText tone="danger" fix={{ label: "Retry", onClick: () => save() }}>
  Couldn't save
</StatusText>
```

### With a peek behind it

```tsx
<StatusText
  tone="danger"
  detail={{
    title: "Overdue",
    facts: [["Due", "Sat 17 Oct · INV-0042"]],
  }}
>
  Overdue
</StatusText>
```