# chart

Draws a source's rows as an area, line, bar, donut or spark chart, such as tickets closed per hour or where the money goes.

`kind` picks the shape: `line` or `area` for a value over time, `bar` to compare a few categories, `donut` for the
parts of one whole, `spark` for a small trend without axes. `x` is the column along the bottom (a time or a label)
and `series` the 1 to 5 number columns drawn, one row per point in the source's order (sort it with the source's
`order`). `format` writes the values as kpis do. `title` names the chart in a few words.

Category: data. Tier 1. Contract version 1.

## When to use

- A value over time, such as tickets closed and handed off per hour today.
- A few categories compared, such as this month's spend by category.
- The parts of one whole, such as where the money goes.

## When to use another block

- Exact values a person reads or sorts. Use [`grid`](/catalog/grid.md).
- One figure, now. Use [`kpis`](/catalog/kpis.md).
- One figure against a limit. Use [`progress`](/catalog/progress.md).

## Props

- `id` (name: a-z, 0-9 and -): The block's id: its Markdown anchor and its actions' route (`/act/<id>/<action>`). Default `<type>-<n>`, n counting blocks of this type depth-first from 1.
- `title` (text ≤ 120): The chart's title.
- `kind` (one of area, line, bar, donut, spark, required): The chart's shape.
- `source` (a source of the screen, required): The source whose rows it draws.
- `x` (column, required): The column along the x axis (a time or a label).
- `series` (list of 1–5: column, required): The number columns drawn, one series each.
- `format` (one of number, usd, percent, duration, bytes, default `number`): How values are written.

## Data

Reads the rows of `source`, in order.

Shape: one row per x value: `x` a time or label column, each of `series` a number column.

## Actions

None: this block only shows.

## States

- **ready**: the source's rows, drawn
- **empty**: the source has no rows: an Empty part saying why and what comes next
- **error**: the source failed: "We couldn't load …" naming the block's rows, the source's sentence and Try again; the page still answers 200

## Examples

### Closed and handed off per hour

```yaml
chart: { title: Closed per hour today, kind: bar, source: hourly, x: hour, series: [closed, handed_off] }
```

As an agent reads it:

```markdown
<a id="chart-1"></a>

**Closed per hour today** — bar chart, 3 points, hour 08:00 … 10:00

- closed: 31–52
- handed_off: 3–6

```

### Where the money goes

```yaml
chart: { title: Where the money goes this month, kind: donut, source: spend, x: category, series: [usd], format: usd }
```

As an agent reads it:

```markdown
<a id="chart-1"></a>

**Where the money goes this month** — donut chart, 4 points, category Agent results … Hosting

- usd: $780–$6,140

```

### Daily cost this week

```yaml
chart:
  title: Model cost per day
  kind: area
  source: daily
  x: day
  series: [cost_usd]
  format: usd
```

As an agent reads it:

```markdown
<a id="chart-1"></a>

**Model cost per day** — area chart, 4 points, day 2026-10-27 … 2026-10-30

- cost_usd: $188–$231

```

## Invalid

```yaml
chart: { kind: bars, source: hourly, x: hour, series: [closed] }
```

Answers: `chart.kind: unknown value bars; allowed: area, line, bar, donut, spark; did you mean bar?`

## Composition

- Sits in: screen, card, columns
- Pairs with: kpis, timeline, list
- Up to five series; two read best.
- Beside the list or timeline that explains it, in `columns`.
- Apple HIG: Keep charts simple and labelled, so the point is clear at a glance.

## Telemetry

chart.view

JSON Schema: [/catalog/chart.schema.json](/catalog/chart.schema.json)