inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/sources.d.ts

@@ -0,0 +1,116 @@
+import { DataSource, type DataSourceAttributes, type FillPlan, type FillResult, type PlanContext, type PointView } from './data.ts';
+import type { Extent } from './geometry.ts';
+/** A row's number, by property name or by function. A function also gets the index, which is how a domain can be derived. */
+export type Field<Row> = (keyof Row & (string | number)) | ((row: Row, index: number) => number);
+export interface ObjectDataSourceAttributes<Row, Channel extends string = string> extends DataSourceAttributes {
+    source: readonly Row[];
+    /** Where each row is along the domain. Leave it out and it is the row's index: 0, 1, 2 ... in order. */
+    domain?: Field<Row>;
+    value: Field<Row>;
+    /** Extra columns that bindings can address by name: a size, a colour, a category, the x of an XY plot. */
+    channels?: Readonly<Record<Channel, Field<Row>>>;
+}
+/** Rows as objects. Convenient and not the fastest: reading goes through the field accessors, so the numbers are loaded into the managed buffer once per change. */
+export declare class ObjectDataSource<Row = any, Channel extends string = string> extends DataSource<ObjectDataSourceAttributes<Row, Channel>, Channel> {
+    constructor(attrs: ObjectDataSourceAttributes<Row, Channel>);
+    /** Without a domain the rows are numbered in order, which is ascending by construction. */
+    protected get ordered(): boolean;
+    get pointCount(): number;
+    get channelNames(): readonly string[];
+    protected scanDomain(): Extent | null;
+    /** Rows are not numbers in an array, so reading them in place means loading them once into the managed buffer. */
+    protected orderedView(): PointView;
+    protected fill(out: Float64Array, context: PlanContext): FillResult;
+}
+export interface FlatDataSourceAttributes<Channel extends string = string> extends DataSourceAttributes {
+    /** Float64Array, Float32Array, or any numeric array. Read in place; never copied. */
+    data: ArrayLike<number>;
+    /** Numbers per point. Default 2 (x, y pairs), or 1 when `regularDomain` is set. */
+    stride?: number;
+    /** Where the domain and the value sit within a point's `stride` numbers. Default 0 and 1 (0 when there is no stored domain). */
+    domainOffset?: number;
+    /** Where the value sits within a point's `stride` numbers. Default 1 (0 when there is no stored domain). */
+    valueOffset?: number;
+    /** Number of points. Default: `data.length / stride`. */
+    count?: number;
+    /** Evenly spaced domain with no stored x values: a y-only array. */
+    regularDomain?: {
+        start: number;
+        step: number;
+    };
+    /** Extra columns that bindings can address by name, as offsets within a point's `stride` numbers. */
+    channels?: Readonly<Record<Channel, number>>;
+}
+/** Numbers in a typed array (or any numeric array), read where they are: the fast path for large data. */
+export declare class FlatDataSource<Channel extends string = string> extends DataSource<FlatDataSourceAttributes<Channel>, Channel> {
+    static attrTypes: {
+        isSorted: 3;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+        domainOffset: 2;
+        regularDomain: 0;
+        valueOffset: 2;
+    };
+    constructor(attrs: FlatDataSourceAttributes<Channel>);
+    private get stride();
+    get pointCount(): number;
+    get channelNames(): readonly string[];
+    /** A regular domain ascends by construction (if its step is positive); anything else says so with `isSorted`. */
+    protected get ordered(): boolean;
+    protected orderedView(): PointView;
+    protected scanDomain(): Extent | null;
+    protected fill(out: Float64Array, context: PlanContext): FillResult;
+}
+export interface SyntheticDataSourceAttributes extends DataSourceAttributes {
+    /** Value at a domain position. NaN is a gap. */
+    fn: (x: number) => number;
+    /** The span the function is defined over: the data's whole domain. */
+    domain: Extent;
+    /**
+     * Number of samples, evenly spaced across the domain, always. Leave it out and the source samples as finely as the
+     * plot needs: one per pixel of width across the part of the domain in view, so zooming in stays smooth and zooming
+     * out never draws more than the screen can show.
+     */
+    count?: number;
+}
+/**
+ * A function of the domain, sampled when drawn. There is no storage, so points are made up, not rows: they carry no
+ * `rowOf` and cannot be edited. Samples ascend by construction. It offers no channels.
+ */
+export declare class SyntheticDataSource extends DataSource<SyntheticDataSourceAttributes> {
+    constructor(attrs: SyntheticDataSourceAttributes);
+    protected get ordered(): boolean;
+    get pointCount(): number;
+    protected scanDomain(): Extent | null;
+    /** How many samples, over which part of the domain, for this plot. */
+    private span;
+    protected fill(out: Float64Array, context: PlanContext): FillResult;
+    /** Room for the samples this plot asks for, which depends on its width; the points are made up, so there is no `rowOf`. */
+    plan(context: PlanContext): FillPlan;
+}
+/** A named column in a composite source: an array (typed or plain), or a function of the row index. */
+export type Column = ArrayLike<number> | ((index: number) => number);
+export interface CompositeDataSourceAttributes<Channel extends string = string> extends DataSourceAttributes {
+    count: number;
+    /** Where each row is along the domain: for a made-up domain, `(i) => start + step * i`. */
+    domain: Column;
+    value: Column;
+    /** Extra columns that bindings and tooltips can address by name. */
+    channels?: Readonly<Record<Channel, Column>>;
+}
+/**
+ * Each column kept by itself: the shape of column-oriented data (an `x` array and a `y` array, a table by column), and of
+ * data whose domain is made up, with any column a function of the row index. Nothing is copied from arrays that are
+ * already in order (`isSorted`); otherwise the columns are gathered into the managed buffer once per change.
+ */
+export declare class CompositeDataSource<Channel extends string = string> extends DataSource<CompositeDataSourceAttributes<Channel>, Channel> {
+    constructor(attrs: CompositeDataSourceAttributes<Channel>);
+    get pointCount(): number;
+    get channelNames(): readonly string[];
+    protected scanDomain(): Extent | null;
+    protected fill(out: Float64Array, context: PlanContext): FillResult;
+}

