@umriss-ui/charts 0.8.2 → 0.10.0

package/dist/index.d.ts

@@ -7,32 +7,42 @@ import { ReactNode } from 'react';
  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 (R-2.5). */
+    /** Upper edge; null/undefined/NaN/±Infinity means a gap.
+     @remarks 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. */
+    /** Lower edge. In a `stack` the stack below is the lower edge, and this is
+     not read.
+     @default a fixed baseline at 0 */
     baseline?: Accessor<T>;
-    /** 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 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,11 +62,13 @@ 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. */
@@ -106,6 +118,7 @@ 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;
@@ -117,8 +130,9 @@ export declare interface AxisConfig<T = unknown> {
     /** "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
@@ -138,33 +152,46 @@ export declare interface AxisConfig<T = unknown> {
     onDomainChange?: (domain: [number, number]) => void;
 }
 
+/** 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";
 
+/** 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 props of `Bar`. */
 export declare interface BarProps<T> {
-    /** Height; null/undefined/NaN/±Infinity means a gap (R-2.5). */
+    /** Height; null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
     accessor: Accessor<T>;
-    /** 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 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,12 +211,132 @@ 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. */
     barWidth: number;
 }
 
+/** The named channels of a box: one number per point, NaN where the median
+ is a gap; and its outliers (ADR-0040). */
+export declare interface BoxChannels extends BoxNumbers<Float64Array> {
+    /** Every box's outliers, flat, box after box; null without `outliers`. */
+    outliers: Float64Array | null;
+    /** Where each box's outliers begin, and one past the last: box i's stand
+     from outlierOffsets[i] to outlierOffsets[i + 1]. null without
+     `outliers`. */
+    outlierOffsets: Uint32Array | null;
+    /** The optional numbers, each null where not given. */
+    mean: Float64Array | null;
+    notchLower: Float64Array | null;
+    notchUpper: Float64Array | null;
+    count: Float64Array | null;
+}
+
+/** The optional numbers of a box (box-plot 04), by name. */
+export declare interface BoxExtras<V = number> {
+    mean: V;
+    notchLower: V;
+    notchUpper: V;
+    count: V;
+}
+
+/** A box's further numbers beside its median, by name. */
+export declare interface BoxNumbers<V = number> {
+    lowerQuartile: V;
+    upperQuartile: V;
+    lowerWhisker: V;
+    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`. */
+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>;
+    /** The box's lower edge. */
+    lowerQuartile: Accessor<T>;
+    /** The box's upper edge. */
+    upperQuartile: Accessor<T>;
+    /** Where the lower whisker ends - the caller's rule, not the minimum. */
+    lowerWhisker: Accessor<T>;
+    /** Where the upper whisker ends - the caller's rule, not the maximum. */
+    upperWhisker: Accessor<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>;
+    /** The mean, drawn as a small ×: beside the median it shows a skew. */
+    mean?: Accessor<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>;
+    /** The notch's upper bound; see `notchLower`. */
+    notchUpper?: Accessor<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.
+     @remarks R-4.12 */
+    xAxisId?: string;
+    /** Binding to a y axis.
+     @remarks R-4.12 */
+    yAxisId?: string;
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
+    data?: readonly 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;
+    /** 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
+     judgement, not the library's. */
+    tone?: "ok" | "warning" | "alarm";
+    /** Width as a fraction of the step, as a bar's: boxes and bars on one x axis
+     share this fraction and stand side by side. */
+    boxWidth?: number;
+}
+
+/** A box plot (CONTEXT.md: Box). The base accessor is the median; the four
+ further numbers are the caller's, computed by whatever method the caller
+ 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>;
+    /** The values beyond the whiskers, per box (ADR-0040). */
+    outliers?: ListAccessor<T>;
+    mean?: Accessor<T>;
+    /** Both bounds or neither (CONTEXT.md: Notch). */
+    notchLower?: Accessor<T>;
+    notchUpper?: Accessor<T>;
+    /** How many values stand behind the box; no y value. */
+    count?: Accessor<T>;
+    /** Width as a fraction of the step; boxes and bars on one x axis share it. */
+    boxWidth: number;
+}
+
 /** The breaks in working time that lie within the extent [from, to] - what the
  axis must mark, in domain units. */
 export declare function breaks(input: CalendarInput, from: number, to: number): number[];
@@ -202,27 +349,36 @@ 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;
 
-/** 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;
 }
 
+/** The props of `Chart`. */
 export declare interface ChartProps<T> {
-    /** Shared data basis (required); access only through accessors (R-2.4). */
+    /** Shared data basis (required); access only through accessors.
+     @remarks 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. */
+    /** 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;
@@ -232,32 +388,37 @@ 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`. */
     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`). */
@@ -297,38 +458,30 @@ export declare interface ChartsWording {
     rowColumn: string;
     /** The table's caption: the visible stretch it lists, both ends formatted. */
     tableCaption: (from: string, to: string) => string;
+    /** A box's numbers, top to bottom as drawn: the tooltip's rows, the
+     readout's parts and the data table's columns (box-plot B9). */
+    upperWhisker: string;
+    upperQuartile: string;
+    median: string;
+    lowerQuartile: string;
+    lowerWhisker: string;
+    /** A box's outliers: the row's name, and the row's value - their count and
+     the first few values, the rest counted (box-plot B9). */
+    outliers: string;
+    /** A box's optional readings: its mean, its notch's two bounds as one row,
+     and how many values stand behind it. */
+    mean: string;
+    notch: string;
+    count: string;
+    outlierList: (values: readonly string[], more: number) => string;
     /** Added to the caption where the table shows the downsampled course (C2):
      how many readings its rows stand for. */
     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;
-}
-
-declare interface CommonProps_2<T> {
-    /** Axis id, through which series bind themselves (R-4.12). */
+declare interface CommonProps<T> {
+    /** 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. */
@@ -342,7 +495,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
@@ -350,8 +505,13 @@ 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>;
@@ -361,18 +521,21 @@ export declare interface ControlChartProps<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". */
@@ -382,15 +545,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. */
@@ -429,6 +595,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
@@ -441,8 +611,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
@@ -455,21 +630,27 @@ export declare const DEFAULT_GRADIENT: readonly string[];
  lengths are therefore parameters. */
 export declare const defaultRules: RuleOptions;
 
+/** 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;
 
+/** 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;
 
+/** 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
@@ -487,15 +668,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
@@ -520,16 +707,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;
 }
@@ -554,8 +779,12 @@ 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 {
     readonly domain: readonly [number, number];
     readonly range: readonly [number, number];
@@ -568,33 +797,40 @@ 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). */
+    /** Y value; null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
     accessor: Accessor<T>;
-    /** 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 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
@@ -606,6 +842,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;
@@ -615,6 +852,10 @@ 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
+ 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;
+
 /** 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
  for a grid up to the next clock change. */
@@ -624,23 +865,31 @@ 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
      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. */
     w: Float64Array | null;
+    /** A box's further numbers beside its median in y; null for every other
+     kind (ADR-0011). */
+    box: BoxChannels | null;
     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
@@ -656,36 +905,46 @@ 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. */
+    /** How the value 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 value as the tooltip writes it. The y axis' `tickFormat` writes the
+     row, not the value.
+     @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. */
 export declare interface MatrixSeriesConfig<T = unknown> extends SeriesBase<T> {
     kind: "matrix";
     /** The value that decides the colour - the third channel (ADR-0011).
@@ -694,8 +953,10 @@ export declare interface MatrixSeriesConfig<T = unknown> extends SeriesBase<T> {
     coloring: MatrixColoring;
 }
 
+/** One minute in milliseconds. */
 export declare const MINUTE: number;
 
+/** Space in CSS pixels on each side of a rectangle. */
 export declare interface Padding {
     top: number;
     right: number;
@@ -716,6 +977,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. */
@@ -741,23 +1004,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. */
@@ -779,6 +1047,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;
@@ -811,6 +1080,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;
@@ -867,6 +1138,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];
@@ -884,29 +1157,37 @@ 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 (R-2.5). */
+    /** Y value; null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
     accessor: Accessor<T>;
-    /** 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 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";
@@ -914,18 +1195,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). */
+    /** Y value; null/undefined/NaN/±Infinity means a gap.
+     @remarks R-2.5 */
     accessor: Accessor<T>;
-    /** Series-own data; overrides the container data (R-2.4). */
+    /** Series-own data; overrides the container data.
+     @remarks R-2.4 */
     data?: readonly T[];
     xAxisId: string;
     yAxisId: string;
@@ -942,8 +1229,11 @@ export declare interface SeriesBase<T = unknown> {
     hidden?: boolean;
 }
 
-export declare type SeriesConfig<T = unknown> = LineSeriesConfig<T> | AreaSeriesConfig<T> | BarSeriesConfig<T> | ScatterSeriesConfig<T> | StateSeriesConfig<T> | MatrixSeriesConfig<T>;
+/** 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
@@ -976,6 +1266,7 @@ declare interface Stackable {
  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 -
      and a gap stays a hole, it gets no colour for "unknown". A colour would
@@ -983,15 +1274,18 @@ export declare interface StateBandProps<T> {
     accessor: Accessor<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.
@@ -1009,6 +1303,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,
@@ -1032,13 +1328,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>[];
@@ -1048,7 +1350,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;
@@ -1074,14 +1377,21 @@ export declare interface TooltipPoint<T = unknown> {
         to: number;
         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). */
+    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;
 }
 
@@ -1212,9 +1522,13 @@ 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;
 
-export declare interface XAxisProps<T> extends CommonProps_2<T> {
+/** The props of `XAxis`. */
+export declare interface XAxisProps<T> extends CommonProps<T> {
     /** `"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
@@ -1245,9 +1559,12 @@ export declare interface XAxisProps<T> extends CommonProps_2<T> {
     onDomainChange?: (domain: [number, number]) => void;
 }
 
+/** 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;
 
-export declare interface YAxisProps<T> extends CommonProps_2<T> {
+/** The props of `YAxis`. */
+export declare interface YAxisProps<T> extends CommonProps<T> {
     /** 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