@umriss-ui/charts 0.6.0 → 0.8.0

package/dist/de.d.ts

@@ -18,10 +18,28 @@ declare interface ChartsWording {
         value: string;
         x: string;
     }[]) => string;
+    /** The last row of a stack in the tooltip and the readout: the sum of its
+     members at the point (charts-stacking K4). */
+    stackTotal: string;
+    /** A share in a normalised stack, its number already formatted (K5). */
+    percent: (value: string) => string;
     /** The keys that walk the chart. */
     walkHelp: string;
     /** The keys that zoom and pan it - only where the chart can be zoomed. */
     zoomHelp: string;
+    /** The data table's disclosure key, closed and open (charts-alternatives
+     C1). */
+    showData: string;
+    hideData: string;
+    /** The heading of the table's x column where its axis has no `label`, and
+     of a matrix' row column where its y axis has none. */
+    positionColumn: string;
+    rowColumn: string;
+    /** The table's caption: the visible stretch it lists, both ends formatted. */
+    tableCaption: (from: string, to: string) => string;
+    /** Added to the caption where the table shows the downsampled course (C2):
+     how many readings its rows stand for. */
+    downsampled: (readings: number) => string;
 }
 
 export declare const GERMAN_CHARTS_WORDING: ChartsWording;

package/dist/index.d.ts

