API index

ControlChart

ControlChart – Centre line, control limits and the rule violations of a process (an SPC or Shewhart chart). Reach for it to see a process drift before it leaves its specification.

Used on Scenarios and ControlChart.

DataTable

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.

function DataTable(): ReactNode;

Used on Chart, BoxPlot and Tooltip.

Legend

Legend – What the colours mean (a key), and a switch for every series: a click hides it and shows it again, a double click shows only it (a solo).

Used on Scenarios, Chart, Axis, View, Line, Area, Bar, Scatter, BoxPlot, StateBand, LimitLine, Pareto, Tooltip, Legend and Benchmark.

LimitBand

LimitLine – A limit drawn as a band between two values of an axis - a tolerance or a zone. Otherwise a LimitLine.

Used on Scenarios, Chart, LimitLine and Tooltip.

LimitLine

LimitLine – The limits a course is read against (a threshold, a reference line): a line above the series, a band beneath them. Reach for it for objectives, budgets and alert levels.

Used on Scenarios, Chart, Scatter, BoxPlot, LimitLine, ControlChart, Pareto and Tooltip.

Tooltip

Tooltip – What a hover reports (a hover card), and the values as a table for a reader who wants them all at once.

Used on Scenarios, Installation, Chart, Axis, Zoom and pan, View, Line, Area, Bar, Scatter, BoxPlot, StateBand, Matrix, LimitLine, ControlChart, Pareto, Tooltip, Legend and Benchmark.

useChart

A chart over your rows: the parts it returns are typed at your row, so that a field name in value is checked by the compiler.

• rows – The rows every series reads that brings no data of its own.
• options – The view to start from and the handler of its changes.
• Returns Chart, XAxis, YAxis and every series kind - each keeps its identity over the renders -, the view, its domains and hidden, and the setters that change them.

function useChart<Z>(rows: readonly Z[], options?: ChartOptions<Z>): ChartParts<Z>;

Used on Scenarios, Installation, Chart, Axis, Zoom and pan, View, Line, Area, Bar, Scatter, BoxPlot, StateBand, Matrix, LimitLine, ControlChart, Pareto, Tooltip, Legend and Benchmark.

assess

What the value is, given the limit set. A pure function of the two. A missing or non-finite value yields unknown - and nothing else: the deviation of a value nobody has is unknown to everybody too. A bound is violated when the value lies beyond it, not when it lies on it. A value exactly on the upper bound is in order. That is decided once here (ADR-0006), so that two building blocks on the same screen do not disagree about the edge. Where several bounds are violated the most severe wins; among equally severe ones the one the value lies furthest beyond. Under a tie in both, the one named first. No hysteresis: that would need the previous state, and a function of one value has none. Exactly that is the property which makes this module safe to duplicate.

function assess(value: number | null | undefined, set?: LimitSet): Assessment;

bin

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.

function bin(values: readonly (number | null | undefined)[], options?: BinOptions): Bin[];
function bin<T>(rows: readonly T[], value: (row: T) => number | null | undefined, options?: BinOptions): Bin[];

Used on Bar.

breaks

The breaks in working time that lie within the extent [from, to] - what the axis must mark, in domain units.

function breaks(input: CalendarInput, from: number, to: number): number[];

calendarFrom

Calendar from an input - a built calendar is passed straight through, a raw list is built once and remembered.

function calendarFrom(input: CalendarInput): WorkingCalendar;

controlLimits

Centre line and control limits. Either given or calculated from exactly the named reference window - never from the whole series and never from the visible excerpt. Gaps (NaN) count neither in the centre line nor in the moving range. A window without values yields NaN limits, not an error: the chart then draws no line instead of bursting.

function controlLimits(values: readonly number[], origin: ControlLimitOrigin): ControlLimits;

Used on Scenarios, LimitLine and ControlChart.

invalidateTheme

Explicit invalidation: devalue the cache, every living chart reads anew and redraws.

function invalidateTheme(): void;

localOffset

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.

function localOffset(instant: number): number;

pareto

Sorts descending, accumulates, collects the tail and finds the cutoff crossing. Ties keep the input order - explicitly through the input index, not in reliance on a stable sort - so that two reasons with the same count do not swap places between two frames. The remainder stands last, independently of its value. Two hundred small reasons regularly yield a remainder larger than the third real bar; sorted into place, the chart would claim there is a fault reason called "other" which is the third biggest problem.

function pareto(items: readonly ParetoItem[], options?: ParetoSettings): ParetoResult;

Used on Pareto.

removedIntervals

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.

function removedIntervals(input: CalendarInput): RemovedSpan[];

resolveColours

Any number of CSS colours - a token, light-dark(…), var(--…), a literal - resolved to values a canvas can draw, in the scheme that applies at root. The same probe resolveTheme uses, for a canvas of a neighbouring package (ADR-0022): the schedule draws its subtasks with the colours of

function resolveColours<K extends string>(root: Element, colours: Readonly<Record<K, string>>): Record<K, string>;

subscribeTheme

Subscribe to theme invalidations - a switch of color-scheme on the document, the system's preference, or invalidateTheme(). The scenes of the charts use it, and so does any canvas that resolved its colours with resolveColours. Returns the unsubscribe.

