# StatusLabel

> Slug: `status-label` · Category: Display

## When to use
- Communicate state next to an item: order status ("Shipped"), validation ("Active"), severity ("Error").
- Provide a compact visual signal with semantic tone (positive, caution, critical, info, strong).
- Accompany list rows, cards, table cells, or form values where state is part of the data.

## When NOT to use
- Promotional emphasis or value props — use `PromoLabel`.
- Selectable filters — use `FilterChip` or `Chips`.
- Toast-style ephemeral feedback — use `Snackbar` or `Tidbit`.

## Variants & decision tree
- Tone via `status`:
  - `positive` — success, on-track
  - `caution` — warning, attention
  - `critical` — error, blocking
  - `info` — neutral notice
  - `strong` — high-contrast emphasis
- Visual style via `style`: `dot` (default — colored dot prefix), `icon` (renders the `icon` prop), `none` (text only).
- Background fill via `backgroundColor`: `primary` (default), `secondary`, `no-fill` (text-only on transparent), `status` (matches status tone).
- Sizes: `small`, `xs`.

## States
- Inverse-aware (theme or `inverse` prop).
- Returns `null` when `label` is empty.
- `no-fill` is ignored when `status="strong"` (Arrow rule).

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`label`** | `ReactNode` | — | Visible status text. |
| `status` | `'positive' \| 'caution' \| 'critical' \| 'info' \| 'strong'` | — | Semantic tone. |
| `style` | `'dot' \| 'icon' \| 'none'` | `'dot'` | Visual prefix. |
| `icon` | `ReactNode` | — | SVG icon (only renders when `style="icon"`). |
| `iconA11yLabel` | `string` | — | Accessible label for icon. |
| `backgroundColor` | `'primary' \| 'secondary' \| 'no-fill' \| 'status'` | `'primary'` | Fill treatment. |
| `size` | `'small' \| 'xs'` | — | Sets `data-size`. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Extra class names. |

## Usage examples
```tsx
import { StatusLabel } from 'arrow-react-bootstrap';

// Order status
<StatusLabel status="positive" label="Shipped" />

// Critical with text-only style
<StatusLabel status="critical" style="none" label="Payment failed" />

// Caution with icon
<StatusLabel
  status="caution"
  style="icon"
  icon={<svg viewBox="0 0 24 24"><path d="M1 21h22L12 2 1 21z"/></svg>}
  label="Attention needed"
/>

// Strong / high-emphasis
<StatusLabel status="strong" backgroundColor="status" label="Live" />
```

## Composition
- Place in list rows (`ListItem` trailing slot), `Table` cells, `BillCard`, or beside a value in a form summary.
- Combine with `Tidbit` for richer alerts that need a body and dismiss affordance.

## Accessibility
- Renders a non-interactive `<div>`; the label text is read.
- Color is not the only signal — keep `label` text descriptive ("Failed", not just a red dot).
- For icon-only meaning, ensure the SVG has `role="img"` + accessible name.

## Do / Don't
- Do: pair `status` with descriptive `label` text; never rely on color alone.
- Do: pick `style="none"` when surrounding context already implies status visually.
- Don't: stack multiple status labels per item; pick the most relevant one.
- Don't: use for actionable affordances — status labels are non-interactive.
