# ProgressRing

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

## When to use
- A compact, glanceable progress indicator — dashboard tiles, "75%" complete badges, score rings, hero overview cards.
- You want the value rendered in the center of the ring, formatted as a percentage or fraction.

## When NOT to use
- Linear / wide progress with axis labels -> `ProgressBar`.
- Indeterminate loading -> `DotLoader`.
- Wizard step counts -> `Stepper` or `StepIndicator`.

## Variants & decision tree
- Standard tile size -> `variant="regular"`.
- Hero / dashboard centerpiece -> `variant="hero"` (note: `monochrome` color is not supported in hero).
- Center text format: percent of max (`format="percentage"`) or "X / Y" (`format="fraction"`).

## States
- `inverse` — dark-background styling.
- Color via `color` prop conveys semantic state.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | Optional label rendered with the ring. |
| `currentValue` | `number` | `0` | Current value. |
| `maxValue` | `number` | `100` | Maximum value. |
| `variant` | `'regular' \| 'hero'` | `'regular'` | Size variant. |
| `color` | `'branded' \| 'monochrome' \| 'negative' \| 'positive' \| 'historical'` | `'branded'` | Ring color. |
| `format` | `'percentage' \| 'fraction'` | `'percentage'` | Center value format. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Additional class names. |

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

// Hero data-usage ring
<ProgressRing
  variant="hero"
  label="Data used"
  currentValue={42}
  maxValue={50}
  format="fraction"
  color="branded"
/>

// Compact completion indicator
<ProgressRing
  currentValue={3}
  maxValue={4}
  format="fraction"
  color="positive"
  label="Setup steps"
/>
```

## Composition
- Render inside a `Tile`, `BillCard`, or dashboard panel.
- Pair with `Legend` when color carries comparative meaning across rings.

## Accessibility
- Provide a meaningful `label` — the ring is a graphic, the label gives it a name.
- Use `color="negative"` only for genuinely warning states.

## Do / Don't
- Do: use `format="fraction"` when the absolute count matters (3 / 4 steps).
- Do: keep `maxValue` stable — flickering bounds break the visual.
- Don't: combine `variant="hero"` with `color="monochrome"` — Arrow does not support that combo.
- Don't: use this as a spinner.
