@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/math/range.d.ts

@@ -0,0 +1,98 @@
+/** Axis ranging for data plotted from raw values rather than a function. */
+import type { Range, ScaleName, TimeZone } from "@sophistry/core/geometry";
+/** @category Math */
+export interface AutoRangeOptions {
+    /** Roughly how many ticks the rounded range should offer. @default 5 */
+    targetTicks?: number;
+}
+/**
+ * Rounds a data span out to a whole number of nice steps, always including
+ * zero (an axis starting at 90 exaggerates differences). For charts whose
+ * caller gave no explicit range.
+ *
+ * @param values - The data the axis must cover; non-finite entries are ignored.
+ * @returns `[min, max, step]` containing 0; `[0, 1, 1]` when there is no spread.
+ * @category Math & helpers
+ */
+export declare function autoRange(values: readonly number[], options?: AutoRangeOptions): Range;
+/**
+ * Options for {@link fitRange}.
+ *
+ * @category Math & helpers
+ */
+export interface FitRangeOptions {
+    /**
+     * The scale the range is for, which decides what "round" means: a 1-2-5
+     * step for linear, sqrt and symlog, whole decades for log, calendar units
+     * for time and utc.
+     * @default "linear"
+     */
+    type?: ScaleName;
+    /**
+     * Stretch the range to include zero, for marks whose length encodes value
+     * (bars, areas, histograms). Ignored by log and time scales.
+     * @default false
+     */
+    zero?: boolean;
+    /**
+     * Round the ends out to tick values. `false` keeps the data's ends;
+     * `"tight"` rounds an end out only when the next tick is within a quarter
+     * step of the data (weeks 0–11 fit `[0, 11]`, not `[0, 15]`).
+     * @default true
+     */
+    nice?: boolean | "tight";
+    /** Roughly how many ticks the rounded range should offer. @default 5 */
+    targetTicks?: number;
+    /** Log base, when `type` is `"log"`. @default 10 */
+    base?: number;
+    /**
+     * The zone whose calendar a time range rounds to: an IANA name, `"UTC"` or
+     * `"local"`. Omitted, `"utc"` rounds in UTC and `"time"` in local time.
+     */
+    timeZone?: TimeZone;
+    /**
+     * Pad the data's extent by this fraction of its span on each side before
+     * rounding; a side pinned at zero by `zero` stays there. Ignored by log.
+     * @default 0
+     */
+    margin?: number;
+}
+/**
+ * The range an axis should span to show `values`: their extent, stretched to
+ * zero if asked, rounded out to ticks for the scale type. This is how
+ * `<Chart>` fits its axes. Non-finite values (and non-positive ones on a
+ * log scale) are ignored; one value or none still gets a usable span.
+ *
+ * @returns `[min, max, step]` on a nice linear-family range, `[min, max]` otherwise.
+ * @category Math & helpers
+ */
+export declare function fitRange(values: readonly number[], options?: FitRangeOptions): Range;
+/**
+ * Options for {@link alignedRange}.
+ *
+ * @category Math & helpers
+ */
+export interface AlignedRangeOptions {
+    /** Keep zero in range (bars, areas). @default false */
+    zero?: boolean;
+    /**
+     * Pad the data's extent by this fraction of its span first, as {@link FitRangeOptions.margin}.
+     * @default 0
+     */
+    margin?: number;
+    /** The two axes run opposite ways (one is reversed). @default false */
+    opposite?: boolean;
+}
+/**
+ * A secondary axis range whose ticks fall exactly where the primary's do,
+ * so one grid serves both: the same number of tick intervals, with the
+ * smallest nice step (1, 2, 2.5 or 5 × 10ⁿ) that covers `values`. Linear
+ * axes only.
+ *
+ * @param primary - The primary axis's range, `[min, max, step?]` (either order).
+ * @param primaryTicks - The primary's major tick values, evenly spaced (at least two).
+ * @param values - The data the secondary axis must show.
+ * @returns `[min, max, step]` ascending, or undefined when the primary has fewer than two ticks.
+ * @category Math & helpers
+ */
+export declare function alignedRange(primary: Range, primaryTicks: readonly number[], values: readonly number[], options?: AlignedRangeOptions): Range | undefined;

