stream-charts 1.2.1 → 2.0.1-snapshot

package/README.md

@@ -1,1225 +1,1012 @@
-# <span id="top">stream-charts</span>
-[Homepage](https://robphilipp.github.io/stream-charts/) •
-[Code Docs](docs/index.html) •
-[Change History](changes.md) •
-[Example Project](https://github.com/robphilipp/stream-charts-examples)
-
-## [&#10514;](#top) <span id="intro">intro</span>
-`stream-charts` is a [react](https://reactjs.org)-based library for building real-time time-series charts for viewing high frequency data. Ingesting and plotting new data for about 100 time-series every 25 ms isn't generally a problem. 
-
-The following plot types are currently available:
-
-1. **Scatter Plot**: for plotting time-series data.
-2. **Raster Plot**: for plotting event-timing data.
-3. **Bar Plot**: for plotting time-series as bars that show the current value and its minimum, maximum, and mean values for all times and time-windows.
-4. **Poincare Plot**: for plotting function iterates (`f[n](t)` vs `f[n-m](t)`).
-
-> Try it on codesandbox [stream-charts](https://codesandbox.io/p/sandbox/n7c8jm)
-
-`Charts` are composable using react components. So you can add different axis types, multiple axes, trackers, tooltips, and plots. `stream-charts` provides the following react components from which to build your own charts:
-1. The [Chart](#chart-usage) serves as the container, holding the other components as children, and providing the data to the plot.
-2. The [ContinuousAxis](#continuous-axes-usage) and [OrdinalAxis](#ordinal-axes-usage) components define the x- and y-axes, and provide the scales for the axes. Charts are required to have at least one x-axis and one y-axis.
-3. The optional [Tracker](#tracker-usage) component shows the value associated with the current mouse location of the axes to which it is assigned.
-4. The optional [Tooltip](#tooltip-usage) component shows the `TooltipContent` for the datum under the mouse cursor. Each plot type has a default tooltip content component ([ScatterPlotTooltipContent](#scatterplot-tooltip-usage), [RasterPlotTooltipContent](#rasterplot-tooltip-usage), [BarPlotTooltipContent](#barplot-tooltip-usage), [PoincarePlotTooltipContent](#poincareplot-tooltip-usage)).
-5. The `Plot` component displays the data. Currently, there are four plot components: [ScatterPlot](#scatter-plot-usage), [RasterPlot](#raster-plot-usage), [BarPlot](#bar-plot-usage), and [PoincarePlot](#poincare-plot-usage).
-
-### [&#10514;](#content) <span id="axes">capabilities</span>
-Charts can have multiple x-axes and y-axes, and these axes can have different scales. Time series can be assigned to an axis or use the default one. Currently, there are continuous and ordinal (category) axes. Continuous axes are available with all the scales supported by [d3](https://d3js.org) (for example, linear scales, logarithmic scales, and power scales).
-
-Each plot type comes with a default tooltip and tooltip content. However, you can customize the tooltip and tooltip content to suit your needs.
-
-The charts are designed to be responsive to changes in size, for example, to support window resizing.
-
-With `stream-charts` you can display initial (static) data as well as live data from an [Observable](https://rxjs-dev.firebaseapp.com/api/index/class/Observable).
-
-All aspects of the `Charts` style are exposed allowing you to use your favorite frameworks theme provider, or none at all.
-
-`Charts` provide zooming and panning that can be enabled or disabled. And zooming is set to use a modifier key by default so that it doesn't interfere with normal scrolling.
-
-### [&#10514;](#top) <span id="content">rendering performance</span>
-Charts can easily ingest and plot new data for about 100 time-series every 25 ms. 
-
-When using lower update frequencies, such as < 250 ms, and data updates are sparse, you can set an update cadence so that the plot's time smoothly scrolls, rather than updating only when new data arrives.
-
-`Charts` can have a data TTL (time-to-live) to drop older data to allow long-running streams of data. With the data-update callback you can capture that data and store it in local storage, memory, or a location of your choice.
-
-To achieve this type of performance, the charts:
-1. accept an [rxjs](https://rxjs-dev.firebaseapp.com) [Observable](https://rxjs-dev.firebaseapp.com/api/index/class/Observable) as the source of the time-series data, and
-2. are implemented using [d3](https://d3js.org) SVG elements wrapped in [react](https://reactjs.org) functional components, and
-3. keep chart updates outside [react](https://reactjs.org)'s render cycle.
-
-
-### [&#10514;](#top) <span id="content">project status</span>
-The following plots are currently available:
-
-1. **Scatter Plot**: for plotting time-series data.
-2. **Raster Plot**: for plotting event-timing data.
-3. **Bar Plot**: for plotting windowed stats (min, max, mean).
-4. **Poincare Plot**: for plotting iterates (n vs n-1).
-
-Over time, I'll add additional chart types. In the meantime, I welcome any contributions to create new chart types (gauges, etc).
-
-## [&#10514;](#top) <span id="content">content</span>
-
-**[quick start](#quick-start)**
-- [example raster chart code](#example-raster-chart-code)
-- [example scatter chart code](#example-scatter-chart-code)
-- [example bar chart code](#example-bar-chart-code)
-- [example poincare chart code](#example-poincare-chart-code)
-
-**[intro](#intro)**
-- [terminology](#terminology)
-- [data ttl, time-windows, performance](#data-ttl)
-
-**[chart](#chart)**
-- [&lt;Chart/&gt;](#chart-usage)
-  - [dimensions](#chart-usage-dimensions)
-  - [styling](#chart-usage-styling)
-  - [initial data](#chart-usage-initial-data)
-  - [streaming data](#chart-usage-streaming-data)
-
-**[axes](#axes)**
-- [&lt;ContinuousAxis/&gt;](#continuous-axes-usage)
-  - [base properties](#continuous-axes-usage-base)
-  - [styling](#continuous-axes-usage-styling)
-
-- [&lt;OrdinalAxis/&gt;](#ordinal-axes-usage)
-  - [base properties](#ordinal-axes-usage-base)
-  - [styling](#ordinal-axes-usage-styling)
-
-**[plots](#plots)**
-- [&lt;ScatterPlot/&gt;](#scatter-plot-usage)
-  - [base properties](#scatter-plot-usage-base)
-  - [view-modifying interactions](#scatter-plot-usage-view)
+[![npm](https://img.shields.io/npm/v/stream-charts)](https://www.npmjs.com/package/stream-charts) [![build](https://github.com/robphilipp/stream-charts/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/robphilipp/stream-charts/actions/workflows/main.yml) [![license: MIT](https://img.shields.io/npm/l/stream-charts)](LICENSE)
 
-- [&lt;RasterPlot/&gt;](#raster-plot-usage)
-  - [base properties](#raster-plot-usage-base)
-  - [view-modifying interactions](#raster-plot-usage-view)
-
-- [&lt;BarPlot/&gt;](#bar-plot-usage)
-  - [base properties](#bar-plot-usage-base)
-  - [view-modifying interactions](#bar-plot-usage-view)
-
-- [&lt;PoincarePlot/&gt;](#poincare-plot-usage)
-  - [base properties](#poincare-plot-usage-base)
-  - [view-modifying interactions](#poincare-plot-usage-view)
-
-**[utilities](#utilities)**
-- [&lt;Tracker/&gt;](#tracker-usage)
-  - [base properties](#tracker-usage-base)
-  - [styling](#tracker-usage-styling)
-- [&lt;Legend/&gt;](#legend-usage)
-  - [base properties](#legend-usage-base)
-  - [styling](#legend-usage-styling)
-- [&lt;Tooltip/&gt;](#tooltip-usage)
-- [&lt;RasterPlotTooltipContent/&gt;](#rasterplot-tooltip-usage)
-- [&lt;ScatterPlotTooltipContent/&gt;](#scatterplot-tooltip-usage)
-- [&lt;BarPlotTooltipContent/&gt;](#barplot-tooltip-usage)
-- [&lt;PoincarePlotTooltipContent/&gt;](#poincareplot-tooltip-usage)
+[Homepage](https://robphilipp.github.io/stream-charts/) •
+[API Docs](https://robphilipp.github.io/stream-charts/docs/modules.html) •
+[Change History](changes.md)
+
+**`stream-charts`** is a [React](https://react.dev) library for real-time charts of high-frequency streaming data. This repository holds the library, and a **demo app** that shows each of its charts at work and lets you explore them.
+
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="packages/examples/public/images/charts-collage-dark.gif">
+    <img src="packages/examples/public/images/charts-collage-light.gif" alt="the five stream-charts plots: a scatter chart streaming live, scrolling smoothly with a 25 ms cadence, with two x-axes, a linear and a logarithmic y-axis, and a legend whose hovered entry highlights its series; a raster chart of neuron spikes with a legend and a tooltip; a bar chart with windowed statistics and a tooltip; a Poincaré plot of an iterated map with a tooltip; and an outlier chart with confidence bands, flagged outliers, and a tooltip">
+</picture>
+
+*Scatter, streaming (two x-axes, linear and log y-axes, hovering the legend highlights a series, 25 ms cadence) · raster (legend, tooltip) · bar (running and windowed statistics, tooltip) · Poincaré (tooltip) · outlier (confidence bands, flagged outliers, tooltip)*
+
+**The library** charts data that never stops arriving. You hand it an [RxJS](https://rxjs.dev) observable of new data, and it buffers the updates, scrolls the time axes, and redraws – on a single canvas, so plotting new data for about 100 series every 25 ms isn't generally a problem. Along the way:
+
+- **The data lives in a data source that your application owns**, not in the chart, so it keeps streaming while the chart is off screen, and the chart picks up where it left off when it comes back.
+- **The charts stay usable while the data streams**: zoom and pan without losing "now", filter the series with a regular expression, and hover for tooltips (with statistics and sparklines), trackers, and legends that highlight the hovered series.
+- **The charts are built from React components** – axes, a plot, and the extras you want – with up to two x-axes and two y-axes per chart, linear or logarithmic scales, and y-axes that can grow to fit the data.
+
+**The demo app** (in [`packages/examples`](#run-demo)) has a tab for each chart type, each with a control bar for trying out the chart's options while the data streams – buffering, update rates, markers, interpolation, legends, and so on. Its intro walks through the charts and the library's design, with tutorials on adding your own data source, writing your own tooltips, and building a scatter chart from sensor data.
+
+Five plot types are available:
+
+| plot | for | example |
+|---|---|---|
+| [&lt;ScatterPlot/&gt;](#scatter-plot) | values over time (lines, with optional markers) | sensor readings, weights |
+| [&lt;RasterPlot/&gt;](#raster-plot) | events over time, one row per category | neuron spikes |
+| [&lt;BarPlot/&gt;](#bar-plot) | the current value and running statistics of each category | min, max, mean, and windowed min/max/mean |
+| [&lt;PoincarePlot/&gt;](#poincare-plot) | a sequence plotted against itself (`f[n+m](x)` vs `f[n](x)`) | iterated maps, chaotic systems |
+| [&lt;OutlierPlot/&gt;](#outlier-plot) | values over time, with confidence bands that flag outliers | a price index with 1σ, 2σ, 3σ bands |
+
+> Try the demo app on CodeSandbox: [stream-charts demo](https://codesandbox.io/p/github/robphilipp/stream-charts/master). It opens this repository, installs it, and runs the demo app (it takes a minute or so to start).
+
+## <span id="content">content</span>
+
+**[getting started](#getting-started)**
+- [using the library in your application](#installation)
+- [quick start](#quick-start)
+- [how it works](#how-it-works)
+- [migrating from 1.x](#migrating)
+- [this repository: the library and the demo app](#repository)
+- [running the demo app](#run-demo)
+- [working on the library](#contributing)
+
+**[data](#data)**
+- [data sources](#data-sources)
+- [generators](#generators)
+- [chart data, one shape for each plot](#chart-data)
+- [series and datum helpers](#series-helpers)
+- [performance: data TTL, windowing, and cadence](#performance)
+
+**[components](#components)**
+- [&lt;Chart/&gt;](#chart)
+- [axes: &lt;ContinuousAxis/&gt;, &lt;OrdinalAxis/&gt;, &lt;EmptyAxis/&gt;](#axes)
+- [plots](#plots)
+  - [properties common to the plots](#plot-common)
+  - [&lt;ScatterPlot/&gt;](#scatter-plot)
+  - [&lt;RasterPlot/&gt;](#raster-plot)
+  - [&lt;BarPlot/&gt;](#bar-plot)
+  - [&lt;PoincarePlot/&gt;](#poincare-plot)
+  - [&lt;OutlierPlot/&gt;](#outlier-plot)
+- [&lt;Tracker/&gt;](#tracker)
+- [&lt;Legend/&gt;](#legend)
+- [&lt;Tooltip/&gt; and tooltip content](#tooltip)
+  - [writing your own tooltip content](#custom-tooltip)
+
+**[more](#more)**
+- [theming](#theming)
+- [filtering series](#filtering)
 - [hooks](#hooks)
+- [further reading](#further-reading)
 
+---
 
-## [&#10514;](#content) <span id="quick-start">quick start</span>
+## <span id="getting-started">getting started</span> [↑](#content "back to contents")
 
-```shell
-npm install stream-charts
-```
+What to install depends on what you'd like to do:
 
-### [&#10514;](#content) <span id="example-raster-chart-code">example raster chart</span>
-An example raster chart (see [example](https://github.com/robphilipp/stream-charts-examples/blob/master/src/app/examples/StreamingRasterChart.tsx))
+| you'd like to... | install | then see |
+|---|---|---|
+| **use the charts in your own application** | the library, from npm | [using the library in your application](#installation), then the [quick start](#quick-start) |
+| **explore the charts**, see how each one is put together, and try out ideas – a chart of your own, say – in a working app | the demo app: clone this repository | [running the demo app](#run-demo) |
+| **add charts or features to the library**, and contribute them back with a pull request | the library's source, which comes with the demo app: fork this repository | [working on the library](#contributing) |
 
-![raster-chart](https://github.com/robphilipp/stream-charts/blob/develop/images/raster-chart-video.gif)
+### <span id="installation">using the library in your application</span> [↑](#content "back to contents")
 
-
-```typescript jsx
-<Chart
-    chartId={chartId.current}
-    width={useGridCellWidth()}
-    height={useGridCellHeight()}
-    margin={{...defaultMargin, top: 40, right: 75, left: 70, bottom: 40}}
-    // svgStyle={{'background-color': 'pink'}}
-    color={theme.color}
-    backgroundColor={theme.backgroundColor}
-    seriesStyles={new Map([
-        ['neuron1', {
-            ...defaultLineStyle(),
-            color: 'orange',
-            lineWidth: 2,
-            highlightColor: 'orange'
-        }],
-        ['neuron2', {
-            ...defaultLineStyle(),
-            color: 'orange',
-            lineWidth: 2,
-            highlightColor: 'orange'
-        }],
-        ['neuron3', {
-            ...defaultLineStyle(),
-            color: 'orange',
-            lineWidth: 2,
-            highlightColor: 'orange'
-        }],
-        ['neuron4', {
-            ...defaultLineStyle(),
-            color: 'orange',
-            lineWidth: 2,
-            highlightColor: 'orange'
-        }],
-        ['neuron5', {
-            ...defaultLineStyle(),
-            color: 'orange',
-            lineWidth: 2,
-            highlightColor: 'orange'
-        }],
-        ['neuron6', {
-            ...defaultLineStyle(),
-            color: theme.name === 'light' ? 'blue' : 'gray',
-            lineWidth: 3,
-            highlightColor: theme.name === 'light' ? 'blue' : 'gray',
-            highlightWidth: 5
-        }],
-        // ['test3', {...defaultLineStyle, color: 'dodgerblue', lineWidth: 1, highlightColor: 'dodgerblue', highlightWidth: 3}],
-    ])}
-    initialData={initialDataRef.current}
-    seriesFilter={filter}
-    seriesObservable={observableRef.current}
-    shouldSubscribe={running}
-    onUpdateAxesBounds={handleChartTimeUpdate}
-    windowingTime={25}
-    // onSubscribe={subscription => console.log("subscribed raster")}
->
-    <ContinuousAxis
-        axisId="x-axis-1"
-        location={AxisLocation.Bottom}
-        domain={[0, 5000]}
-        label="t (ms)"
-        // font={{color: theme.color}}
-    />
-    <ContinuousAxis
-        axisId="x-axis-2"
-        location={AxisLocation.Top}
-        domain={[0, 5000]}
-        label="t (ms)"
-        // font={{color: theme.color}}
-    />
-    <OrdinalAxis
-        axisId="y-axis-1"
-        location={AxisLocation.Left}
-        categories={initialDataRef.current.map(series => series.name)}
-        label="neuron"
-        axisTickStyle={{rotation: 25}}
-    />
-    <OrdinalAxis
-        axisId="y-axis-2"
-        location={AxisLocation.Right}
-        categories={initialDataRef.current.map(series => series.name)}
-        label="neuron"
-    />
-    <Tracker
-        visible={visibility.tracker}
-        labelLocation={TrackerLabelLocation.ByAxis}
-        labelFormatter={x => `${d3.format(",.0f")(x)} ms`}
-        style={{color: theme.color}}
-        font={{color: theme.color}}
-        // onTrackerUpdate={update => console.dir(update)}
-    />
-    <Tooltip
-        visible={visibility.tooltip}
-        style={{
-            fontColor: theme.color,
-            backgroundColor: theme.backgroundColor,
-            borderColor: theme.color,
-            backgroundOpacity: 0.9,
-        }}
-    >
-        <RasterPlotTooltipContent
-            xFormatter={value => formatNumber(value, " ,.0f") + ' ms'}
-            yFormatter={value => formatNumber(value, " ,.1f") + ' mV'}
-        />
-    </Tooltip>
-    <RasterPlot
-        axisAssignments={new Map([
-            // ['test', assignAxes("x-axis-1", "y-axis-1")],
-            ['neuron1', assignAxes("x-axis-2", "y-axis-2")],
-            ['neuron2', assignAxes("x-axis-2", "y-axis-2")],
-            ['neuron3', assignAxes("x-axis-2", "y-axis-2")],
-            ['neuron4', assignAxes("x-axis-2", "y-axis-2")],
-            ['neuron5', assignAxes("x-axis-2", "y-axis-2")],
-            ['neuron6', assignAxes("x-axis-2", "y-axis-2")],
-            // ['test3', assignAxes("x-axis-1", "y-axis-1")],
-        ])}
-        spikeMargin={1}
-        dropDataAfter={5000}
-        panEnabled={true}
-        zoomEnabled={true}
-        zoomKeyModifiersRequired={true}
-        withCadenceOf={50}
-    />
-</Chart>
+```shell
+npm install stream-charts react react-dom rxjs d3
 ```
 
-### [&#10514;](#content) <span id="example-scatter-chart-code">example scatter chart</span>
+> This README describes version 2, whose API is different from version 1's. To upgrade from 1.x, see [migrating from 1.x](#migrating).
 
-An example scatter chart  (see [example](https://github.com/robphilipp/stream-charts-examples/blob/master/src/app/examples/StreamingScatterChart.tsx))
+`stream-charts` has four peer dependencies: React 19 (`react`, `react-dom`), [RxJS](https://rxjs.dev) 7, and [d3](https://d3js.org) 7. Your application uses them directly – to render the components, create the observables that feed the charts, and pass d3 scales and curves to the axes and plots – so the library shares your copies rather than bringing its own. TypeScript users get d3's type definitions (`@types/d3`) with the library.
 
-![scatter-chart-tooltip](https://github.com/robphilipp/stream-charts/blob/develop/images/scatter-chart-video.gif)
+### <span id="quick-start">quick start</span> [↑](#content "back to contents")
 
+This complete example streams three made-up temperature sensors, each reporting every 100 ms, into a scatter chart with a **Run**/**Pause** button. There are four steps: an [RxJS](https://rxjs.dev) observable that emits the data, a generator that creates that observable, a data source that holds the data, and a chart that shows it.
 
-```typescript jsx
-<Chart
-    chartId={chartId.current}
-    width={useGridCellWidth()}
-    height={useGridCellHeight()}
-    margin={{...defaultMargin, top: 40, bottom: 40, right: 60}}
-    // svgStyle={{'background-color': 'pink'}}
-    color={theme.color}
-    backgroundColor={theme.backgroundColor}
-    seriesStyles={new Map([
-        ['test1', {
-            ...defaultLineStyle(),
-            color: 'orange',
-            lineWidth: 1,
-            highlightColor: 'orange'
-        }],
-        ['test2', {
-            ...defaultLineStyle(),
-            color: theme.name === 'light' ? 'blue' : 'gray',
-            lineWidth: 3,
-            highlightColor: theme.name === 'light' ? 'blue' : 'gray',
-            highlightWidth: 5
-        }],
-        ['test3', {
-            ...defaultLineStyle(),
-            color: theme.name === 'light' ? 'dodgerblue' : 'gray',
-            lineWidth: 3,
-            highlightColor: theme.name === 'light' ? 'dodgerblue' : 'gray',
-            highlightWidth: 5
-        }],
-    ])}
-    initialData={initialDataRef.current}
-    seriesFilter={filter}
-    seriesObservable={observableRef.current}
-    shouldSubscribe={running}
-    onUpdateAxesBounds={handleChartTimeUpdate}
-    windowingTime={25}
->
-    <ContinuousAxis
-        axisId="x-axis-1"
-        location={AxisLocation.Bottom}
-        domain={[10, 10000]}
-        label="x-axis"
-    />
-    <ContinuousAxis
-        axisId="y-axis-1"
-        location={AxisLocation.Left}
-        domain={[0, 1000]}
-        label="y-axis"
-    />
-    <ContinuousAxis
-        axisId="x-axis-2"
-        location={AxisLocation.Top}
-        domain={[100, 5000]}
-        label="x-axis (2)"
-    />
-    <ContinuousAxis
-        axisId="y-axis-2"
-        location={AxisLocation.Right}
-        scale={d3.scaleLog()}
-        domain={[100, 1200]}
-        label="y-axis (2)"
-    />
-    <Tracker
-        visible={visibility.tracker}
-        labelLocation={TrackerLabelLocation.ByAxis}
-        labelFormatter={x => `${d3.format(",.0f")(x)} ms`}
-        style={{color: theme.color}}
-        font={{color: theme.color}}
-        // onTrackerUpdate={update => console.dir(update)}
-    />
-    <Tooltip
-        visible={visibility.tooltip}
-        style={{
-            fontColor: theme.color,
-            backgroundColor: theme.backgroundColor,
-            borderColor: theme.color,
-            backgroundOpacity: 0.9,
-        }}
-    >
-        <ScatterPlotTooltipContent
-            xLabel="t (ms)"
-            yLabel="count"
-            yValueFormatter={value => formatNumber(value, " ,.0f")}
-            yChangeFormatter={(y1, y2) => formatNumber(y2 - y1, " ,.0f")}
-        />
-    </Tooltip>
-    <ScatterPlot
-        interpolation={interpolation}
-        axisAssignments={new Map([
-            // ['test1', assignAxes("x-axis-1", "y-axis-1")],
-            ['test2', assignAxes("x-axis-2", "y-axis-2")],
-            ['test3', assignAxes("x-axis-2", "y-axis-1")],
-        ])}
-        dropDataAfter={20000}
-        panEnabled={true}
-        zoomEnabled={true}
-        zoomKeyModifiersRequired={true}
-        // withCadenceOf={30}
-        // timeWindowBehavior={TimeWindowBehavior.SQUEEZE}
-    />
-</Chart>
+```tsx
+import {type JSX} from "react"
+import {interval, type Observable} from "rxjs"
+import {map} from "rxjs/operators"
+import {
+    AxisLocation,
+    Chart,
+    ContinuousAxis,
+    type DataGenerator,
+    type Datum,
+    emptySeries,
+    ScatterPlot,
+    type TimeSeries,
+    type TimeSeriesChartData,
+    TimeSeriesDataSource,
+    useDataSourceRunning,
+} from "stream-charts"
+
+// 1. an observable that emits each sensor's *new* readings, every `updatePeriod` ms
+function sensorReadings(names: Array<string>, startTime: number, updatePeriod: number): Observable<TimeSeriesChartData> {
+    const clockStart = performance.now()
+    return interval(updatePeriod).pipe(
+        // use the wall clock (not a tick count), so the time stays right when the browser throttles timers
+        map(() => startTime + (performance.now() - clockStart)),
+        map(time => ({
+            seriesNames: new Set(names),
+            maxTime: time,
+            maxTimes: new Map(names.map(name => [name, time])),
+            newPoints: new Map<string, Array<Datum>>(names.map(name => [
+                name,
+                [{x: time, y: 20 + 5 * Math.sin(time / 1000) + Math.random()}]
+            ])),
+        }))
+    )
+}
 
+// 2. a generator: the data source calls it each time it starts, handing it the series it holds
+//    right now, so that Run after Pause carries on from where the data left off
+const sensorGenerator = (updatePeriod: number): DataGenerator<TimeSeriesChartData, TimeSeries> =>
+    currentSeries => {
+        const latestTime = currentSeries.reduce(
+            (latest, series) => Math.max(latest, series.last().map(datum => datum.x).getOrElse(0)),
+            0
+        )
+        return sensorReadings(currentSeries.map(series => series.name), latestTime, updatePeriod)
+    }
+
+// 3. the data source holds the data. It lives outside the component (here, at module level),
+//    so it keeps its data, and keeps streaming, even when the chart is unmounted
+const dataSource = new TimeSeriesDataSource({
+    initialData: ['kitchen', 'garage', 'attic'].map(name => emptySeries<Datum>(name)),
+    generator: sensorGenerator(100),
+    dropDataAfter: 30_000,   // keep the last 30 seconds of data
+})
+
+// 4. the chart reads from the data source
+export function SensorChart(): JSX.Element {
+    const running = useDataSourceRunning(dataSource)
+    return (
+        <div>
+            <button onClick={() => running ? dataSource.stop() : dataSource.start()}>
+                {running ? 'Pause' : 'Run'}
+            </button>
+            <Chart chartId={1} width={800} height={400} dataSource={dataSource} windowingTime={100} dataUpdatePeriod={100}>
+                <ContinuousAxis axisId="x-axis" location={AxisLocation.Bottom} domain={[0, 10_000]} label="time (ms)"/>
+                <ContinuousAxis axisId="y-axis" location={AxisLocation.Left} domain={[10, 30]} label="temperature (°C)"/>
+                <ScatterPlot/>
+            </Chart>
+        </div>
+    )
+}
 ```
 
-### [&#10514;](#content) <span id="example-bar-chart-code">example bar chart</span>
+Click **Run** and the three sensors start drawing. When the data reaches the end of the x-axis, the axis scrolls to keep up. To show your real data, replace `sensorReadings` with an observable of your own: a web socket (`rxjs/webSocket`), server-sent events, polling (`interval` + `switchMap` to a `fetch`), or a simulation. Nothing else needs to change.
 
-Example bar chart showing windowed statistics (see [example](https://github.com/robphilipp/stream-charts-examples/blob/develop/src/app/examples/StreamingBarChart.tsx)).
+From here you can add [colors](#chart-styling), a [tooltip](#tooltip), a [tracker](#tracker), a [legend](#legend), and [zooming and panning](#plot-common). The [demo app](#run-demo), in this repository's `packages/examples`, has a complete, working example of each plot type. Its tutorial, [adding your own data source](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/adding-a-data-source.md), builds this quick start one step at a time.
 
-![bar-chart-tooltip](https://github.com/robphilipp/stream-charts/blob/develop/images/bar-chart-video.gif)
+### <span id="how-it-works">how it works</span> [↑](#content "back to contents")
 
-```typescript jsx
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="packages/examples/public/images/data-flow-dark.png">
+    <img src="packages/examples/public/images/data-flow-light.png" alt="how the data flows: the generator feeds the data source, which feeds a view driver for each mounted plot, which feeds the plot">
+</picture>
 
-<Chart<OrdinalChartData, OrdinalDatum, BarSeriesStyle, WindowedOrdinalStats>
-    chartId={chartId.current}
-    width={useGridCellWidth()}
-    height={useGridCellHeight()}
-    margin={{...defaultMargin, top: 60, bottom: 80, right: 75, left: 70}}
-    // svgStyle={{'background-color': 'pink'}}
-    color={theme.color}
-    backgroundColor={theme.backgroundColor}
-    seriesStyles={new Map<string, BarSeriesStyle>([
-        ['neuron1', {
-            ...defaultBarSeriesStyle('orange'),
-            lineWidth: 2,
-            minMaxBar: {
-                ...defaultBarSeriesStyle('orange').minMaxBar,
-                stroke: {
-                    ...defaultBarSeriesStyle('orange').minMaxBar.stroke,
-                    width: 0
-                }
-            }
-        } as BarSeriesStyle],
-        ['neuron14', {
-            ...defaultBarSeriesStyle(theme.name === 'light' ? 'blue' : 'gray'),
-            lineWidth: 3,
-            highlightWidth: 5,
-            minMaxBar: {
-                ...defaultBarSeriesStyle(theme.name === 'light' ? 'blue' : 'gray').minMaxBar,
-                widthFraction: 1
-            }
-
-        } as BarSeriesStyle],
-        ['neuron31', {
-            ...defaultBarSeriesStyle('green'),
-            lineWidth: 2,
-        } as BarSeriesStyle],
-    ])}
-    initialData={initialDataRef.current}
-    seriesObservable={observableRef.current}
-    seriesFilter={filter}
-    shouldSubscribe={running}
-    onUpdateChartTime={handleChartTimeUpdate}
-    onUpdateAxesBounds={handleChartRangeUpdate}
-    windowingTime={25}
->
-    <OrdinalAxis
-        axisId="x-axis-1"
-        location={AxisLocation.Bottom}
-        categories={initialDataRef.current.map(series => series.name)}
-        label="neuron"
-        axisTickStyle={{rotation: 90}}
-    />
-    <OrdinalAxis
-        axisId="x-axis-2"
-        location={AxisLocation.Top}
-        categories={initialDataRef.current.map(series => series.name)}
-        label="neuron"
-        axisTickStyle={{rotation: 40}}
-    />
-    <ContinuousAxis
-        axisId="y-axis-1"
-        location={AxisLocation.Left}
-        domain={[-1.1, 1.1]}
-        label="ρ (mV)"
-    />
-    <ContinuousAxis
-        axisId="y-axis-2"
-        location={AxisLocation.Right}
-        domain={[-1.1, 1.1]}
-        label="ρ (mV)"
-    />
-    <Tracker
-        visible={visibility.tracker}
-        trackerAxis={AxisLocation.Left}
-        labelLocation={TrackerLabelLocation.ByAxis}
-        labelFormatter={x => `${d3.format(".2f")(x)} mV`}
-        style={{color: theme.color}}
-        font={{color: theme.color}}
-        // onTrackerUpdate={update => console.dir(update)}
-    />
-    <Tooltip
-        visible={visibility.tooltip}
-        style={{
-            fontColor: theme.color,
-            backgroundColor: theme.backgroundColor,
-            borderColor: theme.color,
-            backgroundOpacity: 0.9,
-        }}
-    >
-        <BarPlotTooltipContent ordinalUnits="mV"/>
-    </Tooltip>
-    <BarPlot
-        barMargin={1}
-        dropDataAfter={5000}
-        panEnabled={true}
-        zoomEnabled={true}
-        zoomKeyModifiersRequired={true}
-        // withCadenceOf={50}
-
-        // to have the upper axis zoom when the series zoom, we must have at
-        // least one series assigned to this axis.
-        axisAssignments={new Map([
-            ['neuron1', assignAxes("x-axis-2", "y-axis-2")],
-        ])}
-
-        showMinMaxBars={showMinMax}
-        showValueLines={showValue}
-        showMeanValueLines={showMean}
-        showWindowedMinMaxBars={showWinMinMax}
-        showWindowedMeanValueLines={showWinMean}
-    />
-</Chart>
-```
+(The diagram is from the demo app, whose data generators stand in for your application's.)
 
-### [&#10514;](#content) <span id="example-poincare-chart-code">example poincare chart</span>
+1. **The generator** is a function that creates an RxJS observable of chart data. Each emission holds only the *new* points since the last one.
+2. **The data source** subscribes to the generator's observable when you call `start()`, adds each chunk of new points to its series, and drops the points that are older than its `dropDataAfter` setting. `stop()` unsubscribes, and nothing keeps running in the background.
+3. **The `<Chart>`** is handed the data source. The chart and its plots only *read* from the data source; they never subscribe to the stream themselves. While a plot is mounted, its *view driver* listens for the data source's updates, batches them (see `windowingTime`), scrolls the time axes, and has the plot redraw.
+4. **The plot** draws the data onto a single `<canvas>`, outside of React's render cycle.
 
-Example Poincare (iterates) chart (see [example](https://github.com/robphilipp/stream-charts-examples/blob/develop/src/app/examples/StreamingPoincareChart.tsx)).
+Because the data source isn't tied to any component, *you* decide how long it lives. Keep it in a store, a context, or at module level, and it outlives the chart. The user can start a chart, navigate to another page, and come back to find that it kept streaming the whole time. (The examples keep theirs in [zustand](https://www.npmjs.com/package/zustand) stores, but any of these works.) For a longer walk through this, see [how the data flows](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/how-the-data-flows.md).
 
-![poincare-chart-with-tooltip](https://github.com/robphilipp/stream-charts/blob/develop/images/poincare-video.gif)
+The chart is composed from React components, so you pick the pieces you need: up to two x-axes and two y-axes, a plot, and optionally a tracker, a tooltip, and a legend.
 
-```typescript jsx
-<Chart
-    chartId={chartId.current}
-    width={useGridCellWidth()}
-    height={useGridCellHeight()}
-    margin={{...defaultMargin, top: 40, bottom: 30, right: 60}}
-    // svgStyle={{'background-color': 'pink'}}
-    color={theme.color}
-    backgroundColor={theme.backgroundColor}
-    seriesStyles={new Map([
-        ['test1', {
-            ...defaultLineStyle(),
-            color: 'orange',
-            lineWidth: 1,
-            highlightColor: 'orange'
-        }],
-        ['test2', {
-            ...defaultLineStyle(),
-            color: theme.name === 'light' ? 'blue' : 'gray',
-            lineWidth: 1,
-            highlightColor: theme.name === 'light' ? 'blue' : 'gray',
-            highlightWidth: 5
-        }],
-        ['test3', {
-            ...defaultLineStyle(),
-            color: theme.name === 'light' ? 'red' : 'gray',
-            lineWidth: 1,
-            highlightColor: theme.name === 'light' ? 'dodgerblue' : 'gray',
-            highlightWidth: 5
-        }],
-    ])}
-    initialData={initialDataRef.current}
-    // seriesFilter={filter}
-    seriesObservable={observableRef.current}
-    shouldSubscribe={running}
-    onUpdateChartTime={handleChartTimeUpdate}
-    windowingTime={25}
->
-    <ContinuousAxis
-        axisId="x-axis-1"
-        location={AxisLocation.Bottom}
-        domain={axesRange}
-        label="f[n](x)"
-        updateAxisBasedOnDomainValues={false}
-    />
-    <ContinuousAxis
-        axisId="y-axis-1"
-        location={AxisLocation.Left}
-        domain={axesRange}
-        label={`f[n+${lagN}](x)`}
-        updateAxisBasedOnDomainValues={false}
-    />
-    <ContinuousAxis
-        axisId="x-axis-2"
-        location={AxisLocation.Top}
-        domain={axesRange}
-        label="f[n](x)"
-        updateAxisBasedOnDomainValues={false}
-    />
-    <ContinuousAxis
-        axisId="y-axis-2"
-        location={AxisLocation.Right}
-        domain={axesRange}
-        label={`f[n+${lagN}](x)`}
-        updateAxisBasedOnDomainValues={false}
-    />
-    <Tracker
-        key="tracker-x-axis"
-        visible={visibility.tracker}
-        // labelLocation={TrackerLabelLocation.Nowhere}
-        labelLocation={TrackerLabelLocation.ByAxis}
-        trackerAxis={AxisLocation.Bottom}
-        labelFormatter={x => `${d3.format(",.3f")(x)}`}
-        style={{color: theme.color}}
-        font={{color: theme.color}}
-        // onTrackerUpdate={update => console.dir("bottom", update)}
-    />
-    <Tracker
-        key="tracker-y-axis"
-        visible={visibility.tracker}
-        // labelLocation={TrackerLabelLocation.Nowhere}
-        labelLocation={TrackerLabelLocation.ByAxis}
-        trackerAxis={AxisLocation.Left}
-        labelFormatter={x => `${d3.format(",.3f")(x)}`}
-        style={{color: theme.color}}
-        font={{color: theme.color}}
-        // onTrackerUpdate={update => console.dir("left", update)}
-    />
-    <Tooltip
-        visible={visibility.tooltip}
-        style={{
-            fontColor: theme.color,
-            backgroundColor: theme.backgroundColor,
-            borderColor: theme.color,
-            backgroundOpacity: 0.9,
-        }}
-    >
-        <PoincarePlotTooltipContent
-            xLabel="t (ms)"
-            yLabel="f(x)"
-            yValueFormatter={value => formatNumber(value, " ,.4f")}
-            style={{
-                ...defaultTooltipStyle,
-                fontColor: 'black',
-                // fontColor: theme.color,
-                fontWeight: 650
-            }}
-        />
-    </Tooltip>
-    <PoincarePlot
-        interpolation={interpolation}
-        dropDataAfter={dropAfterMs}
-        panEnabled={true}
-        zoomEnabled={true}
-        zoomKeyModifiersRequired={true}
-        // withCadenceOf={30}
-    />
+```tsx
+<Chart dataSource={dataSource} ...>
+    <ContinuousAxis axisId="x-axis-1" location={AxisLocation.Bottom} .../>
+    <ContinuousAxis axisId="y-axis-1" location={AxisLocation.Left} .../>
+    <Tracker .../>
+    <Tooltip ...><ScatterPlotTooltipContent .../></Tooltip>
+    <Legend .../>
+    <ScatterPlot .../>
 </Chart>
 ```
 
-## [&#10514;](#content) <span id="intro">intro</span>
+### <span id="migrating">migrating from 1.x</span> [↑](#content "back to contents")
 
-`stream-charts` aim to provide high-performance charts for displaying large amounts of data in real-time. The examples (above) show various plot types whose data can be updated about every 25 ms.
+This version is a substantial redesign, and code written for 1.x needs updating.
 
-There are obviously limits to the amount of data, and the performance of the plots. For example, the raster chart plots thousands of lines in the chart. When displaying more data in the raster plot, update performance will suffer. Therefore, you must tune your plots somewhat when you are working in the limits of their performance.
+| 1.x | now |
+|---|---|
+| `<Chart initialData={...} seriesObservable={...} shouldSubscribe={running}>` | Create a [data source](#data-sources) with your initial data and a [generator](#generators), and pass it as `<Chart dataSource={...}>`. Start and stop it with `dataSource.start()` and `dataSource.stop()`. |
+| `onSubscribe`, `onUpdateData` on the `<Chart>` | `onUpdateData` is now an option of the data source. To watch the stream, subscribe to `dataSource.chartDataUpdatesObservable`, or to `dataSource.isRunningObservable` to follow start/stop. |
+| `dropDataAfter` on the plot | `dropDataAfter` is an option of the data source (change it later with `setDropDataAfter`). |
+| `Datum` was `{time, value}` | `Datum` is `{x, y}`. Create one with `datumOf(time, value)`. |
+| `seriesFromTuples(name, tuples)` | `timeSeriesFromTuples(name, tuples)` (and `iterateSeriesFromTuples`, `ordinateSeriesFromTuples` for the other shapes). |
+| charts drawn with SVG elements | charts drawn on a single `<canvas>`. The `svgStyle` prop is still accepted, and styles the chart's container. |
+| `TrackerLabelLocation.WithMouse` | removed. Use `TrackerLabelLocation.ByAxis` (the default) or `TrackerLabelLocation.Nowhere`. |
+| `zoomKeyModifiersRequired` defaulted to `false` | it now defaults to `true`: hold shift (or ctrl) while scrolling to zoom. |
+| `useDataObservable()`, `useInitialData()` hooks | `useDataSource()`, and `useDataSourceRunning(dataSource)`. |
+| deep imports, such as `stream-charts/dist/app/charts/...` | import everything from `stream-charts`. Anything not exported from the package root is internal and may change. |
 
-### [&#10514;](#content) <span id="terminology">terminology</span>
+New in this version: the [&lt;OutlierPlot/&gt;](#outlier-plot), [&lt;EmptyAxis/&gt;](#empty-axis), [auto-scaling y-axes](#continuous-axis-autoscale), markers on the scatter plot, axis highlighting on hover, colorized lines in the Poincaré plot, zoom state that survives remounting (bar and Poincaré plots), [custom tooltip content](#custom-tooltip) built on `<TooltipContent>`, and data that keeps streaming while the chart is unmounted.
 
-A &lt;Chart/&gt; holds a `plot`, the `axes`, and optionally, a &lt;Tracker/&gt;, and a &lt;Tooltip/&gt;. A &lt;Chart/&gt; is generic, and holds a specific type of `plot`, for example, a &lt;RasterPlot/&gt;, &lt;ScatterPlot/&gt;, &lt;BarPlot/&gt;, or &lt;PoincarePlot/&gt;. The `plot` holds the data, and optionally provides pan and zoom. The `axes` provide the scale of the data. For example, the scale could be a continuous numeric logarithmic scale, or an ordinal scale. The `axes` are also generic. Though, a `plot` can restrict the type of `axes` allowed. For example, a &lt;RasterPlot/&gt; requires that the y-axes are ordinal axes. &lt;Trackers/&gt; are generic. &lt;Tooltips/&gt; are also generic, though the tooltip content is a child, specific to a plot type, that it knows how to interpret and present the data.
+### <span id="repository">this repository: the library and the demo app</span> [↑](#content "back to contents")
 
-**&lt;Chart/&gt;** [&#8628;](#chart)<br>
-Generic container which holds the `Axes`, `Plot`, `Tracker`, `Tooltip`.
+This repository is a monorepo (npm workspaces) holding two packages: the library, and a demo app that uses it.
 
-**Axes** [&#8628;](#axes)<br>
-Defines the scale of the data. `stream-charts` current has two axis types: [&lt;ContinuousAxis/&gt;](#continuous-axes-usage) and [&lt;OrdinalAxis/&gt;](#ordinal-axes-usage). The &lt;ContinuousAxis/&gt; can be used as an x-axis or y-axis. However, the &lt;OrdinalAxis/&gt; can only be used as a y-axes because these are all time-series charts and the x-axis currently only represents time.
+| where | what |
+|---|---|
+| `packages/stream-charts` | **The library**, published to npm as `stream-charts`. Its code is in `src/app/charts`, and its public API – everything you can import from `"stream-charts"` – is `src/index.ts`. |
+| `packages/examples` | **The demo app** (not published). The examples are in `src/app/examples`, and the guide pages shown in its intro are the markdown files in `src/app/examples/docs`. |
+| `docs/` | The API docs, generated from the library's source, and served at [robphilipp.github.io/stream-charts/docs](https://robphilipp.github.io/stream-charts/docs/modules.html). |
+| `README.md`, `changes.md` | This page and the change history – the library's, copied into its package when it's published. |
 
-**Plot** [&#8628;](#plots)<br>
-The plot is a container for the data that uses the `axes` for scale, domain, and range information. Plots provide panning and zooming of the x-axis (time), interacting with the `axes` to update the time-range. The plot is the visual representation of the data. Currently, four types of plots are available: [&lt;RasterPlot/&gt;](#raster-plot-usage), [&lt;ScatterPlot/&gt;](#scatter-plot-usage), [&lt;BarPlot/&gt;](#bar-plot-usage), and [&lt;PoincarePlot/&gt;](#poincare-plot-usage).
+While you're working in this repository, the demo app's `"stream-charts"` import resolves to the library's TypeScript *source* (through a `source` condition in the library's `exports`), so a change to the library shows up in the running app right away, with no build step. Published copies of the library don't use that condition, and get the compiled `dist/`.
 
-**&lt;Tracker/&gt;** [&#8628;](#tracker-usage)<br>
-The tracker displays the current plot time of the mouse. When multiple x-axes are used in the chart, then the tracker displays both times (i.e. from the upper and lower x-axis).
+### <span id="run-demo">running the demo app</span> [↑](#content "back to contents")
 
-**&lt;Tooltip/&gt;** [&#8628;](#tooltip-usage)<br>
-The tooltip is a generic component for rendering information about the data when the user mouses over a series or datum. The `<Tooltip/>` expects a child component that understands the data and renders the information show in the tooltip. For example, when using a [&lt;RasterPlot/&gt;](#raster-plot-usage), the [&lt;RasterPlotTooltipContent/&gt;](#rasterplot-tooltip-usage) renders the data for the raster plot tooltip. And when using a [&lt;ScatterPlot/&gt;](#scatter-plot-usage), the [&lt;ScatterPlotTooltipContent/&gt;](#scatterplot-tooltip-usage) renders the data for the scatter plot tooltip. The tooltip content can be extended.
+The demo app, in `packages/examples`, has one tab for each plot type, with a control bar for trying out the plots' options, and an intro made of guide pages and tutorials. You'll need [Node.js](https://nodejs.org) 22.12+ (or 20.19+) and npm 7+. Clone the repository and start the app:
 
-### [&#10514;](#content) <span id="data-ttl">data ttl, time-windows, performance</span>
+```shell
+git clone https://github.com/robphilipp/stream-charts.git
+cd stream-charts
+npm install        # installs both packages (one node_modules, one lockfile, at the root)
+npm run dev        # starts the demo app (Vite), at http://localhost:5173
+```
 
-The `stream-charts` have been designed to work with fairly large amounts of high frequency data. When the data time exceeds the larges time on the x-axes, the chart begins to scroll, shifting the time-window to keep up with the present data time. The data that *falls off* the chart is held in memory and can be viewed by changing the time-window with "zoom" or panning to earlier times.
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="packages/examples/public/images/intro-example-parts-dark.png">
+    <img src="packages/examples/public/images/intro-example-parts-light.png" alt="the anatomy of an example chart: the tabs and control bar are the demo app's, and the chart and its legend are the library's">
+</picture>
 
-For long-running charts, the amount of data may get large. Because of this, each `stream-charts` plot provides a data time-to-live (TTL) setting called `dropDataAfter` which is the number of milliseconds, in chart time, after which the data is dropped. The TTL applies to data that *falls off* the chart. The TTL does not refer to real time. The data will not dissappear fro the plot of the `dropDataAfter` milliseconds (see [dropDataAfter](#raster-plot-drop) for raster plots, and [dropDataAfter](#scatter-plot-drop) for scatter plots).
+Each tab runs one chart: click **Run**, and open its control bar to try the options while the data streams. The **Intro** tab walks through the charts and how they work. The tabs and control bars are the demo app's; the chart and its legend are the library's.
 
-As the amount of data and the update frequency increase, you have three levers to make your plots run more smoothly when the start to stutter. Each set of streaming data is unique and may require tuning when the default settings aren't giving the desired results.
+To try out an idea, change an example in `packages/examples/src/app/examples` (for example, `StreamingScatterChart.tsx`), and the app reloads as you save. The tutorial [your own scatter chart, from sensor data](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/scatter-chart-from-sensor-data.md) builds a new chart from scratch. To give a new example its own tab:
 
-1. **Drop data with the data TTL.** By dropping data, `d3` has less data to manage and will run faster. Without TTD, the data the falls off the time-window as the plot scroll is still kept in memory, and is still processed by `d3`, but it is clipped, and so not shown. Dropping data will reduce the processing load as data is streamed in. To later view that dropped data, you can store the data from your observable with a separate observer, and when the streaming is complete, load that data once into the plot.
-2. **Decrease the windowing-time.** The windowing-time, not to be confused with the time-window described below, determines how long (in milliseconds) the incoming data is buffered before the plot is updated. Longer windowing times give better performance, though, at the cost of more choppy scrolling.
-3. **Decrease the time-window.** The time-window is defined by the (min, max) time values of your axes. Smaller time-windows mean less data, but also it will stream by faster.
+1. Put the example component in `packages/examples/src/app/examples`.
+2. Add a route component for it in `packages/examples/src/app/routeComponents.tsx`.
+3. Add a route for it to the route tree in `packages/examples/src/app/router.tsx`.
+4. Add `{name, path}` for the tab to `TABS` in `packages/examples/src/app/routeData.ts`.
 
-As a final note, generally, the &lt;ScatterPlot/&gt; performs better than the &lt;RasterPlot/&gt;.
+The demo app imports everything from `"stream-charts"`, just as your application would, so the chart code carries over to your application. The app's stores (zustand), control bars, and routing are its own.
 
-## [&#10514;](#content) <span id="chart">chart</span>
+### <span id="contributing">working on the library</span> [↑](#content "back to contents")
 
-The `stream-charts` module wraps [d3](http://d3js.org) elements with functional [react](http://reactjs.org) in a way that keeps the chart (d3) updates out of the react render cycle. All `stream-charts` start with the [&lt;Chart/&gt;](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/Chart.tsx) root element.
+To add a chart or a feature to the library (see [this repository](#repository) for where everything is):
 
-### [&#10514;](#content) <span id="chart-usage">&lt;Chart/&gt;</span>
+1. **Fork the repository** on GitHub, clone your fork (instead of this repository), and make a branch from `develop` for your change. You'll need the same Node.js and npm as for [running the demo app](#run-demo).
+2. **Run the demo app** (`npm run dev`), and change the library in `packages/stream-charts/src/app/charts`. The demo app runs on the library's source, so your change shows up as you save. Add or change an example in the demo app to show it off.
+3. **Add tests** next to the code you changed: the library's tests are the `*.test.ts` files in `packages/stream-charts/src/app/charts`, and the demo app's are the `*.test.ts` files in `packages/examples/src`. Check that everything passes: `npm test`, `npm run lint`, and `npm run build`.
+4. **Update the docs**: this README for anything that changes the library's API, and `changes.md` for the change history. Leave the `version` in `packages/stream-charts/package.json` alone: a merge to `master` with a new version stages the library on npm, for a maintainer to approve and release.
+5. **Open a pull request** against `develop`. The repository's CI runs only for `master` (where the releases are), not for pull requests to `develop`, so run the checks in step 3 yourself before you open it.
 
-The `Chart` component creates the main SVG element (container) holding the chart, manages a reference to that container, and is the wraps the children in the chart context provider so that they have access to the [useChart](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/hooks/useChart.tsx) hook which holds properties, styles, callbacks, subscription needed to construct the charts and make them interactive.
+The commands, all from the repository's root:
 
-The `Chart`s properties fall into four categories:
-1. container dimensions
-2. chart style
-3. initial (static data)
-4. streamed data and how to manage the stream of data
+```shell
+npm run dev        # runs the demo app, on the library's source
+npm run build      # compiles the library to packages/stream-charts/dist, then builds the demo app
+npm test           # runs both packages' tests
+npm run lint       # lints both packages
+npm run docs       # regenerates the API docs into docs/
+```
 
-#### [&#10514;](#content) <span id="chart-usage-dimensions">&lt;Chart/&gt; dimensions</span>
-**width (pixels)**<br>
-The width (in pixels) of the container that holds the chart. The actual plot will be smaller based on the margins.
+To work on one package, add `-w` and its name: for example, `npm test -w stream-charts` runs only the library's tests, and `npm run preview -w stream-charts-examples` serves the demo app's production build (after `npm run build`). To see what would be published, `npm pack -w stream-charts --dry-run`.
 
-**height (pixels)**<br>
-The height (in pixels) of the container that holds the chart. The actual plot will be smaller based on the margins.
+---
 
-#### [&#10514;](#content) <span id="chart-usage-styling">&lt;Chart/&gt; styling</span>
-**margin ([Margin](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/margins.ts), optional)**<br>
-The margin (in pixels) around plot. For example, if the container has a (h, w) = (300, 600) and a margin of 10 pixels for the top, left, right, bottom, then the actual plot will have a (h, w) = (290, 590), leaving only 10 pixels around the plot for axis titles, ticks, and axis labels. 
+## <span id="data">data</span> [↑](#content "back to contents")
 
-The Margin has the following shape 
->```typescript
->interface Margin {
-  top: number
-  bottom: number
-  left: number
-  right: number
->}
->```
+### <span id="data-sources">data sources</span> [↑](#content "back to contents")
 
+A data source owns the stream. It holds the series, subscribes to the generator while it's running, and applies the data-retention rules. Each plot type has its own kind of data, and so its own data source.
 
-**color (string, optional)**<br>
-The color of the axis lines and text, which can be overridden specifically by the axes styles.
+| your data is... | data source | chart data | datum | plot |
+|---|---|---|---|---|
+| values over time | `TimeSeriesDataSource` | `TimeSeriesChartData` | `Datum` (`{x, y}`) | `<ScatterPlot>` |
+| events over time | `TimeSeriesDataSource` | `TimeSeriesChartData` | `Datum` (`{x, y}`) | `<RasterPlot>` |
+| a sequence plotted against itself | `IteratesDataSource` | `IterateChartData` | `IterateDatum` (`{time, iterateN, iterateN_1}`) | `<PoincarePlot>` |
+| the latest value of each category | `OrdinalDataSource` | `OrdinalChartData` | `OrdinalDatum` (`{time, ordinal, value}`) | `<BarPlot>` |
+| values over time, with confidence bounds | `OutlierDataSource` | `OutlierChartData` | `OutlierDatum` (`{datum, bounds}`) | `<OutlierPlot>` |
 
-**backgroundColor (string, optional)**<br>
-The color of the chart background (the whole chart, not just the plot).
+Every data source is created with an options object:
 
-**svgStyle ([SvgStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/svgStyle.ts), optional)**<br>
-The style attributes for the main SVG element, in case you want to change those. Generally, this is not needed.
+```ts
+const dataSource = new TimeSeriesDataSource({
+    initialData,            // the series to start with
+    generator,              // creates the observable each time the source starts
+    dropDataAfter: 20_000,  // optional: drop data older than 20 s (default: never drop)
+    onUpdateData: (seriesName, newData) => {/* e.g. archive the data */},  // optional
+})
+```
 
-The SvgStyle has the following shape 
->```typescript
->interface SvgStyle {
-  height?: string | number 
-  width?: string | number 
-  outline?: string
-  // any valid SVG CSS attribute
-  [propName: string]: any
->}
->```
+| option | description |
+|---|---|
+| `initialData` | The series to start with. The data source takes ownership of these series, and changes them in place as data arrives. For the time-series, iterates, and ordinal data sources, **the initial data decides the series**: points for a series that isn't in the initial data are ignored. So start with one (possibly empty) series for each series you expect. The outlier data source is the exception: it adds a series the first time it appears in the stream. |
+| `generator` | A [generator](#generators): the function that creates the observable of chart data each time the data source starts. |
+| `dropDataAfter` | Optional time-to-live (ms, in data time, not wall-clock time) for the data. As new data arrives, points older than this, relative to the latest time, are dropped. Defaults to `Infinity` (keep everything). See [performance](#performance). |
+| `onUpdateData` | Optional callback that is handed each series' new points as they arrive, for example to store the data elsewhere before it's dropped. |
+| `timeGroupFor` | `TimeSeriesDataSource` only, optional. Assigns each series to a "time group" whose latest time `dropDataAfter` is measured against. Use it when series on different x-axes run on different clocks, for example `name => axisAssignments.get(name)?.xAxis ?? 'x-axis-1'`. By default, all series share one clock. |
+
+Every data source has the same lifecycle and the same read-only view of its data:
+
+| member | description |
+|---|---|
+| `start()` | Subscribes to the generator, handing it the current series. Does nothing when already running. A data source starts out stopped. |
+| `stop()` | Unsubscribes from the generator. Nothing keeps generating in the background. The data stays. |
+| `running` | Whether the data source is running. |
+| `isRunningObservable` | Emits whether the data source is running, starting with the current value. Useful for a Run/Pause button (or use the [`useDataSourceRunning`](#hooks) hook). The data source also stops on its own when the generator's observable completes or fails. |
+| `chartDataUpdatesObservable` | Emits each chunk of chart data *after* it has been added to the series. |
+| `series`, `seriesList()` | The live series (a map by name, and an array, in insertion order). They change in place as data arrives, so copy what you need. |
+| `latestTime()` | The latest time of any datum in any series (`-Infinity` when there's no data). |
+| `setDropDataAfter(ms)` | Changes the data TTL. It takes effect as the next data arrives. |
+| `setGenerator(generator)` | Replaces the generator, for example when the update period changes. Only allowed while the data source is stopped; the next `start()` uses it. |
+| `dispose()` | Stops the data source and completes its observables. A disposed data source can't be started again. To start over with new data (a "Reset"), dispose of the old data source and create a new one. |
+
+Two data sources keep extra state that their plots use:
+- `OrdinalDataSource.stats` holds the lifetime and windowed statistics (min, max, mean) of each category, which keep accumulating while no plot is mounted.
+- `IteratesDataSource.droppedCountFor(seriesName)` counts the points dropped from a series, so that the Poincaré plot's colorized lines keep their colors as old points are dropped.
+
+To build a data source for some other shape of data, extend `BaseStreamingDataSource` and implement `ingest(data)` and `latestTime()`.
+
+### <span id="generators">generators</span> [↑](#content "back to contents")
+
+A data source doesn't take an observable. It takes a `DataGenerator`, a function that *creates* the observable:
+
+```ts
+type DataGenerator<CD extends ChartData, S> = (currentSeries: Array<S>) => Observable<CD>
+```
 
-**seriesStyles (Map&lt;string, [SeriesLineStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) &gt;, optional)**<br>
-A map holding the data series name with an associated SeriesLineStyle. Any series listed in this map will use the associated styles for that series. Any series not in the map will use the default series styles.
+The data source calls the generator each time it starts, and hands it the series as they are *right now*. That's what lets **Run** after **Pause** carry on from the latest data, rather than starting over from the initial data. A typical generator reads the latest time from the current series and starts the new stream from there (see the [quick start](#quick-start)).
 
-The SeriesLineStyle has the following shape
-```typescript
-interface SeriesLineStyle {
-   color: string
-   lineWidth: number
-   // the color of the series when the user mouses over the series
-   highlightColor: string
-   // the line width of the series when the user mouses over the series 
-   highlightWidth: number
-   // the line margin used for raster charts
-   margin?: number
-}
->```
+Two things to get right in your observable:
+- **Emit only what's new.** Each emission's `newPoints` holds the points since the last emission. The data source keeps everything that came before.
+- **Make each emission a new object.** Give every emission its own `newPoints` map and its own arrays. The chart can buffer several emissions before it draws them, and if they share (and change) the same map, the buffered emissions all end up holding the latest values.
 
-#### [&#10514;](#content) <span id="chart-usage-initial-data">&lt;Chart/&gt; initial data</span>
+### <span id="chart-data">chart data, one shape for each plot</span> [↑](#content "back to contents")
 
-Holds the initial (static data). This data is displayed in the chart even before subscribing to the chart-data observable. The initial data can be used to generate static charts.
+Every chart data object holds `seriesNames: Set<string>`, and a `newPoints` map from each series' name to its new points. Each plot's chart data adds a little more.
 
-**initialData (Array<[Series](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/datumSeries.ts) >)**<br>
-An array holding the initial data series to be plotted before subscribing to the chart-data observable.  
->
-The Series has the following shape
-```typescript
-interface Series {
-   // the series name
-   readonly name: string
-   // the array of time-value pairs
-   data: Array<Datum>
-   // ... accessor functions
-   // . 
-   // . 
-   // . 
+**`TimeSeriesChartData`** (scatter and raster plots)
+```ts
+interface TimeSeriesChartData {
+    seriesNames: Set<string>
+    newPoints: Map<string, Array<Datum>>  // each series' new {x: time, y: value} points
+    maxTimes: Map<string, number>         // each series' latest time
+    maxTime: number                       // the latest time of all of them
+    currentTime?: number
 }
 ```
-And the [Datum](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/datumSeries.ts) is an immutable object that has the following shape 
-```typescript
-interface Datum {
-   readonly time: number;
-   readonly value: number;
-}
->```
-There are a number of helper functions for creating `Series` and `Datum`.
->> `seriesFrom(name: string, data: Array<Datum> = []): Series`<br>
->> `seriesFromTuples(name: string, data: Array<[number, number]> = []): Series`<br>
->> `emptySeries(name: string): Series`<br>
->> `emptySeriesFor(names: Array<string>): Array<Series>`<br>
-
-#### [&#10514;](#content) <span id="chart-usage-streaming-data">&lt;Chart/&gt; streaming data</span>
-
-A set of properties, functions, and callbacks to control and observe the streaming of live data into the chart.
-
-**seriesObservable (Observable<[ChartData](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/chartData.ts) >)**<br>
-An observable of (source for) chart-data. The `shouldSubscribe` property controls whether the chart subscribes to the observable, or unsubscribes. This is the source of live data to the chart. An example of an observable is shown below.
-```typescript
-function randomSpikeDataObservable(
-    series: Array<Series>,
-    updatePeriod: number = UPDATE_PERIOD_MS,
-    spikeProbability: number = 0.1
-): Observable<ChartData> {
-  const seriesNames = series.map(series => series.name)
-  const initialData = initialChartData(series)
-  return interval(updatePeriod).pipe(
-    // convert the number sequence to a time
-    map(sequence => (sequence + 1) * updatePeriod),
-    // create a random spike for each series
-    map((time) => randomSpikeData(time, seriesNames, initialData.maxTimes, updatePeriod, spikeProbability))
-  )
-}
+For a raster plot, each datum is an event (for example, a neuron's spike) at time `x`. Its `y` is shown in the tooltip.
+
+**`IterateChartData`** (Poincaré plot)
+
+You rarely build iterate data by hand. Write an observable of `TimeSeriesChartData` holding the sequence's values over time, and convert it with `iteratesObservable(observable, n)`, which pairs each value `f[m](x)` with the value `n` steps later, `f[m+n](x)`:
+
+```ts
+import {interval, map, scan, type Observable} from "rxjs"
+import {iteratesObservable, type IterateChartData, type IterateSeries, type DataGenerator, type TimeSeriesChartData} from "stream-charts"
+
+// the logistic map, x[n+1] = r x[n] (1 - x[n]), one value every 25 ms
+const logisticMap = (r: number, x0: number): Observable<TimeSeriesChartData> =>
+    interval(25).pipe(
+        scan(({x}, tick) => ({time: (tick + 1) * 25, x: r * x * (1 - x)}), {time: 0, x: x0}),
+        map(({time, x}) => ({
+            seriesNames: new Set(['logistic']),
+            maxTime: time,
+            maxTimes: new Map([['logistic', time]]),
+            newPoints: new Map([['logistic', [{x: time, y: x}]]]),
+        }))
+    )
+
+const generator: DataGenerator<IterateChartData, IterateSeries> =
+    () => iteratesObservable(logisticMap(3.8, 0.2), 1)   // 1-iterates: (f[m](x), f[m+1](x))
 ```
 
-**shouldSubscribe (boolean, optional, default = false)**<br>
-Optional property, that when set from `false` to `true`, causes the &lt;Chart/&gt; to subscribe to the chart-data observable. When set to `false` after a subscription, causes the &lt;Chart/&gt; to unsubscribe from the chart-data observable. 
-
-**windowingTime (number, milliseconds, optional, default = 100 ms)**<br>
-Optional property that defines a time-window during which incoming events are buffered, and then handed to plot, causing the plot to update. The `windowingTime` defines the maximum plot update rate, though not the maximum data update rate. The larger the windowing time, the fewer updates per unit time, and the more choppy the updates. Large amounts of data with high update rates can cause rendering delays. The windowing time provides a lever to manage the plot update rates to get the smoothest plot updates that keep up with real-time.
-
-**shouldSubscribe (number, optional, default = false)**<br>
-Optional property that default to `false`. When changed to `true`, from `false`, signals the &lt;Chart/&gt; to subscribe to the `seriesObservable`, streaming in the `ChartData` and updating the &lt;Chart/&gt; in real-time.
-
-**onSubscribe (callback function, (subscription: Subscription) => void, optional, default = noop**<br>
-Optional callback function that is called when the &lt;Chart/&gt; subscribes to the `ChartData` observable.
-
-**onUpdateData (callback function, (seriesName: string, data: Array<Datum>)) => void, optional, default = noop)**<br>
-Optional callback function that is called when the data updates. This callback can be used if you would like to respond to data updates. For example, use this callback if you would like to have the plot drop data after 10 seconds, but would like to store that data in an in-browser database. Though, a more efficient way to store the data would be to subscribe to the series-observable separately, and then use that observer to stream the data to the storage.
-
-**onUpdateTime (callback function, (times: Map<string, [start: number, end: number]>) => void, optional, default = noop)**<br>
-Optional callback this is called whenever the time-ranges change. Use this to track the current time of the plot.
-
-## [&#10514;](#content) <span id="axes">axes</span>
-
-### [&#10514;](#content) <span id="continuous-axes-usage">&lt;ContinuousAxis/&gt;</span>
-
-The &lt;ContinuousAxis/&gt; must be a child of the &lt;Chart/&gt;. Each &lt;Chart/&gt can one or two continuous axes for the x-axes and for the y-axes. When a &lt;Chart/&gt has multiple x-axes or y-axes then you must assign series to the axes in one of the `Plot` components. Any series that are not explicitly assigned an axis will be assigned to the default x-axis or y-axis. The default x-axis is the bottom axis in the &lt;Chart/&gt, and the default y-axis is the left-hand side axis in the &lt;Chart/&gt.
-
-When creating a &lt;ContinuousAxis/&gt;, you must specify its location using the `AxisLocation` enum defined in the [axes.ts](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) file. Each axis must have a unique axis ID. By default a &lt;ContinuousAxis/&gt; will have a linear scale (d3.scaleLinear). The `scale` property can by used to set the scale to a `log` (d3.scaleLog) or `power` (d3.scalePow) scale or any other continuous numeric scale available in `d3`. The `domain` property defines the initial min and max values for the axis, and when data streams into the plot, that defines the time-window displayed for the axis (unless changed by a zoom event).
-
-#### [&#10514;](#content) <span id="continuous-axes-usage-base">&lt;ContinuousAxis/&gt; base properties</span>
-
-The base properties defining the axis.
-
-**axisId (string)**<br>
-The unique ID of the axis. The axis can then be referred to by this ID. For example, when assigning axes to series, the assignment is made by associating the axis ID to the series name.
-
-**location ([AxisLocation](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) )**<br>
-The location of the axis. As defined by the `AxisLocation` in the the [axes.ts](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) file, x-axes can be placed on the `bottom` or the `top`, and y-axes can be placed on the `left` or the `right`. 
-
-**scale (ScaleContinuousNumeric<number, number>, optional, default = d3.scaleLinear)**<br>
-The optional scale (factory) of the continuous axis. The scale of the axis is like the axis ruler and determines how the points are placed on the screen. For example, a linear scale is like an evenly spaced ruler, and the mapping between screen location and data value are linear. As another example, the log scale has a logarithmic mapping between the screen location and the data. The scale can be a linear scale (default scale, d3.scaleLinear), a logarithmic scale (d3.scaleLog), a power scale (d3.scalePower), or any other d3 continouos numeric scale that works. Not that if a chart, for example, has two x-axes, that the x-axes are **not** required to have the same scale.
-
-**domain ([min: number, max: number])**<br>
-The domain of the axis (in d3 terminology) is effectively the minimum value of the axis and the maximum value of the axis when the initial data is displayed. The domain defines the time-window of the displayed data. For example, if the `domain` for an x-axis is specified as `[1000, 6000]`, then the axis starts at `1000` and ends at `6000`, and the time-window is `5000`. Once data starts to stream past the axis end, the plot starts to scroll, maintaining the calculated time-window (in out example, 5000). Of course, a zooming event will change the domain, and also the time-window.
-
-**label (string)**<br>
-The axis label.
-
-#### [&#10514;](#content) <span id="continuous-axes-usage-styling">&lt;ContinuousAxis/&gt; styling</span>
+**`OrdinalChartData`** (bar plot)
 
-A set of properties to update the style of the axes.
+Like the iterate data, ordinal data is usually derived: `ordinalsObservable(timeSeriesObservable, compactingSize?, initialStats?)` turns a `TimeSeriesChartData` observable (one series per category) into ordinal data, accumulating each category's statistics. Pass `calculateOrdinalStats(currentSeries)` as the `initialStats`, so that a restarted stream's statistics include the data the data source already holds:
 
-**font (Partial<[AxesLabelFont](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) >)**<br>
-An optional CSS properties specifying the font for the axis and tick labels.
+```ts
+const generator: DataGenerator<OrdinalChartData, OrdinalSeries> =
+    currentSeries => ordinalsObservable(myCategoryValues(currentSeries), undefined, calculateOrdinalStats(currentSeries))
+```
 
+**`OutlierChartData<M>`** (outlier plot)
+```ts
+interface OutlierChartData<M extends readonly number[]> {
+    seriesNames: Set<string>
+    newPoints: Map<string, Array<OutlierDatum<M>>>
+    currentTime?: number
+}
+```
+`M` is a tuple of *measures*, the confidence level of each band, for example `[0.68, 0.95, 0.997] as const` for 1σ, 2σ, and 3σ. Each `OutlierDatum<M>` holds the point (`datum: {x, y}`) and one `{lower, upper}` bound for each measure (`bounds`). Create them with `outlierDatumFor(datum, measures, bounds)` and `outlierBoundsFor(lower, upper)`. Both check that there's one bound for each measure, and return a `Result`.
 
-### [&#10514;](#content) <span id="ordinal-axes-usage">&lt;OrdinalAxis/&gt;</span>
+### <span id="series-helpers">series and datum helpers</span> [↑](#content "back to contents")
 
-The &lt;OrdinalAxis/&gt; must be a child of the &lt;Chart/&gt;. Each &lt;Chart/&gt; can have one or two ordinal axes for the y-axes. Unlike the [&lt;ContinuousAxis/&gt;](#continuous-axes-usage), the &lt;OrdinalAxis/&gt; can only be used as a y-axis because for stream charts (at this point) the x-axes represent time. In the same way as with the [&lt;ContinuousAxis/&gt;](#continuous-axes-usage), when using multiple multiple y-axes you must assign the series to the axes in one of the `Plot` components. Any series that are not explicitly assigned an axis will be assigned to the default y-axis, which is the left-hand side axis in the &lt;Chart/&gt;.
+A series is a named array of data. Its data is held in a `FastShiftArray`, so that dropping the oldest points is cheap.
 
-When creating an &lt;OrdinalAxis/&gt;, you must specify its location using the `AxisLocation` enum defined in the [axes.ts](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) file. Each axis must have a unique axis ID. The &lt;OrdinalAxis/&gt; uses a band scale (d3.scaleBand).
+| function | creates |
+|---|---|
+| `emptySeries<D>(name)`, `emptySeriesFor<D>(names)` | empty series (a good start for streaming data) |
+| `seriesFrom<D>(name, data)` | a series holding the data |
+| `timeSeriesFromTuples(name, [[time, value], ...])` | a time series (scatter, raster) |
+| `iterateSeriesFromTuples(name, [[time, iterateN, iterateN_1], ...])` | an iterate series (Poincaré) |
+| `ordinateSeriesFromTuples(name, [[time, ordinal, value], ...])` | an ordinal series (bar) |
+| `outlierSeriesFor(name, measures, [[time, value, bounds], ...])`, `outlierSeriesFrom(name, data, measures)` | an outlier series |
+| `datumOf(time, value)`, `iterateDatumOf(...)`, `ordinalDatumOf(...)` | a single datum |
+| `initialTimeSeriesChartData(series)`, `initialOrdinalChartData(series)` | chart data to start a stream from |
 
-#### [&#10514;](#content) <span id="ordinal-axes-usage-base">&lt;OrdinalAxis/&gt; base properties</span>
+> **Ownership:** `seriesFrom` wraps the array you hand it *by reference*. As data streams in and ages out, the library changes that array in place. If you keep your own reference to it, pass a copy (`data.slice()`) instead.
 
-The base properties defining the axis.
+`series.last()` returns a `Result` (from [result-fn](https://github.com/robphilipp/result-fn)), which is a failure when the series is empty: `series.last().map(datum => datum.x).getOrElse(0)`.
 
-**axisId (string)**<br>
-The unique ID of the axis. The axis can then be referred to by this ID. For example, when assigning axes to series, the assignment is made by associating the axis ID to the series name.
+### <span id="performance">performance: data TTL, windowing, and cadence</span> [↑](#content "back to contents")
 
-**location ([AxisLocation](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) )**<br>
-The location of the axis. As defined by the `AxisLocation` in the the [axes.ts](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) file, x-axes can be placed on the `bottom` or the `top`, and y-axes can be placed on the `left` or the `right`.
+`stream-charts` is built for large amounts of high-frequency data. When the data's time passes the end of the x-axis, the chart scrolls to keep up. The data that scrolls off the chart is still held, so you can pan or zoom back to it. To get there, the charts:
+1. take their data from an [RxJS](https://rxjs.dev) observable, through a data source,
+2. draw onto a single `<canvas>` (with [d3](https://d3js.org) scales and shapes), and
+3. keep the drawing outside React's render cycle.
 
-**categories (Array<string>)**<br>
-The required `categories` property holds the names of the categories, in the order that they will be displayed on the axis. The first element in the array will be shown at the top of the axis. The second element will be lower, and the last element will be at the bottom of the axis.
+There are limits, of course. When a chart starts to stutter, you have these levers. Each stream is different, so expect to tune them.
 
-**domain ([min: number, max: number])**<br>
-The domain of the axis (in d3 terminology) is effectively the minimum value of the displayed axis and the maximum value of the displayed axis when the initial data is displayed. The domain defines the time-window of the displayed data. For example, if the `domain` for an x-axis is specified as `[1000, 6000]`, then the axis starts at `1000` and ends at `6000`, and the time-window is `5000`. Once data starts to stream past the axis end, the plot starts to scroll, maintaining the calculated time-window (in our example, 5000). Of course, a zooming event will change the domain, and also the time-window.
+1. **Drop old data (`dropDataAfter`, on the data source).** Without it, the data that scrolls off the chart is kept, and processed, forever. With it, a scrolling chart can run indefinitely. The TTL is measured in data time, not wall-clock time. To keep the dropped data, store it with the data source's `onUpdateData` callback (or a separate subscription to your observable).
+2. **Batch the updates (`windowingTime`, on the chart).** The chart collects incoming data for this long (ms) before redrawing. Longer windows mean fewer redraws, and so better performance, at the cost of choppier scrolling.
+3. **Tell the chart your update period (`dataUpdatePeriod`, on the chart).** When your data arrives at a known, regular period, the chart buffers a fixed number of updates rather than a fixed amount of time, which makes scrolling smoother. Leave it out when your data arrives at irregular times.
+4. **Use a cadence for slow data (`withCadenceOf`, on the plot).** When updates are slow (more than about 100 ms apart), a cadence of 10–25 ms advances the time axis smoothly between updates. At high update rates it's unnecessary, and a cadence that's too short hurts performance.
+5. **Shorten the time window (the x-axis `domain`).** A shorter window holds less data, though the data streams by faster.
 
-**label (string)**<br>
-The axis label.
+---
 
-#### [&#10514;](#content) <span id="ordinal-axes-usage-styling">&lt;OrdinalAxis/&gt; styling</span>
+## <span id="components">components</span> [↑](#content "back to contents")
 
-A set of properties to update the style of the axes.
+### <span id="chart">&lt;Chart/&gt;</span> [↑](#content "back to contents")
 
-**font (Partial<[AxesLabelFont](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/axes.ts) >, optional)**<br>
-An optional CSS properties specifying the font for the axis and tick labels.
+The `<Chart>` is the container for everything else: the axes, the plot, and the tracker, tooltip, and legend. It creates the canvas, reads from the data source, and provides the shared state that its children use (see [hooks](#hooks)).
 
+```tsx
+<Chart
+    chartId={1}
+    width={800}
+    height={400}
+    margin={{...defaultMargin, top: 40, right: 60}}
+    color={theme.color}
+    backgroundColor={theme.backgroundColor}
+    seriesStyles={new Map([['kitchen', {...defaultLineStyle(), color: 'orange', highlightColor: 'orange'}]])}
+    seriesFilter={filter}
+    dataSource={dataSource}
+    windowingTime={50}
+    dataUpdatePeriod={50}
+    onUpdateAxesBounds={ranges => setXAxisRange(ranges.get('x-axis-1'))}
+>
+    {/* axes, plot, tracker, tooltip, legend */}
+</Chart>
+```
 
-## [&#10514;](#content) <span id="plots">plots</span>
+The chart is generic in its data: `Chart<CD, D, S, TM, AR, A>`, where `CD` is the chart data, `D` the datum, `S` the series style, `TM` the tooltip metadata, `AR` the axis range, and `A` the axis type. TypeScript infers these for most charts. For a bar chart, spell them out:
 
-### [&#10514;](#content) <span id="scatter-plot-usage">&lt;ScatterPlot/&gt;</span>
+```tsx
+<Chart<OrdinalChartData, OrdinalDatum, BarSeriesStyle, WindowedOrdinalStats, OrdinalAxisRange, OrdinalStringAxis> ...>
+```
 
-In `stream-charts`, the `plot` is the data visualization component. To work, a plot must be a child of the &lt;Chart/&gt; component so that it is plugged into the `stream-charts` ecosystem. The plot determines how to render the data. But it relies on the axes to determine scaling information so that it can map data to screen locations. And therefore, a plot must have sibling axes ([&lt;ContinousAxis/&gt;](#continuous-axes-usage), [&lt;OrdinalAxis/&gt;](#ordinal-axes-usage)) components for the x-axis and the y-axis. Because the plot is responsible for data visualization, it is also where the data series are assigned to axes. The assignment of axes to series is optional, and any series not explicitly assigned to an axis will be assigned to the default axes. The default x-axis is the bottom axis, and the default y-axis is the axis on the left-hand side of the plot. 
+#### <span id="chart-dimensions">dimensions</span>
 
-The plot determines what view-modifying user interactions are available. Specifically, panning the data to the left and right in time, and zooming in time.
+| prop | type | description |
+|---|---|---|
+| `chartId` | `number` | **Required.** A unique ID for the chart. |
+| `width` | `number` | **Required.** The width (px) of the chart's container. The plot area is this, less the margins. |
+| `height` | `number` | **Required.** The height (px) of the chart's container. The plot area is this, less the margins. |
+| `margin` | `Partial<Margin>` | The space (px) between the container's edges and the plot area, which holds the axes, their ticks, and labels. Any side you leave out uses `defaultMargin`. `Margin` is `{top, bottom, left, right}`. |
 
-The &lt;ScatterPlot/&gt; specifically is used to plot time-series data, where the x-values are time. The x-axis and y-axis are required to be a [&lt;ContinousAxis/&gt;](#continuous-axes-usage).
+The chart draws onto a canvas, which must know its exact size in pixels, so the chart doesn't size itself to its container: you hand it `width` and `height`. It redraws when they change. To follow a resizing window or layout, measure the chart's container, for example with a `ResizeObserver`, and pass the size along. (The examples get their sizes from the grid cells of [react-resizable-grid-layout](https://www.npmjs.com/package/react-resizable-grid-layout), with `useGridCellWidth()` and `useGridCellHeight()`.)
 
-#### [&#10514;](#content) <span id="scatter-plot-usage-base">&lt;ScatterPlot/&gt; base properties</span>
+#### <span id="chart-styling">styling</span>
 
-**axisAssignments (Map<string, [AxesAssignment](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/plot.ts) >, optional, default = Map())**<br>
-An optional property that assigns data series to (x, y)-axes. Any series not assigned to an axis will use the default axis. The default x-axis is the bottom axis, and the default y-axis is the axis on the left-hand side of the plot. The `Map` associates the series name with an [AxesAssignment](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/plot.ts), which is a simple object (`{xAxis: string, yAxis: string}`) that holds the axis ID for the x-axis and for the y-axis assigned to the series.
+| prop | type | description |
+|---|---|---|
+| `color` | `string` | The default color of the axes and text (default `'#d2933f'`). The axes' own styles can override it. |
+| `backgroundColor` | `string` | The background color of the whole chart (default `'#202020'`). |
+| `seriesStyles` | `Map<string, S>` | Maps a series' name to its style. A series that isn't in the map uses the default style. For the scatter, raster, Poincaré, and outlier plots, the style is a `SeriesLineStyle` (start from `defaultLineStyle()`). For the bar plot, it's a `BarSeriesStyle` (start from `defaultBarSeriesStyle(color)`). |
+| `svgStyle` | `Partial<SvgStyle>` | CSS overrides for the chart's container element. Rarely needed. |
 
-**interpolation (d3.CurveFactory, optional, default = d3.curveLinear)**<br>
-An optional property that defines how the data series line will be interpolated between individual data points. You can use any valid [d3.CurveFactory](https://github.com/d3/d3-shape#curves) for the interpolation. Changing the interpolation once the data is already display, will cause a re-render of the data with the new interpolation.
+```ts
+interface SeriesLineStyle {
+    color: string
+    lineWidth: number
+    highlightColor: string   // the color of the series when the mouse is over it
+    highlightWidth: number   // the line width of the series when the mouse is over it
+    margin?: number          // the raster plot's spike margin, for this series
+}
+```
 
-<span id="scatter-plot-drop">**dropDataAfter (number, milliseconds, opitional, default = Infinity)**</span><br>
-Optional property that sets when to drop data (effectively a TTL). This only drops data while streaming. Don't worry, your data won't disappear after the streaming has stopped. By default, none of the data is dropped. However, when large amounts of data are being streamed and plotted over long periods of time, memory and performance may become an issue. Setting this value allows a scrolling chart to run forever without running into resource issues.
+All styles are exposed as props, so you can drive them from your theme provider, or not use one at all (see [theming](#theming)).
 
-#### [&#10514;](#content) <span id="scatter-plot-usage-view">&lt;ScatterPlot/&gt; view-modifying interactions</span>
+#### <span id="chart-data-props">data</span>
 
-View-modifying interactions are those that change the way the data is displayed. For example, zooming in time, panning in time.
+| prop | type | description |
+|---|---|---|
+| `dataSource` | `StreamingDataSource` | **Required.** The [data source](#data-sources) that holds the chart's data. The chart only reads from it; you start and stop it. Handing the chart a *new* data source resets the plots to that data source's data. |
+| `windowingTime` | `number` (ms) | How long the chart collects incoming data before it redraws (default 100 ms). See [performance](#performance). |
+| `dataUpdatePeriod` | `number` (ms) | The period at which your generator emits, when you know it. The chart then buffers a fixed number of updates (`windowingTime / dataUpdatePeriod`), which makes scrolling smoother. |
+| `seriesFilter` | `RegExp` | Only the series whose names match are shown. It can change while streaming. Patterns that risk catastrophic backtracking are ignored, with a warning (see [filtering series](#filtering)). |
+| `onUpdateAxesBounds` | `(ranges: Map<string, AxisInterval>) => void` | Called when the axes' ranges change, for example as the x-axis scrolls, or when the user zooms or pans. The map is keyed by axis ID. Use it to keep the current time range in your state (and to hand it back as the axis `domain` when the chart remounts). |
+| `onUpdateChartTime` | `(time: number) => void` | Called with the current chart time. Mainly for plots whose axes don't show time, like the Poincaré and bar plots. |
+| `children` | | The axes, the plot, and optionally the tracker, tooltip, and legend. |
 
-**panEnabled (boolean, optional, default = false)**<br>
-Optional property that defaults to `false`. When set to `true` then enables "panning" which allows the user to drag the plot to the left and right.
+### <span id="axes">axes</span> [↑](#content "back to contents")
 
-**zoomEnabled (boolean, optional, default = false)**<br>
-Optional property that defaults for `false`. When set to `true` then enables "zooming" which allows the user to increase or decrease the displayed time range. By default, scrolling will cause the zoom effect. See the `zoomKeyModifiersRequired` property which requires the `shift` key to be pressed in order for the zoom action to apply.
+A chart has one or two x-axes (`AxisLocation.Bottom`, `AxisLocation.Top`) and one or two y-axes (`AxisLocation.Left`, `AxisLocation.Right`). Each axis has a unique `axisId`. When a chart has more than one x-axis or y-axis, you assign series to axes with the plot's [`axisAssignments`](#plot-common). A series without an assignment uses the default axes: the first x-axis and the first y-axis in the chart's children, whatever their location.
 
-**zoomKeyModifiersRequired (boolean, optional, default = false)**<br>
-An optional property that defaults to `false`. When set to `true`, and the `zoomEnabled` property is also set to `true`, then requires that the `shift` key be pressed when scrolling in order to activate the zoom. This is nice when a user can scroll through your page containing the plot, so that zooming doesn't interfere with scrolling. 
+#### <span id="plot-axes">which axes each plot takes</span>
 
-**withCadenceOf (number, optional, default = undefinded)**<br>
-An optional property that defaults to `undefined`. When set, uses a cadence with the specified refresh period (in milliseconds). For plots with slow data updates (> 100 ms) using a cadence of 10 to 25 ms smooths out the updates so the time scrolling doesn't appear choppy. When updates are around 25 ms or less, then setting the cadence period too small will result in poor update performance. Generally at high update speeds, the cadence is unnecessary. Finally, using cadence, sets the max time to the current time. See also the related &lt;Chart/&gt's `windowingTime` property.
+Each plot needs particular kinds of axes:
 
+| plot | x-axis | y-axis |
+|---|---|---|
+| `<ScatterPlot>` | `<ContinuousAxis>` | `<ContinuousAxis>` |
+| `<RasterPlot>` | `<ContinuousAxis>` | `<OrdinalAxis>` |
+| `<PoincarePlot>` | `<ContinuousAxis>` | `<ContinuousAxis>` |
+| `<BarPlot>` | `<OrdinalAxis>` | `<ContinuousAxis>` |
+| `<OutlierPlot>` | `<ContinuousAxis>` | `<ContinuousAxis>` |
 
-### [&#10514;](#content) <span id="raster-plot-usage">&lt;RasterPlot/&gt;</span>
+- **An `<EmptyAxis>` counts as a continuous axis.** It's fine as a raster chart's top x-axis, but a raster chart's series can't use one as their y-axis.
+- **The order of the axes matters.** Unassigned series use the *first* x-axis and the *first* y-axis, so put the axes your series use before any `<EmptyAxis>`. In a raster chart with an `<EmptyAxis>` on the right, list the `<OrdinalAxis>` first; otherwise the empty (continuous) axis becomes the default y-axis.
+- **The Poincaré plot only uses the first x-axis and the first y-axis** (it has no `axisAssignments`). Any others just mirror them.
+- **A series assigned to an axis ID that doesn't exist isn't drawn.** It doesn't fall back to the default axes.
+- **The wrong kind of axis is reported when the plot draws.** The chart logs the error to the console, along the lines of `<RasterPlot> needs its y-axis to be an <OrdinalAxis>, but the y-axis "y-axis-2" is a <ContinuousAxis> (or an <EmptyAxis>)`, and skips that drawing. The axes are child components, so TypeScript can't catch the mismatch.
 
-In `stream-charts`, the `plot` is the data visualization component. To work, a plot must be a child of the &lt;Chart/&gt; component so that it is plugged into the `stream-charts` ecosystem. The plot determines how to render the data. But it relies on the axes to determine scaling information so that it can map data to screen locations. And therefore, a plot must have sibling axes ([&lt;ContinousAxis/&gt;](#continuous-axes-usage), [&lt;OrdinalAxis/&gt;](#ordinal-axes-usage)) components for the x-axis and the y-axis. Because the plot is responsible for data visualization, it is also where the data series are assigned to axes. The assignment of axes to series is optional, and any series not explicitly assigned to an axis will be assigned to the default axes. The default x-axis is the bottom axis, and the default y-axis is the axis on the left-hand side of the plot.
+#### <span id="continuous-axis">&lt;ContinuousAxis/&gt;</span>
 
-The plot determines what view-modifying user interactions are available. Specifically, panning the data to the left and right in time, and zooming in time.
+A numeric axis, for time on the x-axis, or for values on either axis.
 
-The &lt;RasterPlot/&gt; specifically is used to plot event-timing data, where the x-values are time, and the y-values are a category to which the event belongs. The x-axis is required to be a [&lt;ContinuousAxis/&gt;](#continuous-axes-usage), and the y-axis is required to be an [&lt;OrdinalAxis/&gt;](#ordinal-axes-usage).
+```tsx
+<ContinuousAxis axisId="y-axis-2" location={AxisLocation.Right} scale={d3.scaleLog()} domain={[100, 1200]} label="distance (µm)"/>
+```
 
-#### [&#10514;](#content) <span id="raster-plot-usage-base">&lt;RasterPlot/&gt; base properties</span>
+| prop | type | description |
+|---|---|---|
+| `axisId` | `string` | **Required.** The axis' unique ID, used to assign series to it. |
+| `location` | `AxisLocation` | **Required.** `Bottom` or `Top` for an x-axis; `Left` or `Right` for a y-axis. |
+| `domain` | `[min, max]` | **Required.** The axis' starting range. For a time axis, this is also the time window: a domain of `[0, 5000]` shows 5 seconds, and once data passes 5000 ms, the axis scrolls, keeping that window (until a zoom changes it). |
+| `label` | `string` | **Required.** The axis label. |
+| `scale` | `ScaleContinuousNumeric` | The d3 scale (default `d3.scaleLinear()`). Any continuous numeric d3 scale works, such as `d3.scaleLog()` or `d3.scalePow()`. Two x-axes (or y-axes) can have different scales. |
+| `font` | `Partial<AxesFont>` | The font of the ticks and label. |
+| `updateAxisBasedOnDomainValues` | `boolean` | When `true` (the default), the axis resets when the *values* of `domain` change, so you can pass a new tuple literal on each render. For charts that don't scroll, such as the Poincaré plot, set it to `false` to reset when the `domain` *object* changes instead, for example when the user picks a new function. |
 
-**axisAssignments (Map<string, [AxesAssignment](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/plot.ts) >, optional, default = Map())**<br>
-An optional property that assigns data series to (x, y)-axes. Any series not assigned to an axis will use the default axis. The default x-axis is the bottom axis, and the default y-axis is the axis on the left-hand side of the plot. The `Map` associates the series name with an [AxesAssignment](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/plot.ts), which is a simple object (`{xAxis: string, yAxis: string}`) that holds the axis ID for the x-axis and for the y-axis assigned to the series.
+<span id="continuous-axis-autoscale">**Auto-scaling y-axes**</span> (scatter, bar, and outlier plots). With `autoScale`, a y-axis grows to fit the data on screen. It only ever grows, and goes back to `domain` when the plot's data is replaced, or when `domain` or the limits change.
 
-<span id="raster-plot-drop">**dropDataAfter (number, milliseconds, opitional, default = Infinity)**</span><br>
-Optional property that sets when to drop data (effectively a TTL). This only drops data while streaming. Don't worry, your data won't disappear after the streaming has stopped. By default, none of the data is dropped. However, when large amounts of data are being streamed and plotted over long periods of time, memory and performance may become an issue. Setting this value allows a scrolling chart to run forever without running into resource issues.
+| prop | type | description |
+|---|---|---|
+| `autoScale` | `boolean` | Turns auto-scaling on (default `false`). Ignored, with a warning, on x-axes and in plots that don't support it. |
+| `autoScaleMin`, `autoScaleMax` | `number` | The limits the domain may grow to (default `-Infinity` and `Infinity`). |
+| `autoScalePadding` | `number` | The fraction of the axis left beyond the data's extreme (0 to 0.45, default 0.05). |
+| `autoScaledDomain`, `onAutoScale` | `[min, max]`, `(domain) => void` | Keep the grown domain across remounts: store what `onAutoScale` hands you, and pass it back as `autoScaledDomain`. |
 
-**spikeMargin (number, pixels, default = 2)**<br>
-Optional property that adds a margin to the top and bottom of the raster (event) lines to give vertical spacing to the events in the plot. Margins on individual series can also be set through the [Chart.seriesStyles](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/hooks/useChart.tsx) property.
+#### <span id="ordinal-axis">&lt;OrdinalAxis/&gt;</span>
 
-#### [&#10514;](#content) <span id="raster-plot-usage-view">&lt;RasterPlot/&gt; view-modifying interactions</span>
+A category axis (a d3 band scale). The raster plot uses one for its y-axis (one row per series), and the bar plot uses one for its x-axis (one bar per series).
 
-View-modifying interactions are those that change the way the data is displayed. For example, zooming in time, panning in time.
+```tsx
+<OrdinalAxis axisId="y-axis-1" location={AxisLocation.Left} categories={dataSource.seriesList().map(s => s.name)} label="neuron"/>
+```
 
-**panEnabled (boolean, optional, default = false)**<br>
-Optional property that defaults to `false`. When set to `true` then enables "panning" which allows the user to drag the plot to the left and right.
+| prop | type | description |
+|---|---|---|
+| `axisId` | `string` | **Required.** The axis' unique ID. |
+| `location` | `AxisLocation` | **Required.** Where the axis goes. |
+| `categories` | `Array<string>` | **Required.** The category names, in display order. On a y-axis, the first category is at the top. |
+| `label` | `string` | **Required.** The axis label. |
+| `axisTickStyle` | `Partial<AxisTickStyle>` | The style of the tick labels, for example `{rotation: 45}` for long category names. |
+| `font` | `Partial<AxesFont>` | The font of the ticks and label. |
+| `scale` | `ScaleBand<string>` | The d3 band scale (rarely needed). |
 
-**zoomEnabled (boolean, optional, default = false)**<br>
-Optional property that defaults for `false`. When set to `true` then enables "zooming" which allows the user to increase or decrease the displayed time range. By default, scrolling will cause the zoom effect. See the `zoomKeyModifiersRequired` property which requires the `shift` key to be pressed in order for the zoom action to apply.
+#### <span id="empty-axis">&lt;EmptyAxis/&gt;</span>
 
-**zoomKeyModifiersRequired (boolean, optional, default = false)**<br>
-An optional property that defaults to `false`. When set to `true`, and the `zoomEnabled` property is also set to `true`, then requires that the `shift` key be pressed when scrolling in order to activate the zoom. This is nice when a user can scroll through your page containing the plot, so that zooming doesn't interfere with scrolling.
+A plain line where an axis would be, without ticks or a label. Use it to frame the plot on a side that has no axis of its own. It counts as a continuous axis, so list it after the axes your series use (see [which axes each plot takes](#plot-axes)).
 
-**withCadenceOf (number, optional, default = undefinded)**<br>
-An optional property that defaults to `undefined`. When set, uses a cadence with the specified refresh period (in milliseconds). For plots with slow data updates (> 100 ms) using a cadence of 10 to 25 ms smooths out the updates so the time scrolling doesn't appear choppy. When updates are around 25 ms or less, then setting the cadence period too small will result in poor update performance. Generally at high update speeds, the cadence is unnecessary. Finally, using cadence, sets the max time to the current time. See also the related &lt;Chart/&gt's `windowingTime` property.
+```tsx
+<EmptyAxis axisId="x-axis-2" location={AxisLocation.Top}/>
+```
 
-### [&#10514;](#content) <span id="bar-plot-usage">&lt;BarPlot/&gt;</span>
+### <span id="plots">plots</span> [↑](#content "back to contents")
 
-The &lt;BarPlot/&gt; is used to plot windowed statistics for a data series. It can display the current value, the mean value, and the min/max range for the windowed data.
+The plot draws the data. It reads the series from the chart's data source and the scales from its sibling axes. A chart holds one plot.
 
-#### [&#10514;](#content) <span id="bar-plot-usage-base">&lt;BarPlot/&gt; base properties</span>
+#### <span id="plot-common">properties common to the plots</span>
 
-**axisAssignments (Map<string, [AxesAssignment](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/plot.ts) >, optional, default = Map())**<br>
-An optional property that assigns data series to (x, y)-axes. Any series not assigned to an axis will use the default axis. The default x-axis is the bottom axis, and the default y-axis is the axis on the left-hand side of the plot.
+| prop | type | plots | description |
+|---|---|---|---|
+| `axisAssignments` | `Map<string, AxesAssignment>` | all but Poincaré | Assigns series to axes: `new Map([['kitchen', assignAxes('x-axis-2', 'y-axis-2')]])`. Unassigned series use the first x-axis and the first y-axis (see [which axes each plot takes](#plot-axes)). |
+| `panEnabled` | `boolean` | all | Lets the user drag the plot to pan (default `false`). |
+| `zoomEnabled` | `boolean` | all | Lets the user scroll to zoom (default `false`). |
+| `zoomKeyModifiersRequired` | `boolean` | all | When `true` (the default), zooming requires holding shift (or ctrl) while scrolling, so that zooming doesn't get in the way of scrolling the page. |
+| `withCadenceOf` | `number` (ms) | all | Advances the time axis on this cadence, between data updates, for smooth scrolling of slow data. See [performance](#performance). (The Poincaré plot accepts it, but doesn't use it, since its axes don't show time.) |
+| `highlightAxesOnMouseOver` | `boolean` | all | When `true`, hovering over a series also highlights the axes it's plotted against (default `false`). |
+| `onZoomReset` | `(resetZoom: () => void) => void` | all | Hands you a `resetZoom` function, to call when you reset the axes yourself (for example, from a **Reset** button). The zoom keeps its own state, separate from the axes' ranges. Without `resetZoom`, the next zoom gesture after such a reset jumps back to the old zoom. |
 
-**showMinMaxBars (boolean, optional, default = false)**<br>
-When `true`, displays bars representing the minimum and maximum values in the data.
+#### <span id="scatter-plot">&lt;ScatterPlot/&gt;</span>
 
-**showWindowedMinMaxBars (boolean, optional, default = false)**<br>
-When `true`, displays bars representing the windowed minimum and maximum values.
+Values over time, drawn as lines, with optional markers. Both axes are `<ContinuousAxis>`. Uses a `TimeSeriesDataSource`. ([full example](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/StreamingScatterChart.tsx), [walkthrough](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/scatter-chart.md))
 
-**showValueLines (boolean, optional, default = false)**<br>
-When `true`, displays lines representing the current values of the data series.
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="packages/examples/public/images/scatter-chart-dark.png">
+    <img src="packages/examples/public/images/scatter-chart-light.png" alt="the scatter chart example: ten random walks on two x-axes and two y-axes, with an external legend">
+</picture>
 
-**showMeanValueLines (boolean, optional, default = false)**<br>
-When `true`, displays lines representing the mean values of the data series.
+[▶ watch it stream](packages/examples/public/images/scatter-chart-streaming.gif) (animated)
 
-**showWindowedMeanValueLines (boolean, optional, default = false)**<br>
-When `true`, displays lines representing the windowed mean values.
+| prop | type | description |
+|---|---|---|
+| `interpolation` | `d3.CurveFactory` | How the line is drawn between points (default `d3.curveLinear`). Any [d3 curve](https://d3js.org/d3-shape/curve) works, such as `d3.curveMonotoneX` or `d3.curveStep`. |
+| `timeWindowBehavior` | `TimeWindowBehavior` | `SCROLL` (the default) scrolls the time axis as data passes its end. `SQUEEZE` compresses the time axis to fit all the data instead. |
+| `markerRadius` | `number` (px) | Draws a circle of this radius at each point. No markers when omitted. |
+| `hideMarkersWhileRunning` | `boolean` | Hides the markers while the data source is running, showing them when paused (default `true`). |
 
-**barMargin (number, pixels, optional, default = 2)**<br>
-Optional property that adds a margin to the top and bottom of the bars.
+```tsx
+<Chart chartId={1} width={width} height={height} dataSource={dataSource} seriesStyles={seriesStyles}
+       windowingTime={50} dataUpdatePeriod={50} onUpdateAxesBounds={handleAxesBounds}>
+    <ContinuousAxis axisId="x-axis-1" location={AxisLocation.Bottom} domain={[0, 10_000]} label="time (ms)"/>
+    <ContinuousAxis axisId="y-axis-1" location={AxisLocation.Left} domain={[0, 1000]} label="distance (µm)"/>
+    <ContinuousAxis axisId="x-axis-2" location={AxisLocation.Top} domain={[0, 5000]} label="expanded time (ms)"/>
+    <ContinuousAxis axisId="y-axis-2" location={AxisLocation.Right} scale={d3.scaleLog()} domain={[100, 1200]} label="distance (µm)"/>
+    <Tracker visible={true} labelFormatter={x => `${d3.format(",.0f")(x)} ms`}/>
+    <Tooltip visible={true}>
+        <ScatterPlotTooltipContent xLabel="t (ms)" yLabel="distance" yValueFormatter={value => formatNumber(value, " ,.0f")}/>
+    </Tooltip>
+    <ScatterPlot
+        interpolation={d3.curveMonotoneX}
+        axisAssignments={new Map([['test2', assignAxes('x-axis-2', 'y-axis-2')]])}
+        panEnabled={true}
+        zoomEnabled={true}
+        markerRadius={2}
+    />
+</Chart>
+```
 
-#### [&#10514;](#content) <span id="bar-plot-usage-view">&lt;BarPlot/&gt; view-modifying interactions</span>
+#### <span id="raster-plot">&lt;RasterPlot/&gt;</span>
 
-**panEnabled**, **zoomEnabled**, **zoomKeyModifiersRequired**, **withCadenceOf**<br>
-These properties behave the same as in [&lt;ScatterPlot/&gt;](#scatter-plot-usage-view).
+Events over time: each series is a row, and each datum is a short vertical line (a "spike") at its time. The x-axis is a `<ContinuousAxis>`, and the y-axis is an `<OrdinalAxis>` whose categories are the series names. Uses a `TimeSeriesDataSource`. ([full example](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/StreamingRasterChart.tsx), [walkthrough](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/raster-chart.md))
 
-### [&#10514;](#content) <span id="poincare-plot-usage">&lt;PoincarePlot/&gt;</span>
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="packages/examples/public/images/raster-chart-dark.png">
+    <img src="packages/examples/public/images/raster-chart-light.png" alt="the raster chart example: fifty neurons, one row each, with a spike for each event">
+</picture>
 
-The &lt;PoincarePlot/&gt; (also known as an iterates plot) is used to plot the current value of a series against its previous value (n vs n-1). This is useful for identifying patterns or oscillations in the data.
+[▶ watch it stream](packages/examples/public/images/raster-chart-streaming.gif) (animated)
 
-#### [&#10514;](#content) <span id="poincare-plot-usage-base">&lt;PoincarePlot/&gt; base properties</span>
+| prop | type | description |
+|---|---|---|
+| `spikeMargin` | `number` (px) | Space above and below each spike, within its row (default 2). Set it per series with the series style's `margin`. |
 
-**interpolation (d3.CurveFactory, optional, default = undefined)**<br>
-An optional property that defines how the line between iterates will be interpolated. Use `NoCurveFactory` to disable the line.
+```tsx
+<Chart chartId={2} width={width} height={height} dataSource={dataSource} seriesStyles={seriesStyles} windowingTime={50}>
+    <ContinuousAxis axisId="x-axis-1" location={AxisLocation.Bottom} domain={[0, 5000]} label="t (ms)"/>
+    <EmptyAxis axisId="x-axis-2" location={AxisLocation.Top}/>
+    <OrdinalAxis axisId="y-axis-1" location={AxisLocation.Left} categories={dataSource.seriesList().map(s => s.name)} label="neuron"/>
+    <EmptyAxis axisId="y-axis-2" location={AxisLocation.Right}/>
+    <Tracker visible={true} labelFormatter={x => `${d3.format(",.0f")(x)} ms`}/>
+    <Tooltip visible={true}>
+        <RasterPlotTooltipContent xFormatter={value => formatNumber(value, " ,.0f") + ' ms'}/>
+    </Tooltip>
+    <RasterPlot spikeMargin={1} panEnabled={true} zoomEnabled={true}/>
+</Chart>
+```
 
-**showPoints (boolean, optional, default = false)**<br>
-When `true`, displays individual data points on the plot.
+#### <span id="bar-plot">&lt;BarPlot/&gt;</span>
 
-#### [&#10514;](#content) <span id="poincare-plot-usage-view">&lt;PoincarePlot/&gt; view-modifying interactions</span>
+One bar per category, showing the category's latest value and its statistics, both over all time ("lifetime") and over the data currently held ("windowed", which depends on the data source's `dropDataAfter`). The x-axis is an `<OrdinalAxis>`, and the y-axis is a `<ContinuousAxis>`. Uses an `OrdinalDataSource`. ([full example](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/StreamingBarChart.tsx), [walkthrough](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/bar-chart.md))
 
-**panEnabled**, **zoomEnabled**, **zoomKeyModifiersRequired**, **withCadenceOf**<br>
-These properties behave the same as in [&lt;ScatterPlot/&gt;](#scatter-plot-usage-view).
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="packages/examples/public/images/bar-chart-dark.png">
+    <img src="packages/examples/public/images/bar-chart-light.png" alt="the bar chart example: fifty categories, each with its value, min/max, and mean">
+</picture>
 
-## [&#10514;](#content) <span id="utilities">utilities</span>
+[▶ watch it stream](packages/examples/public/images/bar-chart-streaming.gif) (animated)
 
-### [&#10514;](#content) <span id="tracker-usage">&lt;Tracker/&gt;</span>
+| prop | type | description |
+|---|---|---|
+| `showValueLines` | `boolean` | Shows each category's latest value (default `true`). |
+| `showMinMaxBars` | `boolean` | Shows each category's lifetime min-to-max bar (default `true`). |
+| `showMeanValueLines` | `boolean` | Shows each category's lifetime mean (default `true`). |
+| `showWindowedMinMaxBars` | `boolean` | Shows each category's windowed min-to-max bar (default `true`). |
+| `showWindowedMeanValueLines` | `boolean` | Shows each category's windowed mean (default `true`). |
+| `barMargin` | `number` (px) | Space between a category's edges and its bars (default 2). |
+| `barSeriesStyle` | `BarSeriesStyle` | The default style for categories without one in the chart's `seriesStyles` (default `defaultBarSeriesStyle()`). |
+| `zoomState`, `onZoomStateChange` | `BarPlotZoomState`, `(state) => void` | Keep the zoom across remounts: store what `onZoomStateChange` hands you, and pass it back as `zoomState`. It's read once, when the plot mounts. |
 
-The tracker, when enabled, follows the mouse when it is in the plot area, renders a vertical line from the bottom x-axis to the top of the plot, and displays the time value for either one or both the x-axes.
+Style the bars with `defaultBarSeriesStyle(color)`, and override the parts you want:
 
-#### [&#10514;](#content) <span id="tracker-usage-base">&lt;Tracker/&gt; base properties</span>
+```tsx
+seriesStyles={new Map<string, BarSeriesStyle>([
+    ['HC 1', {...defaultBarSeriesStyle('orange'), lineWidth: 2}],
+    ['HC 14', {
+        ...defaultBarSeriesStyle('blue'),
+        minMaxBar: {...defaultBarSeriesStyle('blue').minMaxBar, widthFraction: 1}
+    }],
+])}
+```
 
-**visible (boolean)**<br>
-When set to `true` the tracker is visible when the mouse is in the plot area. When set to `false` the tracker is not shown.
+```tsx
+<Chart<OrdinalChartData, OrdinalDatum, BarSeriesStyle, WindowedOrdinalStats, OrdinalAxisRange, OrdinalStringAxis>
+    chartId={3} width={width} height={height} dataSource={dataSource} seriesStyles={seriesStyles}
+    windowingTime={50} onUpdateChartTime={setChartTime}
+>
+    <OrdinalAxis axisId="x-axis-1" location={AxisLocation.Bottom} categories={categories} label="neuron" axisTickStyle={{rotation: 90}}/>
+    <ContinuousAxis axisId="y-axis-1" location={AxisLocation.Left} domain={[-1.1, 1.1]} label="ρ (mV)"/>
+    <Tracker visible={true} trackerAxis={AxisLocation.Left} labelFormatter={y => `${d3.format(".2f")(y)} mV`}/>
+    <Tooltip visible={true}>
+        <BarPlotTooltipContent ordinalUnits="mV"/>
+    </Tooltip>
+    <BarPlot barMargin={1} panEnabled={true} zoomEnabled={true} showWindowedMinMaxBars={false}/>
+</Chart>
+```
 
-**labelLocation ([TrackerLabelLocation](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/Tracker.tsx), optional, default = TrackerLabelLocation.WithMouse)**<br>
-Optional property specifies the location of the label. The `TrackerLabelLocation` is an enumeration with three values `Nowhere`, `WithMouse`, and `ByAxes`. By default, the label location is with the mouse (i.e. `WithMouse`). The `Nowhere` location can be used to hide the label, in cases where you would like to use your own. The `WithMouse` value has the label follow the mouse in the vertical direction along the tracker line. And the `ByAxes` displays the labels next to their respective axes, with the tracker line.
+#### <span id="poincare-plot">&lt;PoincarePlot/&gt;</span>
 
-**onTrackerUpdate ((update: TrackerAxisUpdate) => void, optional, default = noop)**<br>
-Optional callback function that accepts the update from the tracker. Use this to display the tracker and data information outside of the &lt;Chart/&gt. The `TrackerAxisUpdate` is a `Map<string, TrackerAxisInfo>`, the `TrackerAxisInfo` has the shape `{x: number, axisLocation: AxisLocation}`, and the `AxisLocation` is an same enumeration used for placing the axes on the chart (i.e. `AxisLocation.Bottom`, `AxisLocation.Top`).
+A Poincaré (iterates) plot shows each value of a sequence against a later value of the same sequence: `(f[m](x), f[m+n](x))`. Patterns that are hard to see over time, such as cycles and attractors, show up as shapes. Random noise fills the plot with a shapeless cloud, but a series generated by a rule, even a chaotic one that *looks* random over time, traces out a distinct shape. That makes the plot handy for spotting auto-correlations, and for telling random apart from complicated-but-deterministic. Both axes are `<ContinuousAxis>` and don't scroll, so set `updateAxisBasedOnDomainValues={false}` on them. Uses an `IteratesDataSource`, usually fed by [`iteratesObservable`](#chart-data). ([full example](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/StreamingPoincareChart.tsx), [walkthrough](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/poincare-chart.md), with the tent, logistic, and Gauss maps)
 
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="packages/examples/public/images/poincare-chart-dark.png">
+    <img src="packages/examples/public/images/poincare-chart-light.png" alt="the Poincaré chart example: the tent map at a lag of 1, with colorized lines">
+</picture>
 
-#### [&#10514;](#content) <span id="tracker-usage-styling">&lt;Tracker/&gt; styling</span>
+[▶ watch it stream](packages/examples/public/images/poincare-chart-streaming.gif) (animated)
 
-**style ([TrackerStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/trackerUtils.ts), optional, default = {visible: false, color: '#d2933f', lineWidth: 1})**<br>
-Optional property defining the style for the tracker line. Has a shape of `{visible: boolean, color: string, lineWidth: number}`.
+| prop | type | description |
+|---|---|---|
+| `interpolation` | `d3.CurveFactory` | How the line between successive points is drawn. Use `NoCurveFactory` to draw no line. |
+| `showPoints` | `boolean` | Draws the points as well as the line (default `true`). |
+| `colorizeLines` | `boolean` | Colors the line along its length, one step per point, so that its direction and age can be seen (default `false`). |
+| `lineStartColor`, `lineEndColor` | `string` | The colors the colorized line sweeps between (defaults `DEFAULT_LINE_START_COLOR`, a blue, and `DEFAULT_LINE_END_COLOR`, a red). |
+| `lineColorSteps` | `number` | The number of points it takes the color to sweep from start to end, and as many to sweep back (default `DEFAULT_LINE_COLOR_STEPS`, 1,000). |
+| `zoomMinScaleFactor`, `zoomMaxScaleFactor` | `number` | Limit how far the user can zoom in and out. The plot starts at a scale factor of 1; smaller factors zoom in, and larger ones zoom out (2 shows twice the range). The defaults, 0 and 1, let the user zoom in as far as they like, but not out past the starting view. |
+| `zoomState`, `onZoomStateChange` | `PoincarePlotZoomState`, `(state) => void` | Keep the zoom across remounts, as for the bar plot. |
 
-**font ([TrackerLabelFont](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/trackerUtils.ts), optional, default = {size: 12, color: '#d2933f', weight: 300, family: 'sans-serif'})**<br>
-Optional property defining the font for the tracker label. Has a shape of `{size: number, color: string, family: string, weight: number}`.
+```tsx
+<Chart chartId={4} width={width} height={height} dataSource={dataSource} seriesStyles={seriesStyles}
+       windowingTime={25} onUpdateChartTime={setChartTime}>
+    <ContinuousAxis axisId="x-axis-1" location={AxisLocation.Bottom} domain={[0, 1]} label="f[n](x)" updateAxisBasedOnDomainValues={false}/>
+    <ContinuousAxis axisId="y-axis-1" location={AxisLocation.Left} domain={[0, 1]} label="f[n+1](x)" updateAxisBasedOnDomainValues={false}/>
+    <Tracker visible={true} trackerAxis={AxisLocation.Bottom} labelFormatter={x => d3.format(",.3f")(x)}/>
+    <Tracker visible={true} trackerAxis={AxisLocation.Left} labelFormatter={y => d3.format(",.3f")(y)}/>
+    <Tooltip visible={true}>
+        <PoincarePlotTooltipContent xLabel="t (ms)" yLabel="f(x)" yValueFormatter={value => formatNumber(value, " ,.4f")}/>
+    </Tooltip>
+    <PoincarePlot interpolation={d3.curveLinear} colorizeLines={true} panEnabled={true} zoomEnabled={true}/>
+</Chart>
+```
 
+#### <span id="outlier-plot">&lt;OutlierPlot/&gt;</span>
 
-### [&#10514;](#content) <span id="legend-usage">&lt;Legend/&gt;</span>
+Values over time, like the scatter plot, with a translucent band for each confidence level (measure) around the line. Points that fall outside a band are marked, so outliers stand out. Both axes are `<ContinuousAxis>`. Uses an `OutlierDataSource`. ([full example](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/StreamingOutlierChart.tsx), [walkthrough](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/outlier-chart.md))
 
-The `<Legend/>` component displays a legend for the chart, mapping series names to their respective colors. It can be placed inside the `<Chart/>` component and can be rendered either within the chart's SVG area or into an external HTML container.
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="packages/examples/public/images/outlier-chart-dark.png">
+    <img src="packages/examples/public/images/outlier-chart-light.png" alt="the outlier chart example: a price index inside its 1σ, 2σ, and 3σ bands, with the points outside the bands marked">
+</picture>
 
-#### [&#10514;](#content) <span id="legend-usage-base">&lt;Legend/&gt; base properties</span>
+[▶ watch it stream](packages/examples/public/images/outlier-chart-streaming.gif) (animated)
 
-**visible (boolean)**<br>
-When set to `true`, the legend is visible.
+| prop | type | description |
+|---|---|---|
+| `interpolation` | `d3.CurveFactory` | How the central line is drawn between points (default `d3.curveLinear`). |
+| `timeWindowBehavior` | `TimeWindowBehavior` | `SCROLL` (the default) or `SQUEEZE`, as for the scatter plot. |
+| `bandOpacity` | `number` | The fill opacity of the outermost (widest) band (default 0.15). |
+| `bandOpacityStep` | `number` | The opacity added for each tighter band (default 0.12). |
+| `markerRadius` | `number` (px) | Draws a marker at each point while the data source is paused. |
+| `outlierMarkerColors` | `Array<string>` | The color of an outlier's marker, by band: `outlierMarkerColors[i]` marks a point outside band `i`. When a point is outside several bands, the widest band's color wins (default red). |
 
-**location ([LegendLocation](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/legends/Legend.tsx), optional, default = LegendLocation.TOP_RIGHT)**<br>
-Specifies where to anchor the legend within the plot area. Ignored when `container` is provided. Available locations are `TOP_LEFT`, `TOP_RIGHT`, `BOTTOM_LEFT`, and `BOTTOM_RIGHT`.
+The plot's type parameter is the measures tuple:
 
-**offset ({ x: number; y: number }, optional, default = { x: 10, y: 10 })**<br>
-Optional offset in pixels from the chosen corner, applied after the margin. Ignored when `container` is provided.
+```tsx
+const MEASURES = [0.68, 0.95, 0.997] as const   // 1σ, 2σ, 3σ
+type Measures = typeof MEASURES
+
+<Chart chartId={5} width={width} height={height} dataSource={dataSource} windowingTime={50} dataUpdatePeriod={25}>
+    <ContinuousAxis axisId="x-axis-1" location={AxisLocation.Bottom} domain={[0, 10_000]} label="time (ms)"/>
+    <ContinuousAxis axisId="y-axis-1" location={AxisLocation.Left} domain={[-50, 150]} label="spot price index (USD)" autoScale={true}/>
+    <OutlierPlot<Measures>
+        bandOpacity={0.12}
+        bandOpacityStep={0.14}
+        outlierMarkerColors={['#f4c542', '#f08a3b', '#d62728']}
+        panEnabled={true}
+        zoomEnabled={true}
+    />
+    <Tooltip visible={true}>
+        <OutlierPlotTooltipContent
+            datumFormatter={(x, y) => `${y.toFixed(2)} USD @ ${x.toFixed(0)} ms`}
+            measureFormatter={(inside, outside) => `${(inside * 100).toFixed(1)}% inside, ${(outside * 100).toFixed(1)}% outside`}
+        />
+    </Tooltip>
+</Chart>
+```
 
-**container (React.RefObject<HTMLElement | null>, optional)**<br>
-When provided, the legend renders as an HTML element portal into this external container instead of inside the chart SVG. Position the container however you like — the legend fills it.
+### <span id="tracker">&lt;Tracker/&gt;</span> [↑](#content "back to contents")
 
-#### [&#10514;](#content) <span id="legend-usage-styling">&lt;Legend/&gt; styling</span>
+The tracker follows the mouse over the plot with a line, and labels the axes' values at the mouse. By default it's a vertical line that tracks the x-axes. Use `trackerAxis={AxisLocation.Left}` (or `Right`) for a horizontal line that tracks the y-axes, and add two trackers to track both.
 
-**style ([LegendStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/legends/Legend.tsx), optional, default = [defaultLegendStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/legends/Legend.tsx))**<br>
-Optional property defining the style for the legend. The following style elements are available:
+| prop | type | description |
+|---|---|---|
+| `visible` | `boolean` | **Required.** Whether the tracker is shown. |
+| `trackerAxis` | `AxisLocation` | The axes the tracker reports (default `AxisLocation.Bottom`). `Bottom` or `Top` gives a vertical line; `Left` or `Right` a horizontal one. |
+| `labelLocation` | `TrackerLabelLocation` | `ByAxis` (the default) shows each value next to its axis. `Nowhere` hides the labels, for when you show the values yourself with `onTrackerUpdate`. |
+| `labelFormatter` | `(value: number) => string` | Formats the labels (default: a whole number, with thousands separators). |
+| `style` | `Partial<TrackerStyle>` | The line's style: `{visible, color, lineWidth}` (default color `'#d2933f'`, width 1). |
+| `font` | `Partial<TrackerLabelFont>` | The labels' font: `{size, color, family, weight}`. |
+| `onTrackerUpdate` | `(update: TrackerAxisUpdate) => void` | Called as the mouse moves, with a map from axis ID to `{x, axisLocation}`, where `x` is the axis' value at the mouse (for a y-axis, too). Use it to show the values outside the chart. |
 
-1. **fontSize** (number): Font size for the legend labels.
-2. **fontFamily** (string): Font family for the legend labels.
-3. **fontColor** (string): Font color for the legend labels.
-4. **backgroundColor** (string): Background fill color for the legend box.
-5. **backgroundOpacity** (number): Background opacity for the legend box.
-6. **borderColor** (string): Border/stroke color for the legend box.
-7. **borderWidth** (number): Border width for the legend box.
-8. **borderOpacity** (number): Border opacity for the legend box.
-9. **borderRadius** (number): Corner radius of the legend box.
-10. **padding** (number): Padding inside the legend box (in pixels).
-11. **rowGap** (number): Vertical space between legend entries.
-12. **swatchWidth** (number): Width of the color swatch next to each label.
-13. **swatchHeight** (number): Height of the color swatch next to each label.
-14. **swatchLabelGap** (number): Gap between the swatch and the label text.
-15. **maxHeight** (number, optional): Maximum height of the legend before it starts scrolling.
-16. **transitionDuration** (number): Duration of the visibility transition in milliseconds.
+### <span id="legend">&lt;Legend/&gt;</span> [↑](#content "back to contents")
 
-#### [&#10514;](#content) <span id="legend-usage-examples">&lt;Legend/&gt; examples</span>
+The legend shows each series' name and color. It reads the names from the chart's data and the colors from the chart's `seriesStyles`, so there's nothing to keep in sync. It lists only the series that pass the chart's `seriesFilter`, and scrolls when there are more series than fit. Hovering over a legend entry highlights its series (and fades the rest), and hovering over a series highlights its entry. It can sit over a corner of the plot, or render into a container of your own, outside the chart. ([walkthrough](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/legends.md))
 
-**Basic internal legend**
 ```tsx
+// over the plot's top-right corner
+<Legend visible={true} location={LegendLocation.TOP_RIGHT}/>
+
+// in your own container, anywhere on the page
+const legendContainer = useRef<HTMLDivElement>(null)
+...
+<div ref={legendContainer} style={{width: 200}}/>
 <Chart ...>
     ...
-    <Legend visible={true} location={LegendLocation.TOP_RIGHT} />
+    <Legend visible={true} container={legendContainer}/>
 </Chart>
 ```
 
-**External container legend**
-```tsx
-const legendContainer = useRef<HTMLDivElement>(null);
-...
-<>
-    <div ref={legendContainer} style={{ width: 200 }} />
-    <Chart ...>
-        ...
-        <Legend visible={true} container={legendContainer} />
-    </Chart>
-</>
-```
+| prop | type | description |
+|---|---|---|
+| `visible` | `boolean` | **Required.** Whether the legend is shown. |
+| `location` | `LegendLocation` | The corner of the plot the legend sits in: `TOP_LEFT`, `TOP_RIGHT` (the default), `BOTTOM_LEFT`, or `BOTTOM_RIGHT`. Ignored when `container` is set. |
+| `offset` | `{x, y}` | The offset (px) from that corner (default `{x: 10, y: 10}`). Ignored when `container` is set. |
+| `container` | `RefObject<HTMLElement \| null>` | Renders the legend into this element (through a React portal), instead of over the plot. The legend fills the container. |
+| `style` | `Partial<LegendStyle>` | `fontSize`, `fontFamily`, `fontColor`, `backgroundColor`, `backgroundOpacity`, `borderColor`, `borderWidth`, `borderOpacity`, `borderRadius`, `padding`, `rowGap`, `swatchWidth`, `swatchHeight`, `swatchLabelGap`, `maxHeight` (the legend scrolls beyond it), and `transitionDuration` (ms). Defaults are in `defaultLegendStyle`. |
 
-### [&#10514;](#content) <span id="tooltip-usage">&lt;Tooltip/&gt;</span>
+### <span id="tooltip">&lt;Tooltip/&gt; and tooltip content</span> [↑](#content "back to contents")
 
-A tooltip renders information about the data over which the mouse is hovering. The &lt;Tooltip/&gt; component in `stream-charts` is the container for the tooltip content. It is responsible for rendering the area in which the tooltip contents are displayed. The tooltip content is a child of the &lt;Tooltip/&gt; component so that it can be (relatively) easily extended. Currently `stream-charts` has two tooltip contents, one for each plot type (&lt;ScatterPlotTooltipContent/&gt; and &lt;RasterPlotTooltipContent/&gt;). Each of these will be covered after we discuss the &lt;Tooltip/&gt;.
-
-The properties for the lt;Tooltip/&gt; are simple and limited. The tooltip content components have more options.
-
-**visible (boolean)**<br>
-When set to `true` the the tooltip is shown when the mouse hovers over a data series or point.
-
-**style ([TooltipStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/tooltipUtils.ts), optional, default = [defaultTooltipStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/tooltipUtils.ts) )**<br>
-Optional property defining the style of the tooltip. The following style elements are available
-1. **visible**<br>Visibility of the tooltip when the mouse hovers over a data series or point
----
-2. **fontSize**<br>The size of the font displayed in the tooltip
-3. **fontColor**<br>The color of the text displayed in the tooltip
-4. **fontFamily**<br>The font weight for the text displayed in the tooltip
-5. **fontWeight**<br>The font weight for the text displayed in the tooltip
----
-6. **backgroundColor**<br>The background color of the tooltip
-7. **backgroundOpacity**<br>The opacity of the background (i.e. how transparent it is)
----
-8. **borderColor**<br>The color of the border surrounding the tooltip content
-9. **borderWidth**<br>The width of the border surrounding the tooltip content
-10. **borderRadius**<br>The radius of the border surrounding the tooltip content
----
-11. **paddingLeft**<br>The padding to the left of the tooltip content
-12. **paddingRight**<br>The padding to the right of the tooltip content
-13. **paddingTop**<br>The padding to the top of the tooltip content
-14. **paddingBottom**<br>The padding to the bottom of the tooltip content
+The tooltip shows information about the *data* under the mouse: a line, a spike, a point, a bar, or a band. (The [tracker](#tracker), by contrast, shows the mouse's *position*.) The `<Tooltip>` provides the box and its style. Its child, the *tooltip content*, decides what goes in the box. Each plot has its own content component, most of which take formatters for their values, and you can [write your own](#custom-tooltip). ([walkthrough](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/tooltips-and-trackers.md))
 
-**children (&lt;ScatterPlotTooltipContent/&gt; and &lt;RasterPlotTooltipContent/&gt;)**<br>
-The tooltip content.
+```tsx
+<Tooltip visible={true} style={{fontColor: theme.color, backgroundColor: theme.backgroundColor, borderColor: theme.color, backgroundOpacity: 0.9}}>
+    <ScatterPlotTooltipContent xLabel="t (ms)" yLabel="count"/>
+</Tooltip>
+```
 
+| `<Tooltip>` prop | type | description |
+|---|---|---|
+| `visible` | `boolean` | **Required.** Whether the tooltip is shown when the mouse is over one of the plot's elements. |
+| `style` | `Partial<TooltipStyle>` | The box's style: `fontSize`, `fontColor`, `fontFamily`, `fontWeight`, `backgroundColor`, `backgroundOpacity`, `borderColor`, `borderOpacity`, `borderWidth`, `borderRadius`, and `paddingLeft`/`Right`/`Top`/`Bottom`. Defaults are in `defaultTooltipStyle`. |
+| `children` | | **Required.** The tooltip content. |
 
-### [&#10514;](#content) <span id="scatterplot-tooltip-usage">&lt;ScatterPlotTooltipContent/&gt;</span>
+Each content component also takes a `style` that overrides parts of the `<Tooltip>`'s style.
 
-The &lt;ScatterPlotTooltipContent/&gt; renders a table displaying the series datum that immediately precedes the mouse location, and immediately follows the mouse location. The first row shows the x-values, and the second row shows the y-values. The table below maps the properties to the table elements they effect.
+**&lt;ScatterPlotTooltipContent/&gt;** shows a table of the points around the mouse – the point before and the point after (or the point under the mouse, when it's on one), and the change between them – followed by statistics of the series (its number of points, mean value, standard deviation, and mean interval between points) and a sparkline of its autocorrelation.
 
----
-series name
+| prop | description |
+|---|---|
+| `xLabel`, `yLabel` | **Required.** The row headers for the x-values and y-values. |
+| `beforeHeader`, `pointHeader`, `afterHeader`, `deltaHeader` | The column headers (defaults: before, point, after, ∆). |
+| `xValueFormatter`, `yValueFormatter` | Format the values (defaults `formatTime` and `formatValue`). |
+| `xChangeFormatter`, `yChangeFormatter` | Format the change, `(value1, value2) => string` (defaults `formatTimeChange` and `formatValueChange`). |
+| `intervalFormatter` | Formats the statistics' mean interval between points, a duration (defaults to the `xValueFormatter`). Give it its own formatter when the x-values aren't formatted as durations, for example as the time of day. |
 
-|  | beforeHeader | afterHeader | deltaHeader |
-|---|-------------|-------------|-------------|
-| xLabel | xValueFormatter | xValueFormatter | xChangeFormatter |
-| yLabel | yValueFormatter | yValueFormatter | yChangeFormatter |
+**&lt;RasterPlotTooltipContent/&gt;** shows the spike under the mouse (its series, time, and value) along with statistics of the series' spikes: their count, the mean and standard deviation of their values, and the mean time between them, with a sparkline of their values.
 
----
+| prop | description |
+|---|---|
+| `xFormatter` | Formats the spike's time. |
+| `yFormatter` | Formats the values (the spike's value, and the mean and standard deviation of the values). |
+| `intervalFormatter` | Formats the mean time between spikes, a duration (defaults to the `xFormatter`). Give it its own formatter when the times aren't formatted as durations, for example as the time of day. |
 
-**xLabel (string)**<br>
-Required property that gives a name to the x-values. This is the label for the x-values in the tooltip.
+**&lt;BarPlotTooltipContent/&gt;** shows the category under the mouse, with its value and statistics, and a sparkline of its values over the data the chart holds.
 
-**yLabel (string)**<br>
-Required property that gives a name to the y-values. This is the label for the y-values in the tooltip.
+| prop | description |
+|---|---|
+| `ordinalUnits` | The units shown after the values, for example `"mV"`. |
 
-**beforeHeader (string, optional, default = 'before')**<br>
-Optional property that gives a name to the data point that is immediately before the mouse location.
+**&lt;PoincarePlotTooltipContent/&gt;** shows the point under the mouse, with the iterates before and after it, and a sparkline of the series' values around it.
 
-**afterHeader (string, optional, default = 'after')**<br>
-Optional property that gives a name to the data point that is immediately after the mouse location.
+| prop | description |
+|---|---|
+| `xLabel`, `yLabel` | **Required.** The row headers. |
+| `nMinusLagHeader`, `nHeader`, `nPlusLagHeader` | The column headers for the previous, current, and next iterates. |
+| `xValueFormatter`, `yValueFormatter`, `xChangeFormatter`, `yChangeFormatter` | Format the values and their changes. |
 
-**deltaHeader (string, optional, default = '∆')**<br>
-Optional property that gives a name to the difference between the datum immediately before and after the mouse location.
+**&lt;OutlierPlotTooltipContent/&gt;** shows the point and band under the mouse.
 
-**xValueFormatter ((value: number) => string, optional, default =** [**formatTime**](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/utils.ts) <br>
-Optional function that formats the x-value immediately before and after the mouse location. The default function formats that x-values as natural numbers representing milliseconds.
+| prop | description |
+|---|---|
+| `datumFormatter` | `(x, y) => string \| JSX.Element`: describes the point. |
+| `bandFormatter` | `(lower, upper) => string \| JSX.Element`: describes the band. It's handed the band's *measures* (for example 0.68 and 0.95), not its bounds. |
+| `measureFormatter` | `(innerProb, outerProb) => string \| JSX.Element \| Array<string>`: describes the probabilities of a point being inside and outside the band. |
+| `children` | Optional custom content. Inside it, `useOutlierTooltip()` hands you the hovered point and band (`tooltipContent`), the style, and the formatters. Defaults to `<DefaultOutlierTooltipContent/>`. |
 
-**yValueFormatter ((value: number) => string, optional, default =** [**formatValue**](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/utils.ts) <br>
-Optional function that formats the x-value immediately before and after the mouse location. The default function formats the y-values as floating point with 3 values to the right of the decimal point.
+#### <span id="custom-tooltip">writing your own tooltip content</span>
 
-**xChangeFormatter ((value1: number, value2: number) => string, optional, default =** [**formatTimeChange**](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/utils.ts) <br>
-Optional function that formats the change in the x-value of the points immediately before and after the mouse location. The default function formats the value as a natural number. 
+All of the content components above are built on `<TooltipContent>`, and so can yours. It does the plumbing (it registers with the chart, hides when the mouse leaves, and places the box next to the mouse, flipping it to stay on the chart). You supply two functions:
 
-**yChangeFormatter ((value1: number, value2: number) => string, optional, default =** [**formatValueChange**](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/utils.ts) <br>
-Optional function that formats the change in the y-value of the points immediately before and after the mouse location. The default function formats the value as floating point with 3 values to the right of the decimal point.
+- **`capture(seriesName, time, tooltipData, providerId?)`** turns what the plot knows about the element under the mouse into your own content (any value you like), or `undefined` to show nothing. It's called on every mouse move, so keep it quick, and copy what you need out of the series, which keep changing.
+- **`children(content, style)`** renders that content.
 
-**style ([TooltipStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/tooltipUtils.ts), optional, default = [defaultTooltipStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/tooltipUtils.ts) )**<br>
-Optional styles for the tooltip content. The styles are the same as those for the &lt;Tooltip/&gt;.
+```tsx
+import {type ReactElement} from "react"
+import {TooltipContent, type Datum, type ScatterTooltipMetadata} from "stream-charts"
+
+function MyScatterTooltip(): ReactElement {
+    return (
+        <TooltipContent<Datum, ScatterTooltipMetadata, {seriesName: string, count: number}>
+            capture={(seriesName, _time, {series}) => ({seriesName, count: series.length})}
+        >
+            {({seriesName, count}) => <div>{seriesName}: {count} points</div>}
+        </TooltipContent>
+    )
+}
 
+<Tooltip visible={true}>
+    <MyScatterTooltip/>
+</Tooltip>
+```
 
-### [&#10514;](#content) <span id="rasterplot-tooltip-usage">&lt;RasterTooltipContent/&gt;</span>
-The &lt;RasterPlotTooltipContent/&gt; shows the series name, the time, and value of the point over which the mouse is hovering. There are only three properties.
+What `tooltipData` holds (`{series, metadata}`) depends on the plot:
 
-**xFormatter ((value: number) => string, optional, default =** [**formatTime**](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/utils.ts) <br>
-Optional function that formats the x-value immediately before and after the mouse location. The default function formats that x-values as natural numbers representing milliseconds.
+| plot | `series` | `metadata` |
+|---|---|---|
+| scatter | the series' data (`Datum`s) | `ScatterTooltipMetadata`: `points`, either `{kind: 'point', before, point, after}` or `{kind: 'segment', before, after}` |
+| raster | the spike under the mouse (`series[0]`) | `RasterTooltipMetadata`: `spikes`, all of the series' spikes |
+| bar | the category's data | `WindowedOrdinalStats`, the lifetime and windowed statistics. `providerId` says which element is under the mouse (see `BAR_CHART_TOOLTIP_PROVIDER_IDS`). |
+| outlier | the series' data | `OutlierBandTooltipMetadata`: the `datum`, the band's `upperMeasure` and `lowerMeasure`, its `bandIndex`, and `pointsInBand` |
 
-**yFormatter ((value: number) => string, optional, default =** [**formatValue**](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/utils.ts) <br>
-Optional function that formats the x-value immediately before and after the mouse location. The default function formats the y-values as floating point with 3 values to the right of the decimal point.
+Other props: `style` overrides the tooltip's style, `boxStyle` adds CSS to the box, and `topFor(content, height)` places the box's top yourself. The tutorial [writing your own tooltips](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/writing-tooltips.md) builds a custom tooltip for each plot.
 
-**style ([TooltipStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/tooltipUtils.ts), optional, default = [defaultTooltipStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/tooltipUtils.ts) )**<br>
-Optional styles for the tooltip content. The styles are the same as those for the &lt;Tooltip/&gt;.
+---
 
-### [&#10514;](#content) <span id="barplot-tooltip-usage">&lt;BarPlotTooltipContent/&gt;</span>
+## <span id="more">more</span> [↑](#content "back to contents")
 
-The &lt;BarPlotTooltipContent/&gt; displays the series name and current statistics in a table format.
+### <span id="theming">theming</span> [↑](#content "back to contents")
 
-**ordinalUnits (string, optional)**<br>
-Optional units to display alongside the values.
+The library has no theme object. It has colors: every component takes its colors as props, so to theme a chart, you hand it a different set of colors. When the colors change, the chart redraws in them, even while it's paused.
 
-**style ([TooltipStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/tooltipUtils.ts), optional)**<br>
-Optional styles for the tooltip content.
+| component | its colors come from |
+|---|---|
+| `<Chart>` | `color` (the axes, their ticks, and labels) and `backgroundColor` |
+| the series | the chart's `seriesStyles`, one style per series, with its `color` and `highlightColor` |
+| `<ContinuousAxis>`, `<OrdinalAxis>` | the chart's `color`, unless you give the axis its own `font` |
+| `<Tooltip>` | its `style`: `fontColor`, `backgroundColor`, `borderColor`, and their opacities. The tooltip content (tables, sparklines) draws in the `fontColor`. |
+| `<Tracker>` | its `style` (the line) and `font` (the labels) |
+| `<Legend>` | its `style`: `fontColor`, `backgroundColor`, and `borderColor` |
+| `<BarPlot>` | its series styles (start from `defaultBarSeriesStyle(color)`) |
+| `<OutlierPlot>` | the series' color (the line and its bands), and `outlierMarkerColors` |
+| `<PoincarePlot>` | the series' colors, and `lineStartColor`/`lineEndColor` when colorizing |
 
-### [&#10514;](#content) <span id="poincareplot-tooltip-usage">&lt;PoincarePlotTooltipContent/&gt;</span>
+A component you don't hand colors to uses the library's defaults, which are tuned for a dark background: orange (`#d2933f`) axes on near-black (`#202020`), with teal (`#008aad`) series. On a light page, pass colors to every component. The simplest way is to collect them in one theme object and spread it into each component's props. Themes change only colors; fonts, line widths, and margins each have their own props.
 
-The &lt;PoincarePlotTooltipContent/&gt; displays the series name and the current, previous, and next iterates in a table format.
+The demo app's [theming page](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/theming.md) shows a light/dark theme held in a store, and how to add a third theme.
 
-**xLabel (string)**<br>
-Required label for the x-axis values.
+### <span id="filtering">filtering series</span> [↑](#content "back to contents")
 
-**yLabel (string)**<br>
-Required label for the y-axis values.
+The chart's `seriesFilter` is a `RegExp` that's tested against each series' name on every redraw. For a filter typed in by the user, build the regex with one of these helpers. Each returns a `Result` rather than throwing, so a half-typed pattern is easy to handle:
 
-**nMinusLagHeader**, **nHeader**, **nPlusLagHeader** (string, optional)<br>
-Optional headers for the previous, current, and next iterates.
+- `regexFilter(text)` compiles `text` as a regex. It fails when the pattern is invalid, *or* when it risks catastrophic backtracking (which would freeze the render loop).
+- `literalFilter(text)` matches `text` literally, escaping regex characters such as `.` and `*`.
+- `isSafeRegex(pattern)` checks a pattern on its own.
 
-**xValueFormatter**, **yValueFormatter**, **xChangeFormatter**, **yChangeFormatter** (optional)<br>
-Optional formatters for values and their changes.
+```ts
+const filter = regexFilter(filterText).getOrElse(/./)
+```
 
-**style ([TooltipStyle](https://github.com/robphilipp/stream-charts/blob/master/src/app/charts/tooltipUtils.ts), optional)**<br>
-Optional styles for the tooltip content.
+### <span id="hooks">hooks</span> [↑](#content "back to contents")
 
-## [&#10514;](#content) <span id="hooks">hooks</span>
+For advanced use, such as building your own components inside a `<Chart>`:
 
-For advanced usage, `stream-charts` provides several hooks to interact with the chart's internal state.
+| hook | description |
+|---|---|
+| `useDataSourceRunning(dataSource)` | Whether the data source is running, re-rendering when it starts or stops. Works anywhere, inside a chart or not. Handy for a Run/Pause button. |
+| `useDataSource()` | The chart's data source (inside a `<Chart>`). |
+| `useChart()` | The chart's shared state: its ID, canvas and drawing context, colors, series styles, series filter, axes, mouse, and tooltip. Custom components draw onto the canvas by registering a draw function with `useChart().canvasContext`. |
+| `usePlotDimensions()` | The plot area's dimensions and the margins. |
+| `useHoveredSeries()` | The name of the series under the mouse (in the plot or the legend), and a setter. |
+| `useTooltipStyle()` | The enclosing tooltip's style (inside a tooltip's content). |
+| `useOutlierTooltip()` | The hovered point and band, the style, and the formatters (inside an `<OutlierPlotTooltipContent>`). |
 
-- **useChart()**: Access the chart's context, including dimensions, scales, and registration functions for tooltips and trackers.
-- **useAxes()**: Access the state of the x and y axes.
-- **usePlotDimensions()**: Access the dimensions of the plot area and margins.
-- **useDataObservable()**: Access the data stream observable.
+The full API, including the formatting helpers (`formatNumber`, `formatTime`, `formatValue`, and friends), is in the [API docs](https://robphilipp.github.io/stream-charts/docs/modules.html).
 
-## [&#10514;](#content) <span id="building">building</span>
+### <span id="further-reading">further reading</span> [↑](#content "back to contents")
 
-Testing
-```shell
-npm run test
-```
+The [demo app](#run-demo) in `packages/examples` has one tab for each plot type, and a set of guide pages (shown in the app's intro, and readable on GitHub):
 
-Creating docs
-```shell
-npm install typedoc
-npx typedoc src/app/charts/*
-```
+- **Getting oriented:** [intro](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/intro.md), [what the pages cover](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/contents.md), [anatomy of an example](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/anatomy-of-example.md), and [the common controls](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/common-controls.md), which says which library option each control is wired to.
+- **The plots:** [scatter](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/scatter-chart.md), [raster](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/raster-chart.md), [Poincaré](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/poincare-chart.md), [bar](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/bar-chart.md), and [outlier](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/outlier-chart.md).
+- **The extras:** [axes](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/axes.md) (the kinds of axes, their options, and which plots take which), [legends](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/legends.md), [theming](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/theming.md), and [tooltips and trackers](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/tooltips-and-trackers.md).
+- **Under the hood:** [some context](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/some-context.md) (which supporting libraries you need, sizing charts, and keeping state), [where the code lives](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/where-the-code-lives.md), and [how the data flows](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/how-the-data-flows.md).
+- **Tutorials:** [adding your own data source](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/adding-a-data-source.md), from an RxJS observable to a chart; [writing your own tooltips](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/writing-tooltips.md), one for each plot; and [your own scatter chart, from sensor data](https://github.com/robphilipp/stream-charts/blob/master/packages/examples/src/app/examples/docs/scatter-chart-from-sensor-data.md), with irregular readings, two y-axes, and a legend, tracker, and tooltip.