# Step capsules

The steps of a plan or a run as a wrapping row of small cards, one per step, where `StepList`'s column is too tall: a header strip, a narrow panel, a summary. It takes `StepList`'s steps and draws the same marks and status words: a tick or cross drawn when a step settles while on screen, a spinner only while it runs, its status read with its title. A step added after the capsules first drew rises in; the steps they loaded with are still. Titles from the agent are drawn as text, in their own direction (`bdi`).

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

## Install

```bash
npx candor-ui add step-capsules
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/step-capsules`.
It brings in: bidi, motion, status, step-list, tokens, utils.

## Example

```tsx
"use client"

import { StepCapsules } from "@/components/candor/step-capsules"
import type { Step } from "@/components/candor/step-list"

const steps: Step[] = [
  { id: "1", title: "Read the order history", status: "succeeded", meta: "3s" },
  { id: "2", title: "Draft the refund", status: "succeeded", meta: "5s" },
  { id: "3", title: "Ask a person to approve", status: "waiting" },
  { id: "4", title: "Issue the refund", status: "idle" },
]

// StepList's steps as a wrapping row: the same marks and status words, for a header strip or a narrow panel.
export default function Example() {
  return <StepCapsules steps={steps} className="max-w-xl" />
}
```

## <StepCapsules>

Props:

- `steps: Step[]`: The steps in order, each with a status, and optional detail and meta: `StepList`'s.
- `className?: string | undefined`: Classes for the list, merged with Candor's.

## Motion

- **arrive** (arrive, rise): A step's card rises in when the app adds it after the capsules first drew. The steps they were drawn with appear still. Each card's mark is StepList's: a tick or cross drawn when the step settles on screen (step-list:mark), and a spinner that turns only while the step runs (step-list:working).

Set with `--cd-motion-step-capsules-<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`.