Timeline

import { Canvas, Controls, Meta, Title } from '@storybook/addon-docs/blocks';

import * as TimelineStories from './Timeline.stories';

<Meta of={TimelineStories} name='Usage' />

<Title />

## Purpose

A list of events over time, with an optional rail that joins their icons.

## TL;DR: Chain of Thought, Timeline or Milestone List?

- **Chain of Thought:** an agent's reasoning under a reply, behind a summary line ("Thought for 17s") that opens on demand. No line, no rail.
- **Timeline:** events that happened or are happening, one line each (status icon, label, time). Always open, and the main content of a screen: a deploy history, an event log, an agent's run. Optional rail between the icons.
- **Milestone List:** steps people read in order, often still ahead of them, with a heading and a paragraph each on a card. One line runs down the whole list: the stages of an application process.

Quick test:

1. Do the steps sit under a reply and need to stay out of the way? **Chain of Thought.**
2. Otherwise, does each entry have a status icon or a time at the end of the row? **Timeline.**
3. Otherwise, does each have a heading and a paragraph? **Milestone List.**

A Chain of Thought is built from a Timeline and uses the same rows, and it can sit inside a Timeline as one entry in a log. Do not mix Timeline Items and Milestones in one list.

## Usage

Use it for an event log, a deploy history or an agent's run: anything that reads top to bottom in time order.

- Each child becomes a list item. `TimelineItem`s are joined by the rail; a divider, a Chain of Thought or a Thinking State in between breaks it.
- Turn on `hasRail` for a log of events over time, especially with timestamps, where people scan down to find when something happened. Dividers split the log into segments, since they break the rail.
- Leave it off where the list sits under a summary line, as in Chain of Thought, and for a short progress list with no timestamps; the status icons already show the order.
- For rows with large content under them (logs, diagrams, screenshots), start without a rail.
- To show an agent joining a log, put an agentic Labeled Divider before its items and mark them `isAgentic`.

## Implementation

See the table below for the available props. Timeline Item has its own page.

<hr />

<Canvas of={TimelineStories.Default} />
<Controls of={TimelineStories.Default} />