## timeline (`poetry_timeline`)

A sequence of dated events as an ordered list.

Class: Poetry::Ui::Timeline::Component - BEM block `poetry-ui-timeline`.
Slot REQUIRED: with_item (at least one item (title:, with the description as its block)) - a call without it raises.
- `orientation:` (symbol) - one of vertical|horizontal, default "vertical" - The layout axis: :vertical reads as a feed, :horizontal as a step tracker.
Slots: items (Declares one event: title:, optional time: (renders a <time>), optional icon: (replaces the dot), completed: for progress - the description is the block.; many; with_item yields NOTHING to the block - no |param|, write content directly).
- PART `timeline` - The <ol> root - the event sequence | states: data-orientation=vertical|horizontal (always - the layout axis)
- PART `timeline-item` - One event (<li>): indicator + rail segment + header + description | states: data-completed (the step is done - recolors its indicator and rail segment)
- PART `timeline-indicator` - The decorative marker on the rail - a dot, or icon:'s glyph (aria-hidden; the sequence lives in the list semantics)
- PART `timeline-separator` - The decorative rail segment toward the next item - hidden on the last
- PART `timeline-header` - The title/time row
- PART `timeline-title` - The event's name
- PART `timeline-time` - The event's <time> - muted, small
- PART `timeline-content` - Muted description under the header (the item's block)
- RULE: A sequence of dated events (activity feed, order status, deploy history) is a Timeline - never a hand-rolled stack of dots and left borders (this is the <ol> the sequence owes its readers).
- RULE: Each with_item takes title:, optional time: (renders a <time>), optional icon: (swaps the dot for a glyph), completed: for progress - the description is the block.
- RULE: completed: colors the item's indicator and its rail segment - mark every step up to the current one, not just the latest.
- RULE: orientation: :horizontal lays the steps left-to-right (an order tracker); the vertical default reads as a feed. For steps the USER advances through, use Stepper - a Timeline records, it never navigates.