@umriss-ui/charts 0.13.0 → 0.15.0

package/dist/de.d.ts

@@ -11,6 +11,12 @@ declare interface ChartsWording {
     visibleRange: (from: string, to: string) => string;
     /** The summary's lowest and highest value of one series in that stretch. */
     seriesExtent: (name: string, min: string, max: string) => string;
+    /** The summary's labelled limits, each with its value in its axis' format
+     (a band's two edges as one value). */
+    limitList: (limits: readonly {
+        name: string;
+        value: string;
+    }[]) => string;
     /** What is read after a key: the position, then each series with its value
      (and its own x where it stands on another x axis), the emphasised one
      first. */
@@ -26,6 +32,8 @@ declare interface ChartsWording {
     percent: (value: string) => string;
     /** The keys that walk the chart. */
     walkHelp: string;
+    /** The key that reports the Active point - only where `onSelect` is given. */
+    selectHelp: 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. */

package/dist/index.d.ts

@@ -110,8 +110,9 @@ export declare interface AxisConfig<T = unknown> {
     orientation: AxisOrientation;
     position: AxisPosition;
     /** Where a row lies along the axis; an x axis' only - along y the series
-     place their rows. */
-    accessor?: (d: T, index: number) => number;
+     place their rows. A number is a position or an instant, a string a
+     category, a `Date` an instant (ADR-0052). */
+    accessor?: (d: T, index: number) => AxisValue;
     label?: string;
     tickCount?: number;
     tickFormat?: (v: number) => string;
@@ -122,12 +123,17 @@ export declare interface AxisConfig<T = unknown> {
      @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
-     Pareto. */
+    /** Fixed tick values instead of the 1-2-5 algorithm, on a numeric axis: an
+     hour axis' named hours, a lane grid. */
     ticks?: readonly number[];
-    /** The values are instants in milliseconds: ticks on local boundaries,
-     labels by level. A calendar implies it. */
+    /** The categories of the axis, in their order: the list is the order and
+     the extent, and makes the axis a category axis (ADR-0052). */
+    categories?: readonly string[];
+    /** What is written for a category, wherever it is written. */
+    categoryLabel?: (category: string) => string;
+    /** The values are instants - milliseconds, and where this is said ISO 8601
+     strings as well: ticks on local boundaries, labels by level. A calendar
+     implies it, and so do rows that bring a `Date` (ADR-0052). */
     time?: boolean;
     /** Working calendar: the intervals in which time counts. With it,
      materialisation maps wall clock time onto working time before the scale
@@ -143,6 +149,13 @@ export declare interface AxisConfig<T = unknown> {
     zoomLimits?: ZoomLimits;
 }
 
+/** The fields of a row an axis can read - or, with `V`, those that hold only
+ some of what an axis reads: a matrix' row is a position or a category,
+ never an instant. */
+export declare type AxisField<T, V = AxisValue> = NoInfer<{
+    [K in keyof T & string]-?: T[K] extends V ? K : never;
+}[keyof T & string]>;
+
 /** Whether an axis or a limit runs along x or along y. */
 export declare type AxisOrientation = "x" | "y";
 
@@ -153,6 +166,14 @@ export declare type AxisPosition = "bottom" | "top" | "left" | "right";
 /** The span each zoomable x axis shows, by axis `id`, in the axis' units. */
 export declare type AxisSpans = Readonly<Record<string, readonly [number, number]>>;
 
+/** What an axis reads from a row (ADR-0052): a number - a position, or an
+ instant on a time axis -, a string, which is a category, or a `Date`,
+ which is an instant. The type of the value decides what kind the axis is,
+ never its content: `"2024"` is a category, `2024` a number. On an axis
+ that says `time` a string is an ISO 8601 instant. null/undefined is no
+ place. */
+export declare type AxisValue = number | string | Date | null | undefined;
+
 /** The props of `Bar`. */
 export declare interface BarProps<T> {
     /** Height - a number field of the row or a function of it;
@@ -203,6 +224,43 @@ export declare interface BarSeriesConfig<T = unknown> extends SeriesBase<T>, Sta
     barWidth: number;
 }
 
+/** A bin, the way it is drawn. */
+export declare interface Bin {
+    /** Lower edge; the bin holds it. */
+    readonly from: number;
+    /** Upper edge; the bin holds it only if it is the last one. */
+    readonly to: number;
+    /** The middle, `(from + to) / 2` - the bar's x. */
+    readonly x: number;
+    /** How many values fall in it. */
+    readonly count: number;
+}
+
+/** Counts values into bins of equal width.
+
+ A value on an edge belongs to the bin that edge starts - `[from, to)` - but
+ the last bin is closed, so the greatest value of a domain is counted and not
+ lost. Values that are not finite (`NaN`, ±Infinity, `null`, `undefined`)
+ are skipped, as a gap is on a chart. Without values there are no bins; with
+ values there is at least one, even when they are all equal. */
+export declare function bin(values: readonly (number | null | undefined)[], options?: BinOptions): Bin[];
+
+export declare function bin<T>(rows: readonly T[], value: (row: T) => number | null | undefined, options?: BinOptions): Bin[];
+
+/** The settings of `bin`. */
+export declare interface BinOptions {
+    /** The width of a bin. Wins over `count`. Without a `domain` the edges are
+     multiples of it. */
+    readonly width?: number;
+    /** About how many bins: the width becomes the next 1-2-5 step, so the number
+     comes out near it and not exactly - with a `domain`, exactly.
+     @default 10 */
+    readonly count?: number;
+    /** The span the bins cover, the first edge on its start and the last on its
+     end. Values outside it are left out, not clamped into the end bins. */
+    readonly domain?: readonly [number, 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> {
@@ -328,7 +386,7 @@ export declare type CalendarInput = WorkingCalendar | readonly WorkingInterval[]
 
 /** What `useChart` takes besides the rows: the view to start from and the
  handler that hears every change of it. */
-export declare interface ChartOptions {
+export declare interface ChartOptions<Z = unknown> {
     /** 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
@@ -340,6 +398,13 @@ export declare interface ChartOptions {
      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;
+    /** The reader chose a point: a click on a hit (a tap too), or Enter on the
+     Active point - the same hit the tooltip's `render` receives. Once per
+     click; the end of a drag does not report, and the second click of a
+     double click does not either. The chart holds no selection and draws
+     none: what is chosen is the application's state. Needs a `<Tooltip>`,
+     which makes the hits; the hit does not travel over `syncId`. */
+    onSelect?: (hit: TooltipHit<Z>) => void;
 }
 
 /** What `useChart` hands back: the chart and its parts, typed at the row `Z`,
@@ -357,7 +422,7 @@ export declare interface ChartParts<Z> {
     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;
+    StateBand: <T = Z>(props: StateBandProps<T> & OneLane) => null;
     Matrix: <T = Z>(props: MatrixProps<T>) => null;
     BoxPlot: <T = Z>(props: BoxPlotProps<T>) => null;
     /** How the reader is looking at the chart. */
@@ -464,6 +529,12 @@ export declare interface ChartsWording {
     visibleRange: (from: string, to: string) => string;
     /** The summary's lowest and highest value of one series in that stretch. */
     seriesExtent: (name: string, min: string, max: string) => string;
+    /** The summary's labelled limits, each with its value in its axis' format
+     (a band's two edges as one value). */
+    limitList: (limits: readonly {
+        name: string;
+        value: string;
+    }[]) => string;
     /** What is read after a key: the position, then each series with its value
      (and its own x where it stands on another x axis), the emphasised one
      first. */
@@ -479,6 +550,8 @@ export declare interface ChartsWording {
     percent: (value: string) => string;
     /** The keys that walk the chart. */
     walkHelp: string;
+    /** The key that reports the Active point - only where `onSelect` is given. */
+    selectHelp: 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. */
@@ -548,10 +621,22 @@ declare interface CommonProps {
      @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
-     Pareto. */
+    /** Fixed tick values instead of the 1-2-5 algorithm, on a numeric axis: an
+     hour axis' named hours, a lane grid. An axis that reads categories needs
+     none - every category has its tick. */
     ticks?: readonly number[];
+    /** The categories of the axis, in their order. Without it they stand in
+     the order the rows first bring them. With it the list is the order and
+     the extent: a category no row carries keeps its empty place, and a row
+     whose category is not listed is not drawn - DEV names it. It makes the
+     axis a category axis whatever the rows hold (ADR-0052). */
+    categories?: readonly string[];
+    /** What is written for a category - under its tick, in the tooltip, the
+     readout and the data table - where the rows hold a key and not a name.
+     Two categories may share a label and keep two places. Compared by its
+     source text, as `tickFormat` is.
+     @default the category itself */
+    categoryLabel?: (category: string) => string;
 }
 
 /** A control chart inside a `Chart`: the values as a line, the control limits
@@ -753,11 +838,12 @@ export declare interface LimitBandConfig extends LimitBase {
 /** 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;
+    /** Lower edge of the band, in domain units of its axis; along a time axis
+     an instant, in milliseconds or as a `Date`. */
+    from: number | Date;
     /** Upper edge, in domain units of its axis. A band drawn backwards (`from` above `to`) is drawn between
      the two all the same - the pair is a range, not a direction. */
-    to: number;
+    to: number | Date;
 }
 
 declare interface LimitBase {
@@ -825,8 +911,9 @@ export declare interface LimitLineConfig extends LimitBase {
 
 /** The props of `LimitLine`. */
 export declare interface LimitLineProps extends LimitCommonProps {
-    /** Where the line lies, in domain units of its axis. */
-    value: number;
+    /** Where the line lies, in domain units of its axis; along a time axis
+     an instant, in milliseconds or as a `Date`. */
+    value: number | Date;
 }
 
 /** What a limit stands for. The difference is not cosmetic: a specification
@@ -978,9 +1065,12 @@ export declare type MatrixColoring = {
 
 /** The props of `Matrix`. */
 export declare interface MatrixProps<T> {
-    /** 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 row on the y axis - a field of the data's row or a function of it.
+     A number is a position, as every series' y is; a string is a category:
+     the y axis then has a named row per distinct one, the first at the top,
+     in the order the data bring them or the y axis' `categories`
+     (ADR-0052). Never an instant: a `Date` is refused. */
+    value: AxisField<T, number | string | null | undefined> | ((d: T, index: number) => number | string | null | undefined);
     /** 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>;
@@ -1008,7 +1098,9 @@ export declare interface MatrixProps<T> {
 }
 
 /** A `Matrix` as the chart holds it once registered: its base accessor is the
- row, `level` the colour. */
+ row, `level` the colour. The row may be named: where the accessor yields a
+ string, materialisation gives it its category's place (ADR-0052) - the one
+ series kind whose base accessor reads more than a number. */
 export declare interface MatrixSeriesConfig<T = unknown> extends SeriesBase<T> {
     kind: "matrix";
     /** The level that decides the colour - the third channel (ADR-0011).
@@ -1025,6 +1117,17 @@ export declare type NumberField<T> = NoInfer<{
     [K in keyof T & string]-?: T[K] extends number | null | undefined ? K : never;
 }[keyof T & string]>;
 
+/** A lane is named or given by its edges: the compiler refuses both at once.
+ Beside the props and not in them, so that `StateBandProps` stays an
+ interface another can extend. */
+export declare type OneLane = {
+    lane: string;
+    laneFrom?: undefined;
+    laneTo?: undefined;
+} | {
+    lane?: undefined;
+};
+
 /** Space in CSS pixels on each side of a rectangle. */
 export declare interface Padding {
     top: number;
@@ -1054,8 +1157,8 @@ export declare const paretoDefaults: Omit<ParetoOptions, "remainderName">;
 export declare interface ParetoEntry {
     readonly name: string;
     readonly value: number;
-    /** Category and at the same time x value: category n lies at x = n
-     (ADR-0002). */
+    /** The entry's rank from 0, in the order drawn - its place on an x axis
+     that reads `name`, and an x value for one that reads numbers. */
     readonly index: number;
     /** Share of the total, 0…1. */
     readonly share: number;
@@ -1318,7 +1421,8 @@ declare interface Stackable {
     normalize?: boolean;
 }
 
-/** The props of `StateBand`. */
+/** The props of `StateBand`. Its lane is named, or given by its two edges -
+ one way or the other (`OneLane`). */
 export declare interface StateBandProps<T> {
     /** Index of the state in `states` - a number field of the row or a
      function of it; null/undefined/NaN/±Infinity is a gap -
@@ -1340,9 +1444,16 @@ export declare interface StateBandProps<T> {
      unnamed series is a colour nobody can look up.
      @default "Series n", after its place in the chart */
     name?: string;
-    /** Lower edge of the lane in domain units of the y axis. */
+    /** The lane by its name: a category of the y axis, whose place the band
+     takes, as wide as a bar is. The y axis then lists a lane per name, the
+     first at the top, in the bands' order or its own `categories`
+     (ADR-0052). Not together with `laneFrom` or `laneTo`. */
+    lane?: string;
+    /** Lower edge of the lane in domain units of a numeric y axis.
+     @default the beginning of the axis' domain */
     laneFrom?: number;
-    /** Upper edge of the lane in domain units of the y axis. */
+    /** Upper edge of the lane in domain units of a numeric y axis.
+     @default the end of the axis' domain */
     laneTo?: number;
 }
 
@@ -1359,6 +1470,9 @@ export declare interface StateSeriesConfig<T = unknown> extends SeriesBase<T> {
     /** The closed set of states. The accessor yields the index into it - a number,
      not a key (ADR-0007). */
     states: readonly StateEntry[];
+    /** The lane by its name: a category of the y axis, whose place the band
+     takes (ADR-0052). */
+    lane?: string;
     /** Lower edge of the lane in domain units of the y axis; without a value the
      beginning of the axis domain. */
     laneFrom?: number;
@@ -1385,6 +1499,7 @@ 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";
+    limits?: boolean;
     render?: (hit: TooltipHit<T>) => ReactNode;
 }
 
@@ -1438,6 +1553,12 @@ export declare interface TooltipPoint<T = unknown> {
 export declare interface TooltipProps<T> {
     /** "x": every series at the x position; "nearest": only the nearest point. */
     mode?: "x" | "nearest";
+    /** Adds a row for every labelled `LimitLine` and `LimitBand` on the hit's y
+     axis - its label and value in that axis' format - to the built-in
+     tooltip, and the same to what a key reads out. Limits are not series and
+     stay out of the tooltip unless asked for.
+     @default false */
+    limits?: boolean;
     /** 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 */
@@ -1486,7 +1607,7 @@ export declare function toWorkingTimeClamped(wallClock: number, input: CalendarI
  @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>;
+export declare function useChart<Z>(rows: readonly Z[], options?: ChartOptions<Z>): 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`). */
@@ -1593,28 +1714,38 @@ export declare function workingTimeTicks(input: CalendarInput, from: number, to:
 
 /** 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
+    /** Where a row lies on this axis: a field of the row, compared by its
+     name, or a function of it, compared by its source text as a series' is
+     (`ValueFunction`) - with the same closure limit. A number is a position,
+     a `Date` an instant, a string a category: every distinct one gets a
+     place of its own, in the order the rows bring them, a tick and its name
+     as the label (ADR-0052). The type decides, never the content - `"2024"`
+     is a category, `2024` a number - and a row without a value has no
+     place. The axis reads the rows
+     of every series bound to it; where those bring their own `data`, name
      their row: `<XAxis<HourCount> value="hour" />`. */
-    value: NumberField<T> | ((d: T, index: number) => number);
+    value: AxisField<T> | ((d: T, index: number) => AxisValue);
     /** `"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. 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];
+     longer -, `"data"` keeps it, a pair is fixed: numbers, on a time axis
+     milliseconds or two `Date`s, on a category axis places. On a `zoomable`
+     axis it is the start: what the axis shows while the chart's view names
+     no span for it. */
+    domain?: "nice" | "data" | readonly [number, number] | readonly [Date, Date];
     /** 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. */
     position?: "bottom" | "top";
-    /** The values are instants (milliseconds since the epoch): ticks on local
-     boundaries from the minute to the month, labels by level in en-GB with a
-     24-hour clock - `15:00`, `17 Mar`, `Mar 2026` - and the date on the first
-     tick and on the first of a new day (`17 Mar 00:00`); a day tick there
-     carries the year. The tooltip's x value carries the seconds where the
-     readings lie less than a minute apart. Another language is a `tickFormat`,
-     which is handed the instant. `calendar` implies it. */
+    /** The values are instants: milliseconds since the epoch, or with `time`
+     said ISO 8601 strings as an API sends them, read by the platform's rule -
+     a date with a time and no offset is local time, a date alone is UTC; a
+     string that is none is not drawn. Rows that hold a `Date` put the axis
+     in time without `time`. Ticks on local boundaries from the minute to the
+     month, labels by level in en-GB with a 24-hour clock - `15:00`, `17 Mar`,
+     `Mar 2026` - and the date on the first tick and on the first of a new
+     day (`17 Mar 00:00`); a day tick there carries the year. The tooltip's x
+     value carries the seconds where the readings lie less than a minute
+     apart. Another language is a `tickFormat`, which is handed the instant
+     in milliseconds. `calendar` implies it. */
     time?: boolean;
     /** Working calendar: the intervals in which time counts. With it the axis
      stands in working time - nights and weekends are out, and every
@@ -1637,7 +1768,9 @@ export declare interface XAxisProps<T> extends CommonProps {
 }
 
 /** The props of `YAxis`. It reads no value of its own: where a row lies
- along y is its series' `value`. */
+ along y is its series' `value`. It has categories where a `Matrix` reads
+ its rows from a string or a `StateBand` names its `lane`; the first stands
+ at the top (ADR-0052). */
 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 -,

package/dist/wording/de.js

@@ -1,13 +1,15 @@
-const r = {
+const i = {
   roleDescription: "Diagramm",
   empty: "Keine Daten",
   seriesList: (e) => `${e.length === 1 ? "1 Serie" : `${e.length} Serien`}: ${e.join(", ")}.`,
   visibleRange: (e, n) => `Von ${e} bis ${n}.`,
   seriesExtent: (e, n, t) => `${e} von ${n} bis ${t}.`,
+  limitList: (e) => `Grenzen: ${e.map((n) => `${n.name} ${n.value}`).join(", ")}.`,
   readout: (e, n) => [`${e}.`, ...n.map((t) => `${t.name} ${t.value}${t.x === "" ? "" : ` bei ${t.x}`}.`)].join(" "),
   stackTotal: "Summe",
   percent: (e) => `${e} %`,
   walkHelp: "Pfeil links und rechts gehen durch die Werte, Pfeil hoch und runter wechseln die Serie, Pos1 und Ende springen zum ersten und letzten Wert, Escape hebt die Markierung auf.",
+  selectHelp: "Enter wählt den Punkt.",
   zoomHelp: "Plus und Minus zoomen, Umschalt mit Pfeil links oder rechts verschiebt, 0 kehrt zum eigenen Bereich der Achse zurück.",
   legendHelp: "In der Legende blendet Enter eine Serie aus oder ein, Umschalt+Enter zeigt nur sie.",
   allShown: "Sonst wäre nichts mehr zu sehen, darum werden alle Serien gezeigt.",
@@ -31,5 +33,5 @@ const r = {
   downsampled: (e) => `Ausgedünnt aus ${e.toLocaleString("de-DE")} Messwerten: erster, kleinster, größter und letzter Wert je Abschnitt.`
 };
 export {
-  r as GERMAN_CHARTS_WORDING
+  i as GERMAN_CHARTS_WORDING
 };