Milestone

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

import * as MilestoneStories from './Milestone.stories';

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

<Title />

## Purpose

One milestone in a sequence: a dot on a line, a title, a subtitle and a short body, on a card or flat.

## 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 steps over time that people read in order, for example the stages of an application process. If the entry is something that happened, with a status icon and a time at the end of the row (a deploy, a check, an agent's work), use Timeline Item instead; the Timeline page compares them.

- Put it in a Milestone List; that draws the line and places the dots.
- Set `isActive` on the milestone in focus, such as the current step: its dot takes the accent color with a ring and it gets `aria-current='step'`. The others are neutral.
- `subtitle` is the quiet line in the secondary color: a date, a range, a stage or a short description. Where it goes is set on the Milestone List (`subtitlePosition`: above or below the title, or beside the dot). Pass it already formatted and translated; wrap a date in a `time` element if it needs a machine-readable value.
- `badgeLabel` adds a PDS Badge beside the subtitle, for example “You’re here”; it shows when the label is set. `badgeColor` sets its type (`info-muted` unless set) and `badgeSize` its size (`xs` unless set).
- The body (`children`) is everything under the title: put the description in it, then anything else (a table, a summary, a form). Blocks in it sit a small, fixed distance apart (`spacing-xs`).
- Set `headingLevel` to fit the page's outline.
- The card is the default Panel. It follows the Milestone List: `variant` there is `card` (default) or `flat`, for text on the line, and a milestone can set `variant` itself to differ from the rest.

## Implementation

The table below lists the props of the Milestone and of the Milestone List, and says which component each belongs to. The Milestone List page has the same table and the same examples, with several milestones together.

<hr />

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