@@ -12,7 +12,8 @@ export declare function Area<T>(props: AreaProps<T>): null;
 export declare interface AreaProps<T> {
     /** Upper edge; null/undefined/NaN/±Infinity means a gap (R-2.5). */
     accessor: Accessor<T>;
-    /** Lower edge; without a value the fixed baseline 0. */
+    /** Lower edge; without a value the fixed baseline 0. In a `stack` the stack
+     below is the lower edge, and this is not read. */
     baseline?: Accessor<T>;
     /** Binding to an x axis (R-4.12). */
     xAxisId?: string;
@@ -36,6 +37,16 @@ export declare interface AreaProps<T> {
     /** A role instead of a colour value; the theme resolves it. `color` beats
      it. */
     tone?: "ok" | "warning" | "alarm";
+    /** The stack this series stands in: every Bar and Area with the same id on
+     the same x and y axis stands on the ones registered before it. A gap
+     stacks as zero; negative values stack downward from zero. The tooltip
+     names each series' own value and the stack's total. */
+    stack?: string;
+    /** On any member of a stack, every x of the stack sums to 100 %: each value
+     becomes its share, and the y axis reads in percent unless it has a
+     `tickFormat`. The total stays the readings' own sum, written in the
+     series' `format`. */
+    normalize?: boolean;
     /** Opacity of the fill, from 0 to 1; the outline stays fully opaque. */
     fillOpacity?: number;
     /** Width of the outline along the upper edge in CSS pixels; 0 leaves it
@@ -46,7 +57,7 @@ export declare interface AreaProps<T> {
     dash?: readonly number[];
 }
 
-export declare interface AreaSeriesConfig<T = unknown> extends SeriesBase<T> {
+export declare interface AreaSeriesConfig<T = unknown> extends SeriesBase<T>, Stackable {
     kind: "area";
     /** Lower edge; without a value the fixed baseline 0. */
     baseline?: Accessor<T>;
@@ -116,10 +127,10 @@ export declare interface AxisConfig<T = unknown> {
     /** The values are instants in milliseconds: ticks on local boundaries,
      labels by level. A calendar implies it. */
     time?: boolean;
-    /** Operating calendar: the intervals in which time counts. With it,
-     materialisation maps wall clock time onto operating time before the scale
+    /** Working calendar: the intervals in which time counts. With it,
+     materialisation maps wall clock time onto working time before the scale
      calculates - the scale stays affine (ADR-0001). */
-    calendar?: readonly OperatingInterval[];
+    calendar?: readonly WorkingInterval[];
     /** y axes only: this axis' ticks on the first y axis' grid. */
     alignTicks?: boolean;
     /** x axes only: where wheel, drag, pinch and double click propose a
@@ -158,28 +169,38 @@ export declare interface BarProps<T> {
     /** A role instead of a colour value; the theme resolves it. `color` beats
      it. */
     tone?: "ok" | "warning" | "alarm";
+    /** The stack this series stands in: every Bar and Area with the same id on
+     the same x and y axis stands on the ones registered before it. A gap
+     stacks as zero; negative values stack downward from zero. The tooltip
+     names each series' own value and the stack's total. */
+    stack?: string;
+    /** On any member of a stack, every x of the stack sums to 100 %: each value
+     becomes its share, and the y axis reads in percent unless it has a
+     `tickFormat`. The total stays the readings' own sum, written in the
+     series' `format`. */
+    normalize?: boolean;
     /** Width as a fraction of the step; just under 1, so that neighbours do not
      touch. Several bar series share this fraction. */
     barWidth?: number;
 }
 
-export declare interface BarSeriesConfig<T = unknown> extends SeriesBase<T> {
+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 breaks in operating time that lie within the extent [from, to] - what the
+/** 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[];
 
 /** Calendar from an input - a built calendar is passed straight through, a raw
  list is built once and remembered. */
-export declare function calendarFrom(input: CalendarInput): OperatingCalendar;
+export declare function calendarFrom(input: CalendarInput): WorkingCalendar;
 
 /** Every function of this module takes either: the raw list as it stands on the
  axis, or the calendar built from it. */
-export declare type CalendarInput = OperatingCalendar | readonly OperatingInterval[];
+export declare type CalendarInput = WorkingCalendar | readonly WorkingInterval[];
 
 export declare function Chart<T>(props: ChartProps<T>): ReactNode;
 
@@ -217,6 +238,13 @@ export declare interface ChartProps<T> {
      fall back to English. German: `GERMAN_CHARTS_WORDING` from
      `@umriss-ui/charts/wording/de`. */
     wording?: Partial<ChartsWording>;
+    /** How series are told apart. `"color"` (the default): 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. */
+    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
@@ -250,10 +278,28 @@ export declare interface ChartsWording {
         value: string;
         x: string;
     }[]) => string;
+    /** The last row of a stack in the tooltip and the readout: the sum of its
+     members at the point (charts-stacking K4). */
+    stackTotal: string;
+    /** A share in a normalised stack, its number already formatted (K5). */
+    percent: (value: string) => string;
     /** The keys that walk the chart. */
     walkHelp: string;
     /** The keys that zoom and pan it - only where the chart can be zoomed. */
     zoomHelp: string;
+    /** The data table's disclosure key, closed and open (charts-alternatives
+     C1). */
+    showData: string;
+    hideData: string;
+    /** The heading of the table's x column where its axis has no `label`, and
+     of a matrix' row column where its y axis has none. */
+    positionColumn: string;
+    rowColumn: string;
+    /** The table's caption: the visible stretch it lists, both ends formatted. */
+    tableCaption: (from: string, to: string) => 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 {
@@ -264,7 +310,7 @@ declare interface CommonProps {
      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 plant screen are noise. */
+     on a dense screen are noise. */
     severity?: Severity;
     /** What the value means. A line at 90 does not say what 90 is. */
     label?: string;
@@ -383,6 +429,18 @@ export declare interface ControlLimits {
  chart then draws no line instead of bursting. */
 export declare function controlLimits(values: readonly number[], origin: ControlLimitOrigin): ControlLimits;
 
+export declare function DataTable(): ReactNode;
+
+/** One table of the data table: the series of one x axis, or one matrix. Every
+ cell is text already, in the format the tooltip writes. */
+export declare interface DataTableGroup {
+    key: string;
+    caption: string;
+    columns: readonly string[];
+    /** The first cell of each row is its x - the row's heading. */
+    rows: readonly (readonly string[])[];
+}
+
 export declare const DAY: number;
 
 export declare const DEFAULT_CHARTS_WORDING: ChartsWording;
@@ -543,7 +601,7 @@ export declare interface LineProps<T> {
      to be seen by - `always`, or `never`, not even that one. */
     markers?: "auto" | "always" | "never";
     /** Sample-and-hold: each value holds as a horizontal until the next sample
-     and jumps there - a set point, a digital signal. A gap ends the hold at
+     and jumps there - a target, a digital signal. A gap ends the hold at
      its x. The tooltip reports the sample the hold began with. */
     step?: boolean;
 }
@@ -638,70 +696,6 @@ export declare interface MatrixSeriesConfig<T = unknown> extends SeriesBase<T> {
 
 export declare const MINUTE: number;
 
-/** An operating calendar: sorted, merged intervals with the operating time
- accumulated before each one begins. An empty calendar is no calendar: it maps
- unchanged.
-
- Build once, then pass around: the mapping runs once per point, and were it to
- sort and accumulate every time, the calendar would be the most expensive
- thing about the frame. */
-export declare interface OperatingCalendar {
-    readonly intervals: readonly OperatingInterval[];
-    /** Operating time accumulated before the respective interval begins. */
-    readonly offsets: readonly number[];
-    /** The whole operating time - the axis' extent is [0, total]. */
-    readonly total: number;
-}
-
-/** Builds a calendar: sorts, merges overlapping and abutting intervals and
- throws away empty, reversed and non-finite ones. Merging is not a courtesy
- but a precondition: only over separated intervals is the reverse mapping
- unambiguous. */
-export declare function operatingCalendar(intervals: readonly OperatingInterval[]): OperatingCalendar;
-
-/** An interval in which time counts; thought of as half-open, but mappable from
- both sides at its edges: both `from` and `to` have an operating time. */
-export declare interface OperatingInterval {
-    readonly from: number;
-    readonly to: number;
-}
-
-/** Tick values for an axis extent that already stands in OPERATING TIME - the
- route the axis layout takes.
-
- The extent is trimmed to the operating time that exists (an extent widened to
- nice boundaries reaches beyond it), calculated back into wall clock time, and
- the candidates arise there. The step comes from the span in operating time and
- not from the one in wall clock time: roughly one candidate per step of
- operating time survives, and calculated from the wall clock span, four out of
- ten wanted ticks would be left. */
-export declare function operatingTicks(input: CalendarInput, from: number, to: number, count: number, offset?: number): number[];
-
-/** A tick: where it stands on the clock and where it lies on the axis. */
-export declare interface OperatingTimeTick {
-    readonly wallClock: number;
-    readonly operatingTime: number;
-}
-
-/** Ticks for an operating time axis, from an extent in WALL CLOCK TIME.
-
- The candidates arise in wall clock time on multiples of the step - hours,
- shift changes, days - whatever lies in removed time falls away, the rest is
- mapped. Never the other way round: ticks generated in operating time land in
- the middle of a shift and yield an axis labelled 14.5 and 29.0 which nobody
- can read.
-
- The offset shifts the grid; with it a local time hits its own midnight without
- this module having to know about time zones.
-
- If two candidates fall on the same operating time - the end of one shift and
- the beginning of the next - the earlier one stays: two labels on the same
- pixel would be one too many.
-
- Both times come back, because the axis needs both: the operating time to
- place the tick, the wall clock time to label it. */
-export declare function operatingTimeTicks(input: CalendarInput, from: number, to: number, step: number, offset?: number): OperatingTimeTick[];
-
 export declare interface Padding {
     top: number;
     right: number;
@@ -792,7 +786,7 @@ export declare interface Rect {
     height: number;
 }
 
-/** The removed spans between the operating intervals, for the mark in the axis
+/** The removed spans between the working intervals, for the mark in the axis
  band. A chart that takes a weekend out and does not say so claims a
  continuity it does not have. Before the first and after the last interval
  there is nothing to mark: that lies outside the axis' extent. */
@@ -802,8 +796,8 @@ export declare function removedIntervals(input: CalendarInput): RemovedSpan[];
 export declare interface RemovedSpan {
     readonly from: number;
     readonly to: number;
-    /** Operating time on which the whole span lies - a point, not a stretch. */
-    readonly operatingTime: number;
+    /** Working time on which the whole span lies - a point, not a stretch. */
+    readonly workingTime: number;
 }
 
 /** Any number of CSS colours - a token, `light-dark(…)`, `var(--…)`, a
@@ -833,6 +827,9 @@ export declare interface ResolvedTheme {
     font: string;
     fontMono: string;
     series: readonly string[];
+    /** The page is in forced colours: every colour above is a system colour, and
+     the chart encodes by marks whatever its `encoding`. */
+    forced: boolean;
 }
 
 /** Name of a rule, the way it is switched on and off in `violations`. */
@@ -951,7 +948,7 @@ export declare type SeriesKind = SeriesConfig["kind"];
 
 /** How seriously a violation weighs. Exactly two: one severity that advises and
  one that calls for action. Five severities would be five colours, and five
- colours on a control room screen are noise. Whoever needs a third
+ colours on a dense screen are noise. Whoever needs a third
  distinction sets a second limit. */
 export declare type Severity = "warning" | "alarm";
 
@@ -962,6 +959,15 @@ export declare type Side = "upper" | "lower";
  baseline has been handed down as a centre line and a control limit. */
 export declare function sigmaFromLimit(center: number, upper: number): number;
 
+/** What the two filled kinds share: a place in a stack (charts-stacking). */
+declare interface Stackable {
+    /** The stack this series stands in: series with the same id, on the same x
+     and y axis, stack in registration order (K1). */
+    stack?: string;
+    /** On any member, the whole stack sums to 100 at every x (K5). */
+    normalize?: boolean;
+}
+
 /** A band of states: each point's state holds from its x until the next
  point's. The last one holds until the latest reading of the chart - the
  last x of any visible series on the same x axis - and where the band itself
@@ -1049,6 +1055,8 @@ export declare interface TooltipPoint<T = unknown> {
     /** The point's x value on its own x axis - with several x axes it can
      differ from the hit's. */
     xValue: number;
+    /** The point's y value; in a stack its own value, not its top - in a
+     normalised stack its share in percent. */
     yValue: number;
     datum: T;
     index: number;
@@ -1077,7 +1085,15 @@ export declare interface TooltipProps<T> {
     render?: (hit: TooltipHit<T>) => ReactNode;
 }
 
-/** Wall clock time → operating time.
+/** Working time → wall clock time; outside [0, total] there is none.
+
+ At a seam - the end of an interval which is at the same time the beginning of
+ the next - the beginning of the next comes out: from there time counts again,
+ and a pointer aiming there aims at the coming interval. Only the end of the last
+ interval has no next and comes back as itself. */
+export declare function toWallClock(workingTime: number, input: CalendarInput): number;
+
+/** Wall clock time → working time.
 
  A point in a removed interval is a gap and becomes `NaN` - the encoding every
  gap of this library already uses, and the drawing loop breaks the mark at it
@@ -1087,30 +1103,22 @@ export declare interface TooltipProps<T> {
  before the first and after the last interval.
 
  The end of one interval and the beginning of the next fall on the same value:
- in operating time they are neighbours, and the line between two points on
+ in working time they are neighbours, and the line between two points on
  either side is drawn. That is not a lie but the whole purpose of the axis; the
  mark in the axis band tells the reader that time was taken out there. */
-export declare function toOperatingTime(wallClock: number, input: CalendarInput): number;
+export declare function toWorkingTime(wallClock: number, input: CalendarInput): number;
 
-/** Wall clock time → operating time, but without NaN: whatever lies in removed
+/** Wall clock time → working time, but without NaN: whatever lies in removed
  time falls onto the seam that this span collapses onto anyway; whatever lies
  before the first or after the last interval onto 0 or onto the whole
- operating time respectively.
+ working time respectively.
 
  Why this exists: the materialised x values must stay ascending. Binary search
  - for a hit as for a segment boundary - assumes that, and every comparison
  with NaN is false, so that a search over a block of NaN silently lands on the
  wrong point. The clamped value is a POSITION, not a statement: the point
  itself is carried as a gap and is never drawn and never hit. */
-export declare function toOperatingTimeClamped(wallClock: number, input: CalendarInput): number;
-
-/** Operating time → wall clock time; outside [0, total] there is none.
-
- At a seam - the end of an interval which is at the same time the beginning of
- the next - the beginning of the next comes out: from there time counts again,
- and a pointer aiming there aims at the coming shift. Only the end of the last
- interval has no next and comes back as itself. */
-export declare function toWallClock(operatingTime: number, input: CalendarInput): number;
+export declare function toWorkingTimeClamped(wallClock: number, input: CalendarInput): number;
 
 /** What a value is. Four outcomes, not three.
 
@@ -1140,6 +1148,70 @@ export declare interface Violation {
  listed beside the chart as well as marked on it. */
 export declare function violations(values: readonly number[], limits: ControlLimits, options?: Partial<RuleOptions>): Violation[];
 
+/** A working calendar: sorted, merged intervals with the working time
+ accumulated before each one begins. An empty calendar is no calendar: it maps
+ unchanged.
+
+ Build once, then pass around: the mapping runs once per point, and were it to
+ sort and accumulate every time, the calendar would be the most expensive
+ thing about the frame. */
+export declare interface WorkingCalendar {
+    readonly intervals: readonly WorkingInterval[];
+    /** Working time accumulated before the respective interval begins. */
+    readonly offsets: readonly number[];
+    /** The whole working time - the axis' extent is [0, total]. */
+    readonly total: number;
+}
+
+/** Builds a calendar: sorts, merges overlapping and abutting intervals and
+ throws away empty, reversed and non-finite ones. Merging is not a courtesy
+ but a precondition: only over separated intervals is the reverse mapping
+ unambiguous. */
+export declare function workingCalendar(intervals: readonly WorkingInterval[]): WorkingCalendar;
+
+/** An interval in which time counts; thought of as half-open, but mappable from
+ both sides at its edges: both `from` and `to` have a working time. */
+export declare interface WorkingInterval {
+    readonly from: number;
+    readonly to: number;
+}
+
+/** Tick values for an axis extent that already stands in WORKING TIME - the
+ route the axis layout takes.
+
+ The extent is trimmed to the working time that exists (an extent widened to
+ nice boundaries reaches beyond it), calculated back into wall clock time, and
+ the candidates arise there. The step comes from the span in working time and
+ not from the one in wall clock time: roughly one candidate per step of
+ working time survives, and calculated from the wall clock span, four out of
+ ten wanted ticks would be left. */
+export declare function workingTicks(input: CalendarInput, from: number, to: number, count: number, offset?: number): number[];
+
+/** A tick: where it stands on the clock and where it lies on the axis. */
+export declare interface WorkingTimeTick {
+    readonly wallClock: number;
+    readonly workingTime: number;
+}
+
+/** Ticks for a working time axis, from an extent in WALL CLOCK TIME.
+
+ The candidates arise in wall clock time on multiples of the step - hours,
+ interval changes, days - whatever lies in removed time falls away, the rest is
+ mapped. Never the other way round: ticks generated in working time land in
+ the middle of an interval and yield an axis labelled 14.5 and 29.0 which nobody
+ can read.
+
+ The offset shifts the grid; with it a local time hits its own midnight without
+ this module having to know about time zones.
+
+ If two candidates fall on the same working time - the end of one interval and
+ the beginning of the next - the earlier one stays: two labels on the same
+ pixel would be one too many.
+
+ Both times come back, because the axis needs both: the working time to
+ place the tick, the wall clock time to label it. */
+export declare function workingTimeTicks(input: CalendarInput, from: number, to: number, step: number, offset?: number): WorkingTimeTick[];
+
 export declare function XAxis<T>(props: XAxisProps<T>): null;
 
 export declare interface XAxisProps<T> extends CommonProps_2<T> {
@@ -1157,11 +1229,11 @@ export declare interface XAxisProps<T> extends CommonProps_2<T> {
      readings lie less than a minute apart. Another language is a `tickFormat`,
      which is handed the instant. `calendar` implies it. */
     time?: boolean;
-    /** Operating calendar: the intervals in which time counts. With it the axis
-     stands in operating time - weekends and night shifts are out, and every
+    /** Working calendar: the intervals in which time counts. With it the axis
+     stands in working time - nights and weekends are out, and every
      removed span gets a break mark. The scale stays affine; the mapping happens
      in materialisation (ADR-0001). */
-    calendar?: readonly OperatingInterval[];
+    calendar?: readonly WorkingInterval[];
     /** Zoom and pan, controlled: Ctrl or ⌘ with the wheel - and a pinch - zoom
      around the pointer, a drag, a horizontal wheel or Shift with the wheel pan,
      a double click proposes the whole data range. Each proposes a domain in

package/dist/wording/de.js

@@ -1,13 +1,21 @@
-const t = {
+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, i) => `${e} von ${n} bis ${i}.`,
-  readout: (e, n) => [`${e}.`, ...n.map((i) => `${i.name} ${i.value}${i.x === "" ? "" : ` bei ${i.x}`}.`)].join(" "),
+  seriesExtent: (e, n, t) => `${e} von ${n} bis ${t}.`,
+  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.",
-  zoomHelp: "Plus und Minus zoomen, Umschalt mit Pfeil links oder rechts verschiebt, 0 zeigt alles."
+  zoomHelp: "Plus und Minus zoomen, Umschalt mit Pfeil links oder rechts verschiebt, 0 zeigt alles.",
+  showData: "Daten zeigen",
+  hideData: "Daten verbergen",
+  positionColumn: "Position",
+  rowColumn: "Zeile",
+  tableCaption: (e, n) => `Werte von ${e} bis ${n}.`,
+  downsampled: (e) => `Ausgedünnt aus ${e.toLocaleString("de-DE")} Messwerten: erster, kleinster, größter und letzter Wert je Abschnitt.`
 };
 export {
-  t as GERMAN_CHARTS_WORDING
+  i as GERMAN_CHARTS_WORDING
 };