@umriss-ui/charts 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1,38 +1,34 @@
 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;
-
-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 (R-2.5). */
-    accessor: Accessor<T>;
-    /** Lower edge; without a value the fixed baseline 0. In a `stack` the stack
-     below is the lower edge, and this is not read. */
-    baseline?: Accessor<T>;
-    /** Binding to an x axis (R-4.12). */
+    /** Upper edge - a number field of the row or a function of it;
+     null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
+    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?: Value<T>;
+    /** Binding to an x axis.
+     @remarks R-4.12 */
     xAxisId?: string;
-    /** Binding to a y axis (R-4.12). */
+    /** Binding to a y axis.
+     @remarks R-4.12 */
     yAxisId?: string;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
-    /** The name in legend and tooltip. Without one the series is called
-     "Series n" and a warning stands in DEV - an unnamed series is a colour
-     nobody can look up. */
+    /** The name in legend and tooltip. Without one a warning stands in DEV - an
+     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; without one the y axis' `tickFormat`,
-     then the default. */
+    /** The value as the tooltip writes it.
+     @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
-    /** Any CSS colour value; without one the palette --uc-series-N. */
+    /** Any CSS colour value.
+     @default the palette's `--uc-series-N` */
     color?: string;
     /** A role instead of a colour value; the theme resolves it. `color` beats
      it. */
@@ -52,15 +48,17 @@ export declare interface AreaProps<T> {
     /** Width of the outline along the upper edge in CSS pixels; 0 leaves it
      out. */
     strokeWidth?: number;
-    /** Dash pattern of the outline as a run of lengths in CSS pixels; without
-     one a solid outline. The fill stays whole. */
+    /** Dash pattern of the outline as a run of lengths in CSS pixels. The fill
+     stays whole.
+     @default a solid outline */
     dash?: readonly number[];
 }
 
+/** An `Area` as the chart holds it once registered. */
 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;
@@ -106,19 +104,23 @@ export declare interface Assessment {
     deviation?: number;
 }
 
+/** An `XAxis` or `YAxis` as the chart holds it once registered. */
 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;
     /** "visible" is a y axis' only: the extent of what its series show inside
      their x axis' domain. */
     domain: "nice" | "data" | "visible" | readonly [number, number];
-    /** undefined = the default per R-4.15 (only the first registered axis per
-     orientation). */
+    /** Whether the axis draws its grid lines.
+     @default only the first registered axis per orientation
+     @remarks R-4.15 */
     grid?: boolean;
     /** Fixed tick values instead of the 1-2-5 algorithm. For axes whose values are
      not numbers but places: the lanes of a state stack, the categories of a
@@ -133,38 +135,48 @@ 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. */
 export declare type AxisOrientation = "x" | "y";
 
+/** The edge of the plot an axis stands at: `bottom` or `top` for x, `left` or
+ `right` for y. */
 export declare type AxisPosition = "bottom" | "top" | "left" | "right";
 
-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 (R-2.5). */
-    accessor: Accessor<T>;
-    /** Binding to an x axis (R-4.12). */
+    /** Height - a number field of the row or a function of it;
+     null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
+    value: Value<T>;
+    /** Binding to an x axis.
+     @remarks R-4.12 */
     xAxisId?: string;
-    /** Binding to a y axis (R-4.12). */
+    /** Binding to a y axis.
+     @remarks R-4.12 */
     yAxisId?: string;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
-    /** The name in legend and tooltip. Without one the series is called
-     "Series n" and a warning stands in DEV - an unnamed series is a colour
-     nobody can look up. */
+    /** The name in legend and tooltip. Without one a warning stands in DEV - an
+     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; without one the y axis' `tickFormat`,
-     then the default. */
+    /** The value as the tooltip writes it.
+     @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
-    /** Any CSS colour value; without one the palette --uc-series-N. */
+    /** Any CSS colour value.
+     @default the palette's `--uc-series-N` */
     color?: string;
     /** A role instead of a colour value; the theme resolves it. `color` beats
      it. */