package/dist/sources.js

@@ -0,0 +1,237 @@
+/** The data sources: rows of objects, flat typed arrays, generated points and separate columns. The contract and the base class are in data.ts. */
+/* oxlint-disable typescript/no-non-null-assertion -- numeric kernels over flat typed-array buffers (stride-addressed rows): every index is bounded by the row count, which `noUncheckedIndexedAccess` cannot see */
+import { AUTO, NUMBER } from './attrs.js';
+import { DataSource, NO_POINTS, endsOf, num } from './data.js';
+import { fail } from './element.js';
+/** Rows as objects. Convenient and not the fastest: reading goes through the field accessors, so the numbers are loaded into the managed buffer once per change. */
+// oxlint-disable-next-line typescript/no-explicit-any -- the default row type: untyped rows (from JSON, or JSX/React where no type argument can be written) must be accepted, and `unknown` would reject every field accessor
+export class ObjectDataSource extends DataSource {
+    // oxlint-disable-next-line eslint/no-useless-constructor -- makes the attributes required (the base class accepts none)
+    constructor(attrs) { super(attrs); }
+    /** Without a domain the rows are numbered in order, which is ascending by construction. */
+    get ordered() { return this.attrs.domain === undefined || this.attrs.isSorted === true; }
+    get pointCount() { return this.attrs.source.length; }
+    get channelNames() { return Object.keys(this.attrs.channels ?? {}); }
+    scanDomain() {
+        const { source, domain } = this.attrs;
+        const n = source.length;
+        if (domain === undefined)
+            return n > 0 ? { min: 0, max: n - 1 } : null;
+        const read = typeof domain === 'function' ? domain : (row) => num(row[domain]);
+        return endsOf(n, (i) => read(source[i], i));
+    }
+    /** Rows are not numbers in an array, so reading them in place means loading them once into the managed buffer. */
+    orderedView() { return this.managedView(); }
+    fill(out, context) {
+        const { source, domain, value, channels } = this.attrs;
+        const xFn = typeof domain === 'function' ? domain : null;
+        const yFn = typeof value === 'function' ? value : null;
+        const names = context.channels, k = names.length, stride = 2 + k;
+        const cFns = names.map((name) => {
+            const f = channels?.[name] ?? fail(`the data has no channel "${name}"`);
+            return typeof f === 'function' ? f : (row) => num(row[f]);
+        });
+        const cMin = new Float64Array(k).fill(Infinity), cMax = new Float64Array(k).fill(-Infinity);
+        const n = source.length;
+        let xMin = Infinity, xMax = -Infinity, yMin = Infinity, yMax = -Infinity;
+        for (let i = 0; i < n; i++) {
+            const row = source[i];
+            const x = xFn ? xFn(row, i) : domain === undefined ? i : num(row[domain]);
+            const y = yFn ? yFn(row, i) : num(row[value]);
+            out[stride * i] = x;
+            out[stride * i + 1] = y;
+            if (x < xMin)
+                xMin = x;
+            if (x > xMax)
+                xMax = x;
+            if (y < yMin)
+                yMin = y;
+            if (y > yMax)
+                yMax = y;
+            for (let c = 0; c < k; c++) {
+                const v = cFns[c](row, i);
+                out[stride * i + 2 + c] = v;
+                if (v < cMin[c])
+                    cMin[c] = v;
+                if (v > cMax[c])
+                    cMax[c] = v;
+            }
+        }
+        const extents = [{ min: xMin, max: xMax }, { min: yMin, max: yMax }];
+        for (let c = 0; c < k; c++)
+            extents.push({ min: cMin[c], max: cMax[c] });
+        return { count: n, extents };
+    }
+}
+/** Numbers in a typed array (or any numeric array), read where they are: the fast path for large data. */
+export class FlatDataSource extends DataSource {
+    static attrTypes = { ...DataSource.attrTypes, domainOffset: NUMBER, regularDomain: AUTO, valueOffset: NUMBER };
+    // oxlint-disable-next-line eslint/no-useless-constructor -- makes the attributes required (the base class accepts none)
+    constructor(attrs) { super(attrs); }
+    get stride() { return this.attrs.stride ?? (this.attrs.regularDomain ? 1 : 2); }
+    get pointCount() { return this.attrs.count ?? Math.floor(this.attrs.data.length / this.stride); }
+    get channelNames() { return Object.keys(this.attrs.channels ?? {}); }
+    /** A regular domain ascends by construction (if its step is positive); anything else says so with `isSorted`. */
+    get ordered() {
+        const r = this.attrs.regularDomain;
+        return r ? r.step > 0 : this.attrs.isSorted === true;
+    }
+    orderedView() {
+        const a = this.attrs, r = a.regularDomain;
+        return {
+            data: a.data,
+            count: this.pointCount,
+            stride: this.stride,
+            domainOffset: a.domainOffset ?? 0,
+            valueOffset: a.valueOffset ?? (r ? 0 : 1),
+            regularDomain: r ?? null,
+        };
+    }
+    scanDomain() {
+        const { data, regularDomain: r, domainOffset = 0 } = this.attrs;
+        const n = this.pointCount;
+        if (n === 0)
+            return null;
+        if (r)
+            return { min: r.start, max: r.start + r.step * (n - 1) };
+        const stride = this.stride;
+        return endsOf(n, (i) => data[i * stride + domainOffset]);
+    }
+    fill(out, context) {
+        const { data, regularDomain: r, domainOffset = 0, channels } = this.attrs;
+        const stride = this.stride, n = this.pointCount;
+        const valueOffset = this.attrs.valueOffset ?? (r ? 0 : 1);
+        const names = context.channels, k = names.length, os = 2 + k;
+        const offsets = names.map((name) => channels?.[name] ?? fail(`the data has no channel "${name}"`));
+        const cMin = new Float64Array(k).fill(Infinity), cMax = new Float64Array(k).fill(-Infinity);
+        let xMin = Infinity, xMax = -Infinity, yMin = Infinity, yMax = -Infinity;
+        for (let i = 0, j = 0; i < n; i++, j += stride) {
+            const x = r ? r.start + r.step * i : data[j + domainOffset];
+            const y = data[j + valueOffset];
+            out[os * i] = x;
+            out[os * i + 1] = y;
+            if (x < xMin)
+                xMin = x;
+            if (x > xMax)
+                xMax = x;
+            if (y < yMin)
+                yMin = y;
+            if (y > yMax)
+                yMax = y;
+            for (let c = 0; c < k; c++) {
+                const v = data[j + offsets[c]];
+                out[os * i + 2 + c] = v;
+                if (v < cMin[c])
+                    cMin[c] = v;
+                if (v > cMax[c])
+                    cMax[c] = v;
+            }
+        }
+        if (n === 0)
+            return { count: 0, extents: [NO_POINTS, NO_POINTS, ...names.map(() => NO_POINTS)] };
+        const extents = [{ min: xMin, max: xMax }, { min: yMin, max: yMax }];
+        for (let c = 0; c < k; c++)
+            extents.push({ min: cMin[c], max: cMax[c] });
+        return { count: n, extents };
+    }
+}
+// ─── Generated and column-wise sources ───
+/** Samples when nothing says how many: the plot's width is not known when a source is only asked for its extent. */
+const DEFAULT_SAMPLES = 512;
+/**
+ * A function of the domain, sampled when drawn. There is no storage, so points are made up, not rows: they carry no
+ * `rowOf` and cannot be edited. Samples ascend by construction. It offers no channels.
+ */
+export class SyntheticDataSource extends DataSource {
+    // oxlint-disable-next-line eslint/no-useless-constructor -- makes the attributes required (the base class accepts none)
+    constructor(attrs) { super(attrs); }
+    get ordered() { return true; }
+    get pointCount() { return this.attrs.count ?? DEFAULT_SAMPLES; }
+    scanDomain() {
+        const d = this.attrs.domain;
+        return d.min <= d.max ? d : null;
+    }
+    /** How many samples, over which part of the domain, for this plot. */
+    span(context) {
+        const d = this.attrs.domain, lo = Math.max(d.min, context.domainRange.min), hi = Math.min(d.max, context.domainRange.max);
+        if (!(lo <= hi))
+            return { lo, hi, n: 0 };
+        return { lo, hi, n: this.attrs.count ?? (context.width > 0 ? Math.max(2, Math.ceil(context.width)) : DEFAULT_SAMPLES) };
+    }
+    fill(out, context) {
+        if (context.channels.length)
+            fail(`the data has no channel "${context.channels[0]}"`);
+        // With a fixed count the span is the whole domain whatever is in view; otherwise only the part in view is sampled.
+        const { fn, domain, count } = this.attrs;
+        const { lo, hi, n } = count === undefined ? this.span(context) : { lo: domain.min, hi: domain.max, n: count };
+        if (n === 0)
+            return { count: 0, extents: [NO_POINTS, NO_POINTS] };
+        let yMin = Infinity, yMax = -Infinity;
+        for (let i = 0; i < n; i++) {
+            const x = n === 1 ? lo : i === n - 1 ? hi : lo + ((hi - lo) * i) / (n - 1), y = fn(x);
+            out[2 * i] = x;
+            out[2 * i + 1] = y;
+            if (y < yMin)
+                yMin = y;
+            if (y > yMax)
+                yMax = y;
+        }
+        return { count: n, extents: [{ min: lo, max: hi }, yMin <= yMax ? { min: yMin, max: yMax } : NO_POINTS] };
+    }
+    /** Room for the samples this plot asks for, which depends on its width; the points are made up, so there is no `rowOf`. */
+    plan(context) {
+        if (this.attrs.wrap !== undefined)
+            return super.plan(context);
+        return { capacity: this.attrs.count ?? this.span(context).n, fill: (out) => this.fill(out, context) };
+    }
+}
+const reader = (c) => (typeof c === 'function' ? c : (i) => c[i]);
+/**
+ * Each column kept by itself: the shape of column-oriented data (an `x` array and a `y` array, a table by column), and of
+ * data whose domain is made up, with any column a function of the row index. Nothing is copied from arrays that are
+ * already in order (`isSorted`); otherwise the columns are gathered into the managed buffer once per change.
+ */
+export class CompositeDataSource extends DataSource {
+    // oxlint-disable-next-line eslint/no-useless-constructor -- makes the attributes required (the base class accepts none)
+    constructor(attrs) { super(attrs); }
+    get pointCount() { return this.attrs.count; }
+    get channelNames() { return Object.keys(this.attrs.channels ?? {}); }
+    scanDomain() {
+        const at = reader(this.attrs.domain);
+        return endsOf(this.attrs.count, at);
+    }
+    fill(out, context) {
+        const { count: n, channels } = this.attrs;
+        const xAt = reader(this.attrs.domain), yAt = reader(this.attrs.value);
+        const names = context.channels, k = names.length, stride = 2 + k;
+        const cAt = names.map((name) => reader(channels?.[name] ?? fail(`the data has no channel "${name}"`)));
+        const cMin = new Float64Array(k).fill(Infinity), cMax = new Float64Array(k).fill(-Infinity);
+        let xMin = Infinity, xMax = -Infinity, yMin = Infinity, yMax = -Infinity;
+        for (let i = 0; i < n; i++) {
+            const x = num(xAt(i)), y = num(yAt(i));
+            out[stride * i] = x;
+            out[stride * i + 1] = y;
+            if (x < xMin)
+                xMin = x;
+            if (x > xMax)
+                xMax = x;
+            if (y < yMin)
+                yMin = y;
+            if (y > yMax)
+                yMax = y;
+            for (let c = 0; c < k; c++) {
+                const v = num(cAt[c](i));
+                out[stride * i + 2 + c] = v;
+                if (v < cMin[c])
+                    cMin[c] = v;
+                if (v > cMax[c])
+                    cMax[c] = v;
+            }
+        }
+        const ext = (min, max) => (min <= max ? { min, max } : NO_POINTS);
+        const extents = [ext(xMin, xMax), ext(yMin, yMax)];
+        for (let c = 0; c < k; c++)
+            extents.push(ext(cMin[c], cMax[c]));
+        return { count: n, extents };
+    }
+}

