@pond-ts/charts

Canvas-rendered, streaming-first time-series charts for pond-ts, with a react-timeseries-charts-style declarative layout.

src/examples/first-chart.tsx

import {
  ChartContainer,
  ChartRow,
  Layers,
  LineChart,
  YAxis,
} from '@pond-ts/charts';
import { useSiteChartTheme } from '@site/src/theme/useSiteChartTheme';
import { singleHostSeries } from './lib/server-metrics';

export default function FirstChart() {
  const theme = useSiteChartTheme();
  const series = singleHostSeries();

  return (
    <ChartContainer range={series.timeRange()} width={560} theme={theme}>
      <ChartRow height={220}>
        <Layers>
          <LineChart series={series} column="cpu" axis="pct" />
        </Layers>
        <YAxis id="pct" side="right" format=".0%" />
      </ChartRow>
    </ChartContainer>
  );
}

Hover the chart above — the crosshair, the axis readout, all of it is live, not a screenshot. That's the entire pitch: a chart consumes a pond TimeSeries directly, you compose a container, rows, and draw layers as React components, and the canvas renderer does the drawing. No chart-library data model to adapt to; no imperative escape hatch for interaction.

Install — npm install @pond-ts/charts pond-ts @pond-ts/react react react-dom. Peer-depends on pond-ts, @pond-ts/react, and react; the pond packages release together, so keep their ranges in step. See Using @pond-ts/charts for the two integration gotchas (Storybook react-docgen, the repaint contract).

The layout model

Charts are composed, not configured — the same nesting react-timeseries-charts users will recognise:

• <ChartContainer> — owns the shared x axis (time or value, inferred from the data), the view range, overall width, theme, and cursor mode.
• <ChartRow> — one stacked plot band with its own y axis / height. A container holds one or more rows sharing the x axis.
• <Layers> — the mandatory z-stack inside a row; children draw back-to-front in declaration order.
• <YAxis> / <XAxis> / <TimeAxis> — placeable axes. id links a draw layer's axis to a scale; side places it; format (a d3 specifier or a function) formats ticks and the matching cursor readout.

The minimal API set — compact cut

The primitives you compose a chart from. The generated API reference has every prop, type, and default; this is the map.

Layout & axes

Export	What it is
ChartContainer	Root: shared x axis, range, width, theme, cursor.
ChartRow	A stacked plot band with its own y axis and height.
Layers	The z-stack boundary inside a row.
YAxis	A y axis: id, side, auto-fit or explicit domain, format.
XAxis	A placeable x axis (time or value), custom ticks.
TimeAxis	A thin <XAxis> preset for the time axis.
CategoryAxis	A thin <XAxis> preset for the ordinal category axis.
Canvas	The low-level DPR-aware canvas primitive rows draw on.

Draw layers

Export	What it draws
LineChart	A gap-aware line.
AreaChart	A filled area.
BandChart	A filled lower/upper envelope (variance band).
ScatterChart	Points, with data-driven radius / colour encoding.
BarChart	Bars, histograms — stacked (columns / a Map / bins) and horizontal (guide) — and categorical bars (categories, a bar per category on an ordinal axis; guide).
BoxPlot	Box-and-whisker per bucket (shape: whisker / solid / none) from five pre-computed quantile columns.
Candlestick	First-class OHLC candles (variant: candle / bar / hollow; colorBy; optional showOHLC axis pills). Pairs with the trading-time axis (calendar on ChartContainer).

Every draw layer takes a pond series + a column, an as style identifier (theme lookup), and an axis scale id — style and scale are separate channels by design (no per-component colour/width props).

Annotations & indicators

Export	What it is
Region	A shaded x-range (annotation register — never a data hue).
Baseline	A horizontal value line, optional axis-pill indicator.
Marker	A vertical x line, optional axis-pill indicator.
YAxisIndicator	A live value pill pinned to a y-axis edge.
createLiveValue	High-frequency pill updates with an isolated repaint.

Data adapters & theming

Export	What it is
fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries	Adapters shaping a TimeSeries for the matching layer.
stacksFromGroups, stacksFromColumns, stacksFromBins, categoryStack, transposeRow	Stacked-bar / histogram / categorical readers over pond aggregation output.
defaultTheme	The neutral built-in ChartTheme.
cssVarTheme, useChartTheme	Build a theme from CSS custom properties and follow a dark/light toggle.

Why @pond-ts/charts — and when not to use it

The pitch is narrow on purpose: canvas rendering, streaming-first (a LiveSeries re-render is the same code path as a batch one — no separate "live mode" API), and the pond transform pipeline right up to the plot (rolling, aggregation, gap-fill all feed the same layer props a batch chart uses). If your charts are static SVG dashboards over plain arrays, that's real machinery you don't need — the bridge page covers exporting pond data to Recharts instead.

Some honest constraints, before you commit: you adopt the pond TimeSeries data model end to end (not a drop-in over arbitrary JSON); width is an explicit pixel number, not "100%" — the responsive-width recipe is one ResizeObserver away, and it's what the Gallery's own cards run on; interaction is mouse-only (no keyboard/touch cursor or selection yet); and the package is pre-1.0 — the API is stabilizing, not frozen. None of that is hidden: the Storybook and the Gallery show exactly what ships today, working, not a mockup.

Used in production for activity dashboards and ops telemetry today, with a financial-charts build actively underway. See the CHANGELOG for what's shipped in each release — the whole monorepo tags and publishes together.

Where to go next

• Learn charts — new to the library? Start here: a nine-chapter tutorial track, one running example, a live chart in every chapter.
• Gallery — eight live charts spanning every draw layer, each linking its full Storybook coverage. Touch one before you read another word of API reference.
• Value axis — the chart-level reference for plotting against something other than time: axis-kind inference, byColumn histograms, category axes, and dual x-axes.
• Storybook — every component and interaction mode, one story per prop/state: the systematic, API-adjacent knob walk.
• API reference — the generated, full-width reference: every component, prop, and type.
• Using @pond-ts/charts — install notes and integration gotchas.
• Theming charts — the ChartTheme model and the CSS-token bridge.
• Resizable multi-panel layout — a full chart layout worked end to end.

note

The docs here are an introduction plus the generated type reference. A per-chart-type reference section, a dedicated interaction/annotations reference (deeper than the Learn track's tour), and the financial-charts flagship guide are on the roadmap — see PLAN.md's "Docs site wave" for what's shipped and what's next.