package/dist/math/regression.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Regression and intervals: least-squares polynomial fits with a confidence
+ * band for the fitted mean, LOESS smoothing (optionally robust, with a band),
+ * and the t-based confidence interval of a sample mean.
+ */
+/** @category Math */
+export interface RegressionPoint {
+    x: number;
+    /** The fitted value. */
+    y: number;
+    /** Lower end of the confidence band for the fitted mean (`y` when there is no band). */
+    low: number;
+    /** Upper end of the band. */
+    high: number;
+}
+/** @category Math */
+export interface RegressionOptions {
+    /** Polynomial degree: 1 is a straight line, 2 a parabola, ... @default 1 */
+    degree?: number;
+    /** Confidence level of the band around the fitted mean, 0..1; 0 draws no band. @default 0.95 */
+    level?: number;
+    /** How many evenly spaced x positions to evaluate the fit at. @default 50 */
+    samples?: number;
+    /** The x span to evaluate over. Defaults to the data's x extent. */
+    domain?: [number, number];
+}
+/**
+ * A least-squares polynomial fit of `ys` on `xs`, with the confidence band
+ * of the fitted mean `ŷ ± t(level, n − p) · s · √(x₀ᵀ (XᵀX)⁻¹ x₀)`. Pairs
+ * with a non-finite member are dropped; with no more points than
+ * coefficients the result is `[]`.
+ *
+ * @param ys - Responses, paired with `xs` by index.
+ * @returns Points ascending in x.
+ * @category Math & helpers
+ */
+export declare function regression(xs: readonly number[], ys: readonly number[], options?: RegressionOptions): RegressionPoint[];
+/** @category Math */
+export interface LoessOptions {
+    /** Fraction of the points each local fit uses, 0..1. @default 0.3 */
+    bandwidth?: number;
+    /** How many evenly spaced x positions to evaluate at. @default 50 */
+    samples?: number;
+    /**
+     * Robustness iterations: each re-weights points by their residual (bisquare)
+     * and refits, so outliers stop pulling the smooth; 2 is the usual choice.
+     * @default 0
+     */
+    iterations?: number;
+}
+/** @category Math */
+export interface LoessBandOptions extends LoessOptions {
+    /** Confidence level of the band around the smooth, 0..1; 0 draws no band. @default 0.95 */
+    level?: number;
+}
+/**
+ * LOESS: a locally weighted linear fit at each sample over the nearest
+ * `bandwidth` fraction of the points (tricube weights), optionally robust to
+ * outliers. {@link loessBand} adds a confidence band.
+ *
+ * @param ys - Responses, paired with `xs` by index; non-finite pairs dropped.
+ * @returns Points ascending in x across the data's extent; `[]` with fewer than 2 points.
+ * @category Math & helpers
+ */
+export declare function loess(xs: readonly number[], ys: readonly number[], options?: LoessOptions): {
+    x: number;
+    y: number;
+}[];
+/**
+ * {@link loess} with a confidence band for the smooth:
+ * `ŷ ± t(level, δ₁) · σ̂ · ‖l(x₀)‖`, with `σ̂² = RSS / δ₁` and
+ * `δ₁ = tr((I − L)ᵀ(I − L))` over the smoother matrix `L`. Robustness
+ * weights are folded in, so ignored outliers don't widen the band.
+ *
+ * @param ys - Responses, paired with `xs` by index; non-finite pairs dropped.
+ * @returns Points ascending in x across the data's extent; `[]` with fewer
+ *   than 2 points. With 3 points or fewer, or an interpolating smoother, no
+ *   band (`low === high === y`).
+ * @category Math & helpers
+ */
+export declare function loessBand(xs: readonly number[], ys: readonly number[], options?: LoessBandOptions): RegressionPoint[];
+/** @category Math */
+export interface MeanInterval {
+    mean: number;
+    low: number;
+    high: number;
+    /** How many finite values the interval is over. */
+    n: number;
+}
+/**
+ * The mean of `values` with an interval: `"ci"` the t-based confidence
+ * interval at `level`, `"se"` ± one standard error, `"sd"` ± one sample
+ * standard deviation. Non-finite values are dropped; with none every field
+ * is `NaN` and `n` is 0.
+ *
+ * @param interval - Defaults to `"ci"`.
+ * @param level - Confidence level for `"ci"`, 0..1. Defaults to 0.95.
+ * @category Math & helpers
+ */
+export declare function meanInterval(values: readonly number[], interval?: "ci" | "se" | "sd", level?: number): MeanInterval;
+/**
+ * The `p` quantile of Student's t distribution with `df` degrees of
+ * freedom: exact for 1 and 2, a Cornish–Fisher expansion (within ~0.1%)
+ * above.
+ *
+ * @returns The quantile; `NaN` outside the domain.
+ * @category Math & helpers
+ */
+export declare function studentT(p: number, df: number): number;

