# Chart

Ten typed chart forms with ordered palette roles, responsive geometry, shared inspection and an accessible data table. Compose with Card and DataTrend for metric panels.

## Usage

### When to use

- Show changes, comparisons, composition, conversion, retention or service availability from numeric data.
- Keep an accessible data table beside visual patterns and point inspection.

### When not to use

- A single current value and its change. Use DataTrend.
- Completion toward a known total. Use Progress.
- Editing individual measurements. Use Table with form controls.

## Variants

### type

Required discriminant. Each type accepts only its own data shape.

Values: `line`, `area`, `bar`, `sparkline`, `composition`, `donut`, `funnel`, `timeline`, `cohort`, `uptime`. Default: `undefined`.

### table

Toggle reveals the semantic data view. Hidden keeps the table accessible with visually hidden presentation. Sparkline defaults hidden.

Values: `toggle`, `visible`, `hidden`. Default: `toggle`.

### xScale

Cartesian axis spacing. Numeric and time modes require finite, strictly ascending x values; time uses epoch milliseconds. Without formatX, time positions show a short UTC date.

Values: `category`, `linear`, `time`. Default: `category`.

### stack

Area only: overlaid independent series or a nonnegative summed stack. Null breaks the stack at that row.

Values: `none`, `normal`. Default: `none`.

### orientation

Bar only: vertical or horizontal bars.

Values: `vertical`, `horizontal`. Default: `vertical`.

### layout

Bar only: grouped, signed stacked or nonnegative percentage composition. Percentage rows with zero totals stay empty.

Values: `grouped`, `stacked`, `percentage`. Default: `grouped`.

## Examples

### Three-series line

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="line" label="Weekly activity" data={sampleChartRows} series={sampleChartSeries} />
```

### Overlaid areas

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="area" label="Audience over time" data={sampleChartRows} series={sampleChartSeries} stack="none" />
```

### Stacked areas

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="area" label="Allocation over time" data={sampleChartRows} series={sampleChartSeries} stack="normal" />
```

### Vertical grouped bars

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="bar" label="Grouped activity" data={sampleChartRows} series={sampleChartSeries} orientation="vertical" layout="grouped" />
```

### Vertical stacked bars

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="bar" label="Stacked activity" data={sampleChartRows} series={sampleChartSeries} orientation="vertical" layout="stacked" />
```

### Vertical percentage bars

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="bar" label="Percentage activity" data={sampleChartRows} series={sampleChartSeries} orientation="vertical" layout="percentage" />
```

### Horizontal grouped bars

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="bar" label="Grouped activity" data={sampleChartRows} series={sampleChartSeries} orientation="horizontal" layout="grouped" />
```

### Horizontal stacked bars

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="bar" label="Stacked activity" data={sampleChartRows} series={sampleChartSeries} orientation="horizontal" layout="stacked" />
```

### Horizontal percentage bars

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="bar" label="Percentage activity" data={sampleChartRows} series={sampleChartSeries} orientation="horizontal" layout="percentage" />
```

### Compact table bar

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="bar" label="Views against a shared maximum" data={sampleChartRows} series={sampleSparkSeries} orientation="horizontal" compact domain={[0, 600]} table="hidden" />
```

### Sparkline

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="sparkline" label="Views this week" data={sampleChartRows} series={sampleSparkSeries} />
```

### Composition

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="composition" label="Traffic sources" data={sampleChartParts} />
```

### Donut

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="donut" label="Traffic sources" data={sampleChartParts} />
```

### Ordered funnel

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="funnel" label="Journey conversion" data={sampleFunnelParts} />
```

### Timeline

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="timeline" label="Delivery schedule" data={sampleChartRanges} range={[0, 28]} marker={{ value: 14, label: "Checkpoint" }} />
```

### Cohort retention

Original illustrative cohorts. Null means not yet observed; zero means an observed zero percent.

```tsx
<Chart type="cohort" label="Weekly retention" data={sampleChartCohorts} columns={sampleCohortColumns} />
```

### Service uptime

Original equal-duration observations. Unknown periods remain explicit; summaries average known availability.

```tsx
<Chart type="uptime" label="Daily service availability" data={sampleChartUptime} />
```

### Current and prior periods

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="line" label="Current and prior activity" data={sampleComparisonRows} series={sampleComparisonSeries} />
```

