# timeline

What happened, in time order, such as everything an agent did on a ticket, with who did it and how it went.

`source` names a source of the screen with one row per event; `at` is the column holding the ISO time, `title`
what happened. `detail` (a line under it), `actor` (who or what acted) and `tone` (a column whose values are
`neutral`, `ok`, `warn`, `bad` or `info`) are optional. Events show in the source's order, so set the source's
`order` (`at` oldest first, `-at` newest first); at most 100 are shown.

Category: data. Tier 1. Contract version 1.

## When to use

- Everything that happened on one record, such as the steps an agent took on a ticket.
- The latest events across a queue, newest first.
- An audit trail a person reads to answer "who did what, and when".

## When to use another block

- Rows a person sorts, filters or acts on. Use [`grid`](/catalog/grid.md).
- A trend of counts over time. Use [`chart`](/catalog/chart.md).
- A few links with a title each. Use [`list`](/catalog/list.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.
- `source` (a source of the screen, required): The source whose rows are the events (at most 100 shown).
- `at` (column, required): The column holding each event's time (ISO-8601 text).
- `title` (column, required): The column holding each event's title.
- `detail` (column): The column holding a line of detail.
- `actor` (column): The column naming who or what acted.
- `tone` (column): The column holding each event's tone: neutral, ok, warn, bad or info.

## Data

Reads the first 100 rows of `source`, in the source's order.

Shape: one row per event: an ISO-8601 `at`, a `title`, optional detail, actor and tone columns.

## 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

### What happened on a ticket

```yaml
timeline: { source: events, at: at, title: title, detail: detail, actor: actor, tone: tone }
```

As an agent reads it:

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

- 2026-10-31 09:12 · Opened by M. Okafor from the portal — Device, office and last 10 VPN events attached (portal)
- 2026-10-31 09:12 · Network agent read the ticket and the VPN logs — Matched a known pattern (Network agent)
- 2026-10-31 09:20 · Requester confirmed the fix (M. Okafor)

```

### The latest events, titles only

```yaml
timeline: { id: latest, source: events, at: at, title: title }
```

As an agent reads it:

```markdown
<a id="latest"></a>

- 2026-10-31 09:12 · Opened by M. Okafor from the portal
- 2026-10-31 09:12 · Network agent read the ticket and the VPN logs
- 2026-10-31 09:20 · Requester confirmed the fix

```

### Who changed an agent

```yaml
timeline:
  source: audit
  at: at
  title: what
  actor: who
```

As an agent reads it:

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

- 2026-10-30 16:02 · Procurement agent turned on (A. Lindqvist)
- 2026-10-31 08:40 · Monthly budget raised to $120 (A. Lindqvist)

```

## Invalid

```yaml
timeline: { source: events, at: at, title: summary }
```

Answers: `example.blocks[0].timeline.title: no column summary in the source events; allowed: actor, at, detail, id, title, tone`

## Composition

- Sits in: screen, card, columns
- Pairs with: markdown, approval, chart
- Ten to twenty events read well; past that, link to a grid.
- Apple HIG: Show progress and history in a clear order, with the most useful detail first.

## Telemetry

timeline.view

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