package/dist/math/reveal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Reveals that follow the independent variable: geometry cut off at an x
+ * that sweeps left to right at a constant rate as `progress` runs 0 → 1, so
+ * reveal progress reads as progress along x. Works on points in scene units.
+ */
+import type { Bounds, Point } from "@sophistry/core/geometry";
+/**
+ * The `[min, max]` x of every point in `polylines`, or undefined when there
+ * are none (or none finite).
+ *
+ * @category Math & helpers
+ */
+export declare function xExtent(polylines: readonly (readonly Point[])[]): [number, number] | undefined;
+/**
+ * The parts of an open polyline at or left of `cutoff`; a line doubling back
+ * over the cut comes out in several pieces.
+ *
+ * @returns The kept pieces; pieces of fewer than two points are dropped.
+ * @category Math & helpers
+ */
+export declare function clipPolylineToX(points: readonly Point[], cutoff: number): Point[][];
+/**
+ * A closed ring cut to the half-plane `x <= cutoff`, so a filled area
+ * reveals with a straight front. A ring given closed comes back closed.
+ *
+ * @returns The cut ring, or `[]` when nothing is left of the cut.
+ * @category Math & helpers
+ */
+export declare function clipRingToX(ring: readonly Point[], cutoff: number): Point[];
+/**
+ * Where the cut stands at `progress`: linear across `extent`. Ease the
+ * track driving `progress` for an eased reveal.
+ *
+ * @category Math & helpers
+ */
+export declare function revealCutoff(progress: number, extent: readonly [number, number]): number;
+/**
+ * Open polylines revealed left to right over their joint x extent, all cut
+ * at the same x so lines drawn together advance together.
+ *
+ * @param progress - 0..1.
+ * @category Math & helpers
+ */
+export declare function revealPolylinesAlongX(polylines: readonly (readonly Point[])[], progress: number): Point[][];
+/**
+ * Closed rings (filled areas) revealed left to right over their joint x extent.
+ *
+ * @param progress - 0..1.
+ * @returns The visible rings; a ring entirely right of the cut is dropped.
+ * @category Math & helpers
+ */
+export declare function revealRingsAlongX(rings: readonly (readonly Point[])[], progress: number): Point[][];
+/**
+ * The clip box revealing filled regions left to right: everything left of
+ * the reached x, with room around so only the front cuts. Unlike a cut, it
+ * leaves the geometry whole (no stroked edge along the front).
+ *
+ * @param polylines - The geometry being revealed, in scene units.
+ * @param progress - 0..1.
+ * @returns A box for `<Group clip>`, or undefined at `progress >= 1` or with no geometry.
+ * @category Math & helpers
+ */
+export declare function revealClipAlongX(polylines: readonly (readonly Point[])[], progress: number): Bounds | undefined;

