# HybridBarChart

> Slug: `hybrid-bar-chart` · Category: Data Visualization

## When to use
- Visualize one categorical series per bar — e.g., "current vs. forecast" usage, monthly billing history, or projected charges with deltas.
- You need Arrow's prescribed bar coloring for `current`, `forecast`, `addition`, `subtraction`, `historical`, `pending`, and `inactive` states.
- Bars can show a stacked `delta` to communicate added (or removed) amounts on top of a baseline value.

## When NOT to use
- Time-series with many points / a continuous axis — that's outside the kit; consider a custom chart with the `Legend` component.
- Single-value progress indicator -> `ProgressBar` or `ProgressRing`.
- A simple key/value table -> `Table`.

## Variants & decision tree
- Standard sized chart in a card or panel -> `variant="regular"`.
- Hero / dashboard hero treatment -> `variant="hero"`.
- Bar types map to `tdds-hybrid-bar-chart__bar--{type}` modifiers — `current` is the default and renders no modifier.
- Use `delta` to render an addition/subtraction segment stacked on a base value.

## States
- `inverse` — dark-background styling.
- `pending` / `inactive` bar types display as N/A and use Arrow's neutralized treatment.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`series`** | `ChartBar[]` | — | Bars to render. |
| `variant` | `'regular' \| 'hero'` | `'regular'` | Visual size. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Additional class names. |

`ChartBar`: `{ value?: number; type: ChartBarType; label?: string; subLine?: string; delta?: number }`.

`ChartBarType`: `'current' | 'forecast' | 'addition' | 'subtraction' | 'historical' | 'pending' | 'inactive'`.

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

<HybridBarChart
  series={[
    { type: 'historical', value: 95, label: 'Jul', subLine: 'Bill' },
    { type: 'historical', value: 110, label: 'Aug', subLine: 'Bill' },
    { type: 'current',    value: 105, label: 'Sep', subLine: 'Current' },
    { type: 'addition',   value: 105, delta: 22, label: 'Sep', subLine: 'Projected' },
    { type: 'forecast',   value: 130, label: 'Oct', subLine: 'Forecast' },
  ]}
  variant="hero"
/>
```

## Composition
- Pair with `Legend` (matching `LegendSymbolType` values) so users can decode the colors.
- Render inside a `Tile` or `BillCard` for context-aware framing.

## Accessibility
- Provide labels and sublines on every bar so screen readers can interpret the chart.
- Color alone never carries meaning — the legend is required.

## Do / Don't
- Do: keep series ≤ ~12 bars to preserve readability.
- Do: format numeric values upstream — Arrow handles currency formatting internally for `addition`-style stacks.
- Don't: combine `pending` / `inactive` with real values in the same bar — they render N/A by design.
- Don't: nest charts inside one another.
