# ProgressBar

> Slug: `progress-bar` · Category: Data Visualization

## When to use
- Show a single bounded value against a max — data usage, file-upload progress, fundraiser-style meters, plan utilization.
- Group several related progress indicators (e.g., per-line data usage) by combining via `ProgressBarGroup`.

## When NOT to use
- Indeterminate / "still loading" affordances -> `DotLoader`.
- Circular progress (compact, dashboard tiles) -> `ProgressRing`.
- Stepwise wizards -> `Stepper` or `StepIndicator`.

## Variants & decision tree
- Single bar in a card -> `ProgressBar` standalone.
- Multiple bars (e.g., usage per line) -> `ProgressBarGroup` with optional `hasDivider`.
- Color choice follows semantics: `branded` (default), `monochrome`, `positive`, `negative`, `historical`.
- Labels above (default) vs below the bar -> `labelLocation="bottom"`.

## States
- `inverse` — dark-background styling.
- Color via `color` prop conveys semantic state (positive/negative/etc.).

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | Unique identifier. |
| `title` / `subtitle` | `string` | — | Title block above the bar. |
| `startLabel` / `endLabel` | `string` | — | Min/max axis labels. |
| `currentValue` | `number` | `0` | Current progress. |
| `maxValue` | `number` | `100` | Maximum value. |
| `color` | `ProgressBarColor` | `'branded'` | Highlight color. |
| `labelLocation` | `'top' \| 'bottom'` | `'top'` | Label position. |
| `inverse` | `boolean` | inherits | Dark-background styling. |

`ProgressBarGroupProps`: `progressBars: ProgressBarProps[]`, `hasDivider?: boolean`, `inverse?: boolean`, `className?: string`.

## Usage examples
```tsx
import { ProgressBar, ProgressBarGroup } from 'arrow-react-bootstrap';

// Single bar
<ProgressBar
  title="Data usage"
  subtitle="42 GB of 50 GB used this cycle"
  startLabel="0 GB"
  endLabel="50 GB"
  currentValue={42}
  maxValue={50}
  color="branded"
/>

// Grouped per-line usage
<ProgressBarGroup
  hasDivider
  progressBars={[
    { title: 'Line 1 (Avi)',     currentValue: 18, maxValue: 30, startLabel: '0', endLabel: '30 GB' },
    { title: 'Line 2 (Sam)',     currentValue: 28, maxValue: 30, color: 'negative' },
    { title: 'Line 3 (Tablet)',  currentValue: 4,  maxValue: 30, color: 'monochrome' },
  ]}
/>
```

## Composition
- Render inside a `Tile` or `BillCard`.
- Pair with `Legend` when colors carry meaning across multiple bars.

## Accessibility
- Set meaningful `title`, `startLabel`, and `endLabel`. The component handles the underlying `<progress>` semantics.
- Use `color="negative"` only for genuinely concerning states — color carries meaning here.

## Do / Don't
- Do: provide both `currentValue` and `maxValue` even if you have a percentage — Arrow needs both for ARIA.
- Do: use `ProgressBarGroup` (not multiple sibling `ProgressBar`s) to keep spacing and dividers consistent.
- Don't: animate `currentValue` faster than 250 ms — it works against motion-reduction settings.
- Don't: use this for indeterminate loading.
