Timeline Map

Preview

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

npx shadcn@latest add https://ds.interlace.tools/r/timeline-map.json

npx shadcn@latest add @interlace/timeline-map

Import

4 named exports — pull the parts you need.

import { TimelineMap, TimelineMapAxis, computeTimelineLayout, computeTracePath } from '@/components/ui/patterns/timeline-map';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

(R11 — compound, one memoized context R15)
  <TimelineMap items={…} data-testid="…">
    <TimelineMap.Filter />          — optional category chips (aria-pressed)
    <TimelineMap.Chart />           — axis header + lanes + dots
    <TimelineMap.Detail />          — fixed-height preview strip (CLS=0, R23)
  </TimelineMap>
### Keyboard (R26)
| Key            | Action                                              |
| -------------- | --------------------------------------------------- |
| Tab            | One stop: the current dot (roving tabindex)         |
| → / ←          | Next / previous dot in chronological order          |
| Home / End     | First / last visible dot                            |
| Enter          | Activate the dot's link (native anchor)             |
The app version made every dot a tab stop (89 stops on the blog corpus —
hostile). Roving tabindex per APG: one stop, arrows traverse.
### API parity (R17)
- `onItemClick(item)` mirrors MUI DataGrid's `onRowClick`: the anchor is
  an internal part, so the DS surfaces its activation; navigation itself
  stays native.
- `filter` + `defaultFilter` + `onFilterChange` follow the MUI/shadcn
  controlled+uncontrolled convention (R14). URL-state wiring is the
  consumer's job — the DS never touches routers.
- `linkComponent` (R10 `xxxComponent`) injects a framework Link; default
  is a plain anchor.
### Encoding contract
x = the shared continuous axis — dates by default, or any numeric
measure via `axis={{ kind: "number", format }}` (reading minutes,
bundle KB): a landscape of category × whatever quantity the corpus
is actually navigated by. Row = category, dot diameter = optional
`weight` (0..1 → 10–16px; the Detail strip must spell the value out —
size is never the only carrier). Marks are single-hue `strand-a` (R19
token): identity is carried spatially by labeled lanes, so no
multi-hue palette is needed and none is offered.
Same-(lane, day) groups fan into a center-first 3-row beeswarm (a solo
dot sits centered; burst rows cap radius for lane-border clearance) —
without the fan, 43 of the blog's 89 dots were perfectly stacked.
Static markup is SSR-honest: every item renders as a real anchor with
its accessible name; no floating tooltip (the Detail strip reserves its
height).
### Fit-all width
The strip stretches to fill the container (ResizeObserver), so the
WHOLE territory — every item — is visible at once whenever space
allows. 560px is the floor: below it the strip keeps its size and
scrolls internally, resting at the recent end (state, not motion —
reduced-motion safe). SSR renders honestly at the floor.
### The link weave
`item.links` declares the corpus's internal reference graph, drawn as
strand-b threads between dots — the map shows not just WHEN and WHERE
things were published but how they weave into each other (the division
has an agenda; the threads make it legible). Interaction grammar from
the engage network graph: at rest the web is faint; touching a dot
(hover or keyboard focus — both set `previewed`) lights ITS threads
and recedes everything unrelated. State changes are instant — the
motion vocabulary stays draw/decode. The overlay is aria-hidden; the
Detail strip speaks the same links ("weaves into …") for screen
readers and crawlers.

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour

Native element semantics — no interaction layer to get wrong.

Focus ring (WCAG 2.2 SC 2.4.13)

Inherited from the preflight focus contract shipped in @interlace/theme.

Reduced motion

No animation to gate.

ARIA in the source

• role="group"
• aria-label
• aria-live

Examples

5 more states from the same story file.

Dependencies

Base UI primitive

Native / no Base UI dependency

Lucide icons

none

NPM dependencies

none

Registry dependencies

• @interlace/theme
• @interlace/cn
• @interlace/toggle

Source

The full implementation — components/ui/patterns/timeline-map.tsx once installed.

'use client';

import * as React from 'react';

// @interlace/timeline-map v1.3.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/timeline-map
// What changed since: https://ds.interlace.tools/c/timeline-map#history
// Generated banner — keep it, the upgrade diff reads this version.

import { cn } from '@/lib/utils';
import { Toggle } from '@/components/ui/toggle';

/**
 * TimelineMap — dated entities as linked dots on a shared time axis, one
 * labeled strip per category lane.
 *
 * ## RFC (R3)
 *
 * Generalized from the blog's corpus map (100/100 Lighthouse accessibility
 * + agentic on the live site), born complete with the two rungs the app

…1056 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.