@umriss-ui/charts 0.34.0 → 0.36.0

package/docs/llms-full.md

@@ -1,4 +1,4 @@
-# @umriss-ui/charts 0.34.0
+# @umriss-ui/charts 0.36.0
 
 > React canvas chart library for data-dense dashboards - line, area, bar, box plot, scatter, control and Pareto charts. Few chart kinds, drawn well, fast.
 
@@ -1057,7 +1057,7 @@ npm install @umriss-ui/charts
 
 Demo page: https://romanhaendler.github.io/umriss-ui/charts/installation/
 
-The command installs the package alone: React 18 or 19 is its only peer and stays the application's own, and the package depends on nothing else. The stylesheet comes with the JavaScript, so there is nothing to import - `@umriss-ui/charts/styles.css` is there for setups that link stylesheets by hand. Its colours, type and sizes are `--uc-` tokens that fall back onto core's; [core's Theming page](https://romanhaendler.github.io/umriss-ui/core/theming/#charts-tokens) lists them all.
+The command installs the package alone: React 19 or newer is its only peer and stays the application's own, and the package depends on nothing else. The stylesheet comes with the JavaScript, so there is nothing to import - `@umriss-ui/charts/styles.css` is there for setups that link stylesheets by hand. Its colours, type and sizes are `--uc-` tokens that fall back onto core's; [core's Theming page](https://romanhaendler.github.io/umriss-ui/core/theming/#charts-tokens) lists them all.
 
 A chart takes its container's width and follows it; give it a `height` (300 px without one). `useChart(rows)` hands out `Chart`, its axes and its series, typed at the row; each reads its value from a row through `value`, a field name or a function - a value that is `null`, `undefined` or not finite is a gap, never a zero.
 
@@ -2948,11 +2948,11 @@ The keys of [Chart](#/chart/keyboard-chart) apply here.
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` *required* | [`AxisField`](#type-AxisField)`<T> \| ((d: T, index: number) => `[`AxisValue`](#type-AxisValue)`)` | — | Where a row lies on this axis: a field of the row, compared by its name, or a function of it, compared by its source text as a series' is (`ValueFunction`) - with the same closure limit. A number is a position, a `Date` an instant, a string a category: every distinct one gets a place of its own, in the order the rows bring them, a tick and its name as the label ([ADR-0052](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0052-a-chart-reads-its-rows-as-they-come.md)). The type decides, never the content - `"2024"` is a category, `2024` a number - and a row without a value has no place. The axis reads the rows of every series bound to it; where those bring their own `data`, name their row: `<XAxis<HourCount> value="hour" />`.<br>Shown in: [Fix the domain and name the ticks](#/axis/configuration), [Add axes for other magnitudes](#/axis/axes), [Leave out the hours nobody works](#/axis/working-time) and 74 more |
-| `domain` | `"nice" \| "data" \| readonly [number, number] \| readonly [Date, Date]` | `"nice"` | `"nice"` widens the data's extent to ticks - to named `ticks` where there are any, on a time axis to whole units of a step of hours or longer -, `"data"` keeps it, a pair is fixed: numbers, on a time axis milliseconds or two `Date`s, on a category axis places. On a `zoomable` axis it is the start: what the axis shows while the chart's view names no span for it.<br>Shown in: [Bind every kind of series to a second axis](#/axis/every-kind-on-a-second-axis), [Read it by keyboard and screen reader (Chart)](#/chart/keyboard-and-screen-reader), [Gestures and keys (Zoom and pan)](#/zoom-and-pan/gestures-and-keys) and 10 more |
+| `domain` | `"nice" \| "data" \| readonly [number, number] \| readonly [Date, Date]` | `"nice"` | `"nice"` widens the data's extent to ticks - to named `ticks` where there are any, on a time axis to whole units of a step of hours or longer -, `"data"` keeps it, a pair is fixed: numbers, on a time axis milliseconds or two `Date`s, on a category axis places. On a `zoomable` axis it is the start: what the axis shows while the chart's view names no span for it.<br>Shown in: [Bind every kind of series to a second axis](#/axis/every-kind-on-a-second-axis), [Read it by keyboard and screen reader (Chart)](#/chart/keyboard-and-screen-reader), [Gestures and keys (Zoom and pan)](#/zoom-and-pan/gestures-and-keys) and 11 more |
 | `position` | `"bottom" \| "top"` | `"bottom"` | Which edge the axis stands at. A second x axis on the opposite edge is how a series counts in a unit of its own.<br>Shown in: [Add axes for other magnitudes](#/axis/axes), [Bind every kind of series to a second axis](#/axis/every-kind-on-a-second-axis) |
 | `time` | `boolean` | — | The values are instants: milliseconds since the epoch, or with `time` said ISO 8601 strings as an API sends them, read by the platform's rule - a date with a time and no offset is local time, a date alone is UTC; a string that is none is not drawn. Rows that hold a `Date` put the axis in time without `time`. Ticks on local boundaries from the minute to the month, labels by level in en-GB with a 24-hour clock - `15:00`, `17 Mar`, `Mar 2026` - and the date on the first tick and on the first of a new day (`17 Mar 00:00`); a day tick there carries the year. The tooltip's x value carries the seconds where the readings lie less than a minute apart. Another language is a `tickFormat`, which is handed the instant in milliseconds. `calendar` implies it.<br>Shown in: [Align a second axis to the grid](#/axis/aligned-ticks), [Draw a first chart (Installation)](#/installation/first-chart), [Size a chart by its container (Installation)](#/installation/in-its-container) and 36 more |
 | `calendar` | `readonly `[`WorkingInterval`](#type-WorkingInterval)`[]` | — | Working calendar: the intervals in which time counts. With it the axis stands in working time - nights and weekends are out, and every removed span gets a break mark. The scale stays affine; the mapping happens in materialisation ([ADR-0001](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0001-affine-scale-contract.md)).<br>Shown in: [Leave out the hours nobody works](#/axis/working-time) |
-| `zoomable` | `boolean` | `false` | Zoom and pan: Ctrl or ⌘ with the wheel - and a pinch - zoom around the pointer, a drag, a horizontal wheel or Shift with the wheel pan, a double click goes back to `domain`; with the focus on the chart, + and − zoom, Shift with ← or → pans and 0 goes back. The span shown is part of the chart's view, by this axis' `id` (`useChart`'s `initialView`, `onViewChange`, `setView`, `setDomain`). The plain wheel always scrolls the page.<br>Shown in: [Read it by keyboard and screen reader (Chart)](#/chart/keyboard-and-screen-reader), [Gestures and keys (Zoom and pan)](#/zoom-and-pan/gestures-and-keys), [Limit the zoom (Zoom and pan)](#/zoom-and-pan/zoom-limits) and 5 more |
+| `zoomable` | `boolean` | `false` | Zoom and pan: Ctrl or ⌘ with the wheel - and a pinch - zoom around the pointer, a drag, a horizontal wheel or Shift with the wheel pan, a double click goes back to `domain`; with the focus on the chart, + and − zoom, Shift with ← or → pans and 0 goes back. The span shown is part of the chart's view, by this axis' `id` (`useChart`'s `initialView`, `onViewChange`, `setView`, `setDomain`). The plain wheel always scrolls the page.<br>Shown in: [Read it by keyboard and screen reader (Chart)](#/chart/keyboard-and-screen-reader), [Gestures and keys (Zoom and pan)](#/zoom-and-pan/gestures-and-keys), [Limit the zoom (Zoom and pan)](#/zoom-and-pan/zoom-limits) and 6 more |
 | `zoomLimits` | [`ZoomLimits`](#type-ZoomLimits) | at most the data's extent or this axis' own `domain`, whichever is wider, at least three data steps | The narrowest and the widest span zoom may reach, in the axis' units - milliseconds on a time axis.<br>Shown in: [Limit the zoom (Zoom and pan)](#/zoom-and-pan/zoom-limits) |
 | `id` | `string` | `"x"` | Axis id, through which series bind themselves.<br>Shown in: [Add axes for other magnitudes](#/axis/axes), [Align a second axis to the grid](#/axis/aligned-ticks), [Bind every kind of series to a second axis](#/axis/every-kind-on-a-second-axis) and 7 more |
 | `label` | `string` | — | Axis title.<br>Shown in: [Fix the domain and name the ticks](#/axis/configuration), [Add axes for other magnitudes](#/axis/axes), [Leave out the hours nobody works](#/axis/working-time) and 66 more |
@@ -2967,7 +2967,7 @@ The keys of [Chart](#/chart/keyboard-chart) apply here.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `domain` | `"nice" \| "data" \| "visible" \| readonly [number, number]` | `"nice"` | As on the x axis, and `"visible"`: what the series show inside their x axis' domain - a zoomed hour gets the hour's range, not the week's -, widened to ticks as `"nice"` is. Where the x domain is not fixed that is every point.<br>Shown in: [Fix the domain and name the ticks](#/axis/configuration), [Bind every kind of series to a second axis](#/axis/every-kind-on-a-second-axis), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) and 10 more |
+| `domain` | `"nice" \| "data" \| "visible" \| readonly [number, number]` | `"nice"` | As on the x axis, and `"visible"`: what the series show inside their x axis' domain - a zoomed hour gets the hour's range, not the week's -, widened to ticks as `"nice"` is. Where the x domain is not fixed that is every point.<br>Shown in: [Fix the domain and name the ticks](#/axis/configuration), [Bind every kind of series to a second axis](#/axis/every-kind-on-a-second-axis), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) and 11 more |
 | `alignTicks` | `boolean` | — | On a further y axis: take the first y axis' tick count and widen this axis' domain until its ticks fall on that one's grid lines, the steps still 1-2-5 - one grid serves both. `tickCount` then does not apply; on the first y axis it changes nothing.<br>Shown in: [Align a second axis to the grid](#/axis/aligned-ticks) |
 | `position` | `"left" \| "right"` | `"left"` | Which edge the axis stands at. Several y axes per side are stacked outwards, so that extents of clearly different magnitude stay readable.<br>Shown in: [Add axes for other magnitudes](#/axis/axes), [Align a second axis to the grid](#/axis/aligned-ticks), [Bind every kind of series to a second axis](#/axis/every-kind-on-a-second-axis) and 7 more |
 | `id` | `string` | `"y"` | Axis id, through which series bind themselves.<br>Shown in: [Add axes for other magnitudes](#/axis/axes), [Align a second axis to the grid](#/axis/aligned-ticks), [Bind every kind of series to a second axis](#/axis/every-kind-on-a-second-axis) and 7 more |
@@ -3574,11 +3574,11 @@ The keys of [Chart](#/chart/keyboard-chart) apply here.
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` *required* | [`AxisField`](#type-AxisField)`<T> \| ((d: T, index: number) => `[`AxisValue`](#type-AxisValue)`)` | — | Where a row lies on this axis: a field of the row, compared by its name, or a function of it, compared by its source text as a series' is (`ValueFunction`) - with the same closure limit. A number is a position, a `Date` an instant, a string a category: every distinct one gets a place of its own, in the order the rows bring them, a tick and its name as the label ([ADR-0052](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0052-a-chart-reads-its-rows-as-they-come.md)). The type decides, never the content - `"2024"` is a category, `2024` a number - and a row without a value has no place. The axis reads the rows of every series bound to it; where those bring their own `data`, name their row: `<XAxis<HourCount> value="hour" />`.<br>Shown in: [Gestures and keys](#/zoom-and-pan/gestures-and-keys), [Limit the zoom](#/zoom-and-pan/zoom-limits), [Fit the y axis to what is visible](#/zoom-and-pan/visible-domain) and 74 more |
-| `domain` | `"nice" \| "data" \| readonly [number, number] \| readonly [Date, Date]` | `"nice"` | `"nice"` widens the data's extent to ticks - to named `ticks` where there are any, on a time axis to whole units of a step of hours or longer -, `"data"` keeps it, a pair is fixed: numbers, on a time axis milliseconds or two `Date`s, on a category axis places. On a `zoomable` axis it is the start: what the axis shows while the chart's view names no span for it.<br>Shown in: [Gestures and keys](#/zoom-and-pan/gestures-and-keys), [Limit the zoom](#/zoom-and-pan/zoom-limits), [Fit the y axis to what is visible](#/zoom-and-pan/visible-domain) and 10 more |
+| `domain` | `"nice" \| "data" \| readonly [number, number] \| readonly [Date, Date]` | `"nice"` | `"nice"` widens the data's extent to ticks - to named `ticks` where there are any, on a time axis to whole units of a step of hours or longer -, `"data"` keeps it, a pair is fixed: numbers, on a time axis milliseconds or two `Date`s, on a category axis places. On a `zoomable` axis it is the start: what the axis shows while the chart's view names no span for it.<br>Shown in: [Gestures and keys](#/zoom-and-pan/gestures-and-keys), [Limit the zoom](#/zoom-and-pan/zoom-limits), [Fit the y axis to what is visible](#/zoom-and-pan/visible-domain) and 11 more |
 | `position` | `"bottom" \| "top"` | `"bottom"` | Which edge the axis stands at. A second x axis on the opposite edge is how a series counts in a unit of its own.<br>Shown in: [Add axes for other magnitudes (Axis)](#/axis/axes), [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) |
 | `time` | `boolean` | — | The values are instants: milliseconds since the epoch, or with `time` said ISO 8601 strings as an API sends them, read by the platform's rule - a date with a time and no offset is local time, a date alone is UTC; a string that is none is not drawn. Rows that hold a `Date` put the axis in time without `time`. Ticks on local boundaries from the minute to the month, labels by level in en-GB with a 24-hour clock - `15:00`, `17 Mar`, `Mar 2026` - and the date on the first tick and on the first of a new day (`17 Mar 00:00`); a day tick there carries the year. The tooltip's x value carries the seconds where the readings lie less than a minute apart. Another language is a `tickFormat`, which is handed the instant in milliseconds. `calendar` implies it.<br>Shown in: [Gestures and keys](#/zoom-and-pan/gestures-and-keys), [Limit the zoom](#/zoom-and-pan/zoom-limits), [Fit the y axis to what is visible](#/zoom-and-pan/visible-domain) and 36 more |
 | `calendar` | `readonly `[`WorkingInterval`](#type-WorkingInterval)`[]` | — | Working calendar: the intervals in which time counts. With it the axis stands in working time - nights and weekends are out, and every removed span gets a break mark. The scale stays affine; the mapping happens in materialisation ([ADR-0001](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0001-affine-scale-contract.md)).<br>Shown in: [Leave out the hours nobody works (Axis)](#/axis/working-time) |
-| `zoomable` | `boolean` | `false` | Zoom and pan: Ctrl or ⌘ with the wheel - and a pinch - zoom around the pointer, a drag, a horizontal wheel or Shift with the wheel pan, a double click goes back to `domain`; with the focus on the chart, + and − zoom, Shift with ← or → pans and 0 goes back. The span shown is part of the chart's view, by this axis' `id` (`useChart`'s `initialView`, `onViewChange`, `setView`, `setDomain`). The plain wheel always scrolls the page.<br>Shown in: [Gestures and keys](#/zoom-and-pan/gestures-and-keys), [Limit the zoom](#/zoom-and-pan/zoom-limits), [Fit the y axis to what is visible](#/zoom-and-pan/visible-domain) and 5 more |
+| `zoomable` | `boolean` | `false` | Zoom and pan: Ctrl or ⌘ with the wheel - and a pinch - zoom around the pointer, a drag, a horizontal wheel or Shift with the wheel pan, a double click goes back to `domain`; with the focus on the chart, + and − zoom, Shift with ← or → pans and 0 goes back. The span shown is part of the chart's view, by this axis' `id` (`useChart`'s `initialView`, `onViewChange`, `setView`, `setDomain`). The plain wheel always scrolls the page.<br>Shown in: [Gestures and keys](#/zoom-and-pan/gestures-and-keys), [Limit the zoom](#/zoom-and-pan/zoom-limits), [Fit the y axis to what is visible](#/zoom-and-pan/visible-domain) and 6 more |
 | `zoomLimits` | [`ZoomLimits`](#type-ZoomLimits) | at most the data's extent or this axis' own `domain`, whichever is wider, at least three data steps | The narrowest and the widest span zoom may reach, in the axis' units - milliseconds on a time axis.<br>Shown in: [Limit the zoom](#/zoom-and-pan/zoom-limits) |
 | `id` | `string` | `"x"` | Axis id, through which series bind themselves.<br>Shown in: [Add axes for other magnitudes (Axis)](#/axis/axes), [Align a second axis to the grid (Axis)](#/axis/aligned-ticks), [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) and 7 more |
 | `label` | `string` | — | Axis title.<br>Shown in: [Gestures and keys](#/zoom-and-pan/gestures-and-keys), [Limit the zoom](#/zoom-and-pan/zoom-limits), [Fit the y axis to what is visible](#/zoom-and-pan/visible-domain) and 66 more |
@@ -5507,11 +5507,11 @@ The keys of [Chart](#/chart/keyboard-chart) apply here.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` *required* | [`Value`](#type-Value)`<T>` | — | Y value - a number field of the row or a function of it; null/undefined/NaN/±Infinity means a gap.<br>Shown in: [Plot single measurements](#/scatter/arrivals), [Mark samples that miss a target](#/scatter/against-a-target), [Mix series kinds (Chart)](#/chart/mixed) and 2 more |
+| `value` *required* | [`Value`](#type-Value)`<T>` | — | Y value - a number field of the row or a function of it; null/undefined/NaN/±Infinity means a gap.<br>Shown in: [Plot single measurements](#/scatter/arrivals), [Mark samples that miss a target](#/scatter/against-a-target), [Mix series kinds (Chart)](#/chart/mixed) and 3 more |
 | `xAxisId` | `string` | `"x"` | Binding to an x axis.<br>Shown in: [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) |
 | `yAxisId` | `string` | `"y"` | Binding to a y axis.<br>Shown in: [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) |
 | `data` | `readonly T[]` | — | Series-own data; overrides the container data.<br>Shown in: [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) |
-| `name` | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up.<br>Shown in: [Plot single measurements](#/scatter/arrivals), [Mark samples that miss a target](#/scatter/against-a-target), [Mix series kinds (Chart)](#/chart/mixed) and 2 more |
+| `name` | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up.<br>Shown in: [Plot single measurements](#/scatter/arrivals), [Mark samples that miss a target](#/scatter/against-a-target), [Mix series kinds (Chart)](#/chart/mixed) and 3 more |
 | `format` | `(value: number) => string` | the y axis' `tickFormat`, else the built-in number format | The value as the tooltip writes it. |
 | `color` | `string` | the palette's `--uc-series-N` | Any CSS colour value. |
 | `tone` | `"ok" \| "warning" \| "alarm"` | — | A role instead of a colour value; the theme resolves it.<br>Shown in: [Mark samples that miss a target](#/scatter/against-a-target) |
@@ -6709,12 +6709,12 @@ The keys of [Chart](#/chart/keyboard-chart) apply here.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` *required* | [`Value`](#type-Value)`<T>` | — | Index of the state in `states` - a number field of the row or a function of it; null/undefined/NaN/±Infinity is a gap - and a gap stays a hole, it gets no colour for "unknown". A colour would be a claim about the interval.<br>Shown in: [One vehicle through the day](#/stateband/one-vehicle), [Lay a state under a course](#/stateband/under-a-course), [Give each one a lane](#/stateband/one-lane-each) and 3 more |
-| `states` *required* | `readonly `[`StateEntry`](#type-StateEntry)`[]` | — | The closed set of states, in the order of their codes.<br>Shown in: [One vehicle through the day](#/stateband/one-vehicle), [Lay a state under a course](#/stateband/under-a-course), [Give each one a lane](#/stateband/one-lane-each) and 3 more |
+| `value` *required* | [`Value`](#type-Value)`<T>` | — | Index of the state in `states` - a number field of the row or a function of it; null/undefined/NaN/±Infinity is a gap - and a gap stays a hole, it gets no colour for "unknown". A colour would be a claim about the interval.<br>Shown in: [One vehicle through the day](#/stateband/one-vehicle), [Lay a state under a course](#/stateband/under-a-course), [Give each one a lane](#/stateband/one-lane-each) and 4 more |
+| `states` *required* | `readonly `[`StateEntry`](#type-StateEntry)`[]` | — | The closed set of states, in the order of their codes.<br>Shown in: [One vehicle through the day](#/stateband/one-vehicle), [Lay a state under a course](#/stateband/under-a-course), [Give each one a lane](#/stateband/one-lane-each) and 4 more |
 | `xAxisId` | `string` | — | Binding to an x axis. |
 | `yAxisId` | `string` | — | Binding to a y axis.<br>Shown in: [Lay a state under a course](#/stateband/under-a-course), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells), [Read limits above the states (LimitLine)](#/limitline/limits-and-state) |
 | `data` | `readonly T[]` | — | Series-own data; overrides the container data.<br>Shown in: [Lay a state under a course](#/stateband/under-a-course), [Give each one a lane](#/stateband/one-lane-each), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) and 2 more |
-| `name` | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up.<br>Shown in: [One vehicle through the day](#/stateband/one-vehicle), [Lay a state under a course](#/stateband/under-a-course), [Give each one a lane](#/stateband/one-lane-each) and 3 more |
+| `name` | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up.<br>Shown in: [One vehicle through the day](#/stateband/one-vehicle), [Lay a state under a course](#/stateband/under-a-course), [Give each one a lane](#/stateband/one-lane-each) and 4 more |
 | `lane` | `string` | — | The lane by its name: a category of the y axis, whose place the band takes, as wide as a bar is. The y axis then lists a lane per name, the first at the top, in the bands' order or its own `categories` ([ADR-0052](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0052-a-chart-reads-its-rows-as-they-come.md)). Not together with `laneFrom` or `laneTo`.<br>Shown in: [Give each one a lane](#/stateband/one-lane-each), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells), [Read limits above the states (LimitLine)](#/limitline/limits-and-state) and 1 more |
 | `laneFrom` | `number` | the beginning of the axis' domain | Lower edge of the lane in domain units of a numeric y axis.<br>Shown in: [Lay a state under a course](#/stateband/under-a-course) |
 | `laneTo` | `number` | the end of the axis' domain | Upper edge of the lane in domain units of a numeric y axis.<br>Shown in: [Lay a state under a course](#/stateband/under-a-course) |
@@ -6959,13 +6959,13 @@ The keys of [Chart](#/chart/keyboard-chart) apply here.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` *required* | [`AxisField`](#type-AxisField)`<T, number \| string \| null \| undefined> \| ((d: T, index: number) => number \| string \| null \| undefined)` | — | The row on the y axis - a field of the data's row or a function of it. A number is a position, as every series' y is; a string is a category: the y axis then has a named row per distinct one, the first at the top, in the order the data bring them or the y axis' `categories` ([ADR-0052](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0052-a-chart-reads-its-rows-as-they-come.md)). Never an instant: a `Date` is refused.<br>Shown in: [Colour cells by their limits](#/matrix/by-limits), [Colour cells along a gradient](#/matrix/gradient), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) |
-| `level` *required* | [`Value`](#type-Value)`<T>` | — | The level that decides the colour - a number field of the row or a function of it. A missing level is a hole, not a zero.<br>Shown in: [Colour cells by their limits](#/matrix/by-limits), [Colour cells along a gradient](#/matrix/gradient), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) |
+| `value` *required* | [`AxisField`](#type-AxisField)`<T, number \| string \| null \| undefined> \| ((d: T, index: number) => number \| string \| null \| undefined)` | — | The row on the y axis - a field of the data's row or a function of it. A number is a position, as every series' y is; a string is a category: the y axis then has a named row per distinct one, the first at the top, in the order the data bring them or the y axis' `categories` ([ADR-0052](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0052-a-chart-reads-its-rows-as-they-come.md)). Never an instant: a `Date` is refused.<br>Shown in: [Colour cells by their limits](#/matrix/by-limits), [Colour cells along a gradient](#/matrix/gradient), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) and 1 more |
+| `level` *required* | [`Value`](#type-Value)`<T>` | — | The level that decides the colour - a number field of the row or a function of it. A missing level is a hole, not a zero.<br>Shown in: [Colour cells by their limits](#/matrix/by-limits), [Colour cells along a gradient](#/matrix/gradient), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) and 1 more |
 | `coloring` | [`MatrixColoring`](#type-MatrixColoring) | `{ kind: "gradient", stops: DEFAULT_GRADIENT }` | How the level colours a cell: by assessment against limits, or across a gradient.<br>Shown in: [Colour cells by their limits](#/matrix/by-limits), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) |
 | `xAxisId` | `string` | `"x"` | Binding to an x axis. |
 | `yAxisId` | `string` | `"y"` | Binding to a y axis. |
 | `data` | `readonly T[]` | — | Series-own data; overrides the container data. |
-| `name` | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up.<br>Shown in: [Colour cells by their limits](#/matrix/by-limits), [Colour cells along a gradient](#/matrix/gradient), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) |
+| `name` | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up.<br>Shown in: [Colour cells by their limits](#/matrix/by-limits), [Colour cells along a gradient](#/matrix/gradient), [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells) and 1 more |
 | `format` | `(value: number) => string` | the built-in number format | The level as the tooltip writes it. The y axis' `tickFormat` writes the row, not the level.<br>Shown in: [Colour cells by their limits](#/matrix/by-limits) |
 
 ##### Types on this page
@@ -9956,20 +9956,39 @@ interface LoadPoint {
   s1: number;
   s2: number;
   s3: number;
-}
+  /** A state code 0..3 that holds for a run of about ten points. */
+  st: number;
+  /** Column, row and level of the same points laid out as a grid 200 rows high. */
+  c: number;
+  r: number;
+  lvl: number;
+}
+
+const STATES = [
+  { label: "A", color: "#2f6fb4" },
+  { label: "B", color: "#c08a2e" },
+  { label: "C", color: "#8a8f98" },
+  { label: "D", color: "#6b8e5a" },
+] as const;
+const ROWS = 200;
 
-/** Three random walks of any length. */
+/** Three random walks of any length, with a state, and a grid laid over them. */
 function load(seed: number, n: number): LoadPoint[] {
   const r = random(seed);
   const points = new Array<LoadPoint>(n);
   let s1 = 100;
   let s2 = 60;
   let s3 = 140;
+  let st = 0;
+  const columns = Math.max(1, Math.ceil(n / ROWS));
   for (let i = 0; i < n; i++) {
     s1 += r() - 0.5;
     s2 += (r() - 0.5) * 0.8;
     s3 += (r() - 0.5) * 1.2;
-    points[i] = { t: i, s1, s2, s3 };
+    if (r() < 0.1) st = Math.floor(r() * 4);
+    const c = i % columns;
+    const row = Math.floor(i / columns);
+    points[i] = { t: i, s1, s2, s3, st, c, r: row, lvl: 0.5 + 0.5 * Math.sin(c / 40) * Math.cos(row / 15) + (r() - 0.5) * 0.2 };
   }
   return points;
 }
@@ -9980,11 +9999,15 @@ const WINDOW = 400;
 /** Series kinds of the measuring run. A filled mark and a rectangle per point are
     different work from a stroked path - the measurements in the capability record
     must not hold for lines only. */
-type Mode = "lines" | "mixed";
+type Mode = "lines" | "mixed" | "bars" | "scatter" | "state" | "matrix";
+const MODES: readonly Mode[] = ["lines", "mixed", "bars", "scatter", "state", "matrix"];
+
+/** How many points along x (columns for the matrix) a zoom shows. */
+const ZOOMED = 400;
 
 export default function Benchmark() {
   const [data, setData] = useState<readonly LoadPoint[]>(() => load(5, 1_000));
-  const { Chart, XAxis, YAxis, Line, Bar, Area } = useChart(data);
+  const { Chart, XAxis, YAxis, Line, Bar, Area, Scatter, StateBand, Matrix, setDomain } = useChart(data);
   const [perf, setPerf] = useState<ChartPerf>({
     materializeMs: 0,
     seriesDrawMs: 0,
@@ -9993,6 +10016,14 @@ export default function Benchmark() {
   const [fps, setFps] = useState<number | null>(null);
   const [live, setLive] = useState(false);
   const [mode, setMode] = useState<Mode>("lines");
+  /* The time the chart's handlers take for one pointer move, the mean of the
+     last twenty: the hit test of the matrix is in it. */
+  const [hoverMs, setHoverMs] = useState<number | null>(null);
+  const moves = useRef<number[]>([]);
+  const moveStart = useRef(0);
+  const matrix = mode === "matrix";
+  const columns = matrix ? Math.max(1, Math.ceil(data.length / ROWS)) : data.length;
+  const course = mode === "lines" || mode === "mixed";
 
   const onPerf = useCallback((p: ChartPerf) => setPerf(p), []);
 
@@ -10036,6 +10067,10 @@ export default function Benchmark() {
           s1: last.s1 + (r() - 0.5) * 3,
           s2: last.s2 + (r() - 0.5) * 2.4,
           s3: last.s3 + (r() - 0.5) * 3.6,
+          st: r() < 0.1 ? Math.floor(r() * 4) : last.st,
+          c: last.c + 1,
+          r: last.r,
+          lvl: last.lvl,
         };
         const grown = [...previous, next];
         return grown.length > WINDOW ? grown.slice(grown.length - WINDOW) : grown;
@@ -10047,62 +10082,90 @@ export default function Benchmark() {
   const loadPoints = (n: number) => {
     setLive(false);
     setData(load(5, n));
+    setDomain("x", null);
+    moves.current = [];
+  };
+  const pick = (m: Mode) => {
+    setMode(m);
+    setDomain("x", null);
+    moves.current = [];
+  };
+  /* A span in the middle of the data: a small part of the volume is in view. */
+  const zoom = () => {
+    const from = Math.floor(columns / 2);
+    setDomain("x", [from, from + ZOOMED]);
   };
 
   return (
     <>
       <div className="demo-actions">
         {SIZES.map((n) => (
-          <button key={n} className="demo-button" onClick={() => loadPoints(n)}>
+          <button key={n} className="demo-button" data-role={`points-${n}`} onClick={() => loadPoints(n)}>
             {n.toLocaleString("en-US")} points
           </button>
         ))}
         <button className="demo-button" onClick={() => setLive((v) => !v)}>{live ? "Stop live" : "Live"}</button>
-        <button
-          className="demo-button"
-          data-role="mode"
-          onClick={() => setMode((m) => (m === "lines" ? "mixed" : "lines"))}
-        >
-          {mode === "lines" ? "Mixed" : "Lines only"}
+        {MODES.map((m) => (
+          <button key={m} className="demo-button" data-role={`kind-${m}`} aria-pressed={mode === m} onClick={() => pick(m)}>
+            {m}
+          </button>
+        ))}
+        <button className="demo-button" data-role="zoom" onClick={zoom}>
+          Zoom in
+        </button>
+        <button className="demo-button" data-role="unzoom" onClick={() => setDomain("x", null)}>
+          Whole
         </button>
       </div>
       <dl className="metrics">
         <div>
           <dt>Points</dt>
-          <dd>{perf.points.toLocaleString("en-US")}</dd>
+          <dd data-role="points">{perf.points.toLocaleString("en-US")}</dd>
         </div>
         <div>
           <dt>Materialisation</dt>
-          <dd>{perf.materializeMs.toFixed(1)} ms</dd>
+          <dd data-role="materialize-ms">{perf.materializeMs.toFixed(1)} ms</dd>
         </div>
         <div>
           <dt>Series draw</dt>
-          <dd>{perf.seriesDrawMs.toFixed(1)} ms</dd>
+          <dd data-role="series-draw-ms">{perf.seriesDrawMs.toFixed(1)} ms</dd>
         </div>
         <div>
           <dt>FPS (hover)</dt>
           <dd>{fps === null ? "–" : fps}</dd>
         </div>
+        <div>
+          <dt>Pointer move</dt>
+          <dd data-role="hover-ms">{hoverMs === null ? "–" : `${hoverMs.toFixed(2)} ms`}</dd>
+        </div>
       </dl>
-      <div onPointerEnter={startMeasuring} onPointerLeave={stopMeasuring}>
+      <div
+        data-role="plot"
+        onPointerEnter={startMeasuring}
+        onPointerLeave={stopMeasuring}
+        onPointerMoveCapture={() => {
+          moveStart.current = performance.now();
+        }}
+        onPointerMove={() => {
+          moves.current.push(performance.now() - moveStart.current);
+          if (moves.current.length > 20) moves.current.shift();
+          setHoverMs(moves.current.reduce((a, b) => a + b, 0) / moves.current.length);
+        }}
+      >
         <Chart
           height={320}
           ariaLabel="Benchmark with three series"
           onPerf={onPerf}
         >
-          <XAxis value="t" label="Index" />
-          <YAxis />
-          {mode === "lines" ? (
-            <Line value="s1" name="S1" />
-          ) : (
-            <Bar value="s1" name="S1" />
-          )}
-          {mode === "lines" ? (
-            <Line value="s2" name="S2" />
-          ) : (
-            <Area value="s2" name="S2" />
-          )}
-          <Line value="s3" name="S3" />
+          <XAxis value={matrix ? "c" : "t"} label="Index" domain="data" zoomable />
+          <YAxis domain={mode === "state" ? [0, 1] : undefined} />
+          {mode === "scatter" ? <Scatter value="s1" name="S1" /> : null}
+          {mode === "state" ? <StateBand value="st" states={STATES} name="State" /> : null}
+          {matrix ? <Matrix value="r" level="lvl" name="Level" /> : null}
+          {mode === "bars" ? <Bar value="s1" name="S1" /> : null}
+          {course ? mode === "lines" ? <Line value="s1" name="S1" /> : <Bar value="s1" name="S1" /> : null}
+          {course ? mode === "lines" ? <Line value="s2" name="S2" /> : <Area value="s2" name="S2" /> : null}
+          {course ? <Line value="s3" name="S3" /> : null}
           <Legend placement="top" />
           <Tooltip mode="x" />
         </Chart>
@@ -10319,6 +10382,29 @@ From `BarProps` — the full table stands on [Bar](#/bar/type-BarProps).
 | [`value`](#/bar/BarProps-value) *required* | [`Value`](#/bar/type-Value)`<T>` | — | Height - a number field of the row or a function of it; null/undefined/NaN/±Infinity means a gap. |
 | [`name`](#/bar/BarProps-name) | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up. |
 
+From `ScatterProps` — the full table stands on [Scatter](#/scatter/type-ScatterProps).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| [`value`](#/scatter/ScatterProps-value) *required* | [`Value`](#/scatter/type-Value)`<T>` | — | Y value - a number field of the row or a function of it; null/undefined/NaN/±Infinity means a gap. |
+| [`name`](#/scatter/ScatterProps-name) | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up. |
+
+From `StateBandProps` — the full table stands on [StateBand](#/stateband/type-StateBandProps).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| [`value`](#/stateband/StateBandProps-value) *required* | [`Value`](#/stateband/type-Value)`<T>` | — | Index of the state in `states` - a number field of the row or a function of it; null/undefined/NaN/±Infinity is a gap - and a gap stays a hole, it gets no colour for "unknown". A colour would be a claim about the interval. |
+| [`states`](#/stateband/StateBandProps-states) *required* | `readonly `[`StateEntry`](#/stateband/type-StateEntry)`[]` | — | The closed set of states, in the order of their codes. |
+| [`name`](#/stateband/StateBandProps-name) | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up. |
+
+From `MatrixProps` — the full table stands on [Matrix](#/matrix/type-MatrixProps).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| [`value`](#/matrix/MatrixProps-value) *required* | [`AxisField`](#/matrix/type-AxisField)`<T, number \| string \| null \| undefined> \| ((d: T, index: number) => number \| string \| null \| undefined)` | — | The row on the y axis - a field of the data's row or a function of it. A number is a position, as every series' y is; a string is a category: the y axis then has a named row per distinct one, the first at the top, in the order the data bring them or the y axis' `categories` ([ADR-0052](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0052-a-chart-reads-its-rows-as-they-come.md)). Never an instant: a `Date` is refused. |
+| [`level`](#/matrix/MatrixProps-level) *required* | [`Value`](#/matrix/type-Value)`<T>` | — | The level that decides the colour - a number field of the row or a function of it. A missing level is a hole, not a zero. |
+| [`name`](#/matrix/MatrixProps-name) | `string` | "Series n", after its place in the chart | The name in legend and tooltip. Without one a warning stands in DEV - an unnamed series is a colour nobody can look up. |
+
 From `TooltipProps` — the full table stands on [Tooltip](#/tooltip/type-TooltipProps).
 
 | Prop | Type | Default | Description |
@@ -11013,14 +11099,14 @@ is typed by that `data` instead.
 | `Line` *required* | `<T = Z>(props: `[`LineProps`](#/line/type-LineProps)`<T>) => null` | — | <br>Shown in: [Draw a first chart (Installation)](#/installation/first-chart), [Size a chart by its container (Installation)](#/installation/in-its-container), [Mix series kinds (Chart)](#/chart/mixed) and 47 more |
 | `Area` *required* | `<T = Z>(props: `[`AreaProps`](#/area/type-AreaProps)`<T>) => null` | — | <br>Shown in: [Mix series kinds (Chart)](#/chart/mixed), [Mark every kind (Chart)](#/chart/marks-on-every-kind), [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) and 5 more |
 | `Bar` *required* | `<T = Z>(props: `[`BarProps`](#/bar/type-BarProps)`<T>) => null` | — | <br>Shown in: [Mix series kinds (Chart)](#/chart/mixed), [Mark every kind (Chart)](#/chart/marks-on-every-kind), [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) and 13 more |
-| `Scatter` *required* | `<T = Z>(props: `[`ScatterProps`](#/scatter/type-ScatterProps)`<T>) => null` | — | <br>Shown in: [Mix series kinds (Chart)](#/chart/mixed), [Mark every kind (Chart)](#/chart/marks-on-every-kind), [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) and 2 more |
-| `StateBand` *required* | `<T = Z>(props: `[`StateBandProps`](#/stateband/type-StateBandProps)`<T> & `[`OneLane`](#type-OneLane)`) => null` | — | <br>Shown in: [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells), [One vehicle through the day (StateBand)](#/stateband/one-vehicle), [Lay a state under a course (StateBand)](#/stateband/under-a-course) and 3 more |
-| `Matrix` *required* | `<T = Z>(props: `[`MatrixProps`](#/matrix/type-MatrixProps)`<T>) => null` | — | <br>Shown in: [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells), [Colour cells by their limits (Matrix)](#/matrix/by-limits), [Colour cells along a gradient (Matrix)](#/matrix/gradient) |
+| `Scatter` *required* | `<T = Z>(props: `[`ScatterProps`](#/scatter/type-ScatterProps)`<T>) => null` | — | <br>Shown in: [Mix series kinds (Chart)](#/chart/mixed), [Mark every kind (Chart)](#/chart/marks-on-every-kind), [Bind every kind of series to a second axis (Axis)](#/axis/every-kind-on-a-second-axis) and 3 more |
+| `StateBand` *required* | `<T = Z>(props: `[`StateBandProps`](#/stateband/type-StateBandProps)`<T> & `[`OneLane`](#type-OneLane)`) => null` | — | <br>Shown in: [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells), [One vehicle through the day (StateBand)](#/stateband/one-vehicle), [Lay a state under a course (StateBand)](#/stateband/under-a-course) and 4 more |
+| `Matrix` *required* | `<T = Z>(props: `[`MatrixProps`](#/matrix/type-MatrixProps)`<T>) => null` | — | <br>Shown in: [Mark bands, limits and cells (Chart)](#/chart/bands-limits-and-cells), [Colour cells by their limits (Matrix)](#/matrix/by-limits), [Colour cells along a gradient (Matrix)](#/matrix/gradient) and 1 more |
 | `BoxPlot` *required* | `<T = Z>(props: `[`BoxPlotProps`](#/boxplot/type-BoxPlotProps)`<T>) => null` | — | <br>Shown in: [One box per service (BoxPlot)](#/boxplot/minimal), [A box per hour on a time axis (BoxPlot)](#/boxplot/over-time), [With outliers (BoxPlot)](#/boxplot/outliers) and 4 more |
 | `view` *required* | [`ChartView`](#/view/type-ChartView) | — | How the reader is looking at the chart.<br>Shown in: [Keep and restore a view (View)](#/view/keep-and-restore) |
 | `domains` *required* | [`AxisSpans`](#type-AxisSpans) | — | The span each zoomable x axis shows, by axis `id`; an axis absent shows its own `domain`. |
 | `setView` *required* | `(view: `[`ChartView`](#/view/type-ChartView)`) => void` | — | Goes to a whole view; what it leaves out is shown whole again. Not reported through `onViewChange`: two charts kept in step by `onViewChange: (v) => other.setView(v)` in both directions do not answer each other. A view with the content already shown changes nothing.<br>Shown in: [Read it by keyboard and screen reader (Chart)](#/chart/keyboard-and-screen-reader), [Keep charts in step (Zoom and pan)](#/zoom-and-pan/cursor-sync), [Keep and restore a view (View)](#/view/keep-and-restore) |
-| `setDomain` *required* | `(axisId: string, span: readonly [number, number] \| null) => void` | — | Puts a span in view on a zoomable x axis - a lone one is `"x"`; `null` shows the axis' own `domain` again. |
+| `setDomain` *required* | `(axisId: string, span: readonly [number, number] \| null) => void` | — | Puts a span in view on a zoomable x axis - a lone one is `"x"`; `null` shows the axis' own `domain` again.<br>Shown in: [Measure a million points (Benchmark)](#/benchmark/benchmark) |
 | `hidden` *required* | `readonly string[]` | — | The hidden series, by `name`. |
 | `toggleSeries` *required* | `(name: string) => void` | — | Hides the series `name`, or shows it where it is hidden - as a click on its legend entry does. Hiding the last series visible shows all. |
 | `showOnly` *required* | `(name: string) => void` | — | Hides every series but `name`; all are shown where none carries it.<br>Shown in: [Hide a series from the legend (Legend)](#/legend/hide-a-series) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umriss-ui/charts",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "React canvas chart library for data-dense dashboards - line, area, bar, box plot, scatter, control and Pareto charts. Few chart kinds, drawn well, fast.",
   "license": "MIT",
   "author": "Roman Händler",
@@ -55,8 +55,8 @@
     "./styles.css": "./dist/charts.css"
   },
   "peerDependencies": {
-    "react": ">=18",
-    "react-dom": ">=18"
+    "react": ">=19",
+    "react-dom": ">=19"
   },
   "devDependencies": {
     "@fontsource/geist-mono": "^5.3.0",
@@ -71,7 +71,7 @@
     "vite": "^6.0.0",
     "vite-plugin-dts": "^4.3.0",
     "@umriss-ui/demo": "0.0.0",
-    "@umriss-ui/core": "0.34.0"
+    "@umriss-ui/core": "0.36.0"
   },
   "scripts": {
     "props": "node --disable-warning=ExperimentalWarning --experimental-strip-types demo/props.ts",