### Missing values

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="line" label="Activity with an observation gap" data={sampleMissingRows} series={sampleChartSeries} />
```

### Signed values

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="bar" label="Regional net changes" data={sampleSignedRows} series={sampleSignedSeries} layout="stacked" />
```

### Empty total

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="donut" label="Activity awaiting observations" data={sampleZeroParts} />
```

### Eight series

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="line" label="Eight labeled groups" data={sampleEightRows} series={sampleEightSeries} />
```

### Pending refresh

Original illustrative data stays visible while only the plot dims.

```tsx
<Chart type="line" label="Activity being refreshed" data={sampleChartRows} series={sampleChartSeries} pending />
```

### Localized labels

Original illustrative data. Copy includes the complete local setup.

```tsx
<Chart type="line" label="Activity with custom labels" data={sampleMissingRows} series={sampleChartSeries} locale="en-GB" labels={sampleChartLabels} />
```

## Do and don't

### Do

- Use the ten discriminated data contracts. Keep ids stable and row labels complete.
- Use series in chartPalette order; mark comparisons with comparison=true and supply direct labels or patterns for more than four series.
- Put values and labels on neutral surfaces. Compose metrics with the full DataTrend block and goals with Progress.
- Keep prior content while refreshing. Use a delayed Skeleton only for a first load.
- Label sample datasets as illustrative and derive every chart, metric and table on a screen from the same rows.

### Don't

- Do not pick arbitrary hues, apply color alpha, add opacity steps or animate chart drawing.
- Do not connect across missing values, clamp invalid facts or treat null as zero.
- Do not average unequal-duration availability samples or count status cells as uptime.
- Do not imply that cohort heat bands are success thresholds.
- Do not add a second Card surface around a chart already inside a Card.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `type` (required) | `enum` | `line`, `area`, `bar`, `sparkline`, `composition`, `donut`, `funnel`, `timeline`, `cohort`, `uptime` |  | Required discriminant. Each type accepts only its own data shape. |
| `label` (required) | `string` |  |  | Required accessible chart name. |
| `description` | `string` |  |  | Optional context associated with the chart. |
| `data` (required) | `ChartRow[] \| ChartItem[] \| ChartRange[] \| ChartCohortRow[] \| ChartUptimeRow[]` |  |  | Ordered local data matching type. Null preserves missing or unobserved meaning; invalid values are reported. |
| `series` | `ChartSeries[]` |  |  | Required for line, area, bar and sparkline. Stable ids map to values; comparison adds a dashed stroke. Sparkline takes one series. |
| `height` | `number` |  |  | Plot height in CSS pixels. Defaults to 256, sparkline 48, compact bar 32. Timeline, cohort and uptime size to their rows by default; a height fixes the timeline and caps cohort and uptime, which then scroll. |
| `legend` | `boolean` |  | `true` | Show the series or status legend. Defaults true except sparkline and single-series bar. Composition, donut and funnel keep direct labels without a duplicate legend. |
| `interactive` | `boolean` |  | `true` | Enable pointer, touch and keyboard inspection. Defaults true except sparkline. |
| `pending` | `boolean` |  | `false` | Retain current data, mark the figure busy and dim only the plot. |
| `table` | `enum` | `toggle`, `visible`, `hidden` | `toggle` | Toggle reveals the semantic data view. Hidden keeps the table accessible with visually hidden presentation. Sparkline defaults hidden. |
| `locale` | `string` |  | `en` | Explicit number-formatting locale shared by server and client. |
| `labels` | `Partial<ChartLabels>` |  |  | Override viewData, hideData, loading, empty, missing, unobserved, invalid, noSeries, zeroTotal, value, total, cohortSize, conversion, share, coverage, success, warning, danger, unknown, neutral, start, end, status and point text. Raw values use formatValue; derived percentages always use locale-aware percentage formatting. |
| `formatValue` | `(value: number, id: string) => string` |  |  | Format a finite number and stable series or item id without changing geometry. |
| `xScale` | `enum` | `category`, `linear`, `time` | `category` | Cartesian axis spacing. Numeric and time modes require finite, strictly ascending x values; time uses epoch milliseconds. Without formatX, time positions show a short UTC date. |
| `formatX` | `(value: number) => string` |  |  | Format numeric or time ticks for Cartesian charts and timeline; full row labels remain available. |
| `domain` | `[number, number]` |  |  | Cartesian finite ascending value bounds containing every value. Bar domains must include zero. |
| `axes` | `boolean` |  | `true` | Show Cartesian axes. Defaults true except sparkline and compact bar. |
| `grid` | `boolean` |  | `true` | Show Cartesian grid lines. Defaults true except sparkline and compact bar. |
| `hiddenSeries` | `string[]` |  |  | Controlled hidden Cartesian series ids. Palette positions remain stable. |
| `defaultHiddenSeries` | `string[]` |  |  | Uncontrolled initial hidden Cartesian series ids. |
| `onHiddenSeriesChange` | `(ids: string[]) => void` |  |  | Receive the hidden series ids after a legend action. |
| `stack` | `enum` | `none`, `normal` | `none` | Area only: overlaid independent series or a nonnegative summed stack. Null breaks the stack at that row. |
| `orientation` | `enum` | `vertical`, `horizontal` | `vertical` | Bar only: vertical or horizontal bars. |
| `layout` | `enum` | `grouped`, `stacked`, `percentage` | `grouped` | Bar only: grouped, signed stacked or nonnegative percentage composition. Percentage rows with zero totals stay empty. |
| `compact` | `boolean` |  | `false` | Bar only: short numeric cell display without axes or legend. A shared domain gives comparable lengths. |
| `range` | `[number, number]` |  |  | Timeline only, required finite ascending range in caller-defined units. Every entry must fit. |
| `marker` | `{ value: number; label: string }` |  |  | Optional timeline reference position. Outside-range positions remain described without a visual marker. |
| `columns` | `Array<{ id: string; label: string }>` |  |  | Cohort only, required unique columns. Each row has one percentage or null per column. |
| `thresholds` | `[number, number, number, number]` |  |  | Cohort only: four ascending bounds inside (0, 100), defining five ordered heat bands of chart series 1 that grow stronger with each band; the value prints on the cell. Defaults [20, 40, 60, 80]. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | Named figure with description and loading state. |
| `plot` | Responsive plot and one keyboard inspection surface. Lines and area edges are smooth monotone curves that never overshoot a value; area fills fade from the series color at opacity-subtle to transparent. Grid lines are dashed and quiet; the zero line turns solid on signed domains. Bars are slim, round only their value end and never get outlines. Composition parts and donut sectors are separated by a 2px gap instead of an outline. Inspected line and area points use their series fill, a white 2px color-border-chart-marker ring and drop-shadow-low. The inspected composition part grows 4px above and below the track, and the inspected donut sector grows 4px outward, drawn above its neighbors. |
| `legend` | Series visibility buttons with compact keys (a short stroke for lines, a small swatch for filled marks) or a static status list with status icons. Composition and donut list each category with its amount and share; funnel rows show the conversion from the previous stage, the amount and the share of the first stage, and every stage uses series 1, since stages are one measure. |
| `tooltip` | Compact inspected values beside the pointer or keyboard-selected mark, bounded inside the plot and rounded with radius-container. |
| `table` | Semantic raw-data view with caption and headers. |

