# <motion-pie>

A pie or donut chart for parts of a whole. Pass numbers in `values`, wrap
a `<table>` (labels in the first column, values in the second), or set
`data` from JavaScript. The pie sweeps in when it scrolls into view, the
slices spring to new sizes when the data changes, and the hovered slice
springs outward. More than six slices are combined into "Other".

**Use it for:** showing how a total splits into a few parts, such as
traffic sources or a budget, with six slices or fewer.

**Avoid it for:** values that are not parts of one whole, values over time,
or many categories; use `motion-chart`.

**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` that lists each label, value and share, with `label` as
its caption. The plot is a focusable group with the role description
"pie chart" and `label` as its name. The arrow keys move between slices,
Home and End jump to the first and last, Escape clears the selection, and a
polite live region announces each slice with its value and share. Set
`label`.

**Reduced motion:** the whole pie appears at once when the sweep-in would
start (on mount, or when 30% of it is in view). New values, the hovered
slice and the tooltip change at once, without springs.

**Common mistakes:** passing negative values: they are drawn as 0. Passing
more than six items: the sixth item and all after it are merged into one
slice labeled "Other", so group small items yourself to choose the label.

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

## Install

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

Or without a build step:

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

## Example

```html
<motion-pie values="42, 28, 18, 12" labels="Direct, Search, Social, Email"></motion-pie>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `values` | `string` | `''` | Comma-separated numbers, one per slice. Ignored when a `<table>` or `data` is given. |
| `labels` | `string` | `''` | Comma-separated slice labels. |
| `donut` | `boolean` | `false` | Cuts out the center and shows the total there. |
| `format` | `string` | `''` | Number format: `'compact'`, `'percent'`, `'currency:EUR'` or `'unit:kilometer'`. |
| `total-label` | `string` | `'Total'` | Caption under the total in a donut. |
| `trigger` | `'view' \| 'mount'` | `'view'` | When the sweep-in runs: `'view'` (scrolled into view) or `'mount'`. |
| `duration` | `number` | `0.8` | Spring duration in seconds. |
| `bounce` | `number` | `0.25` | Spring bounciness when the values change (0 = no overshoot). |
| `tooltip` | `boolean` | `true` | Shows a tooltip on hover and keyboard focus. A donut shows the hovered slice in its center instead. Set `tooltip="false"` to hide it. |
| `legend` | `boolean` | `true` | Shows a legend with each share. Set `legend="false"` to hide it. |
| `label` | `string` | `''` | Accessible name of the chart. |

## Properties

| Property | Type | Description |
| --- | --- | --- |
| `data` | `PieData \| null` | Data from JavaScript: `{ labels, 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()` | Sweeps the pie in again. |
| `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 sweep-in starts. |
| `motion-finish` | When the sweep-in 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 slice. `--mc-chart-2` to `--mc-chart-6` color the others. |
| `--mc-chart-surface` | Background behind the chart, used for the gap between slices. Default `Canvas`. |

## CSS parts

| Part | Description |
| --- | --- |
| `legend` | The legend. |
| `tooltip` | The tooltip. |