function subscribeTheme(notify: () => void): () => void;

timeStep

Step for tick candidates in wall clock time, at an intended count. Rounded up to the next readable step, so that no more ticks arise than wanted. Above the day steps it continues in whole days.

function timeStep(span: number, count: number): number;

toWallClock

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.

function toWallClock(workingTime: number, input: CalendarInput): number;

toWorkingTimeClamped

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 working time respectively. The materialised x values must stay ascending: binary search assumes it, and a search over 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.

function toWorkingTimeClamped(wallClock: number, input: CalendarInput): number;

verdictWeight

How heavily a verdict weighs, as a number - for sorting and comparing, as when a matrix is to bring its worst cell to the top. It stands here so that the order is not reinvented at every call site.

function verdictWeight(verdict: Verdict): number;

violatedIndices

All violated indices, ascending and free of duplicates - the scatter drawn beside the line.

function violatedIndices(found: readonly Violation[]): number[];

violations

The rules switched on, each with its indices. Rules without hits do not appear in the list. The indices are data, not merely marks: they can be listed beside the chart as well as marked on it.

function violations(values: readonly number[], limits: ControlLimits, options?: Partial<RuleOptions>): Violation[];

Used on Scenarios and ControlChart.

workingCalendar

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.

function workingCalendar(intervals: readonly WorkingInterval[]): WorkingCalendar;

Used on Axis.

workingTimeTicks

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.

function workingTimeTicks(input: CalendarInput, from: number, to: number, step: number, offset?: number): WorkingTimeTick[];

zones

The faintly drawn zone lines. Rule 4 is about the two-sigma zone, and a reader cannot check it against a chart that does not show it.

function zones(limits: ControlLimits, multiples?: readonly number[]): Zone[];

Used on ControlChart.

DAY

One day of 24 hours in milliseconds; across a clock change a calendar day is an hour longer or shorter.

const DAY: number;

Used on Scenarios, Chart, Axis, Zoom and pan, StateBand, Tooltip and Benchmark.

DEFAULT_CHARTS_WORDING

The instance shipped by default. English; German is GERMAN_CHARTS_WORDING in @umriss-ui/charts/wording/de. A chart takes its own through wording.

Every entry, with its value, stands in the table Charts wording on core's Language page.

const DEFAULT_CHARTS_WORDING: ChartsWording;

DEFAULT_GRADIENT

Default gradient: a sequential set, light to dark, so that it stays readable as an order of lightness even without colour. It is a default, not a restriction - whoever has a scale of their own names it.

const DEFAULT_GRADIENT: readonly string[];

Used on Matrix.

HOUR

One hour in milliseconds.

const HOUR: number;

Used on Chart, Axis, Zoom and pan, Area, BoxPlot, Tooltip and Benchmark.

LinearScale

The affine mapping from a domain onto a pixel range, and back; the scale every axis of the library uses.

class LinearScale implements Scale {
    readonly domain: readonly [number, number];
    readonly range: readonly [number, number];
    /** Pre-computed line equation px = v·m + b - the draw loop uses it directly. */
    readonly m: number;
    readonly b: number;
    constructor(domain: readonly [number, number], range: readonly [number, number]);
    toPx(v: number): number;
    fromPx(px: number): number;
    ticks(n: number): number[];
}

MINUTE

One minute in milliseconds.

const MINUTE: number;

Used on Scenarios, Installation, Chart, Axis, Zoom and pan, View, Line, Area, Scatter, BoxPlot, StateBand, LimitLine, Tooltip, Legend and Benchmark.

SECOND

One second in milliseconds, the unit of a time axis.

const SECOND = 1000;

AreaProps

Its table stands on Area.

BarProps

Its table stands on Bar.

BoxPlotProps

Its table stands on BoxPlot.

ChartOptions

Its table stands on Zoom and pan.

Used on Chart.

Used on Benchmark.

ChartProps

Its table stands on Chart.

ChartView

Its table stands on View.

Used on Zoom and pan and View.

ControlChartProps

Its table stands on ControlChart.

LegendProps

Its table stands on Legend.

LimitBandProps

Its table stands on LimitLine.

LimitLineProps

Its table stands on LimitLine.

Used on Scenarios.

LineProps

Its table stands on Line.

MatrixProps

Its table stands on Matrix.

type RuleName = "outlier" | "run" | "trend" | "twoOfThree";

Used on Scenarios and ControlChart.

ScatterProps

Its table stands on Scatter.

StateBandProps

Its table stands on StateBand.

Used on Axis and Tooltip.

TooltipProps

Its table stands on Tooltip.

Used on ControlChart.

XAxisProps

Its table stands on Axis.

YAxisProps

Its table stands on Axis.

Used on Scenarios, Axis, LimitLine and ControlChart.

Used on Zoom and pan.

GERMAN_CHARTS_WORDING

The German instance, for a chart's wording. Complete, because it is typed ChartsWording.

Every entry, with its value, stands in the table Charts wording on core's Language page.

const GERMAN_CHARTS_WORDING: ChartsWording;

Used on Installation and Chart.