@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/time-input.usage.gts

@@ -0,0 +1,110 @@
+// Pretui — TimeInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { TimeInput } from './time-input';
+
+const HOUR_CYCLES = ['24', '12'];
+
+// ── TimeInput ← wa-time-input ────────────────────────────────────────────
+// Dropped knobs: the popup column picker + @withNow (wa-popup machinery
+// stays upstream), @min/@max/@step constraints, @placement, locale-aware
+// segment order (fixed hour:minute[:second] then AM/PM), @required/form
+// association, @size. Kept: the segmented spinbutton grammar itself —
+// arrows wrap with no carry, empty segments seed from now, two-digit
+// type-through, a/p keys, Backspace clears a segment.
+class TimeInputUsage extends Component {
+  cycleOptions = HOUR_CYCLES;
+  @tracked value = '09:41';
+  @tracked hourCycle = '24';
+  @tracked withSeconds = false;
+  @tracked disabled = false;
+  setValue = (v: string) => (this.value = v);
+  setHourCycle = (v: string) => (this.hourCycle = v);
+  setWithSeconds = (v: boolean) => (this.withSeconds = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get cycleVal() {
+    return this.hourCycle as '24' | '12';
+  }
+  get usage() {
+    let bits = [`@value='${this.value}'`];
+    if (this.hourCycle !== '24') bits.push(`@hourCycle='${this.hourCycle}'`);
+    if (this.withSeconds) bits.push('@withSeconds={{true}}');
+    bits.push('@onValueChange={{this.setValue}}');
+    return `<TimeInput ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='TimeInput'
+      @description="The Calendar family's clock: segmented HH:MM entry (optional seconds, AM/PM in 12-hour mode) speaking the same spinbutton grammar as the date pickers. Arrow keys wrap a segment with no carry into its neighbors, digits type through with the two-digit buffer rule, a/p set the day period, Backspace clears. Transcribed from wa-time-input's segmented field; the popup column picker stayed upstream."
+      @source={{this.usage}}
+    >
+      <:example>
+        <TimeInput
+          @value={{this.value}}
+          @hourCycle={{this.cycleVal}}
+          @withSeconds={{this.withSeconds}}
+          @disabled={{this.disabled}}
+          @onValueChange={{this.setValue}}
+        />
+        <p class='pretui-demo-readout' data-test-time-readout>
+          value = “{{this.value}}”
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @description="Wire value — 'HH:MM', or 'HH:MM:SS' with @withSeconds (native input[type=time] format). Omit and seed @defaultValue for uncontrolled use."
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='hourCycle'
+          @defaultValue='24'
+          @value={{this.hourCycle}}
+          @options={{this.cycleOptions}}
+          @description="'12' adds the AM/PM segment and re-displays hours as 1–12; the wire value stays 24-hour."
+          @onInput={{this.setHourCycle}}
+        />
+        <Args.Bool
+          @name='withSeconds'
+          @defaultValue={{false}}
+          @value={{this.withSeconds}}
+          @description='Adds the seconds segment and the :SS wire suffix.'
+          @onInput={{this.setWithSeconds}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='label'
+          @defaultValue='Time'
+          @description='Group label announced by assistive tech; each segment carries its own spinbutton label (Hour / Minute / Second / AM-PM).'
+        />
+        <Args.String
+          @name='defaultValue'
+          @description='Uncontrolled seed for the internal segments.'
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description="Receives the wire string once all segments are filled, and '' when an edit makes the value incomplete."
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TIME_INPUT: Record<string, unknown> = {
+  TimeInput: TimeInputUsage,
+};

package/bundled-realms/pretui/components/timeline.gts

@@ -0,0 +1,269 @@
+// Pretui — Timeline: an ordered list of events with a decorative rail.
+import Component from '@glimmer/component';
+import { Avatar } from './avatar';
+import { StatusChip } from './status-chip';
+import { Token } from './token';
+import { RelativeTime } from './relative-time';
+import { iconFor } from '../icon-registry';
+
+// ── Timeline ─────────────────────────────────────────────────────────────
+// A chronological sequence, semantically an ordered list.
+//
+// The rail and the markers are pure chrome: the rail is a CSS pseudo-element
+// (invisible to assistive tech by construction) and the marker span carries
+// aria-hidden, so a screen reader reads "1. Lot B-1181 cupped — 3 days ago"
+// and not a stream of bullet noise. Everything with meaning is composed from
+// the kit: StatusChip (hue derived from the value, Law 2), Token (machine
+// values as jewelry, Law 3), RelativeTime (timer-free, @now supplied by the
+// caller), Avatar.
+//
+// Dropped from the upstream surfaces: left/right alternating layout (MUI's
+// signature look — it doubles the CSS, halves the line length, and reads as
+// two unrelated columns at narrow widths), the "opposite content" slot that
+// exists only to feed that layout, and per-event duration bars (that is
+// <Meter> or <ProgressBar> composed into the <:default> block).
+
+export interface TimelineEvent {
+  /** stable id — the {{#each}} key */
+  id: string;
+  /** the headline for this moment */
+  title: string;
+  /** ISO date/time → RelativeTime, rendered against @now */
+  at?: string;
+  /** status value → StatusChip */
+  status?: string;
+  /** machine value (lot id, version, batch) → Token */
+  token?: string;
+  /** person's name → Avatar + name */
+  person?: string;
+  /** one paragraph of detail; the <:default> block replaces it */
+  body?: string;
+  /** icon-registry name for the marker; omitted markers are a dot */
+  icon?: string;
+}
+
+export interface TimelineSignature {
+  Args: {
+    /** the events, oldest or newest first — the order you pass is the order
+     * rendered and numbered */
+    events: TimelineEvent[];
+    /** 'expanded' (default) gives each event a body block and a large marker;
+     * 'compact' collapses to one line per event */
+    density?: 'compact' | 'expanded';
+    /** the instant relative times are measured against; the realm forbids
+     * timers, so nothing ticks — pass a fresh @now to re-derive */
+    now?: string | Date;
+    /** accessible name for the list */
+    label?: string;
+  };
+  Blocks: {
+    /** replaces @body — receives the event */
+    default?: [event: TimelineEvent];
+    /** replaces the marker glyph — receives the event */
+    marker?: [event: TimelineEvent];
+  };
+  Element: HTMLElement;
+}
+
+export class Timeline extends Component<TimelineSignature> {
+  get density(): 'compact' | 'expanded' {
+    return this.args.density ?? 'expanded';
+  }
+  get label(): string {
+    return this.args.label ?? 'Timeline';
+  }
+  iconOf = (event: TimelineEvent) => iconFor(event.icon);
+
+  <template>
+    {{! role='list' is not redundant: list-style:none strips list semantics
+        in Safari/VoiceOver, and the lint rule allows ol+list }}
+    <ol
+      class='pretui-timeline'
+      role='list'
+      data-density={{this.density}}
+      aria-label={{this.label}}
+      data-test-pretui-timeline
+      ...attributes
+    >
+      {{#each @events key='id' as |event|}}
+        <li class='pretui-timeline-event'>
+          <span class='pretui-timeline-marker' aria-hidden='true'>
+            {{#if (has-block 'marker')}}
+              {{yield event to='marker'}}
+            {{else}}
+              {{#let (this.iconOf event) as |EventIcon|}}
+                {{#if EventIcon}}
+                  <EventIcon class='pretui-timeline-glyph' />
+                {{else}}
+                  <span class='pretui-timeline-dot'></span>
+                {{/if}}
+              {{/let}}
+            {{/if}}
+          </span>
+          <div class='pretui-timeline-body'>
+            <div class='pretui-timeline-head'>
+              <span class='pretui-timeline-title'>{{event.title}}</span>
+              {{#if event.token}}<Token @value={{event.token}} />{{/if}}
+              {{#if event.status}}<StatusChip @value={{event.status}} />{{/if}}
+              {{#if event.at}}
+                <RelativeTime
+                  class='pretui-timeline-when'
+                  @date={{event.at}}
+                  @now={{@now}}
+                />
+              {{/if}}
+            </div>
+            {{#if (has-block)}}
+              <div class='pretui-timeline-detail'>{{yield event}}</div>
+            {{else if event.body}}
+              <p class='pretui-timeline-detail'>{{event.body}}</p>
+            {{/if}}
+            {{#if event.person}}
+              <span class='pretui-timeline-person'>
+                <Avatar @name={{event.person}} @size={{18}} />
+                {{event.person}}
+              </span>
+            {{/if}}
+          </div>
+        </li>
+      {{/each}}
+    </ol>
+    <style scoped>
+      /* above RelativeTime's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-timeline {
+          /* one gap and one rail width, resolved once on the root so the
+             pseudo-element rail can never drift from the row spacing */
+          --_gap: var(--pretui-timeline-gap, 14px);
+          --_rail: var(--pretui-timeline-rail, 24px);
+          container-type: inline-size;
+          list-style: none;
+          margin: 0;
+          padding: 0;
+          display: grid;
+          gap: var(--_gap);
+          min-width: 0;
+        }
+        .pretui-timeline[data-density='compact'] {
+          --_gap: var(--pretui-timeline-gap, 4px);
+          --_rail: var(--pretui-timeline-rail, 16px);
+        }
+        .pretui-timeline-event {
+          position: relative;
+          display: grid;
+          grid-template-columns: var(--_rail) 1fr;
+          gap: var(--space-3, 8px);
+          min-width: 0;
+        }
+        /* the rail: chrome only, drawn by a pseudo-element so assistive tech
+           never sees it (Law 1 — a hairline, never a contrast block) */
+        .pretui-timeline-event::before {
+          content: '';
+          position: absolute;
+          left: calc(var(--_rail) / 2);
+          top: 0;
+          bottom: calc(var(--_gap) * -1);
+          width: 1px;
+          background: var(--border);
+        }
+        .pretui-timeline-event:last-child::before {
+          display: none;
+        }
+        .pretui-timeline-marker {
+          position: relative;
+          z-index: 1;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          width: var(--_rail);
+          height: var(--_rail);
+          border-radius: 50%;
+          background: var(--card);
+          color: var(--muted-foreground);
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+        }
+        .pretui-timeline-glyph {
+          width: 13px;
+          height: 13px;
+        }
+        .pretui-timeline-dot {
+          width: 6px;
+          height: 6px;
+          border-radius: 50%;
+          background: var(--pretui-primary-ink, var(--primary));
+        }
+        .pretui-timeline-body {
+          display: grid;
+          gap: 4px;
+          min-width: 0;
+          padding-bottom: 2px;
+        }
+        .pretui-timeline-head {
+          display: flex;
+          align-items: center;
+          flex-wrap: wrap;
+          gap: 6px;
+          min-width: 0;
+        }
+        .pretui-timeline-title {
+          font-size: var(--text-ui-md, 12.5px);
+          font-weight: 600;
+          color: var(--foreground);
+          min-width: 0;
+        }
+        .pretui-timeline-when {
+          margin-left: auto;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+        }
+        .pretui-timeline-detail {
+          margin: 0;
+          font-size: var(--text-ui-md, 12.5px);
+          color: var(--muted-foreground);
+          line-height: 1.5;
+          max-width: 62ch;
+        }
+        .pretui-timeline-person {
+          display: inline-flex;
+          align-items: center;
+          gap: 6px;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+        }
+        /* compact: one line per event, small marker, no marker chrome */
+        .pretui-timeline[data-density='compact'] .pretui-timeline-event {
+          align-items: center;
+        }
+        .pretui-timeline[data-density='compact'] .pretui-timeline-marker {
+          /* no hairline ring at this size — the dot alone punches the rail */
+          box-shadow: none;
+        }
+        .pretui-timeline[data-density='compact'] .pretui-timeline-glyph {
+          width: 11px;
+          height: 11px;
+        }
+        .pretui-timeline[data-density='compact'] .pretui-timeline-body {
+          gap: 2px;
+          padding: 3px 0;
+        }
+        .pretui-timeline[data-density='compact'] .pretui-timeline-detail {
+          font-size: var(--text-ui-sm, 11.5px);
+        }
+        /* unnamed container query — resolves against the .pretui-timeline
+           ancestor container, so it may only style descendants */
+        @container (max-width: 26rem) {
+          .pretui-timeline-when {
+            margin-left: 0;
+          }
+          .pretui-timeline-detail {
+            max-width: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/timeline.md

@@ -0,0 +1,63 @@
+## What it is
+
+A chronological sequence rendered as an ordered list with a vertical rail: audit trails, order history, a record's lifecycle, a batch's journey. Use it when the _order_ and the _when_ are both load-bearing. If items arrive continuously and the reader pages through them, **Feed** is the right pattern (and has the ARIA for it). If the sequence is a process the user is completing, **StepList**. If it is just a list, a list.
+
+## The contract
+
+```
+@events: TimelineEvent[]   { id, title, at?, status?, token?, person?, body?, icon? }
+@label?, @density? ('expanded' | 'compact'), @now?
+<:default>   — replaces the body
+Element: an <ol>
+```
+
+**The order you pass is the order rendered and numbered.** No sorting, no reversing. Newest-first and oldest-first are both legitimate and the component refuses to guess.
+
+**The event fields map onto kit components rather than to strings:** `status` → **StatusChip** (hue derived from the value, Law 2), `token` → **Token** (machine values as jewelry, Law 3), `at` → **RelativeTime** (timer-free, `@now` supplied by the caller), `person` → **Avatar** plus name. That is the interesting design decision: the data shape is declarative, and the visual vocabulary is the kit's, so every timeline in a product looks the same and none of them invent their own status colours.
+
+`@density='compact'` collapses each event to one line with a smaller marker and no marker ring; `expanded` gives each a body block.
+
+## Prior art
+
+**MUI `Timeline`** and the shadcn-community timelines are the references, and the criticism the source makes of them is specific and correct: **their rail is real DOM content** — connector `<span>`s and dot `<span>`s that a screen reader dutifully reads out as noise between every pair of items.
+
+Pretui's departures:
+
+- **The rail is a CSS pseudo-element** and therefore invisible to assistive tech by construction; the marker span carries `aria-hidden`. A screen reader reads "1. Lot B-1181 cupped — 3 days ago" and no bullet noise. This is the single best thing about the component.
+- **It is a real `<ol>`**, so items are numbered and counted by the reader.
+- **No left/right alternating layout.** MUI's signature look is dropped deliberately: it doubles the CSS, halves the line length, and reads as two unrelated columns at narrow widths. The "opposite content" slot that exists only to feed that layout goes with it.
+- **No per-event duration bars** — compose **Meter** or **ProgressBar** into the default block.
+
+Where it is behind MUI: no alternating layout (if you want that look, you cannot have it), no horizontal orientation, and no built-in grouping by day.
+
+The narrow-container behaviour uses an **unnamed container query** — named ones are forbidden in realm code, because the scoped-CSS transpiler silently drops every rule after one — so the timeline reflows against its pane rather than the viewport. Same constraint and same payoff as **FormLayout**.
+
+## Accessibility
+
+No APG pattern; a timeline is a list, governed by WCAG **1.3.1** and **1.3.2 Meaningful Sequence**.
+
+What is right:
+
+- **`<ol>` with `role="list"` set explicitly.** The explicit role is not redundant: `list-style: none` strips list semantics in Safari/VoiceOver, so an unstyled list silently stops being announced as a list. The source calls this out, and most kits ship the bug.
+- **All chrome is `aria-hidden` or a pseudo-element** (above). The reading experience is the content and nothing else.
+- **`aria-label` on the list** gives the sequence a name.
+- **Composed components carry their own semantics**: `RelativeTime` supplies a machine-readable timestamp, `StatusChip` supplies text, `Avatar` supplies a name.
+
+Gaps:
+
+- **Timestamps are relative, and relative time is ambiguous.** "3 days ago" is what **RelativeTime** renders; it renders a `<time datetime>` carrying the exact timestamp, but screen readers announce the relative text, not the attribute. For an audit trail, where the exact timestamp is often what a user needs, put the absolute date in the item's own text.
+- **`@now` is caller-supplied** (realm components own no timers), so a stale `@now` produces stale relative times with no indication. On a long-lived page "3 days ago" can quietly become wrong.
+- **Event `title` is not a heading.** A long timeline has no structure to navigate by; a screen-reader user reads it linearly or not at all.
+- **The status is announced as a bare word** ("Cupped") with no indication that it is a status rather than part of the title. **StatusChip**'s own note applies: a chip has no accessible relationship to the property it is the value of.
+- **No `aria-current`** for a "you are here" event, if the timeline shows one.
+- **Icons come from the icon registry via `@icon`** and are inside the `aria-hidden` marker, so a meaningful icon (error, warning) conveys nothing to assistive tech. Put the meaning in `status` or `title`.
+
+## Theming
+
+Rail and markers: `--border` (rail), `--card` (marker fill), `--pretui-shadow-hairline` (the marker ring, removed at compact density), plus the marker glyph's ink. Content: `--foreground`, `--muted-foreground`, `--text-ui-md`, `--text-ui-sm`. Composed components bring their own — **StatusChip**'s `--chart-*` palette, **Token**'s `--pretui-token-hue`, **Avatar**'s hash palette.
+
+The 11px compact glyph, the marker sizes and the rail width are fixed; density is an arg, not a token.
+
+Because the rail is a pseudo-element behind opaque markers, a theme must keep `--card` (the marker fill) opaque and distinct from `--border` — a transparent or near-border marker fill lets the rail show through and the sequence stops reading as discrete moments.
+
+The styles sit in `@layer PretComposite`, above RelativeTime's `PretComponent` layer, so what this component sets on RelativeTime wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.

package/bundled-realms/pretui/components/timeline.usage.gts

@@ -0,0 +1,180 @@
+// Pretui — Timeline usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Timeline } from './timeline';
+import type { TimelineEvent } from './timeline';
+import { NOW } from '../demo-structure-data';
+
+// ── Timeline ← MUI Timeline / shadcn-community timelines ─────────────────
+const NOW_OPTIONS = [
+  '2026-04-03T10:00:00Z',
+  '2026-05-20T10:00:00Z',
+  '2026-08-12T10:00:00Z',
+  '2027-01-09T10:00:00Z',
+];
+
+// Lot B-1181's life, from booking to the curing room. The events carry
+// exactly the four composed pieces the component knows how to place: a
+// StatusChip (hue derived from the value), a Token (the machine value), a
+// RelativeTime (measured against @now), and an Avatar for the person.
+const SHIPMENT: TimelineEvent[] = [
+  {
+    id: 'booked',
+    title: 'Spring lot booked',
+    at: '2026-03-14T09:20:00Z',
+    status: 'confirmed',
+    token: 'B-1181',
+    person: 'Mei-Lin Chua',
+    icon: 'check',
+    body: 'Wuyi Origins confirmed 48 crates of Da Hong Pao against the spring booking. The deposit cleared the same afternoon and the pick window was fixed at two weeks either side of 12 April.',
+  },
+  {
+    id: 'picked',
+    title: 'Leaf picked at Wuyishan',
+    at: '2026-04-02T23:40:00Z',
+    status: 'complete',
+    person: 'Ryo Katagiri',
+    icon: 'sparkles',
+    body: 'Four days early — the estate called the weather and moved. Yield came in at 51 crates, three over the booking, which the desk took at the quoted rate.',
+  },
+  {
+    id: 'cupped',
+    title: 'Cupping notes filed',
+    at: '2026-04-19T08:05:00Z',
+    status: 'approved',
+    token: 'score 93',
+    person: 'Ingrid Halvorsen',
+    icon: 'star',
+    body: 'Blind against the selling sample, three cups. Above the ninety band, so the lot goes to the ceremonial menu rather than the house blend.',
+  },
+  {
+    id: 'shipped',
+    title: 'Container left Fuzhou',
+    at: '2026-05-07T16:00:00Z',
+    status: 'in transit',
+    token: 'MSKU-4471290',
+    icon: 'send',
+    body: 'Sea freight, paperwork sent ahead of the vessel with the cupping certificate attached.',
+  },
+  {
+    id: 'held',
+    title: 'Held for customs paperwork',
+    at: '2026-06-11T11:30:00Z',
+    status: 'blocked',
+    person: 'Yusuf Demirci',
+    icon: 'triangle-alert',
+    body: 'Phytosanitary certificate named the cultivar but not the estate. Re-issued and cleared in nine days.',
+  },
+  {
+    id: 'received',
+    title: 'Received at the curing room',
+    at: '2026-06-30T07:15:00Z',
+    status: 'complete',
+    token: '51 crates',
+    person: 'Zanele Mokoena',
+    icon: 'folder',
+    body: 'Logged at 58% relative humidity. Re-weighed against the bill of lading with no discrepancy.',
+  },
+];
+
+const TIMELINE_DENSITIES = ['expanded', 'compact'];
+
+class TimelineUsage extends Component {
+  events = SHIPMENT;
+  densityOptions = TIMELINE_DENSITIES;
+  nowOptions = NOW_OPTIONS;
+
+  @tracked density = 'expanded';
+  @tracked label = 'Lot B-1181 — shipment history';
+  @tracked now = NOW;
+
+  setDensity = (v: string) => (this.density = v);
+  setLabel = (v: string) => (this.label = v);
+  setNow = (v: string) => (this.now = v);
+
+  get densityVal() {
+    return this.density as 'compact' | 'expanded';
+  }
+  get usage() {
+    let bits = ['@events={{this.events}}', `@label='${this.label}'`];
+    if (this.density !== 'expanded') bits.push(`@density='${this.density}'`);
+    bits.push(`@now='${this.now}'`);
+    return `<Timeline\n  ${bits.join('\n  ')}\n/>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Timeline'
+      @description="A chronological sequence — a shipment's life, an audit trail, a release history. Semantically it is an ordered list and nothing else: role='list' is stamped explicitly because list-style:none strips list semantics in Safari/VoiceOver, and the rail is a CSS pseudo-element while the marker span carries aria-hidden, so a screen reader hears '1. Spring lot booked, confirmed, B-1181, 5 months ago' and not a stream of bullet noise. Everything with meaning is composed from the kit rather than hand-drawn: StatusChip (hue derived from the value, never picked), Token for machine values, RelativeTime for the when, Avatar for the who. Relative times are timer-free — pass a fresh @now to re-derive them, which is what the 'now' knob below does. Honest limits: no left/right alternating layout and no opposite-content slot (they double the CSS, halve the line length, and read as two unrelated columns at narrow widths), and no per-event duration bars — compose a <Meter> or <ProgressBar> into the default block instead."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='sd-pad'>
+          <Timeline
+            @events={{this.events}}
+            @density={{this.densityVal}}
+            @label={{this.label}}
+            @now={{this.now}}
+          />
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='events'
+          @required={{true}}
+          @value={{this.events}}
+          @description='The events, in the order you want them rendered and numbered — oldest-first or newest-first, the component does not sort. Each TimelineEvent is { id, title, at?, status?, token?, person?, body?, icon? }.'
+        />
+        <Args.String
+          @name='density'
+          @value={{this.density}}
+          @options={{this.densityOptions}}
+          @defaultValue='expanded'
+          @description="'expanded' gives each event a body and a ringed marker; 'compact' tightens the rail to 16px, drops the marker ring and collapses each event toward a single line."
+          @onInput={{this.setDensity}}
+        />
+        <Args.String
+          @name='now'
+          @value={{this.now}}
+          @options={{this.nowOptions}}
+          @description='The instant relative times are measured against. Nothing ticks — the realm forbids timers — so move this to re-derive every phrase at once.'
+          @onInput={{this.setNow}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='Timeline'
+          @description='Accessible name for the list.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Yield
+          @name=':default'
+          @description='Replaces the event body. Receives the event, so a caller can render a diff, a card, or a Meter where the paragraph would go.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name=':marker'
+          @description='Replaces the marker glyph. Receives the event. The marker stays aria-hidden whatever you put in it — it is chrome by construction, so put nothing in it that a reader must parse.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .sd-pad {
+        padding: var(--space-4, 11px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+        min-width: 0;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TIMELINE: Record<string, unknown> = {
+  Timeline: TimelineUsage,
+};