@umriss-ui/charts 0.12.0 → 0.14.0

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;
@@ -357,7 +378,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. */
@@ -394,9 +415,12 @@ export declare interface ChartProps {
      host and follows it through a ResizeObserver.
      @default "100%" */
     width?: number | "100%";
-    /** Height in CSS pixels. Unlike the width, the chart does not take its
-     host's.
-     @default 300 */
+    /** Height in CSS pixels, fixed. Left out, the chart fills its frame - a
+     stretched grid cell, a card the grid stretches, a container of definite
+     height - and never goes below 300 px, which is also its height in a
+     frame without one. A different floor goes through `style`'s `minHeight`
+     (ADR-0050).
+     @default fills the frame, at least 300 px */
     height?: number;
     /** Outer spacing of the plot area in CSS pixels. */
     padding?: number | Partial<Padding>;
@@ -405,9 +429,9 @@ export declare interface ChartProps {
     ariaLabel?: string;
     /** Goes to the root element, as it does everywhere in this workspace. */
     className?: string;
-    /** Goes to the root element. The plot area is measured, never styled from
-     here: a height set past the component is a height the scene does not know
-     about. */
+    /** Goes to the root element, after the chart's own styles: a `height` or
+     `minHeight` set here wins. The plot area is observed in both directions
+     and the scene follows it. */
     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
@@ -545,10 +569,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
@@ -750,11 +786,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 {
@@ -822,8 +859,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
@@ -975,9 +1013,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>;
@@ -1005,7 +1046,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).
@@ -1022,6 +1065,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;
@@ -1051,8 +1105,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;
@@ -1315,7 +1369,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 -
@@ -1337,9 +1392,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;
 }
 
@@ -1356,6 +1418,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;
@@ -1590,28 +1655,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
@@ -1634,7 +1709,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 -,