@@ -184,6 +196,7 @@ export declare interface BarProps<T> {
     barWidth?: number;
 }
 
+/** A `Bar` as the chart holds it once registered. */
 export declare interface BarSeriesConfig<T = unknown> extends SeriesBase<T>, Stackable {
     kind: "bar";
     /** Width as a fraction of the step; the group shares this fraction. */
@@ -222,52 +235,54 @@ export declare interface BoxNumbers<V = number> {
     upperWhisker: V;
 }
 
-export declare function BoxPlot<T>(props: BoxPlotProps<T>): null;
-
+/** 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 (R-2.5). */
-    median: Accessor<T>;
+     box is drawn there, whatever the other numbers say.
+     @remarks R-2.5 */
+    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>;
-    /** Binding to an x axis (R-4.12). */
+    count?: Value<T>;
+    /** Binding to an x axis.
+     @remarks R-4.12 */
     xAxisId?: string;
-    /** Binding to a y axis (R-4.12). */
+    /** Binding to a y axis.
+     @remarks R-4.12 */
     yAxisId?: string;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
-    /** The name in legend and tooltip. Without one the series is called
-     "Series n" and a warning stands in DEV. */
+    /** 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; without
-     one the y axis' `tickFormat`, then the default. */
+    /** 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;
-    /** Any CSS colour value; without one the palette --uc-series-N. */
+    /** Any CSS colour value.
+     @default the palette's `--uc-series-N` */
     color?: string;
     /** A role instead of a colour value; the theme resolves it. `color` beats
      it. Set by the caller: a box out of its specification is the caller's
@@ -283,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;
 }
@@ -311,27 +326,82 @@ export declare function calendarFrom(input: CalendarInput): WorkingCalendar;
  axis, or the calendar built from it. */
 export declare type CalendarInput = WorkingCalendar | readonly WorkingInterval[];
 
-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 (R-5.1). */
+/** Measurements of the instrumentation for the benchmark page.
+ @remarks R-5.1 */
 export declare interface ChartPerf {
     materializeMs: number;
     seriesDrawMs: number;
     points: number;
 }
 
-export declare interface ChartProps<T> {
-    /** Shared data basis (required); access only through accessors (R-2.4). */
-    data: readonly T[];
-    /** Width in CSS pixels, or `"100%"` for the host's. Without a value the chart
-     measures its host and follows it through a ResizeObserver. */
+/** 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%" */
     width?: number | "100%";
-    /** Height in CSS pixels; 300 without a value. Unlike the width, the chart
-     does not take its host's. */
+    /** Height in CSS pixels. Unlike the width, the chart does not take its
+     host's.
+     @default 300 */
     height?: number;
     /** Outer spacing of the plot area in CSS pixels. */
     padding?: number | Partial<Padding>;
-    /** Required in DEV through a warning (R-7.6). */
+    /** Required in DEV through a warning.
+     @remarks R-7.6 */
     ariaLabel?: string;
     /** Goes to the root element, as it does everywhere in this workspace. */
     className?: string;
@@ -341,32 +411,38 @@ 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. Without a value the wording's `empty`; this prop wins over it. */
+     stay.
+     @default the wording's `empty` */
     empty?: ReactNode;
-    /** The chart's words (ADR-0031): English without a value, entries left out
-     fall back to English. German: `GERMAN_CHARTS_WORDING` from
-     `@umriss-ui/charts/wording/de`. */
+    /** 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 */
     wording?: Partial<ChartsWording>;
-    /** How series are told apart. `"color"` (the default): by their colour.
+    /** How series are told apart. `"color"`: by their colour.
      `"marks"`: by a dash and a marker shape as well - a line, an area and a
      scatter -, and by a hatch - a bar, a state, a matrix cell, a limit band -,
      chosen by the same palette place as the colour, so that a reader who does
      not see the colours still tells them apart; the legend's chips show the
-     same. A caller's own `dash` wins over the place's. */
+     same. A caller's own `dash` wins over the place's.
+     @default "color" */
     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 (R-5.1); not needed otherwise. */
+    /** Instrumentation for the benchmark page; not needed otherwise.
+     @remarks R-5.1 */
     onPerf?: (perf: ChartPerf) => void;
     /** The axes, series and companions of this chart. They draw nothing
-     themselves: each registers its configuration and the scene draws it
-     (R-2.1), and the order in the JSX is the drawing order. */
+     themselves: each registers its configuration and the scene draws it,
+     and the order in the JSX is the drawing order.
+     @remarks R-2.1 */
     children?: ReactNode;
 }
 
+/** Everything the charts put out as text. */
 export declare interface ChartsWording {
     /** What a screen reader calls the plot area that takes the keys
      (`aria-roledescription`). */
@@ -396,6 +472,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;
@@ -427,37 +511,21 @@ export declare interface ChartsWording {
     downsampled: (readings: number) => string;
 }
 
-declare interface CommonProps {
-    /** Axis on which the value lies. Without one, the first axis of the
-     orientation. */
-    axisId?: string;
-    /** Whether the value lies on the x or on the y axis. Without one, y: a limit
-     is nearly always a value and not a moment. */
-    orientation?: "x" | "y";
-    /** Two severities, not five: five urgencies are five colours, and five colours
-     on a dense screen are noise. */
-    severity?: Severity;
-    /** What the value means. A line at 90 does not say what 90 is. */
-    label?: string;
-    /** Any CSS colour value, in place of the one the severity yields. A colour
-     handed in instead of a severity puts the rule in the application and the
-     presentation in the library, and the two drift apart as soon as a bound
-     moves - so this is for the case that has no severity, not for taste. */
-    color?: string;
-    /** Whether the value widens the axis extent, so that the limit is certainly
-     visible. Default true; the head of this file says why. */
-    inExtent?: boolean;
-    /** A chosen specification limit (the default) or a calculated control limit.
-     They look different because they mean different things (ADR-0008). */
-    role?: LimitRole;
+/** 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_2<T> {
-    /** Axis id, through which series bind themselves (R-4.12). */
+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. */
@@ -467,7 +535,9 @@ declare interface CommonProps_2<T> {
      a new text or remount. A bound `Intl.NumberFormat#format` is compared by
      identity. */
     tickFormat?: (v: number) => string;
-    /** Grid lines; the default follows R-4.15. */
+    /** Grid lines.
+     @default only on the first axis of its orientation
+     @remarks R-4.15 */
     grid?: boolean;
     /** Fixed tick values instead of the 1-2-5 algorithm. For axes whose values are
      places and not numbers: the lanes of a state stack, the categories of a
@@ -475,29 +545,38 @@ declare interface CommonProps_2<T> {
     ticks?: readonly number[];
 }
 
+/** A control chart inside a `Chart`: the values as a line, the control limits
+ and zones computed from them, and the points that break a rule marked.
+ It draws nothing of its own - it composes `Line`, `LimitLine` and
+ `Scatter`, so that limits, zones and violations come from the same values. */
 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[];
     /** Given, or from a named reference window - never tacitly from everything on
      the screen (ADR-0008). */
     origin: ControlLimitOrigin;
-    /** Binding to an x axis (R-4.12). */
+    /** Binding to an x axis.
+     @remarks R-4.12 */
     xAxisId?: string;
-    /** Binding to a y axis (R-4.12). */
+    /** Binding to a y axis.
+     @remarks R-4.12 */
     yAxisId?: string;
-    /** The name in legend and tooltip. Without one the series is called
-     "Series n" and a warning stands in DEV - an unnamed series is a colour
-     nobody can look up. */
+    /** The name in legend and tooltip. Without one a warning stands in DEV - an
+     unnamed series is a colour nobody can look up.
+     @default "Series n", after its place in the chart */
     name?: string;
-    /** The value as the tooltip writes it - on the line and on the violations;
-     without one the y axis' `tickFormat`, then the default. */
+    /** The value as the tooltip writes it - on the line and on the violations.
+     @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
-    /** Any CSS colour value; without one the palette --uc-series-N. */
+    /** Any CSS colour value.
+     @default the palette's `--uc-series-N` */
     color?: string;
     /** A role instead of a colour value for the line; the theme resolves it.
      The violations are always "alarm". */
@@ -507,15 +586,18 @@ export declare interface ControlChartProps<T> {
     /** The faint zone lines at one and two sigma. Rule 4 is about the two-sigma
      zone; without them a reader cannot check it. */
     zoneLines?: boolean;
-    /** Labels of the control limits in the axis band. Without a value, none: the
-     package brings no text along, not even "UCL" and "LCL". */
+    /** Label of the upper control limit in the axis band. The package brings no
+     text along, not even "UCL" and "LCL".
+     @default no label */
     labelUpper?: string;
     /** The same for the lower control limit. Named separately because a chart may
-     well want one of the two labelled and not the other. */
+     well want one of the two labelled and not the other.
+     @default no label */
     labelLower?: string;
-    /** Name of the scatter of violations in the legend and the tooltip. Without a
-     value, none: a legend then carries it as "Series n" and warns once in DEV.
-     Before this, a German suffix stood on the name of the chart. */
+    /** Name of the scatter of violations in the legend and the tooltip. Without
+     one a legend warns once in DEV. Before this, a German suffix stood on the
+     name of the chart.
+     @default "Series n", after its place in the chart */
     violationName?: string;
     /** The violations as data - they can be listed beside the chart as well as
      marked on it. */
@@ -554,6 +636,10 @@ export declare interface ControlLimits {
  chart then draws no line instead of bursting. */
 export declare function controlLimits(values: readonly number[], origin: ControlLimitOrigin): ControlLimits;
 
+/** The chart's values as a table, on demand: a key - in the legend where
+ there is one - opens a table of what the chart shows, one column per
+ visible series, in the tooltip's format. For a reader who wants every value
+ at once. Place it inside a `Chart`. */
 export declare function DataTable(): ReactNode;
 
 /** One table of the data table: the series of one x axis, or one matrix. Every
@@ -566,8 +652,13 @@ export declare interface DataTableGroup {
     rows: readonly (readonly string[])[];
 }
 
+/** One day of 24 hours in milliseconds; across a clock change a calendar day
+ is an hour longer or shorter. */
 export declare const DAY: number;
 
+/** The instance shipped by default. English; German is
+ `GERMAN_CHARTS_WORDING` in `@umriss-ui/charts/wording/de`. A chart takes
+ its own through `wording`. */
 export declare const DEFAULT_CHARTS_WORDING: ChartsWording;
 
 /** Default gradient: a sequential set, light to dark, so that it stays readable
@@ -580,26 +671,52 @@ 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;
 
 /** Explicit invalidation: devalue the cache, every living chart reads anew and
  redraws. */
 export declare function invalidateTheme(): void;
 
-export declare function Legend({ placement, onToggle }: LegendProps): ReactNode;
+/** The legend of a chart: one entry per series, or per state of a state band.
+ 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 {
     placement: "top" | "bottom";
 }
 
+/** The props of `Legend`. */
 export declare interface LegendProps {
-    /** Which side of the plot area the legend stands on. Without a value, above
-     it. */
+    /** 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
@@ -612,15 +729,21 @@ export declare interface Limit {
     severity: Severity;
 }
 
+/** A limit drawn as a band between two values of an axis - a tolerance or a
+ zone. Otherwise a `LimitLine`. */
 export declare function LimitBand(props: LimitBandProps): null;
 
+/** A `LimitBand` as the chart holds it once registered: the range from `from`
+ to `to`. */
 export declare interface LimitBandConfig extends LimitBase {
     kind: "band";
     from: number;
     to: number;
 }
 
-export declare interface LimitBandProps extends CommonProps {
+/** The props of `LimitBand`: a `LimitLine`'s, with a range in place of
+ `value`. */
+export declare interface LimitBandProps extends LimitCommonProps {
     /** Lower edge of the band, in domain units of its axis. */
     from: number;
     /** Upper edge, in domain units of its axis. A band drawn backwards (`from` above `to`) is drawn between
@@ -645,16 +768,54 @@ declare interface LimitBase {
     inExtent: boolean;
 }
 
+declare interface LimitCommonProps {
+    /** Axis on which the value lies.
+     @default the first axis of the orientation */
+    axisId?: string;
+    /** Whether the value lies on the x or on the y axis - a limit is nearly
+     always a value and not a moment.
+     @default "y" */
+    orientation?: "x" | "y";
+    /** Two severities, not five: five urgencies are five colours, and five colours
+     on a dense screen are noise. */
+    severity?: Severity;
+    /** What the value means. A line at 90 does not say what 90 is. */
+    label?: string;
+    /** Any CSS colour value, in place of the one the severity yields. A colour
+     handed in instead of a severity puts the rule in the application and the
+     presentation in the library, and the two drift apart as soon as a bound
+     moves - so this is for the case that has no severity, not for taste.
+     The line or band takes it; its label keeps the axis's text colour, which
+     stays legible in both themes, and a short stroke before the text in the
+     line's pattern takes this colour. */
+    color?: string;
+    /** Whether the value widens the axis extent, so that the limit is certainly
+     visible.
+     @default true */
+    inExtent?: boolean;
+    /** A chosen specification limit or a calculated control limit. They look
+     different because they mean different things (ADR-0008).
+     @default "specification" */
+    role?: LimitRole;
+}
+
+/** Any registered limit, a line or a band, told apart by `kind`. */
 export declare type LimitConfig = LimitLineConfig | LimitBandConfig;
 
+/** A limit drawn as a line across the plot at one value of an axis - a
+ specification limit, or with `role` a control limit. Not a series: no data,
+ no legend entry, no hit. By default it widens its axis so that it is
+ always seen. */
 export declare function LimitLine(props: LimitLineProps): null;
 
+/** A `LimitLine` as the chart holds it once registered. */
 export declare interface LimitLineConfig extends LimitBase {
     kind: "line";
     value: number;
 }
 
-export declare interface LimitLineProps extends CommonProps {
+/** The props of `LimitLine`. */
+export declare interface LimitLineProps extends LimitCommonProps {
     /** Where the line lies, in domain units of its axis. */
     value: number;
 }
@@ -679,8 +840,8 @@ export declare interface LimitSet {
     target?: number;
 }
 
-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 {
     readonly domain: readonly [number, number];
     readonly range: readonly [number, number];
@@ -693,33 +854,37 @@ export declare class LinearScale implements Scale {
     ticks(n: number): number[];
 }
 
+/** The props of `Line`. */
 export declare interface LineProps<T> {
-    /** Y value; null/undefined/NaN/±Infinity means a gap (R-2.5). */
-    accessor: Accessor<T>;
-    /** Binding to an x axis (R-4.12). */
+    /** Y value - a number field of the row or a function of it;
+     null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
+    value: Value<T>;
+    /** Binding to an x axis.
+     @remarks R-4.12 */
     xAxisId?: string;
-    /** Binding to a y axis (R-4.12). */
+    /** Binding to a y axis.
+     @remarks R-4.12 */
     yAxisId?: string;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
-    /** The name in legend and tooltip. Without one the series is called
-     "Series n" and a warning stands in DEV - an unnamed series is a colour
-     nobody can look up. */
+    /** The name in legend and tooltip. Without one a warning stands in DEV - an
+     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; without one the y axis' `tickFormat`,
-     then the default. */
+    /** The value as the tooltip writes it.
+     @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
-    /** Any CSS colour value; without one the palette --uc-series-N. */
+    /** Any CSS colour value.
+     @default the palette's `--uc-series-N` */
     color?: string;
     /** A role instead of a colour value; the theme resolves it. */
     tone?: "ok" | "warning" | "alarm";
     /** Line width in CSS pixels. */
     strokeWidth?: number;
-    /** Dash pattern as a run of lengths in CSS pixels; without one a solid line. */
+    /** Dash pattern as a run of lengths in CSS pixels.
+     @default a solid line */
     dash?: readonly number[];
     /** When the individual points are drawn as marks: `auto` every point up to
      60 points and above that only a point between two gaps - it has no line
@@ -731,6 +896,7 @@ export declare interface LineProps<T> {
     step?: boolean;
 }
 
+/** A `Line` as the chart holds it once registered. */
 export declare interface LineSeriesConfig<T = unknown> extends SeriesBase<T> {
     kind: "line";
     strokeWidth: number;
@@ -740,9 +906,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
@@ -753,16 +928,17 @@ export declare function localOffset(instant: number): number;
  go it in one piece. Only the first n values are touched. */
 export declare function mapSeries(input: CalendarInput, source: Float64Array, n: number, target: Float64Array): void;
 
-/** Materialised series: the draw loop works only on this (R-2.7).
- Gaps (null/undefined/NaN/±Infinity out of the accessor) are encoded as NaN
- (R-2.5). */
+/** Materialised series: the draw loop works only on this.
+ Gaps (null/undefined/NaN/±Infinity out of the accessor) are encoded as NaN.
+ @remarks R-2.7, R-2.5 */
 export declare interface MaterializedSeries {
     x: Float64Array;
     y: Float64Array;
     /** Lower edge, where the baseline is an accessor of its own; otherwise null.
-     A fixed baseline needs no channel - it is a number (R-2.7). */
+     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. */
@@ -773,8 +949,6 @@ export declare interface MaterializedSeries {
     length: number;
 }
 
-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 = {
@@ -788,46 +962,61 @@ export declare type MatrixColoring = {
      package does not have and is not to get (ADR-0011). Whoever wants a
      finer gradation names more colours. */
     stops: readonly string[];
-    /** Value range of the gradient; without a value taken from the data. */
+    /** Value range of the gradient.
+     @default the range of the data */
     range?: readonly [number, number];
 };
 
+/** 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>;
-    /** Without a value the default gradient across the data range. */
+    /** 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;
-    /** Binding to an x axis (R-4.12). */
+    /** Binding to an x axis.
+     @remarks R-4.12 */
     xAxisId?: string;
-    /** Binding to a y axis (R-4.12). */
+    /** Binding to a y axis.
+     @remarks R-4.12 */
     yAxisId?: string;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
-    /** The name in legend and tooltip. Without one the series is called
-     "Series n" and a warning stands in DEV - an unnamed series is a colour
-     nobody can look up. */
+    /** The name in legend and tooltip. Without one a warning stands in DEV - an
+     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; without one the default. 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, `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;
     right: number;
@@ -848,6 +1037,8 @@ export declare interface Padding {
  which is the third biggest problem. */
 export declare function pareto(items: readonly ParetoItem[], options?: ParetoSettings): ParetoResult;
 
+/** What `pareto` assumes where a call says nothing: a cutoff of 80 %, and no
+ collecting of the tail. */
 export declare const paretoDefaults: Omit<ParetoOptions, "remainderName">;
 
 /** An item, the way it is drawn. */
@@ -873,23 +1064,28 @@ export declare interface ParetoItem {
     readonly value: number;
 }
 
+/** The settings of `pareto`, complete; a call gives `ParetoSettings`. */
 export declare interface ParetoOptions {
     /** The share whose crossing is sought. Whoever lands exactly on it counts as
      the crossing: the question is "which reasons make up eighty per cent", and
-     whoever reaches eighty exactly belongs to them. */
+     whoever reaches eighty exactly belongs to them.
+     @default 0.8 */
     readonly cutoff: number;
     /** How many items stay on their own. Everything behind that becomes a single
      entry. Beyond the number of items no remainder arises at all - not an empty
-     one. Default: infinity, so no collecting. */
+     one.
+     @default Infinity */
     readonly collectRank: number;
     /** Name of the collected remainder. `@umriss-ui/charts` has no wording module
      - every string it draws comes from the caller - and no module is introduced
-     for a single label. Hence no default either: until library-audit 03 the
-     default here was "Sonstige", the one German word the package brought along
-     itself. */
+     for a single label. Until library-audit 03 the name here was
+     "Sonstige", the one German word the package brought along itself.
+     @default none - the caller names it */
     readonly remainderName?: string;
 }
 
+/** What `pareto` returns: the entries as they are drawn, their total and
+ where the cutoff is crossed. */
 export declare interface ParetoResult {
     readonly entries: readonly ParetoEntry[];
     /** Total of the drawn entries - after collecting, the same as before. */
@@ -911,6 +1107,7 @@ export declare type ParetoSettings = {
     readonly remainderName: string;
 });
 
+/** A rectangle in CSS pixels, from its top left corner. */
 export declare interface Rect {
     x: number;
     y: number;
@@ -943,6 +1140,8 @@ export declare interface RemovedSpan {
  without a style engine), a colour is given back as it stands. */
 export declare function resolveColours<K extends string>(root: Element, colours: Readonly<Record<K, string>>): Record<K, string>;
 
+/** A chart's colours and fonts, resolved from the `--uc-*` tokens where the
+ chart stands. */
 export declare interface ResolvedTheme {
     colorAxis: string;
     colorGrid: string;
@@ -999,6 +1198,8 @@ export declare function ruleTrend(values: readonly number[], length?: number): n
  that one is unremarkable and, marked, would look like a measurement error. */
 export declare function ruleTwoOfThree(values: readonly number[], limits: ControlLimits): number[];
 
+/** The mapping of an axis' values onto pixels and back, with its ticks. Every
+ scale of the library is affine; `LinearScale` implements it. */
 export declare interface Scale {
     domain: readonly [number, number];
     range: readonly [number, number];
@@ -1016,29 +1217,30 @@ export declare interface Scale {
     ticks(n: number): number[];
 }
 
-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 (R-2.5). */
-    accessor: Accessor<T>;
-    /** Binding to an x axis (R-4.12). */
+    /** Y value - a number field of the row or a function of it;
+     null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
+    value: Value<T>;
+    /** Binding to an x axis.
+     @remarks R-4.12 */
     xAxisId?: string;
-    /** Binding to a y axis (R-4.12). */
+    /** Binding to a y axis.
+     @remarks R-4.12 */
     yAxisId?: string;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
-    /** The name in legend and tooltip. Without one the series is called
-     "Series n" and a warning stands in DEV - an unnamed series is a colour
-     nobody can look up. */
+    /** The name in legend and tooltip. Without one a warning stands in DEV - an
+     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; without one the y axis' `tickFormat`,
-     then the default. */
+    /** The value as the tooltip writes it.
+     @default the y axis' `tickFormat`, else the built-in number format */
     format?: (value: number) => string;
-    /** Any CSS colour value; without one the palette --uc-series-N. */
+    /** Any CSS colour value.
+     @default the palette's `--uc-series-N` */
     color?: string;
     /** A role instead of a colour value; the theme resolves it. */
     tone?: "ok" | "warning" | "alarm";
@@ -1046,18 +1248,24 @@ export declare interface ScatterProps<T> {
     radius?: number;
 }
 
+/** A `Scatter` as the chart holds it once registered. */
 export declare interface ScatterSeriesConfig<T = unknown> extends SeriesBase<T> {
     kind: "scatter";
     /** Point radius in CSS pixels. */
     radius: number;
 }
 
+/** One second in milliseconds, the unit of a time axis. */
 export declare const SECOND = 1000;
 
+/** What every series registers, whatever its kind: where its values come from,
+ which axes it stands on, and how it is named and coloured. */
 export declare interface SeriesBase<T = unknown> {
-    /** Y value; null/undefined/NaN/±Infinity means a gap (R-2.5). */
-    accessor: Accessor<T>;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Y value; null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
+    accessor: ValueFunction<T>;
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
     xAxisId: string;
     yAxisId: string;
@@ -1070,12 +1278,13 @@ 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`. */
 export declare type SeriesConfig<T = unknown> = LineSeriesConfig<T> | AreaSeriesConfig<T> | BarSeriesConfig<T> | BoxSeriesConfig<T> | ScatterSeriesConfig<T> | StateSeriesConfig<T> | MatrixSeriesConfig<T>;
 
+/** The kinds of series a chart draws: `line`, `area`, `bar`, `box`, `scatter`,
+ `state` and `matrix`. The set is closed. */
 export declare type SeriesKind = SeriesConfig["kind"];
 
 /** How seriously a violation weighs. Exactly two: one severity that advises and
@@ -1100,35 +1309,28 @@ 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 (R-4.12). */
+    /** Binding to an x axis.
+     @remarks R-4.12 */
     xAxisId?: string;
-    /** Binding to a y axis (R-4.12). */
+    /** Binding to a y axis.
+     @remarks R-4.12 */
     yAxisId?: string;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
-    /** The name in legend and tooltip. Without one the series is called
-     "Series n" and a warning stands in DEV - an unnamed series is a colour
-     nobody can look up. */
+    /** The name in legend and tooltip. Without one a warning stands in DEV - an
+     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. */
@@ -1141,6 +1343,8 @@ export declare interface StateEntry {
     color: string;
 }
 
+/** A `StateBand` as the chart holds it once registered: its accessor yields
+ an index into `states`. */
 export declare interface StateSeriesConfig<T = unknown> extends SeriesBase<T> {
     kind: "state";
     /** The closed set of states. The accessor yields the index into it - a number,
@@ -1164,13 +1368,19 @@ export declare function subscribeTheme(notify: () => void): () => void;
  day steps it continues in whole days. */
 export declare function timeStep(span: number, count: number): number;
 
+/** Turns on the pointer's interaction with a chart: crosshair, hover markers
+ and the tooltip, built in or from `render`. Without it the chart does not
+ answer the pointer. */
 export declare function Tooltip<T>(props: TooltipProps<T>): null;
 
+/** A `Tooltip` as the chart holds it once registered. */
 export declare interface TooltipConfig<T = unknown> {
     mode: "x" | "nearest";
     render?: (hit: TooltipHit<T>) => ReactNode;
 }
 
+/** What the pointer hit: the x value under it and one point per series there.
+ A custom tooltip's `render` receives it. */
 export declare interface TooltipHit<T = unknown> {
     xValue: number;
     points: readonly TooltipPoint<T>[];
@@ -1180,7 +1390,8 @@ export declare interface TooltipHit<T = unknown> {
     yPx: number;
 }
 
-/** One hit per series in the tooltip (R-4.4). */
+/** One hit per series in the tooltip.
+ @remarks R-4.4 */
 export declare interface TooltipPoint<T = unknown> {
     seriesName: string;
     color: string;
@@ -1192,11 +1403,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
@@ -1207,19 +1418,20 @@ 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[];
     };
 }
 
+/** The props of `Tooltip`. */
 export declare interface TooltipProps<T> {
     /** "x": every series at the x position; "nearest": only the nearest point. */
     mode?: "x" | "nearest";
-    /** Render prop for content of one's own; without it the built-in tooltip
-     applies. Compared by its source text, like `tickFormat` - with the same
-     closure limit. */
+    /** Render prop for content of one's own. Compared by its source text, like
+     `tickFormat` - with the same closure limit.
+     @default the built-in tooltip */
     render?: (hit: TooltipHit<T>) => ReactNode;
 }
 
@@ -1258,6 +1470,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`
@@ -1350,13 +1582,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[];
 
-export declare function XAxis<T>(props: XAxisProps<T>): null;
-
-export declare interface XAxisProps<T> extends CommonProps_2<T> {
+/** The props of `XAxis`. */
+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. */
@@ -1374,18 +1612,24 @@ export declare interface XAxisProps<T> extends CommonProps_2<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;
 }
 
-export declare function YAxis<T>(props: YAxisProps<T>): null;
-
-export declare interface YAxisProps<T> extends CommonProps_2<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
@@ -1412,4 +1656,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 { }