package/dist/math/sankey.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Sankey layout: nodes in columns, links as ribbons as wide as their value.
+ * Coordinates are in a `[0, width] × [0, height]` box with **y pointing
+ * down**: `y0` is a node's top edge. A y-up renderer maps `y` to `top - y`.
+ */
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * A node id: whatever the links name their endpoints with.
+ *
+ * @category Math & helpers
+ */
+export type SankeyId = string | number;
+/**
+ * One link of the input graph.
+ *
+ * @category Math & helpers
+ */
+export interface SankeyLinkInput {
+    source: SankeyId;
+    target: SankeyId;
+    /** The flow's size; non-finite and negative values count as 0. */
+    value: number;
+}
+/**
+ * How nodes are assigned to columns: `"justify"` by longest path from a
+ * source with sinks in the last column; `"left"` by longest path from a
+ * source; `"right"` by longest path to a sink; `"center"` like `"left"` but
+ * each source one column before its nearest target.
+ *
+ * @category Math & helpers
+ */
+export type SankeyAlign = "justify" | "left" | "right" | "center";
+/**
+ * Options for {@link sankeyLayout}.
+ *
+ * @category Math & helpers
+ */
+export interface SankeyOptions {
+    /**
+     * Node ids in stacking and colour order; ids named only by links are appended. Defaults to the
+     * link endpoints in first-seen order.
+     */
+    nodes?: readonly SankeyId[];
+    /** Width of the layout box. @default 1 */
+    width?: number;
+    /** Height of the layout box. @default 1 */
+    height?: number;
+    /** Width of each node bar. Defaults to 2.4% of `width`. */
+    nodeWidth?: number;
+    /**
+     * Vertical gap between nodes in a column, shrunk if a tall column can't fit it. Defaults to 8%
+     * of `height`.
+     */
+    nodePadding?: number;
+    /** Column assignment; see {@link SankeyAlign}. @default "justify" */
+    align?: SankeyAlign;
+    /** Relaxation passes pulling connected nodes level; 0 keeps the initial stacking. @default 6 */
+    iterations?: number;
+}
+/**
+ * One laid-out node. `y0 < y1` (y points down).
+ *
+ * @category Math & helpers
+ */
+export interface SankeyNode {
+    id: SankeyId;
+    /** Position in the node order (first-seen, or `options.nodes`). */
+    index: number;
+    /** `max(Σ incoming, Σ outgoing)`. */
+    value: number;
+    /** The column the node is drawn in, after `align`; 0 is the leftmost. */
+    depth: number;
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+}
+/**
+ * One laid-out link. `y0`/`y1` are the ribbon's centreline at its source and
+ * target ends; its edges are `width / 2` either side.
+ *
+ * @category Math & helpers
+ */
+export interface SankeyLink {
+    /** Index of the source node in {@link SankeyLayout.nodes}. */
+    source: number;
+    /** Index of the target node in {@link SankeyLayout.nodes}. */
+    target: number;
+    /** The value used (non-finite and negative inputs read as 0). */
+    value: number;
+    /** Centreline y where the link leaves its source. */
+    y0: number;
+    /** Centreline y where the link enters its target. */
+    y1: number;
+    /** `value × ky`: the ribbon's thickness. */
+    width: number;
+    /** Position of the link in the input. */
+    index: number;
+}
+/**
+ * The result of {@link sankeyLayout}.
+ *
+ * @category Math & helpers
+ */
+export interface SankeyLayout {
+    nodes: SankeyNode[];
+    /** In input order. */
+    links: SankeyLink[];
+    /** Number of columns. */
+    columns: number;
+    /** The vertical scale: layout units per unit of value. */
+    ky: number;
+}
+/**
+ * Lays out a Sankey diagram: each node gets a column and a height
+ * proportional to its value (`max(Σ in, Σ out)`), each link its attachment
+ * points. Relaxation passes pull nodes toward their neighbours, and links are
+ * ordered at each node so ribbons don't cross there. Deterministic.
+ *
+ * @returns Nodes and links in a `[0, width] × [0, height]` box, y down.
+ * @throws {Error} If the graph has a cycle (a self-loop included).
+ * @throws {Error} If `options.nodes` is given and a link names an id not in it.
+ * @category Math & helpers
+ */
+export declare function sankeyLayout(links: readonly SankeyLinkInput[], options?: SankeyOptions): SankeyLayout;
+/**
+ * Options for {@link sankeyRibbon}.
+ *
+ * @category Math & helpers
+ */
+export interface SankeyRibbonOptions {
+    /** Points sampled along each edge. @default 24 */
+    samples?: number;
+    /**
+     * How much of the ribbon to keep from the source end, 0..1, for a
+     * left-to-right reveal; the cut is vertical.
+     * @default 1
+     */
+    t?: number;
+}
+/**
+ * The outline of one link's ribbon as an open polygon: a cubic Bézier with
+ * horizontal end tangents along the top edge, the same curve `width` lower
+ * traced back. Coordinates are in the inputs' space.
+ *
+ * @param x0 - Where the ribbon leaves its source (the source node's `x1`).
+ * @param y0 - Centreline y at the source end (the link's `y0`).
+ * @param x1 - Where the ribbon enters its target (the target node's `x0`).
+ * @param y1 - Centreline y at the target end (the link's `y1`).
+ * @param width - The ribbon's thickness (the link's `width`).
+ * @returns `2 × samples` points, top edge forward then bottom edge back; empty when `t` is 0.
+ * @category Math & helpers
+ */
+export declare function sankeyRibbon(x0: number, y0: number, x1: number, y1: number, width: number, options?: SankeyRibbonOptions): Point[];