## Accessibility

Role: `figure`

| Keys | Action |
| --- | --- |
| `Tab` | Enter the plot once; legend buttons and data toggle remain separate controls. |
| `Arrow keys` | Inspect rows and visible series; navigate ranges or matrix cells according to chart type. |
| `Home / End` | Inspect the first or last Cartesian row. |
| `Escape` | Close inspection and restore focus to the plot. |

- The required label names the figure; description supplies context. Every chart retains a semantic data table, including table=hidden.
- Null means missing for Cartesian values and not yet observed for cohorts. Zero is an observed value.
- Series retain palette identity when hidden. More than four series add patterns and dashes; with four or fewer, keep the legend or the data table visible, since a hidden legend leaves color as the only cue.
- Touch taps pin inspection; a second tap or outside tap dismisses it. Normal page scrolling remains available. Mouse hover never receives keyboard focus contours, and a focused plot keeps its focus ring while the mouse moves. Each bar group is one hit band across the value axis; the gaps between groups dismiss inspection. Uptime rows are 44px targets that pick the period under the pointer. In horizontal bars, Up and Down move between rows and Left and Right between series.
- Uptime samples represent equal-duration periods. Coverage and the mean of known availability remain distinct.

## Install

```bash
npx werewolf-ui add chart
```

Run `npx werewolf-ui init` once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See [Installation](https://werewolf-ui.vercel.app/docs/installation.md) for requirements and the alternative registry setup.