Time Series
One metric over time, with the actions that moved it drawn ON the curve.
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/time-series.jsonnpx shadcn@latest add @interlace/time-seriesBehavior
What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.
5 steps, 7 key presses — replayed on every PR by the play function of RangeComparison. Axe cannot press a key, so this — not the a11y scan — is what proves the component is operable without a mouse.
- 1marking one point does not yet claim a changeHomeEnter
- 2a second point turns the readout into a deltaEndEnter
- 3the direction is exposed as data, not only as colour
- 4the live region keeps announcing after the range is lockedArrowLeft
- 5a third mark starts a new rangeHomeEnter
9 states, one closed union — not a boolean per condition. Partial is a state, not an absence: a spinner that hides progress, or a missing prior rendered as 0, is the failure this model exists to make impossible.
| State | Reads as | Role | Encoding |
|---|---|---|---|
| loading | loading | Stands instead of the body | muted |
| error | ! error | Stands instead of the body | danger |
| not-applicable | n/a | Stands instead of the body | hatchedrecede |
| not-counted | not counted | Stands instead of the body | hatchedmuted |
| empty | — none | Stands instead of the body | muted |
| partial | ≥ partial | Stands next to the body and changes how to read it | dashedmuted |
| truncated | ⋯ truncated | Stands next to the body and changes how to read it | dashedmuted |
| first-measurement | · first measurement | Stands next to the body and changes how to read it | dashedaccent |
| idle | — | The absence of absence | muted |
Hatched and dashed are the two absences drawn apart on purpose: not-counted means no measurement was taken and is never a zero; truncated means the total is unknown and must never be used as a denominator. Each state also carries a spoken announcement — transitions, never ticks.
Measured contrast
packages/ui/__tests__/theme-contract-lock.test.ts ↗Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is viz-axis on card at 3.54:1 (interlace · dark), against a floor of 3:1.
| Pair | interlacelight | interlacedark | harborlight | harbordark | Floor |
|---|---|---|---|---|---|
| viz-axis on cardchart axis inside a card | 3.64:1 | 3.54:1 | 3.77:1 | 4.39:1 | 3.0:1SC 1.4.11 |
| viz-axis on backgroundchart axis (SC 1.4.11) | 3.64:1 | 3.82:1 | 3.57:1 | 4.84:1 | 3.0:1SC 1.4.11 |
| destructive on backgrounddestructive tint on the page surface | 8.31:1 | 10.43:1 | 7.60:1 | 10.03:1 | 3.0:1SC 1.4.11 |
| muted-foreground on backgroundsecondary copy | 9.41:1 | 11.32:1 | 7.82:1 | 9.52:1 | 4.5:1SC 1.4.3 |
| destructive on carddestructive tint inside a card | 8.31:1 | 9.66:1 | 8.02:1 | 9.09:1 | 3.0:1SC 1.4.11 |
| muted-foreground on cardsecondary copy in a card | 9.41:1 | 10.48:1 | 8.25:1 | 8.64:1 | 4.5:1SC 1.4.3 |
| foreground on backgroundbody copy | 19.65:1 | 16.97:1 | 17.74:1 | 16.19:1 | 4.5:1SC 1.4.3 |
Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.
Text equivalent
packages/ui/src/charts/time-series.tsx ↗A chart's alt text is not a sentence about the chart — the equivalent of the data is the data. This is what a screen reader gets, read out of the source the install writes into your tree.
Renders <SeriesTable> alongside the graphic: every plotted value is available as a real table row, sr-only by default.
Runtime contract
packages/ui/vitest.config.ts ↗Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.
- Render boundary
'use client'Hydrates. It brings JavaScript to any route that imports it — put the boundary here, not at the page.
- Minimum viewport
MIN_VIEWPORT = 320Declared, not assumed. Below 320 CSS px the preflight contract draws a dev-mode outline — how to switch it on.
- Coverage gate
100% × 4Inside the v8 gate: lines 100, statements 100, functions 100, branches 100. A threshold under 100 only records how much you stopped caring, so there isn't one.
History
This component is at v1.2.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.
Unreleased3 entries
- Addedminor
TimeSeries — mark two points, read the change between them Marking a point (click, or Enter from the keyboard) sets an anchor; marking a second turns the readout into a comparison —
2026-06-01 → 2026-08-01with the absolute change, the percentage and the direction — and shades the span between them on the plot. A third mark starts a new range; Escape clears. The gesture most charts implement as a pointer drag, which no keyboard user can perform. Here both paths resolve through oneselect(), so they cannot disagree about what is selected. The delta is rendered byDeltarather than recomputed, so the sign, the percentage, the tone token and the WCAG 1.4.1 accessible name all come from one place. A point compared with itself clears the selection instead of reporting 0%, and a range with a gap at either end shows nothing rather than bridging it. - Addedminor
The Living Weave — motion, the radial poster form, and the strand field **TimeSeries draws itself.** The plotted series and their annotations are revealed by a clip rect that scales open left→right — the new
--animate-weave-revealtoken, the draw verb's second mechanism for a chart whose dash patterns ARE series identity (MOTION_PHILOSOPHY's draw-gesture exception gains the clip-reveal clause, and the motion lock verifies the utility only ever lands on aclipPathchild). Pure CSS, SSR-drawn, from-only — with no animation at all, nothing is ever hidden. The reveal replays when the drawn geometry changes BY VALUE, never by array identity; the same change resets the crosshair during render. The crosshair now glides between slots on a transform transition (150ms, motion-reduce clamped) while the readout still snaps. **RadialWeave** — the same series wrapped around a dial: the POSTER form. 300° sweep with the gap at the bottom (a closed circle claims the newest observation meets the oldest), the exact dash+hue identity table TimeSeries uses, nulls breaking the arc, an HTML centre value, and deliberately no crosshair — the aria-label sentence, the min/max readout and the losslessSeriesTablecarry inspection. Server component; dial math lives inscale.ts(dialAngle/dialRadius/dialPoint/dialPath/dialRing). **StrandField** — real series lifted into depth: each thread on its own plane in a CSS-3D perspective stage (zero dependencies —perspective+translateZ, never WebGL), fanned apart or collapsed flat viawoven, tilting inside its own bounds with the pointer (never underprefers-reduced-motion), strands entering by the strand-draw verb with a CSS-variable stagger the reduce clamp can zero.aria-hiddentheatre with no focusable element;onStrandSelectis a pointer shortcut for a selection surface the consumer renders accessibly.Components - Changedpatch
TimeSeries — the first mark stays visible, and Space is documented Two review findings from the consumer side. Tapping once left no visible trace: the pointer leaves,
cursorgoes null, and the whole marker disappeared with it. For touch that is the normal state between the first tap and the second, so a touch user had no sign their mark had registered. The selection was always kept in state; only the evidence was missing. The anchor edge is now drawn whether or not a second edge exists. The accessible name promised Enter but Space has always worked too, so the key existed for anyone who guessed it and nobody else.
@interlace/ui 1.1.02 entries
- Addedminor
New
Distributionchart — a quantity spread over a fixed set of named bins, read against a reference distribution. It is a new component rather than an extension ofTimeSeriesbecause three of that component's properties are chronological and cannot be parameterised out: its axis keys are sorted (['Thu','Fri','Sat']sorts into a week that does not exist), a line asserts the metric passed through every value between two samples when between two hourly aggregates there is nothing to pass through, anddelta()first-to-last is arithmetic performed on a circle. An unmeasured bin **hatches**. Everywhere else anullcan simply be dropped, but for bars a height of zero and a bar never drawn are the same picture — this isnull ≠ zeroat its hardest case.bin.noteprints a second axis reading under the first, replacing the timezone toggle a caller would otherwise build; a toggle hides half the truth and is missing from every screenshot. Also:errorstates on every chart that fetches —TimeSeries,Sparkline,MetricTable,NetworkGraph,Distribution— resolved throughresolveDataStateso the precedence is the array indata-state-modelrather than five hand-rolled ladders. In a dashboard "the fetch failed" and "there is no data" are different statements.DeltaandSeriesTableget none: neither has a fetch lifecycle.StatItemgainstone, carried by three signals rather than a hue alone — the rail, the value colour, and ansr-onlyjudgement. - Addedminor
TimeSeriescan plot more than one metric, and it finally draws an x axis.comparetakes further series —{ points, label, unit }— drawn against the same axes. It is purely additive:pointsis still the required single-series prop it always was, so nothing that already calls this component changes. Each line gets a--chart-Nhue **and** a distinct dash pattern, and the new legend swatch repeats the dash, so two lines stay two lines in a greyscale print and to a red-green colour-blind reader. Five series are drawn (the size of the palette); any beyond that stay in the data table and the legend says how many. All series share one y domain, and that is not configurable. A second y axis lets an author slide two unrelated metrics until they appear to cross wherever the argument needs them to; a series two orders of magnitude smaller will render as flat here, which is the true statement about it. The x axis is a baseline, a tick per labelled slot, and up to five HTML labels below the plot — HTML because SVG text scales with theviewBox, and at a 320 viewport this plot is 288px wide against a 900-unit box, sotext-xsinside it paints at 4px. Belowsmthe middle labels drop and the two ends stay. The crosshair readout now names and values every series at the cursor, from the onearia-live<output>that the arrow keys already fed. There is deliberately no second, hover-only tooltip to fall out of step with it.
@interlace/ui 1.0.01 entry
- Addedminor
The visualization layer ships: a token-driven chart set built on the
VISUALIZATION_PHILOSOPHYrow-first doctrine —MetricTableas the centrepiece,TimeSeriesas the thing a row is promoted into, plus a network graph, sparklines and deltas. Every chart carries the DS-wideloadingskeleton opt-in.
Import
31 named exports — pull the parts you need.
import { ANNOTATION_KINDS, AnnotationKind, Direction, MIN_VIEWPORT, NumericPoint, SERIES_STYLE, TimeSeries, areaPath, axisSlots, bandScales, compact, day, delta, describeDistribution, describeSeries, dialAngle, dialPath, dialPoint, dialRadius, dialRing, keepAtNarrow, linePath, nearestIndex, nearestSlot, numeric, peakBin, plotScales, seriesScales, slotAt, stepPath, ticks } from '@/components/ui/charts/time-series';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.
TimeSeriesProps
Also accepts every <figure> attribute.
| Prop | Type | Description |
|---|---|---|
| polarity | Polarity | Which direction counts as good, for the two-point comparison. `normal` (the default) colours a rise as positive. A chart of error rate, latency, cost or bounce rate wants `inverse` — without it a 50% regression is drawn in the same green as a 50% improvement, which is worse than not colouring it at all. |
| points* | readonly Point[] | — |
| compare | readonly ComparisonSeries[] | Further series drawn against the same axes. `points` stays the required single-series prop it always was — every existing call site and story is untouched — and this is purely additive. The alternative (one required `series: Series[]`) would have been a rename of the only prop this component has. All series share ONE y domain. That is the honest choice and it is not configurable: a second y axis lets an author slide two unrelated metrics until they appear to cross wherever the argument needs them to. A series two orders of magnitude smaller will render as flat, which is the true statement about it — give it its own chart, or a `MetricTable` row. |
| annotations | readonly Annotation[] | — |
| height | number | Drawing height in user units. The rendered height follows the container width. |
| label | string | Series name — used in the caption, the accessible label and the readout. |
| unit | string | Noun for the values, e.g. "views". |
| showTable | boolean | Render the data table visibly under the chart instead of `sr-only`. |
| loading | boolean | Render a `<Skeleton variant="chart" />` placeholder. A chart's data is in flight on first paint essentially always, so this is the state the component spends its first frames in — and the one most often left as a spinner, which reserves no space and guarantees a layout shift the moment the series lands. |
| error | unknown | The fetch failed. `unknown` rather than `boolean` for the same reason `DataStateFlags.error` is: a caught value can be handed straight through, and only its truthiness is ever read — nothing here renders it, because a stack trace is not a message for a reader. This is a different STATEMENT from an empty series, not a different severity of one. "No data yet" says the metric has no history; a failed request says the history is unknown, which is the one thing an empty-state message cannot be allowed to claim. Ranked directly under `loading`, per `DATA_STATES`. |
| announce | AnnouncementOptions | Context for the absence sentences — noun, coverage, reason. |
Skeleton
Pass loading and the component renders a shape-matched <Skeleton /> in its own place — same box, so nothing reflows when the data lands. Below is the same story with loading={true}.
<ANNOTATION_KINDS loading={isPending} />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
- Animation is gated on prefers-reduced-motion.
- ARIA in the source
role="alert"role="img"aria-labelaria-live
Examples
17 more states from the same story file.
R-rule compliance
Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.
| Rule | Concept | Where |
|---|---|---|
| R6 | data-slot on every part | `"time-series" / "-plot" / "-axis" / "-legend" / "-readout" / "-range" / "-comparison"` |
| R7 | className merged + ...rest | `cn(...)` + `{...props}` |
| R8 | No `isXxx`; enums | `polarity`; annotation `kind` |
| R13 | Ecosystem first | no charting dep — `plotScales` + SVG is the engine |
| R14 | Declares min viewport | `data-min-viewport={String(MIN_VIEWPORT)}` |
| R18 | Tailwind only | zero inline `style` |
| R19 | Tokens only | `stroke-chart-1..5`, `stroke-viz-*`, `text-muted-foreground` |
| R20 | AA contrast | axis 3.64:1 light / 3.82:1 dark; grid deliberately decorative |
| R23 | Loading reserves its box | `loading` → `<Skeleton variant="chart">`, same height |
| R23 | Absence is a vocabulary | `loading` / `error` / not-enough-data are three messages |
| R25 | Client component | pointer + key handlers, `useState` |
| R26 | A11y | `role="img"` + label + focusable + live readout + table |
Minimum viewport
This primitive declares MIN_VIEWPORT = 320 CSS px (DESIGN_PRINCIPLES #14). When mounted in a container narrower than this, the preflight contract draws a dev-mode outline so the regression is visible during local development.
<body data-interlace-dev>...</body>
Add the data-interlace-dev attribute to the body in development builds only — preflight then outlines any primitive whose container is below its declared data-min-viewport.
Dependencies
- Base UI primitive
- Native / no Base UI dependency
- Lucide icons
- none
- NPM dependencies
- none
Source
The full implementation — components/ui/charts/time-series.tsx once installed.
'use client';
import * as React from 'react';
// @interlace/time-series v1.2.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/time-series
// What changed since: https://ds.interlace.tools/c/time-series#history
// Generated banner — keep it, the upgrade diff reads this version.
/**
* @interlace/ui — TimeSeries
*
* One metric over time, with the actions that moved it drawn ON the curve.
*
* ## The annotation is the point
*
* A line going up is a fact. A line going up with a publish marker at the
* inflection is an *argument*. Everything else in this component — grid, axis,
* crosshair — is chrome that exists so the annotation can be read against a
* scale. If you are adding a feature here and it does not help someone connect
…978 more lines…Registry JSON
The raw registry record — what the shadcn CLI fetches.