package/dist/math/scatter.d.ts

@@ -0,0 +1,14 @@
+/** `scatter(x, y)` — one marker per finite `(x, y)` pair. */
+/** @category Math */
+export interface ScatterPoint {
+    /** Index into the input `xs`/`ys`, keeping `sizes`/`colors` aligned past dropped pairs. */
+    index: number;
+    x: number;
+    y: number;
+}
+/**
+ * The finite `(x, y)` pairs, paired by index, each keeping its index.
+ *
+ * @category Math & helpers
+ */
+export declare function scatterPoints(xs: readonly number[], ys: readonly number[]): ScatterPoint[];

package/dist/math/shared/binning.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Equal-width bin math shared by `histogramBins` (1D) and `histogram2d` (2D):
+ * both bin a continuous range into `n` buckets with the same right-inclusive
+ * last bin and the same degenerate-range widening.
+ */
+/**
+ * How many bins to use and where the last edge lands: an explicit `count`
+ * wins; else a positive `step` is the bin width (`max` extended to a whole
+ * step, with float tolerance so `[0, 0.3, 0.1]` is 3 bins); else
+ * `fallbackCount` bins span `[min, max]`.
+ *
+ * @returns The bin count and the (possibly extended) upper bound.
+ */
+export declare function resolveBinning(min: number, max: number, count: number | undefined, step: number | undefined, fallbackCount: number): {
+    n: number;
+    max: number;
+};
+/** Widens a degenerate `[min, max]` (`min === max`) symmetrically to a small nonzero span. */
+export declare function widenDegenerate(min: number, max: number): [number, number];
+/** Bin index for `value` within `[min, max]` split into `bins` equal buckets, the last bin right-inclusive. */
+export declare function binIndex(value: number, min: number, max: number, bins: number): number;
+/** `n + 1` evenly spaced edges from `min` to `max`, split into `n` bins. */
+export declare function binEdges(min: number, max: number, n: number): number[];

package/dist/math/shared/gridCells.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Grid-cell assembly shared by `imshow` and `pcolormesh`: a value grid laid
+ * onto data-space rectangles from a caller-supplied `rectFor`, ragged rows
+ * tolerated, `min`/`max` over finite values (`[0, 1]` when none).
+ */
+/**
+ * One grid cell: its `(row, column)` and its data-space rectangle.
+ *
+ * @category Math & helpers
+ */
+export interface GridCell {
+    row: number;
+    column: number;
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+    value: number;
+}
+/**
+ * The full gridded result.
+ *
+ * @category Math & helpers
+ */
+export interface GridResult {
+    cells: GridCell[];
+    /** Smallest finite value in the grid, or 0 if there were none. */
+    min: number;
+    /** Largest finite value in the grid, or 1 if there were none. */
+    max: number;
+    nrows: number;
+    ncols: number;
+}
+/** Longest row length across `Z` (ragged rows have fewer cells). */
+export declare function gridNcols(Z: readonly (readonly number[])[]): number;
+/** One `GridCell` per entry of `Z`, positioned by `rectFor(row, col)`, and the finite `min`/`max` (`[0, 1]` when none). */
+export declare function buildGridCells(Z: readonly (readonly number[])[], rectFor: (row: number, col: number) => Pick<GridCell, "x0" | "x1" | "y0" | "y1">): {
+    cells: GridCell[];
+    min: number;
+    max: number;
+};

