@umriss-ui/charts 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -1,26 +1,16 @@
 import { CSSProperties } from 'react';
 import { ReactNode } from 'react';
 
-/** Value access of a series. Compared by its source text, not its identity - an
- inline accessor is new on every render. Known limit: one that reads a
- changed closure variable under the same text is not run again; pass a new
- data reference then. A native or bound function is compared by identity. */
-export declare type Accessor<T> = (d: T, index: number) => number | null | undefined;
-
-/** A series drawn as a filled area between its values and a baseline, 0
- without one. Renders nothing itself: it registers with the surrounding
- `Chart`. With `stack`, areas stand on each other. */
-export declare function Area<T>(props: AreaProps<T>): null;
-
 /** The props of `Area`. */
 export declare interface AreaProps<T> {
-    /** Upper edge; null/undefined/NaN/±Infinity means a gap.
+    /** Upper edge - a number field of the row or a function of it;
+     null/undefined/NaN/±Infinity means a gap.
      @remarks R-2.5 */
-    accessor: Accessor<T>;
-    /** Lower edge. In a `stack` the stack below is the lower edge, and this is
+    value: Value<T>;
+    /** Lower edge - a number field of the row or a function of it. In a `stack` the stack below is the lower edge, and this is
      not read.
      @default a fixed baseline at 0 */
-    baseline?: Accessor<T>;
+    baseline?: Value<T>;
     /** Binding to an x axis.
      @remarks R-4.12 */
     xAxisId?: string;
@@ -34,10 +24,6 @@ export declare interface AreaProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Not drawn, not hit and not counted for its axes' extent - a fixed
-     `domain` keeps the axis still. Its legend entry stays, drawn back.
-     Controlled: the caller sets it, typically from `Legend onToggle`. */
-    hidden?: boolean;
     /** The value as the tooltip writes it.
      @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
@@ -72,7 +58,7 @@ export declare interface AreaProps<T> {
 export declare interface AreaSeriesConfig<T = unknown> extends SeriesBase<T>, Stackable {
     kind: "area";
     /** Lower edge; without a value the fixed baseline 0. */
-    baseline?: Accessor<T>;
+    baseline?: ValueFunction<T>;
     /** Opacity of the fill; the outline stays fully opaque. */
     fillOpacity: number;
     strokeWidth: number;
@@ -123,7 +109,9 @@ export declare interface AxisConfig<T = unknown> {
     id: string;
     orientation: AxisOrientation;
     position: AxisPosition;
-    accessor: (d: T, index: number) => number;
+    /** Where a row lies along the axis; an x axis' only - along y the series
+     place their rows. */
+    accessor?: (d: T, index: number) => number;
     label?: string;
     tickCount?: number;
     tickFormat?: (v: number) => string;
@@ -147,9 +135,12 @@ export declare interface AxisConfig<T = unknown> {
     calendar?: readonly WorkingInterval[];
     /** y axes only: this axis' ticks on the first y axis' grid. */
     alignTicks?: boolean;
-    /** x axes only: where wheel, drag, pinch and double click propose a
-     domain. Without it the axis does not zoom. */
-    onDomainChange?: (domain: [number, number]) => void;
+    /** x axes only: wheel, drag, pinch, double click and the zoom keys move
+     the span the chart's view holds for this axis (ADR-0047). */
+    zoomable?: boolean;
+    /** x axes only: the narrowest and the widest span zoom may reach.
+     @default at most the data's extent, at least three data steps */
+    zoomLimits?: ZoomLimits;
 }
 
 /** Whether an axis or a limit runs along x or along y. */
@@ -159,17 +150,15 @@ export declare type AxisOrientation = "x" | "y";
  `right` for y. */
 export declare type AxisPosition = "bottom" | "top" | "left" | "right";
 
-/** A series drawn as bars from 0 to its values, on the numeric x axis.
- Several bar series on one x axis stand side by side, or on each other with
- `stack`. Renders nothing itself: it registers with the surrounding
- `Chart`. */
-export declare function Bar<T>(props: BarProps<T>): null;
+/** The span each zoomable x axis shows, by axis `id`, in the axis' units. */
+export declare type AxisSpans = Readonly<Record<string, readonly [number, number]>>;
 
 /** The props of `Bar`. */
 export declare interface BarProps<T> {
-    /** Height; null/undefined/NaN/±Infinity means a gap.
+    /** Height - a number field of the row or a function of it;
+     null/undefined/NaN/±Infinity means a gap.
      @remarks R-2.5 */
-    accessor: Accessor<T>;
+    value: Value<T>;
     /** Binding to an x axis.
      @remarks R-4.12 */
     xAxisId?: string;
@@ -183,10 +172,6 @@ export declare interface BarProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Not drawn, not hit and not counted for its axes' extent - a fixed
-     `domain` keeps the axis still. Its legend entry stays, drawn back.
-     Controlled: the caller sets it, typically from `Legend onToggle`. */
-    hidden?: boolean;
     /** The value as the tooltip writes it.
      @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
@@ -250,42 +235,37 @@ export declare interface BoxNumbers<V = number> {
     upperWhisker: V;
 }
 
-/** A series drawn as a box per x: median, quartiles and whiskers, optionally
- outliers, a mean and a notch. The caller brings every number - the library
- computes none. Renders nothing itself: it registers with the surrounding
- `Chart`. */
-export declare function BoxPlot<T>(props: BoxPlotProps<T>): null;
-
-/** The props of `BoxPlot`. */
+/** The props of `BoxPlot`. Every number is a number field of the row or a
+ function of it; `outliers` a list field or a function. */
 export declare interface BoxPlotProps<T> {
     /** The line across the box; null/undefined/NaN/±Infinity means a gap - no
      box is drawn there, whatever the other numbers say.
      @remarks R-2.5 */
-    median: Accessor<T>;
+    median: Value<T>;
     /** The box's lower edge. */
-    lowerQuartile: Accessor<T>;
+    lowerQuartile: Value<T>;
     /** The box's upper edge. */
-    upperQuartile: Accessor<T>;
+    upperQuartile: Value<T>;
     /** Where the lower whisker ends - the caller's rule, not the minimum. */
-    lowerWhisker: Accessor<T>;
+    lowerWhisker: Value<T>;
     /** Where the upper whisker ends - the caller's rule, not the maximum. */
-    upperWhisker: Accessor<T>;
+    upperWhisker: Value<T>;
     /** The values beyond the whiskers, per box: an array, empty or missing
      where there are none. Drawn with their box in its colour - one beyond
      three IQR of the box's own quartiles as a ring -, read in its tooltip
      and table row, never hit on their own (ADR-0040). */
-    outliers?: ListAccessor<T>;
+    outliers?: ListValue<T>;
     /** The mean, drawn as a small ×: beside the median it shows a skew. */
-    mean?: Accessor<T>;
+    mean?: Value<T>;
     /** The notch's lower bound - usually of a confidence interval of the
      median. Both bounds or neither: one alone warns in DEV and is not
      drawn. */
-    notchLower?: Accessor<T>;
+    notchLower?: Value<T>;
     /** The notch's upper bound; see `notchLower`. */
-    notchUpper?: Accessor<T>;
+    notchUpper?: Value<T>;
     /** How many values stand behind the box; read in the tooltip and the
      table, not drawn. */
-    count?: Accessor<T>;
+    count?: Value<T>;
     /** Binding to an x axis.
      @remarks R-4.12 */
     xAxisId?: string;
@@ -298,9 +278,6 @@ export declare interface BoxPlotProps<T> {
     /** The name in legend and tooltip. Without one a warning stands in DEV.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Not drawn, not hit and not counted for its axes' extent. Its legend
-     entry stays, drawn back. Controlled, typically from `Legend onToggle`. */
-    hidden?: boolean;
     /** Every number of the box as the tooltip and the table write it.
      @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
@@ -321,18 +298,18 @@ export declare interface BoxPlotProps<T> {
  chose - the library draws them and computes none. */
 export declare interface BoxSeriesConfig<T = unknown> extends SeriesBase<T> {
     kind: "box";
-    lowerQuartile: Accessor<T>;
-    upperQuartile: Accessor<T>;
-    lowerWhisker: Accessor<T>;
-    upperWhisker: Accessor<T>;
+    lowerQuartile: ValueFunction<T>;
+    upperQuartile: ValueFunction<T>;
+    lowerWhisker: ValueFunction<T>;
+    upperWhisker: ValueFunction<T>;
     /** The values beyond the whiskers, per box (ADR-0040). */
-    outliers?: ListAccessor<T>;
-    mean?: Accessor<T>;
+    outliers?: ListFunction<T>;
+    mean?: ValueFunction<T>;
     /** Both bounds or neither (CONTEXT.md: Notch). */
-    notchLower?: Accessor<T>;
-    notchUpper?: Accessor<T>;
+    notchLower?: ValueFunction<T>;
+    notchUpper?: ValueFunction<T>;
     /** How many values stand behind the box; no y value. */
-    count?: Accessor<T>;
+    count?: ValueFunction<T>;
     /** Width as a fraction of the step; boxes and bars on one x axis share it. */
     boxWidth: number;
 }
@@ -349,10 +326,58 @@ export declare function calendarFrom(input: CalendarInput): WorkingCalendar;
  axis, or the calendar built from it. */
 export declare type CalendarInput = WorkingCalendar | readonly WorkingInterval[];
 
-/** The container of a chart: it holds the data, measures the plot area and
- draws on canvas whatever its children register - axes, series, limits,
- legend and tooltip. The order of the children is the drawing order. */
-export declare function Chart<T>(props: ChartProps<T>): ReactNode;
+/** What `useChart` takes besides the rows: the view to start from and the
+ handler that hears every change of it. */
+export declare interface ChartOptions {
+    /** The view to start from, and to go to whenever one differing in content
+     from the last is handed in - the same view again changes nothing, and
+     what it leaves out is reset; one the chart reported itself, handed back
+     late, is its own state coming back and not gone to - two charts in step
+     do not jump back mid-pan. The chart remembers none: where a view is kept
+     is the application's decision. */
+    initialView?: ChartView;
+    /** Every change of the view, once, always the whole view - the one to keep,
+     or to hand another chart as its `initialView`. A pan or zoom is reported
+     at most once per frame. Not called for the view the chart starts with. */
+    onViewChange?: (view: ChartView) => void;
+}
+
+/** What `useChart` hands back: the chart and its parts, typed at the row `Z`,
+ its view and the setters that change it. A series given `data` of its own
+ is typed by that `data` instead. */
+export declare interface ChartParts<Z> {
+    /** The chart over the hook's rows. One per `useChart`: it holds the view,
+     and a second chart is a second call. */
+    Chart: (props: ChartProps) => ReactNode;
+    /** An x axis reads the rows of every series bound to it: the hook's, or
+     with `<XAxis<Row>>` those the series bring as their own `data`. */
+    XAxis: <T = Z>(props: XAxisProps<T>) => null;
+    YAxis: (props: YAxisProps) => null;
+    Line: <T = Z>(props: LineProps<T>) => null;
+    Area: <T = Z>(props: AreaProps<T>) => null;
+    Bar: <T = Z>(props: BarProps<T>) => null;
+    Scatter: <T = Z>(props: ScatterProps<T>) => null;
+    StateBand: <T = Z>(props: StateBandProps<T>) => null;
+    Matrix: <T = Z>(props: MatrixProps<T>) => null;
+    BoxPlot: <T = Z>(props: BoxPlotProps<T>) => null;
+    /** How the reader is looking at the chart. */
+    view: ChartView;
+    /** The span each zoomable x axis shows, by axis `id`; an axis absent shows
+     its own `domain`. */
+    domains: AxisSpans;
+    /** Puts a span in view on a zoomable x axis - a lone one is `"x"`; `null`
+     shows the axis' own `domain` again. */
+    setDomain: (axisId: string, span: readonly [number, number] | null) => void;
+    /** The hidden series, by `name`. */
+    hidden: readonly string[];
+    /** 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. */
+    toggleSeries: (name: string) => void;
+    /** Hides every series but `name`; all are shown where none carries it. */
+    showOnly: (name: string) => void;
+    /** Shows every series again. */
+    showAllSeries: () => void;
+}
 
 /** Measurements of the instrumentation for the benchmark page.
  @remarks R-5.1 */
@@ -362,11 +387,9 @@ export declare interface ChartPerf {
     points: number;
 }
 
-/** The props of `Chart`. */
-export declare interface ChartProps<T> {
-    /** Shared data basis (required); access only through accessors.
-     @remarks R-2.4 */
-    data: readonly T[];
+/** The props of `Chart`. Its rows are not among them: `useChart(rows)` binds
+ them (ADR-0048). */
+export declare interface ChartProps {
     /** Width in CSS pixels, or `"100%"` for the host's: the chart measures its
      host and follows it through a ResizeObserver.
      @default "100%" */
@@ -388,9 +411,15 @@ export declare interface ChartProps<T> {
     style?: CSSProperties;
     /** Shown in the middle of the plot area when no visible series has a point
      to show - no data, only gaps, or every series hidden. Axes and frame
-     stay.
+     stay. Not while `loading`.
      @default the wording's `empty` */
     empty?: ReactNode;
+    /** The rows are on their way, as the table's `loading` says (ADR-0042). A
+     course already drawn stays: it dims after a moment and takes no pointer
+     until the answer is in. Where there is nothing to show, the empty
+     message waits. The plot is `aria-busy` meanwhile.
+     @default false */
+    loading?: boolean;
     /** The chart's words (ADR-0031); entries left out fall back to English.
      German: `GERMAN_CHARTS_WORDING` from `@umriss-ui/charts/wording/de`.
      @default DEFAULT_CHARTS_WORDING */
@@ -405,8 +434,9 @@ export declare interface ChartProps<T> {
     encoding?: "color" | "marks";
     /** Charts with the same id share the pointer's x position, in domain units:
      each draws its crosshair there, the tooltip stays with the chart under
-     the pointer. Zoom is not shared - give every chart the same controlled
-     `domain`. */
+     the pointer. Zoom is not shared this way: charts zoom together by
+     handing each other their view (`useChart`'s `initialView` and
+     `onViewChange`). */
     syncId?: string;
     /** Instrumentation for the benchmark page; not needed otherwise.
      @remarks R-5.1 */
@@ -448,6 +478,14 @@ export declare interface ChartsWording {
     walkHelp: string;
     /** The keys that zoom and pan it - only where the chart can be zoomed. */
     zoomHelp: string;
+    /** The keys of the legend's entries - only where it has one to press. */
+    legendHelp: string;
+    /** Read out where hiding would leave nothing to see, and every series is
+     shown instead. */
+    allShown: string;
+    /** The control over a zoomed plot that brings every zoomed axis back to
+     its own domain (component-view 04). */
+    showAll: string;
     /** The data table's disclosure key, closed and open (charts-alternatives
      C1). */
     showData: string;
@@ -479,13 +517,21 @@ export declare interface ChartsWording {
     downsampled: (readings: number) => string;
 }
 
-declare interface CommonProps<T> {
+/** How a reader is looking at a chart. Whatever is at its default is absent. */
+export declare interface ChartView {
+    /** The span each zoomable x axis shows, by axis `id` - a lone x axis is
+     `"x"`. An axis absent here shows its own `domain`. An id that names no
+     zoomable x axis falls out. */
+    domains?: AxisSpans;
+    /** The hidden series, by `name`; a series without one cannot be hidden. A
+     name no series carries falls out. */
+    hidden?: readonly string[];
+}
+
+declare interface CommonProps {
     /** Axis id, through which series bind themselves.
      @remarks R-4.12 */
     id?: string;
-    /** Value access of this axis. Compared by its source text, as a series'
-     accessor is (`Accessor`) - with the same closure limit. */
-    accessor: (d: T, index: number) => number;
     /** Axis title. */
     label?: string;
     /** Target value; the 1-2-5 algorithm may deviate. */
@@ -513,8 +559,9 @@ export declare function ControlChart<T>(props: ControlChartProps<T>): ReactNode;
 
 /** The props of `ControlChart`. */
 export declare interface ControlChartProps<T> {
-    /** The values of the chart. */
-    accessor: Accessor<T>;
+    /** The values of the chart - a number field of its `data`'s rows or a
+     function of them. */
+    value: Value<T>;
     /** Required: the limits arise out of these values, not out of what happens to
      be visible. */
     data: readonly T[];
@@ -630,6 +677,27 @@ export declare const DEFAULT_GRADIENT: readonly string[];
  lengths are therefore parameters. */
 export declare const defaultRules: RuleOptions;
 
+/** The views a component reported that may still come back, by their
+ content key - the chart's and the schedule's (ADR-0047), the table holding
+ a copy of its own. An application keeping the view hands
+ it back a frame or more late - by then a pan has moved on, and going to the
+ view handed in would jump back. So a view handed in that equals one
+ reported since the last one handed in, within a second, is the component's
+ own state coming back, not a view to go to. The echoes come in order: one drops
+ itself and every older report, a view from outside drops them all. The
+ second bounds the list where nothing is handed back, and lets such an
+ application still restore a view it kept. */
+export declare class Echoes {
+    private reports;
+    /** Notes a view reported, by its key. */
+    reported(key: string): void;
+    /** Whether the view handed in is a report coming back. */
+    has(key: string): boolean;
+    /** Forgets what the view handed in answers. */
+    handed(key: string): void;
+    private at;
+}
+
 /** One hour in milliseconds. */
 export declare const HOUR: number;
 
@@ -638,9 +706,12 @@ export declare const HOUR: number;
 export declare function invalidateTheme(): void;
 
 /** The legend of a chart: one entry per series, or per state of a state band.
- Hovering an entry highlights its series; with `onToggle` a click hides and
- shows it. */
-export declare function Legend({ placement, onToggle }: LegendProps): ReactNode;
+ Hovering an entry highlights its series; a click hides and shows it, a
+ state's entry the whole band - through the chart's view. A double click,
+ Alt+click or Shift+Enter shows only it, or all where it is the only one
+ visible. Nothing hides every series: what would shows all, and the live
+ region says so. */
+export declare function Legend({ placement }: LegendProps): ReactNode;
 
 /** A `Legend` as the chart holds it once registered. */
 export declare interface LegendConfig {
@@ -652,10 +723,6 @@ export declare interface LegendProps {
     /** Which side of the plot area the legend stands on.
      @default "top" */
     placement?: "top" | "bottom";
-    /** Called with an entry's name when it is clicked - the series' name, or a
-     state's label. The caller flips `hidden` on the series it means. Without
-     it the legend is not clickable. */
-    onToggle?: (name: string) => void;
 }
 
 /** A bound: a value, a side and a severity. No more - a tolerance band is
@@ -779,10 +846,6 @@ export declare interface LimitSet {
     target?: number;
 }
 
-/** A series drawn as a line through its values; a gap breaks it. Renders
- nothing itself: it registers with the surrounding `Chart`. */
-export declare function Line<T>(props: LineProps<T>): null;
-
 /** The affine mapping from a domain onto a pixel range, and back; the scale
  every axis of the library uses. */
 export declare class LinearScale implements Scale {
@@ -799,9 +862,10 @@ export declare class LinearScale implements Scale {
 
 /** The props of `Line`. */
 export declare interface LineProps<T> {
-    /** Y value; null/undefined/NaN/±Infinity means a gap.
+    /** Y value - a number field of the row or a function of it;
+     null/undefined/NaN/±Infinity means a gap.
      @remarks R-2.5 */
-    accessor: Accessor<T>;
+    value: Value<T>;
     /** Binding to an x axis.
      @remarks R-4.12 */
     xAxisId?: string;
@@ -815,10 +879,6 @@ export declare interface LineProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Not drawn, not hit and not counted for its axes' extent - a fixed
-     `domain` keeps the axis still. Its legend entry stays, drawn back.
-     Controlled: the caller sets it, typically from `Legend onToggle`. */
-    hidden?: boolean;
     /** The value as the tooltip writes it.
      @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
@@ -852,9 +912,18 @@ export declare interface LineSeriesConfig<T = unknown> extends SeriesBase<T> {
     step?: boolean;
 }
 
-/** A list per datum - a box's outliers (ADR-0040). null/undefined or an
+/** The fields of a row whose value is a list of numbers, or absent. */
+export declare type ListField<T> = NoInfer<{
+    [K in keyof T & string]-?: T[K] extends readonly number[] | null | undefined ? K : never;
+}[keyof T & string]>;
+
+/** A list computed from the row - a box's outliers (ADR-0040), the
+ function form of `ListValue`. null/undefined or an
  empty array is none; a value that is not finite is left out. */
-export declare type ListAccessor<T> = (d: T, index: number) => readonly number[] | null | undefined;
+export declare type ListFunction<T> = (d: T, index: number) => readonly number[] | null | undefined;
+
+/** A list read from the row: the name of a list field or a function. */
+export declare type ListValue<T> = ListField<T> | ListFunction<T>;
 
 /** The local offset at an instant, as the shift of a grid that is to lie on
  local time: `wallClock = offset + k · step`. Taken at one instant, it holds
@@ -875,7 +944,7 @@ export declare interface MaterializedSeries {
      A fixed baseline needs no channel - it is a number.
      @remarks R-2.7 */
     y0: Float64Array | null;
-    /** Value channel: the third value per point, which today only the matrix
+    /** Level channel: the third value per point, which today only the matrix
      needs. Named rather than overloading y0 - a property that only some kinds
      carry does not belong in the shared type with a comment (ADR-0011). null
      for every kind that does not use it. */
@@ -886,12 +955,6 @@ export declare interface MaterializedSeries {
     length: number;
 }
 
-/** A series drawn as a grid of coloured cells: the accessor gives the row,
- `value` the colour - by the limits of an assessment or across a gradient.
- A missing value is a hole, not a zero. Renders nothing itself: it registers
- with the surrounding `Chart`. */
-export declare function Matrix<T>(props: MatrixProps<T>): null;
-
 /** How a matrix colours its cells. Discretely by assessment - the same limits
  that colour a tile - or across a gradient. */
 export declare type MatrixColoring = {
@@ -912,11 +975,13 @@ export declare type MatrixColoring = {
 
 /** The props of `Matrix`. */
 export declare interface MatrixProps<T> {
-    /** Row position on the y axis. */
-    accessor: Accessor<T>;
-    /** The value that decides the colour. */
-    value: Accessor<T>;
-    /** How the value colours a cell: by assessment against limits, or across
+    /** Row position on the y axis - a number field of the row or a function
+     of it, as every series' y position. */
+    value: 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. */
+    level: Value<T>;
+    /** How the level colours a cell: by assessment against limits, or across
      a gradient.
      @default { kind: "gradient", stops: DEFAULT_GRADIENT } */
     coloring?: MatrixColoring;
@@ -933,29 +998,30 @@ export declare interface MatrixProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Not drawn, not hit and not counted for its axes' extent - a fixed
-     `domain` keeps the axis still. Its legend entry stays, drawn back.
-     Controlled: the caller sets it, typically from `Legend onToggle`. */
-    hidden?: boolean;
-    /** The value as the tooltip writes it. The y axis' `tickFormat` writes the
-     row, not the value.
+    /** The level as the tooltip writes it. The y axis' `tickFormat` writes the
+     row, not the level.
      @default the built-in number format */
     format?: (value: number) => string;
 }
 
 /** A `Matrix` as the chart holds it once registered: its base accessor is the
- row, `value` the colour. */
+ row, `level` the colour. */
 export declare interface MatrixSeriesConfig<T = unknown> extends SeriesBase<T> {
     kind: "matrix";
-    /** The value that decides the colour - the third channel (ADR-0011).
-     The base accessor yields the row position, not this value. */
-    value: Accessor<T>;
+    /** The level that decides the colour - the third channel (ADR-0011).
+     The base accessor yields the row position, not this level. */
+    level: ValueFunction<T>;
     coloring: MatrixColoring;
 }
 
 /** One minute in milliseconds. */
 export declare const MINUTE: number;
 
+/** The fields of a row whose value is a number, or absent. */
+export declare type NumberField<T> = NoInfer<{
+    [K in keyof T & string]-?: T[K] extends number | null | undefined ? K : never;
+}[keyof T & string]>;
+
 /** Space in CSS pixels on each side of a rectangle. */
 export declare interface Padding {
     top: number;
@@ -1157,15 +1223,12 @@ export declare interface Scale {
     ticks(n: number): number[];
 }
 
-/** A series drawn as points only, one per value. Renders nothing itself: it
- registers with the surrounding `Chart`. */
-export declare function Scatter<T>(props: ScatterProps<T>): null;
-
 /** The props of `Scatter`. */
 export declare interface ScatterProps<T> {
-    /** Y value; null/undefined/NaN/±Infinity means a gap.
+    /** Y value - a number field of the row or a function of it;
+     null/undefined/NaN/±Infinity means a gap.
      @remarks R-2.5 */
-    accessor: Accessor<T>;
+    value: Value<T>;
     /** Binding to an x axis.
      @remarks R-4.12 */
     xAxisId?: string;
@@ -1179,10 +1242,6 @@ export declare interface ScatterProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Not drawn, not hit and not counted for its axes' extent - a fixed
-     `domain` keeps the axis still. Its legend entry stays, drawn back.
-     Controlled: the caller sets it, typically from `Legend onToggle`. */
-    hidden?: boolean;
     /** The value as the tooltip writes it.
      @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
@@ -1210,7 +1269,7 @@ export declare const SECOND = 1000;
 export declare interface SeriesBase<T = unknown> {
     /** Y value; null/undefined/NaN/±Infinity means a gap.
      @remarks R-2.5 */
-    accessor: Accessor<T>;
+    accessor: ValueFunction<T>;
     /** Series-own data; overrides the container data.
      @remarks R-2.4 */
     data?: readonly T[];
@@ -1225,8 +1284,6 @@ export declare interface SeriesBase<T = unknown> {
      For series that mean something rather than just being the next one - the
      violating points of a control chart, say. `color` beats it. */
     tone?: "ok" | "warning" | "alarm";
-    /** Not drawn, not hit, not in its axes' extent; its legend entry stays. */
-    hidden?: boolean;
 }
 
 /** Any registered series, told apart by `kind`. */
@@ -1258,20 +1315,13 @@ declare interface Stackable {
     normalize?: boolean;
 }
 
-/** A band of states: each point's state holds from its x until the next
- point's. The last one holds until the latest reading of the chart - the
- last x of any visible series on the same x axis - and where the band itself
- reports last, one median step of its own x values past its last point;
- never beyond the x domain. A state is claimed for as long as it was
- reported, not until the axis' rounded end. */
-export declare function StateBand<T>(props: StateBandProps<T>): null;
-
 /** The props of `StateBand`. */
 export declare interface StateBandProps<T> {
-    /** Index of the state in `states`; null/undefined/NaN/±Infinity is a gap -
+    /** 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. */
-    accessor: Accessor<T>;
+    value: Value<T>;
     /** The closed set of states, in the order of their codes. */
     states: readonly StateEntry[];
     /** Binding to an x axis.
@@ -1287,10 +1337,6 @@ export declare interface StateBandProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Not drawn, not hit and not counted for its axes' extent - a fixed
-     `domain` keeps the axis still. Its legend entry stays, drawn back.
-     Controlled: the caller sets it, typically from `Legend onToggle`. */
-    hidden?: boolean;
     /** Lower edge of the lane in domain units of the y axis. */
     laneFrom?: number;
     /** Upper edge of the lane in domain units of the y axis. */
@@ -1363,11 +1409,11 @@ export declare interface TooltipPoint<T = unknown> {
     yValue: number;
     datum: T;
     index: number;
-    /** Only for the matrix: the value out of the value channel. It stands here and
+    /** Only for the matrix: its level, out of the level channel. It stands here and
      not in yValue, because yValue is the position on the y axis - for a matrix
      therefore the row. Putting both into one field would be exactly the
      overloading ADR-0011 is written against. */
-    value?: number;
+    level?: number;
     /** Only for state series: the section being pointed at.
      A duration does not stand here - it is the difference of two numbers the
      entry already carries, and formatting it would presuppose knowing what the
@@ -1378,7 +1424,7 @@ export declare interface TooltipPoint<T = unknown> {
         label: string;
     };
     /** Only for a box: its further numbers; yValue is its median. Fields of
-     their own for the reason `value` has one (ADR-0011). */
+     their own for the reason `level` has one (ADR-0011). */
     box?: BoxNumbers & Partial<BoxExtras> & {
         /** As the caller gave them; only where the series has `outliers`. */
         outliers?: readonly number[];
@@ -1430,6 +1476,26 @@ export declare function toWorkingTime(wallClock: number, input: CalendarInput):
  itself is carried as a gap and is never drawn and never hit. */
 export declare function toWorkingTimeClamped(wallClock: number, input: CalendarInput): number;
 
+/** A chart over your rows: the parts it returns are typed at your row, so
+ that a field name in `value` is checked by the compiler.
+ @param rows The rows every series reads that brings no `data` of its own.
+ @param options The view to start from and the handler of its changes.
+ @returns `Chart`, `XAxis`, `YAxis` and every series kind - each keeps its
+ identity over the renders -, the `view`, its `domains` and `hidden`, and
+ the setters that change them. */
+export declare function useChart<Z>(rows: readonly Z[], options?: ChartOptions): ChartParts<Z>;
+
+/** A value read from the row (ADR-0048): the name of a number field, compared
+ by its name, or a function, compared by its source text (`ValueFunction`). */
+export declare type Value<T> = NumberField<T> | ValueFunction<T>;
+
+/** A **value** computed from the row - the function form of `Value`.
+ Compared by its source text, not its identity - an inline function is new
+ on every render. Known limit: one that reads a
+ changed closure variable under the same text is not run again; pass a new
+ data reference then. A native or bound function is compared by identity. */
+export declare type ValueFunction<T> = (d: T, index: number) => number | null | undefined;
+
 /** What a value is. Four outcomes, not three.
 
  `unknown` is an outcome of its own and not a `null` return: a `null`
@@ -1522,17 +1588,19 @@ export declare interface WorkingTimeTick {
  place the tick, the wall clock time to label it. */
 export declare function workingTimeTicks(input: CalendarInput, from: number, to: number, step: number, offset?: number): WorkingTimeTick[];
 
-/** A horizontal axis: where a datum lies along x, its ticks, title and grid.
- A chart may have several; series bind to one by its `id`. With `time` or a
- `calendar` it reads instants, with `onDomainChange` it zooms. */
-export declare function XAxis<T>(props: XAxisProps<T>): null;
-
 /** The props of `XAxis`. */
-export declare interface XAxisProps<T> extends CommonProps<T> {
+export declare interface XAxisProps<T> extends CommonProps {
+    /** Where a row lies on this axis: a number 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. The axis reads the
+     rows of every series bound to it; where those bring their own `data`, name
+     their row: `<XAxis<HourCount> value="hour" />`. */
+    value: NumberField<T> | ((d: T, index: number) => number);
     /** `"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 - the one a zoom passes
-     back. */
+     longer -, `"data"` keeps it, a pair is fixed. On a `zoomable` axis it is
+     the start: what the axis shows while the chart's view names no span for
+     it. */
     domain?: "nice" | "data" | readonly [number, number];
     /** 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. */
@@ -1550,21 +1618,24 @@ export declare interface XAxisProps<T> extends CommonProps<T> {
      removed span gets a break mark. The scale stays affine; the mapping happens
      in materialisation (ADR-0001). */
     calendar?: readonly WorkingInterval[];
-    /** Zoom and pan, controlled: 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 proposes the whole data range. Each proposes a domain in
-     the axis' units and changes nothing; the caller passes it back as
-     `domain`, clamped as it likes. Without a handler the axis does not zoom,
-     and the plain wheel always scrolls the page. */
-    onDomainChange?: (domain: [number, number]) => void;
+    /** 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`, `setDomain`). The plain wheel always scrolls the page.
+     @default false */
+    zoomable?: boolean;
+    /** The narrowest and the widest span zoom may reach, in the axis' units -
+     milliseconds on a time axis.
+     @default at most the data's extent or this axis' own `domain`, whichever
+     is wider, at least three data steps */
+    zoomLimits?: ZoomLimits;
 }
 
-/** A vertical axis: the scale series draw their values on, its ticks, title
- and grid. A chart may have several; series bind to one by its `id`. */
-export declare function YAxis<T>(props: YAxisProps<T>): null;
-
-/** The props of `YAxis`. */
-export declare interface YAxisProps<T> extends CommonProps<T> {
+/** The props of `YAxis`. It reads no value of its own: where a row lies
+ along y is its series' `value`. */
+export declare interface YAxisProps extends CommonProps {
     /** 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
@@ -1591,4 +1662,11 @@ export declare interface Zone {
  reader cannot check it against a chart that does not show it. */
 export declare function zones(limits: ControlLimits, multiples?: readonly number[]): Zone[];
 
+/** The narrowest and the widest span zoom may reach, in the axis' units - the
+ schedule's shape. */
+export declare interface ZoomLimits {
+    readonly min: number;
+    readonly max: number;
+}
+
 export { }