# Legend

> Slug: `legend` · Category: Data Visualization

## When to use
- Decode colors and symbols on any data-viz output — `HybridBarChart`, `ProgressBar`, `ProgressRing`, or a custom chart that uses Arrow's data-viz tokens.
- Surface a value next to each label (e.g., "$32.10") for compact summary readouts.

## When NOT to use
- Generic key/value displays -> `List` or `Table`.
- Status pills next to text -> `StatusLabel`.
- Standalone informational labels -> `Tidbit`.

## Variants & decision tree
- Default horizontal arrangement -> omit `position` (or `'horizontal'`).
- Stack as a column under or beside a chart -> `position="vertical"`.
- Symbol selection follows the chart: `current`, `forecast`, `addition`, `subtraction`, `historical`, `pending`, `inactive`.

## States
- `inverse` — dark-background styling.
- No interactive states.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`items`** | `LegendItem[]` | — | Symbols + labels (+ optional values). |
| `position` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Additional class names. |

`LegendItem`: `{ type: LegendSymbolType; label: string; value?: string }`.

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

<HybridBarChart series={series} variant="regular" />

<Legend
  position="horizontal"
  items={[
    { type: 'historical', label: 'Past bills' },
    { type: 'current',    label: 'Current bill', value: '$105.00' },
    { type: 'addition',   label: 'New charges',  value: '+$22.00' },
    { type: 'forecast',   label: 'Forecast' },
  ]}
/>
```

## Composition
- Always render adjacent to the chart it explains — chart on top / left, legend below / right.
- Keep symbol types in the legend identical to the bar / ring types in the chart.

## Accessibility
- The legend is a static list. Screen readers announce each label / value pair.
- Never rely on color alone — the symbol shape and label both convey meaning.

## Do / Don't
- Do: include a value next to a label when the chart cannot show numbers directly.
- Do: use the same `LegendSymbolType` enum that drives chart bars / rings.
- Don't: invent new symbol types — Arrow tokens only support the seven listed.
- Don't: replace `Tabs` or `Chips` with a legend; legends are non-interactive.