package/dist/math/shared/gridExtent.d.ts

@@ -0,0 +1,5 @@
+/** Level resolution shared by contour lines and filled contours: explicit values, or a count spaced over the data's finite extent. */
+/** Smallest/largest finite value in a 2D grid, or `null` if it has none. */
+export declare function dataExtent(z: readonly (readonly number[])[]): [number, number] | null;
+/** Resolves `levels` (explicit values as is, or a count spaced by `evenFn`) against `z`'s extent; `[]` for a constant or all-non-finite field. */
+export declare function resolveLevels(levels: readonly number[] | number, z: readonly (readonly number[])[], evenFn: (min: number, max: number, count: number) => number[]): number[];

package/dist/math/shared/pairs.d.ts

@@ -0,0 +1,2 @@
+/** Number of index-aligned pairs two parallel arrays offer, `Math.min(xs.length, ys.length)`; the longer tail is dropped. */
+export declare function pairCount(xs: readonly unknown[], ys: readonly unknown[]): number;

package/dist/math/shared/polar.d.ts

@@ -0,0 +1,23 @@
+/** The `startAngle`/`clockwise` sweep options shared by the polar charts. */
+export { TAU } from "@sophistry/core/internal";
+/** @category Math */
+export interface PolarSweepOptions {
+    /**
+     * Radians from +x (counter-clockwise, y up) where the first slice, wedge or axis begins. The
+     * default is 12 o'clock.
+     * @default Math.PI / 2
+     */
+    startAngle?: number;
+    /** Sweep direction. @default true */
+    clockwise?: boolean;
+}
+export interface ResolvedPolarSweep {
+    startAngle: number;
+    /** `-1` for clockwise, `1` for counter-clockwise — multiply into an angular step. */
+    direction: 1 | -1;
+}
+/**
+ * Resolves `{ startAngle, clockwise }` to `{ startAngle, direction }`, filling
+ * in the shared defaults (12 o'clock, clockwise).
+ */
+export declare function resolvePolarSweep(options: PolarSweepOptions | undefined): ResolvedPolarSweep;

