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.
4 steps, 3 key presses — replayed on every PR by the play function of KeyboardCrosshair. Axe cannot press a key, so this — not the a11y scan — is what proves the component is operable without a mouse.
- 1the plot is reachable by keyboard at all
- 2ArrowRight reads out a specific valueArrowRight
- 3End jumps to the last observationEnd
- 4Escape clears the crosshair (WCAG 2.1.2)Escape
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.
@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
25 named exports — pull the parts you need.
import { ANNOTATION_KINDS, AnnotationKind, Direction, MIN_VIEWPORT, NumericPoint, TimeSeries, areaPath, axisSlots, bandScales, compact, day, delta, describeDistribution, describeSeries, 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 |
|---|---|---|
| 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
- No animation to gate.
- ARIA in the source
role="alert"role="img"aria-labelaria-live
Examples
16 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"` |
| 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
…686 more lines…Registry JSON
The raw registry record — what the shadcn CLI fetches.