Annotated Time Series

When to reach for it

Use the Annotated Time Series when a line would make a reader hunt for the story — the month growth crossed plan, the spike, the moment the trend turned. Instead of a bare series, the chart marks its own salient points and writes the headline for you. Reach for it in board decks and exec dashboards where the chart has to explain itself in a glance.

How it thinks

deriveAnnotations() runs entirely deterministically (no LLM) over your series and ranks the features it finds:

• Peak / trough — the global extremes, scored by how many σ they sit from the mean.
• Anomaly — points past a z-score threshold, labelled with their σ.
• Trend shift — the sharpest change in slope (largest second difference).
• Crosses plan — the first time actual moves above (beats plan) or below (misses plan) the comparison line.
• Last seen here — the most recent earlier point at today's level.

The top features become collision-avoided callouts on the plot, and the rank-0 feature is handed to summarize() for the one-sentence narrative above the chart — e.g. "Revenue peaked at $225k in Sep 2025."

Good to know

• Pass a plan value on each point to unlock the crosses-plan annotation; omit it and the engine simply works from the series alone.
• Annotations are decorative SVG (aria-hidden); the accessible representation is the data table, where each annotated month carries its note in the Note column.
• Same data in → same annotations out. Nothing is sampled or random, so snapshots and screenshots are stable.

Use it with your data

import { ChartAnnotatedTimeseries } from "@/components/blocks/chart-annotated-timeseries/chart-annotated-timeseries";

<ChartAnnotatedTimeseries series={myData} />

const { data, isLoading, error } = useSWR("/api/metric", fetcher);
// route isLoading/error through <ChartStates>, then:
<ChartAnnotatedTimeseries series={data} />

const series = await fetch(url, {
  next: { revalidate: 3600 },
}).then((r) => r.json());

<ChartAnnotatedTimeseries series={series} />

import { mapRows } from "@/lib/sextant/column-map";

const out = mapRows(rows, { /* contractKey: "yourColumn" */ }, dataSchema);
if (out.ok) <ChartAnnotatedTimeseries series={out.data} />;

Make it yours

Every customization below is an optional prop — omit them all and you get the defaults shown above. Recolor, reformat, restyle, or drop the card chrome without forking the component.

<ChartAnnotatedTimeseries
  series={{ value: { color: "var(--chart-3)", label: "…" } }}
/>

const eur = new Intl.NumberFormat("de-DE", {
  style: "currency",
  currency: "EUR",
  notation: "compact",
});

<ChartAnnotatedTimeseries valueFormatter={(n) => eur.format(n)} />

<ChartAnnotatedTimeseries narrative="Your own one-liner." />

// …or hide it entirely:
<ChartAnnotatedTimeseries narrative={false} />

<ChartAnnotatedTimeseries
  className="max-w-xl"
  classNames={{ body: "bg-muted/20" }}
/>

import { ChartAnnotatedTimeseriesPlot } from "@/components/blocks/chart-annotated-timeseries/chart-annotated-timeseries";

// Just the chart body — bring your own card/layout:
<ChartAnnotatedTimeseriesPlot series={series} config={config} />