package/dist/math/stack.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Stacking: values sharing a position laid end to end as segments (stacked
+ * bars and areas, streamgraphs, normalized and diverging stacks). Input is
+ * one column per position, each a list of `{ series, value }` items stacked
+ * in series order, then placed by the {@link StackOffset}.
+ */
+/**
+ * How a stack is placed: `"zero"` on the baseline; `"normalize"` each
+ * column scaled to 0..1; `"center"` each column centred on zero;
+ * `"wiggle"` shifted to minimise slope change between columns (a
+ * streamgraph), centred overall.
+ *
+ * @category Math & helpers
+ */
+export type StackOffset = "zero" | "normalize" | "center" | "wiggle";
+/**
+ * Which series sits at the bottom: `"appearance"` (given or first-seen
+ * order), `"reverse"`, `"sum"` (largest on top), `"insideOut"` (the
+ * streamgraph order: earliest peaks in the middle), or an array of series
+ * indices bottom to top (unlisted series follow).
+ *
+ * @category Math & helpers
+ */
+export type StackOrder = "appearance" | "reverse" | "sum" | "insideOut" | readonly number[];
+/** @category Math */
+export interface StackColumnsOptions {
+    /** @default "zero" */
+    offset?: StackOffset;
+    /** @default "appearance" */
+    order?: StackOrder;
+    /**
+     * Stack negatives down from the baseline and positives up, as two stacks.
+     * Off, values accumulate in one running total, so a negative dips back down.
+     * @default true
+     */
+    diverging?: boolean;
+    /** Where the stack starts under `"zero"`; other offsets ignore it. @default 0 */
+    baseline?: number;
+}
+/** @category Math */
+export interface StackItem {
+    /** The item's series, 0-based; several items of one series in a column stack one after another. */
+    series: number;
+    /** Its value; a non-finite value takes no room. */
+    value: number;
+}
+/** @category Math */
+export interface StackColumnsResult {
+    /** `[y1, y2]` per item, parallel to the input: segment start (towards the baseline) and end; `[NaN, NaN]` when non-finite. */
+    spans: [number, number][][];
+    /** Series indices, bottom of the stack to top. */
+    order: number[];
+}
+/**
+ * Stacks every column's items in series order, then places each column by
+ * `offset`.
+ *
+ * @param columns - One item list per position, in axis order (only `"wiggle"` reads the order).
+ * @param seriesCount - How many series there are; items name theirs by index.
+ * @category Math & helpers
+ */
+export declare function stackColumns(columns: readonly (readonly StackItem[])[], seriesCount: number, options?: StackColumnsOptions): StackColumnsResult;
+/**
+ * Series indices bottom to top for `order`; see {@link StackOrder}.
+ *
+ * @returns Every series index once, bottom of the stack first.
+ * @category Math & helpers
+ */
+export declare function stackOrder(columns: readonly (readonly StackItem[])[], seriesCount: number, order: StackOrder): number[];

package/dist/math/stackplot.d.ts

@@ -0,0 +1,35 @@
+/** Stacked areas: parallel series stacked on a shared baseline, each band the region between consecutive running totals. */
+import type { Point } from "@sophistry/core/geometry";
+import type { StackOffset, StackOrder } from "./stack.js";
+/** @category Math */
+export interface StackedBand {
+    /** The running total *below* this series, per `x` — the band's lower edge. */
+    bottom: number[];
+    /** `bottom + series`, per `x` — the band's upper edge. */
+    top: number[];
+    /** `top`/`bottom` mapped through `fillBetweenRings`, in data coordinates. */
+    rings: Point[][];
+}
+/** @category Math */
+export interface StackPlotOptions {
+    /** The running total the first series stacks atop, under the `"zero"` offset. @default 0 */
+    baseline?: number;
+    /** Where each x's stack is placed; see {@link StackOffset}. @default "zero" */
+    offset?: StackOffset;
+    /**
+     * Which series sits at the bottom; see {@link StackOrder}. Bands are still
+     * returned in the order given.
+     * @default "appearance"
+     */
+    order?: StackOrder;
+}
+/**
+ * Stacks `series` (each parallel to `xs`) on `baseline`; band `i`'s `rings`
+ * shade the slice that series adds. Other offsets then rescale or shift each
+ * x's stack; `"wiggle"` treats `xs` as evenly spaced.
+ *
+ * @param series - One array per band; missing or non-finite entries count as 0, negatives subtract.
+ * @returns One {@link StackedBand} per series, in the order given.
+ * @category Math & helpers
+ */
+export declare function stackedBands(xs: readonly number[], series: readonly (readonly number[])[], options?: StackPlotOptions): StackedBand[];

package/dist/math/stairs.d.ts

@@ -0,0 +1,17 @@
+/** Stairs: a step function held constant across each `[edges[i], edges[i+1]]`. */
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * The step-function polyline.
+ *
+ * @category Math & helpers
+ */
+export type StairsPolyline = Point[];
+/**
+ * The step-function polyline for `values` held over `edges`.
+ *
+ * @param edges - Step boundaries, one more than `values`; defaults to `0..values.length`.
+ * @returns The polyline in data coordinates, two points per value.
+ * @throws If `edges` is given and its length is not `values.length + 1`.
+ * @category Math & helpers
+ */
+export declare function stairsPolyline(values: readonly number[], edges?: readonly number[]): StairsPolyline;