# <motion-chart>

A bar or line chart drawn from HTML. Pass numbers in `values`, wrap a
`<table>` (first column labels, one series per column), or set `data` from
JavaScript. Bars grow and lines draw in when the chart scrolls into view.
When the data changes, every bar and point springs to its new value, and a
change in the middle of an animation continues from where the chart is. The
scale springs to its new range too: old grid lines fade out and new ones fade
in. Set `animate-scale="false"` to switch the scale at once.

**Use it for:** comparing values across categories with bars, or showing a
trend over time with lines, for up to eight series.

**Avoid it for:** parts of a whole; use `motion-pie`. For a small trend in
a sentence or a table cell, use `motion-sparkline`. Avoid it for more than
eight series, because series after the eighth are not drawn.

**Accessibility:** the drawing is hidden from screen readers, which read a
visually hidden data table instead: your own `<table>`, or one built from
`values` or `data` with `label` as its caption. The plot is a focusable
group with the role description "chart" and `label` as its name. The Left
and Right arrow keys move between points, Home and End jump to the first
and last, Escape hides the tooltip, and a polite live region announces each
point. Set `label`, and give each series a name.

**Reduced motion:** bars and lines appear at their final values at once
when the entrance would start (on mount, or when 30% of the chart is in
view). Data changes and tooltip moves also happen at once.

**Common mistakes:** writing thousands separators in `values`, such as
`1,200`: commas separate values there, so it reads as 1 and 200. Using
numbers such as years as series names in a header row of `<td>` cells: the
row is read as data. Use `<th>` for every cell of that row, or a `<thead>`.

Docs: https://www.motion-components.dev/docs/charts/motion-chart/

## Install

```js
import 'motion-components/motion-chart'
```

Or without a build step:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/motion-components@1/dist/motion-chart.js/+esm"></script>
```

## Example

```html
<motion-chart type="bar" values="12, 19, 8, 24" labels="Mon, Tue, Wed, Thu"></motion-chart>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'bar' \| 'line'` | `'bar'` | `'bar'` or `'line'`. |
| `values` | `string` | `''` | Comma-separated numbers. Separate several series with `;`. Ignored when a `<table>` or `data` is given. |
| `labels` | `string` | `''` | Comma-separated labels for the `values`. |
| `series` | `string` | `''` | Comma-separated series names for the `values`. |
| `min` |  | `NaN` | Lowest value on the axis. Defaults to the lower of `0` and the smallest value. |
| `max` |  | `NaN` | Highest value on the axis. Defaults to the largest value, rounded up. |
| `format` | `string` | `''` | Number format: `'compact'`, `'percent'`, `'currency:EUR'` or `'unit:kilometer'`. |
| `trigger` | `'view' \| 'mount'` | `'view'` | When the entrance runs: `'view'` (scrolled into view) or `'mount'`. |
| `duration` | `number` | `0.8` | Spring duration in seconds. |
| `bounce` | `number` | `0.25` | Spring bounciness (0 = no overshoot). |
| `interval` | `number` | `0.04` | Seconds between one bar group and the next on entrance. |
| `tooltip` | `boolean` | `true` | Shows a tooltip on hover and keyboard focus. Set `tooltip="false"` to hide it. |
| `legend` | `boolean` | `true` | Shows a legend for two or more series. Set `legend="false"` to hide it. |
| `label` | `string` | `''` | Accessible name of the chart. |
| `animate-scale` | `boolean` | `true` | Springs the scale and its grid lines to a new range when the data changes. Set `animate-scale="false"` to switch the scale at once. |

## Properties

| Property | Type | Description |
| --- | --- | --- |
| `data` | `ChartData \| null` | Data from JavaScript: `{ labels, series: [{ name, values }] }`. Takes precedence over a table and `values`. |
| `playState` | `'idle' \| 'running' \| 'paused' \| 'finished'` | Current state: `'idle'`, `'running'`, `'paused'` or `'finished'`. |
| `finished` | `Promise<void>` | Resolves when the current run settles. A new run replaces the promise. |

## Methods

| Method | Description |
| --- | --- |
| `replay()` | Restarts the entrance animation. |
| `play()` | Starts the animation, or resumes it when paused. Resolves once the run settles. Under `prefers-reduced-motion: reduce` the final state is applied immediately without animating. |
| `pause()` | Holds the animation at its current position. No-op unless running. |
| `finish()` | Jumps to the final state and settles. Fires `motion-finish`. |
| `cancel()` | Reverts to the initial state and returns to idle. Fires `motion-cancel`. |

## Events

The `motion-*` events bubble and are composed.

| Event | Description |
| --- | --- |
| `motion-start` | When the entrance animation starts. |
| `motion-finish` | When the entrance animation finishes. |
| `motion-cancel` | When `cancel()` stops a run and resets it. |

## Slots

| Slot | Description |
| --- | --- |
| (default) | An optional `<table>` with the data. It stays available to screen readers. |

## CSS custom properties

| Property | Description |
| --- | --- |
| `--mc-chart-height` | Height of the chart, including the legend. Default `16rem`. |
| `--mc-chart-1` | Color of the first series. `--mc-chart-2` to `--mc-chart-8` color the others. |
| `--mc-chart-surface` | Background of the tooltip. Default `Canvas`. |

## CSS parts

| Part | Description |
| --- | --- |
| `legend` | The legend, shown for two or more series. |
| `tooltip` | The tooltip. |