# StepIndicator

> Slug: `step-indicator` · Category: Navigation

## When to use
- A multi-step progress indicator showing the user's position in a sequential flow (checkout, onboarding, account setup).
- When you need both progress visualization (the bar) and the current step's name in a single compact element.

## When NOT to use
- For numeric increment/decrement (quantity pickers) — use `Stepper`.
- For tabbed page navigation — use `Tabs` or `Subnavigation`.
- For carousel position indicators — use `PaginationDot`.

## Variants & decision tree
- **`variant="text"`** (default): renders the step name as static text alongside the progress bar. Pair with external Back/Next controls. Best for linear flows where the user can't jump steps.
- **`variant="select"`**: renders a native `<select>` so the user can jump to any earlier step (later steps are disabled). Requires `id`. Use when revisiting prior steps is allowed.

## States
- Progress bar fills proportionally to `currentStep / steps.length`.
- For `select` variant, future steps are `disabled`.
- `currentStep` is clamped to `[1, steps.length]`.
- `inverse` swaps to dark-background styling.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `currentStep` | `number` | — | 1-based current step (clamped). |
| `steps` | `string[]` | — | Step names. Length = total step count. |
| `variant` | `'text' \| 'select'` | `'text'` | Display mode. |
| `id` | `string` | — | Required when `variant="select"` (used for `aria-describedby` and `for`). |
| `onStepChange` | `(step: number) => void` | — | Called when select-variant changes. |
| `inverse` | `boolean` | inherited | Dark-background styling. |

## Usage examples
```tsx
<StepIndicator
  currentStep={2}
  steps={['Cart', 'Shipping', 'Payment', 'Review']}
  variant="text"
/>

{/* Jump-to-step */}
<StepIndicator
  id="checkout-steps"
  currentStep={3}
  steps={['Cart', 'Shipping', 'Payment', 'Review']}
  variant="select"
  onStepChange={(n) => goToStep(n)}
/>
```

## Composition
Place above the form/content for the current step. Pair with `ButtonTray` or `ButtonGroupHorizontal` for Back/Continue navigation.

## Accessibility
- The progress bar uses native `<progress>` with an accessible label ("Step N of M, …").
- For `select` variant, the wrapping `<label>` describes the field and warns about page-load consequences (`aria-describedby`).
- Don't add an extra `role="progressbar"` — the native element handles it.

## Do / Don't
- Do keep step names short (1–2 words).
- Do clamp/skip-forward externally if business rules require validating earlier steps.
- Don't use this for non-linear, branching flows.
- Don't treat the `select` variant's "future steps disabled" rule as enforceable security — validate server-side.
