# StatusBadge

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - status-badge.variants — `statusBadgeVariants` is th…
- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…
- status-badge.variants — `statusBadgeVariants` is th…

- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…

- status-badge.variants — `statusBadgeVariants` is th…

- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…

- status-badge.variants — `statusBadgeVariants` is th…

- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…
- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…

## Purpose

`<StatusBadge>` is the chassis status marker with semantic colour and matching iconography. It pairs one of five status colour palettes (`success` / `warning` / `error` / `info` / `neutral`) with a default lucide-react icon (`CheckCircle2Icon` / `AlertTriangleIcon` / `XCircleIcon` / `InfoIcon` / `CircleIcon`) so consumers do not hand-roll status-with-icon markers across the application surface.

`<StatusBadge>` is a **suaveplan-only addition** — shadcn does not ship a `status-badge` registry item upstream (per Wave 3a's reconciliation finding #7). The chassis exposes it because every product surface needs status indicators, and hand-rolled spans diverge across teams (different padding, different colours, different iconography). A discrete primitive enforces consistency.

## Features

- Five status colour palettes via the `status` axis (`success` / `warning` / `error` / `info` / `neutral`).
- Default lucide-react icon per status — overridable via `hideIcon` and a custom child element.
- Translucent backgrounds with matching borders that meet WCAG AA contrast in both light and dark themes.
- `data-status` attribute on the rendered element so tests / consumer CSS can target every status badge by status family.
- `aria-hidden="true"` on the injected icon so the visible text (children) is the accessible name.
- Forwards refs to the underlying `<div>`.

## Usage: Basic Example

```tsx
import { StatusBadge } from "@suaveplan/react-ui";

export function StatusRow() {
    return (
        <div className="flex flex-wrap gap-2">
            <StatusBadge status="success">Active</StatusBadge>
            <StatusBadge status="warning">Pending</StatusBadge>
            <StatusBadge status="error">Failed</StatusBadge>
            <StatusBadge status="info">In review</StatusBadge>
            <StatusBadge status="neutral">Idle</StatusBadge>
        </div>
    );
}
```

## Usage: Advanced Example

```tsx
import { StatusBadge } from "@suaveplan/react-ui";
import { ZapIcon } from "lucide-react";

export function CustomIconStatus() {
    return (
        <StatusBadge status="success" hideIcon>
            <ZapIcon className="size-3" aria-hidden="true" />
            Lightning fast
        </StatusBadge>
    );
}
```

## API Reference

### `<StatusBadge>`

`forwardRef<HTMLDivElement, StatusBadgeProps>` — renders a `<div>` with the variant classes + chassis-injected icon (unless `hideIcon === true`) + children.

#### `StatusBadgeProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `status` | `"success" \| "warning" \| "error" \| "info" \| "neutral"` | `"neutral"` | Semantic colour palette + default icon. |
| `hideIcon` | `boolean` | `false` | When `true`, suppress the chassis-injected icon. Use when children includes a custom icon to avoid double-up. |
| _all_ `HTMLAttributes<HTMLDivElement>` | _native_ | _native_ | Forwarded as-is. |

#### `statusBadgeVariants`

The bare cva resolver — exported so external consumers (themes, ejected source) can re-use the variants directly.

#### Errors

The StatusBadge component does NOT call `useTranslation()` so it does not interact with the i18n provider. Children are consumer-provided `ReactNode`; consumers using TranslationKey-typed strings should resolve them at the call site (`<StatusBadge>{t('status.active')}</StatusBadge>`).

## Implementation Notes

- The default icon for each status is fixed via the `STATUS_ICON` map. To replace the icon, pass `hideIcon` and provide a custom icon element as the first child — this keeps the chassis API simple while leaving the override path open.
- `aria-hidden="true"` is applied to the injected icon so the icon does not duplicate the announcement of the status text. When `hideIcon === true` and the consumer provides their own icon, they are responsible for marking it `aria-hidden` themselves.
- The `data-status` attribute is always written on the rendered `<div>` regardless of whether the icon is shown — this is the canonical hook for tests / consumer CSS targeting status badges by family.
- The icon size is `size-3` (12px) which matches the badge's `text-xs` typography rhythm; consumers wanting a larger icon should pass `hideIcon` and supply their own sized icon.
- RTL: the icon sits at the start (logical inline-start) so `dir="rtl"` automatically flips it to the right. No special-case markup needed.