package/dist/stack.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Stack: series that are drawn on top of each other, or side by side, sharing one domain and one value axis.
+ *
+ * A stack is a group in the plane, and its members are ordinary series, each with its own source, renderers, name and
+ * `hit`. All it adds is where each series' rows sit: for every row a *base* (where it starts) and a *top* (where it is
+ * plotted), which the series reads in place of its own value. So nothing downstream is special:
+ *  - a line or a marker is drawn at the tops, once for each series;
+ *  - an area (or bars) fills from the series' base, which `Series.baseline` now returns row by row;
+ *  - a tooltip or an edit still sees the series' own value, since the raw rows are untouched.
+ *
+ * Modes (`mode`):
+ *  - `stack` (default): each row's values are laid one on another in the order of the members, the first at the bottom.
+ *    Positive values stack up from zero and negative ones down from it, so mixed signs do not cancel.
+ *  - `normalize`: like `stack`, with each row scaled to total 1 (the value axis then runs 0 to 1: give it a format).
+ *  - `center`: a streamgraph, the stack of each row centred on zero.
+ *  - `group`: nothing is laid on anything; every series is drawn from the baseline, and a bar renderer places the series
+ *    side by side, in the order they are listed.
+ * A value that is a gap (NaN) leaves its own layer out and adds nothing to the others in that row.
+ *
+ * The rows of the members have to line up. Normally they do (the same categories, the same table's columns), and the
+ * default `align: 'strict'` checks it. Otherwise `align` says how to merge their domains into the union of all of them,
+ * a row at every position any member has:
+ *  - `gaps`: a member that has no value at a position has a gap there. Right for bars.
+ *  - `interpolate`: it has the straight line between its neighbours' values, and a gap beyond its own first and last
+ *    position. Right for areas and lines, which then add up exactly. The rows made up this way belong to no source row,
+ *    so they cannot be edited, and any channels they bind are gaps. A member with two rows at one position keeps the first.
+ *
+ * Decimation is per series and would thin each differently, so decimate a stack's sources before it, if at all: members
+ * whose rows then differ in domain need `align` as above.
+ */
+import { type BaseAttributes, ChartElement } from './element.ts';
+import type { Extent, Size } from './geometry.ts';
+import type { Plane } from './plane.ts';
+import { DomainSeries, type Rows, type SeriesGroup } from './series.ts';
+export type StackMode = 'stack' | 'normalize' | 'center' | 'group';
+export type StackAlign = 'strict' | 'gaps' | 'interpolate';
+export interface StackAttributes extends BaseAttributes {
+    /** How the members' values are laid out. Default 'stack'. */
+    mode?: StackMode;
+    /** How rows are matched up when the members' domains differ. Default 'strict': they must not. */
+    align?: StackAlign;
+}
+/**
+ * Tables of rows made to share one domain: the union of all of theirs, each with a row at every position, `gaps` or
+ * `interpolate` where it had none. The made-up rows have no source row (`rowOf` negative).
+ */
+export declare function alignRows(tables: readonly Rows[], how: 'gaps' | 'interpolate'): Rows[];
+/** Where every row of every member starts and is plotted, and the extent of it all. */
+export interface Layout {
+    readonly base: Float64Array[];
+    readonly top: Float64Array[];
+    readonly extent: Extent | null;
+}
+/** Lay the values of the (already lined-up) tables out by `mode`. */
+export declare function layOut(tables: readonly Rows[], mode: StackMode): Layout;
+export declare class Stack extends ChartElement<Plane, DomainSeries[], StackAttributes> implements SeriesGroup {
+    /** The series in the stack, in the order they stack. */
+    get members(): readonly DomainSeries[];
+    /** Engine protocol, called by the plane in place of each member's own `load`: read them all, lay them out, report the extents. */
+    load(estimate: Size): void;
+}

package/dist/stack.js

@@ -0,0 +1,172 @@
+/**
+ * Stack: series that are drawn on top of each other, or side by side, sharing one domain and one value axis.
+ *
+ * A stack is a group in the plane, and its members are ordinary series, each with its own source, renderers, name and
+ * `hit`. All it adds is where each series' rows sit: for every row a *base* (where it starts) and a *top* (where it is
+ * plotted), which the series reads in place of its own value. So nothing downstream is special:
+ *  - a line or a marker is drawn at the tops, once for each series;
+ *  - an area (or bars) fills from the series' base, which `Series.baseline` now returns row by row;
+ *  - a tooltip or an edit still sees the series' own value, since the raw rows are untouched.
+ *
+ * Modes (`mode`):
+ *  - `stack` (default): each row's values are laid one on another in the order of the members, the first at the bottom.
+ *    Positive values stack up from zero and negative ones down from it, so mixed signs do not cancel.
+ *  - `normalize`: like `stack`, with each row scaled to total 1 (the value axis then runs 0 to 1: give it a format).
+ *  - `center`: a streamgraph, the stack of each row centred on zero.
+ *  - `group`: nothing is laid on anything; every series is drawn from the baseline, and a bar renderer places the series
+ *    side by side, in the order they are listed.
+ * A value that is a gap (NaN) leaves its own layer out and adds nothing to the others in that row.
+ *
+ * The rows of the members have to line up. Normally they do (the same categories, the same table's columns), and the
+ * default `align: 'strict'` checks it. Otherwise `align` says how to merge their domains into the union of all of them,
+ * a row at every position any member has:
+ *  - `gaps`: a member that has no value at a position has a gap there. Right for bars.
+ *  - `interpolate`: it has the straight line between its neighbours' values, and a gap beyond its own first and last
+ *    position. Right for areas and lines, which then add up exactly. The rows made up this way belong to no source row,
+ *    so they cannot be edited, and any channels they bind are gaps. A member with two rows at one position keeps the first.
+ *
+ * Decimation is per series and would thin each differently, so decimate a stack's sources before it, if at all: members
+ * whose rows then differ in domain need `align` as above.
+ */
+/* oxlint-disable typescript/no-non-null-assertion -- numeric kernels over flat typed-array buffers (stride-addressed rows): every index is bounded by the row count, which `noUncheckedIndexedAccess` cannot see */
+import { ChartElement, fail } from './element.js';
+import { DomainSeries } from './series.js';
+/** The first column of each table is its domain and the second its value (a `DomainSeries`' raw layout). */
+const sameDomain = (a, b) => {
+    if (a.count !== b.count)
+        return false;
+    for (let i = 0; i < a.count; i++)
+        if (a.raw[i * a.stride] !== b.raw[i * b.stride])
+            return false;
+    return true;
+};
+/**
+ * Tables of rows made to share one domain: the union of all of theirs, each with a row at every position, `gaps` or
+ * `interpolate` where it had none. The made-up rows have no source row (`rowOf` negative).
+ */
+export function alignRows(tables, how) {
+    let total = 0;
+    for (const t of tables)
+        total += t.count;
+    const all = new Float64Array(total);
+    let at = 0;
+    for (const t of tables)
+        for (let i = 0; i < t.count; i++)
+            all[at++] = t.raw[i * t.stride];
+    all.sort();
+    let size = 0;
+    for (let i = 0; i < all.length; i++)
+        if (i === 0 || all[i] !== all[i - 1])
+            all[size++] = all[i];
+    return tables.map((t) => {
+        const { raw, count: n, stride: s } = t;
+        const out = new Float64Array(size * s).fill(NaN), rows = new Int32Array(size).fill(-1);
+        for (let u = 0, j = 0; u < size; u++) {
+            const x = all[u];
+            while (j < n && raw[j * s] < x)
+                j++;
+            out[u * s] = x;
+            if (j < n && raw[j * s] === x) {
+                for (let c = 1; c < s; c++)
+                    out[u * s + c] = raw[j * s + c];
+                rows[u] = t.rowOf ? t.rowOf(j) : -1;
+                while (j < n && raw[j * s] === x)
+                    j++;
+            }
+            else if (how === 'interpolate' && j > 0 && j < n) {
+                const x0 = raw[(j - 1) * s], x1 = raw[j * s], v0 = raw[(j - 1) * s + 1], v1 = raw[j * s + 1];
+                if (Number.isFinite(v0) && Number.isFinite(v1))
+                    out[u * s + 1] = v0 + ((x - x0) / (x1 - x0)) * (v1 - v0);
+            }
+        }
+        return { raw: out, count: size, stride: s, rowOf: (i) => rows[i] };
+    });
+}
+/** Lay the values of the (already lined-up) tables out by `mode`. */
+export function layOut(tables, mode) {
+    const members = tables.length, n = tables[0]?.count ?? 0;
+    const base = tables.map(() => new Float64Array(n)), top = tables.map(() => new Float64Array(n));
+    let min = Infinity, max = -Infinity;
+    const note = (v) => { if (v < min)
+        min = v; if (v > max)
+        max = v; };
+    for (let i = 0; i < n; i++) {
+        let total = 0, sum = 0;
+        if (mode === 'normalize' || mode === 'center') {
+            for (let m = 0; m < members; m++) {
+                const t = tables[m], v = t.raw[i * t.stride + 1];
+                if (Number.isFinite(v)) {
+                    total += Math.abs(v);
+                    sum += v;
+                }
+            }
+        }
+        const scale = mode === 'normalize' ? (total > 0 ? 1 / total : 0) : 1;
+        let pos = 0, neg = 0, run = mode === 'center' ? (-sum * scale) / 2 : 0;
+        for (let m = 0; m < members; m++) {
+            const t = tables[m], v = t.raw[i * t.stride + 1];
+            if (!Number.isFinite(v)) {
+                base[m][i] = top[m][i] = NaN;
+                continue;
+            }
+            const w = v * scale;
+            let from, to;
+            if (mode === 'group') {
+                from = 0;
+                to = v;
+            }
+            else if (mode === 'center') {
+                from = run;
+                to = run + w;
+                run = to;
+            }
+            else if (w >= 0) {
+                from = pos;
+                to = pos + w;
+                pos = to;
+            }
+            else {
+                from = neg;
+                to = neg + w;
+                neg = to;
+            }
+            base[m][i] = from;
+            top[m][i] = to;
+            note(from);
+            note(to);
+        }
+    }
+    return { base, top, extent: min <= max ? { min, max } : null };
+}
+export class Stack extends ChartElement {
+    /** The series in the stack, in the order they stack. */
+    get members() {
+        return [...this].filter((c) => c instanceof DomainSeries);
+    }
+    /** Engine protocol, called by the plane in place of each member's own `load`: read them all, lay them out, report the extents. */
+    load(estimate) {
+        const members = this.members.filter((m) => m.shown); // a member that is not shown leaves the stack: the rest close up
+        if (members.length === 0)
+            return;
+        const { domainAxis, valueAxis } = members[0];
+        for (const m of members)
+            if (m.domainAxis !== domainAxis || m.valueAxis !== valueAxis)
+                fail('the series of a stack have to share their domain axis and their value axis');
+        const own = members.map((m) => m.prepare(estimate));
+        const how = this.attrs.align ?? 'strict';
+        let tables = own, made = null;
+        if (!own.every((t) => sameDomain(own[0], t))) {
+            if (how === 'strict')
+                fail("the series of a stack have to share their domain values: give the stack `align: 'gaps'` (bars) or `align: 'interpolate'` (lines, areas) to merge them");
+            tables = made = alignRows(own, how);
+        }
+        const mode = this.attrs.mode ?? 'stack', layout = layOut(tables, mode);
+        members.forEach((m, index) => {
+            m.join({
+                base: layout.base[index], top: layout.top[index], additive: mode !== 'normalize', extent: layout.extent,
+                slot: mode === 'group' ? { index, count: members.length } : { index: 0, count: 1 },
+            }, made ? made[index] : null);
+            m.settle(layout.extent);
+        });
+    }
+}

package/dist/stats.d.ts

@@ -0,0 +1,38 @@
+import { type DataNode, DataTransform, type FillPlan, type PlanContext } from './data.ts';
+import { type BaseAttributes } from './element.ts';
+import type { Extent } from './geometry.ts';
+export interface BoxStatsAttributes extends BaseAttributes {
+    /** 'summary' (the default): a point for each group. 'outliers': a point for each sample beyond the whiskers. */
+    output?: 'summary' | 'outliers';
+    /** How far the whiskers may reach past the box, in interquartile ranges (default 1.5), or 'minmax' for the whole range. */
+    fence?: number | 'minmax';
+    /** How a quartile is found between samples. Default 'inclusive'. */
+    method?: 'inclusive' | 'exclusive';
+    /** Which statistic is the point's value: 'median' (the default; what a box is drawn round) or 'mean' (what error bars from `sd` or `sem` are drawn round). */
+    value?: 'median' | 'mean';
+}
+export declare class BoxStats extends DataTransform<BoxStatsAttributes, [source: DataNode]> {
+    #private;
+    static attrTypes: {
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+        output: 1;
+        fence: 0;
+        method: 1;
+        value: 1;
+    };
+    get source(): DataNode;
+    get channelNames(): readonly string[];
+    /** Anything beneath (the source) bubbles an invalidation up through here, so one counter covers the source and the attributes. */
+    invalidate(): void;
+    get version(): number;
+    get pointCount(): number;
+    domain(): Extent | null;
+    valueExtent(): Extent | null;
+    channelExtent(name: string): Extent | null;
+    plan(context: PlanContext): FillPlan;
+}