# Status dot

A small status mark. Running and waiting pulse, since they are the two states a person may need to watch or act on. When one of them reaches done or failed while on screen, the new dot pops into place (too small for a drawn mark); a dot that mounts finished is still. The label is always available to assistive tech; pass `showLabel` to print it too.

- Registry name: `status-dot` (`@candor/status-dot`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/status-dot

## Install

```bash
npx candor-ui add status-dot
```

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

## Example

```tsx
"use client"

import { StatusDot } from "@/components/status-dot"

export default function Example() {
  return (
    <div className="flex flex-wrap gap-x-6 gap-y-3">
      <StatusDot status="running" showLabel />
      <StatusDot status="waiting" showLabel />
      <StatusDot status="succeeded" showLabel />
      <StatusDot status="failed" showLabel />
      <StatusDot status="queued" showLabel />
    </div>
  )
}
```

## <StatusDot>

Props:

- `status: RunStatus`: Which status to show; running and waiting pulse.
- `showLabel?: boolean | undefined` (default `false`): Print the status name next to the dot.
- `label?: string | undefined`: Words to use instead of the status name.
- `className?: string | 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` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.