/// Data Display
Timeline
A vertical event history with square tone markers on a hairline connector — mono timestamp, sans body.
import { Timeline } from "@protocore/pds";Basics
Pass an events array. Each node gets a square tone marker on the connector, a sans title, an optional tone-coloured state word, and a right-aligned timestamp — pass a RelativeTime atom rather than a formatted string.
- Settlement batch closedsettled
- FX rates refreshed
- Retry scheduled for payout po_3390pending
Composed items
Compose Timeline.Item children when a node carries more than a headline — a detail line and a trailing meta row of actor chips, references, or deltas. Pass actors as RoleChip and ids as CodeRef so the history reads in the same atoms as the rest of the console.
- Transaction reversedreversed
Chargeback received from the issuing bank.
- Payout approvedapproved
Two-person review completed.
- Payout drafted
Marker tones
The marker tone (and the optional state word) carry each node's meaning, drawn from the same five-tone palette as Badge and StatusDot — so a red node means the same thing here as it does in a status column.
- Deploy startedrunning12:00
- Health checks passedhealthy12:02
- Canary latency elevatedwatch12:05
- Rollback triggeredfailed12:07
- Deploy closed12:08
When to use it
Timeline is for an ordered history of discrete events on one entity — an audit trail, a deploy log, a payout's lifecycle. The vertical connector and per-node markers make sequence and status legible at a glance.
It is structure only: it lays out the markers, titles, and timestamps and expects you to fill the slots with value atoms (RelativeTime for the timestamp, RoleChip for the actor, CodeRef for references). Reach for a DefinitionList instead when you're showing an entity's *current* fields rather than its history, and for Steps when you're guiding a user forward through a process rather than recording what already happened.
Usage
Do
- Use it for a chronological event history on a single entity (audit, deploy, lifecycle).
- Pass timestamps as a RelativeTime atom and actors as a RoleChip.
- Keep marker tones consistent with Badge/StatusDot so colour means the same everywhere.
- Put supporting references and deltas in the meta row, not the title.
Don't
- Don't use it for an entity's current fields — that's a DefinitionList.
- Don't use it as a forward-looking wizard — that's Steps.
- Don't bury the timestamp in the title; it has a dedicated right-aligned slot.
- Don't invent marker tones outside the five semantic ones.
Accessibility
- Timeline renders an ordered list (`<ol>` / `<li>`), so assistive tech announces the events as a numbered sequence in order.
- The markers and connector are `aria-hidden` decoration — meaning is carried by the title, the state word, and the timestamp text, never by marker colour alone.
- Because each node is static text, keyboard behaviour comes only from interactive atoms you place inside (e.g. a copyable CodeRef in the meta row).
Timeline props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | — | |
events | TimelineEvent[] | — | Events as data, an alternative to composing `Timeline.Item` children. |
style | CSSProperties | — |