inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/bars.js

@@ -0,0 +1,255 @@
+/**
+ * Bars: from a baseline to a value, one for each point of a series.
+ *
+ * A bar is drawn in the plane's own terms, never in pixels: its four corners are placed through the axes and the plane
+ * like any other point, so the same code gives upright bars on a rectangle, horizontal ones when the domain is on the
+ * vertical axis, and wedges on a polar plane (where the two edges along the angle are subdivided into arcs, since a
+ * straight line between the corners would cut across: the domain's when the domain is the angle, the value's when the value is,
+ * as in a ring or pie).
+ *
+ * Two renderers share all of that, through `BarRenderer`: `BarPath` fills each bar, and `BarLinePath` draws only its
+ * stem, a line from the foot to the value (a spike plot; add a marker to the series for a lollipop). A stem has no
+ * width, so the width rule matters only to series that share a band.
+ *
+ * Where a bar starts is the series' `baseline`, or, in a `Stack`, the row's own start (the layer below it). Its width:
+ *  - on a band axis, the band's `bandwidth`, which the scale's `gap` sets;
+ *  - otherwise `width` (default 0.8) of the smallest gap between neighbouring points, since that is what the bars would
+ *    have to share. With one point and no band there is nothing to measure and the bar takes a fifth of the axis.
+ * Series that stack side by side divide that width between them, in the order the stack lists them.
+ *
+ * The geometry is a free function over `Series.drawn` that hands back polygons, which is also what a pointer hit on a
+ * bar is measured against, so what is clicked is exactly what is drawn.
+ */
+/* 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 { f2 } from './geometry.js';
+import { SeriesRenderer, paintBox } from './renderer.js';
+import { notImplemented } from './stub.js';
+/** How far outside the axes' range a bar may reach before it is cut short: only to keep the numbers sane, the clip does the rest. */
+const REACH = 2;
+/** Most pieces the edge of a bar on a curved plane is cut into. */
+const MAX_ARC = 16;
+/** The same, along the value, when the value is the angle: a segment may span a whole turn. */
+const MAX_VALUE_ARC = 48;
+export function layoutBars(series, options) {
+    const d = series.drawn;
+    if (!d)
+        return null;
+    const n = d.points.count, rs = d.stride, raw = d.raw, first = series.firstAxis, second = series.secondAxis;
+    const baseline = options.baseline ?? 0;
+    const norm = new Float64Array(n * 3);
+    for (let i = 0; i < n; i++) {
+        const v = raw[i * rs + d.secondColumn], ok = Number.isFinite(v);
+        norm[3 * i] = raw[i * rs + d.firstColumn];
+        norm[3 * i + 1] = ok ? (d.base ? d.base[i] : baseline) : NaN;
+        norm[3 * i + 2] = ok ? (d.top ? d.top[i] : v) : NaN;
+    }
+    first.normalize(norm, n, 3, 0);
+    second.normalize(norm, n, 3, 1);
+    second.normalize(norm, n, 3, 2);
+    // The room one bar (or one group of them) has along the domain.
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- a scale is read for the optional `bandwidth` and `gap` that only a band scale has
+    const scale = first.scale;
+    let room = 0;
+    if (typeof scale.bandwidth === 'number' && options.width === undefined) {
+        room = scale.bandwidth;
+    }
+    else {
+        let pitch = Infinity, prev = NaN;
+        for (let i = 0; i < n; i++) {
+            const x = norm[3 * i];
+            if (!Number.isFinite(x))
+                continue;
+            if (prev === prev && x > prev && x - prev < pitch)
+                pitch = x - prev;
+            prev = x;
+        }
+        if (typeof scale.bandwidth === 'number')
+            pitch = scale.bandwidth / (1 - (scale.attrs?.gap ?? 0.2));
+        room = (options.width ?? 0.8) * (pitch < Infinity ? pitch : 0.25);
+    }
+    const { index, count } = d.slot, slot = room / count;
+    return { n, norm, slot, shift: (index - (count - 1) / 2) * slot };
+}
+/**
+ * How far along the domain (as a fraction of the axis) a series' own bars sit from the point's place, when it shares a band
+ * with others (`Stack` in 'group' mode). What goes on the bars (error bars) uses it to stay on them. 0 for a series alone.
+ */
+export function barShift(series, options = {}) {
+    const d = series.drawn;
+    return d && d.slot.count > 1 ? layoutBars(series, options)?.shift ?? 0 : 0;
+}
+const clamp = (v) => (v < -REACH ? -REACH : v > 1 + REACH ? 1 + REACH : v);
+/** The three stems drawn in a bar series' legend sample: position across, height up. */
+const STEM_SAMPLE = [[0.2, 0.6], [0.5, 1], [0.8, 0.4]];
+/**
+ * The outline of every bar of a series in plot pixels, `perShape` points each, in the order of the series' points
+ * (a point that is a gap leaves a shape of NaN). Null before the first projection.
+ */
+export function barShapes(series, options = {}) {
+    const lay = layoutBars(series, options), plane = series.drawn?.plane;
+    if (!lay || !plane)
+        return null;
+    const { n, norm, slot, shift } = lay;
+    // On a curved plane the edges that run along the angle become arcs: the ones along the domain normally, the ones along
+    // the value when the value is the angle (a ring or pie: each bar is a segment of a ring).
+    const roundValue = plane.curved && series.secondAxis.orientation === 'angle';
+    const steps = roundValue ? MAX_VALUE_ARC : plane.curved ? Math.min(MAX_ARC, Math.max(2, Math.ceil(slot * 64))) : 1, per = 2 * (steps + 1);
+    const out = new Float64Array(n * per * 2);
+    for (let i = 0; i < n; i++) {
+        const x = norm[3 * i] + shift, from = norm[3 * i + 1], to = norm[3 * i + 2];
+        const bad = !Number.isFinite(x) || !Number.isFinite(from) || !Number.isFinite(to);
+        const x0 = x - slot / 2, b = bad ? NaN : clamp(from), t = bad ? NaN : clamp(to);
+        let k = i * per * 2;
+        // Along the start edge one way, then back along the end edge: a closed outline.
+        if (roundValue) {
+            for (let j = 0; j <= steps; j++) {
+                out[k++] = x0;
+                out[k++] = b + ((t - b) * j) / steps;
+            }
+            for (let j = steps; j >= 0; j--) {
+                out[k++] = x0 + slot;
+                out[k++] = b + ((t - b) * j) / steps;
+            }
+            continue;
+        }
+        for (let j = 0; j <= steps; j++) {
+            out[k++] = x0 + (slot * j) / steps;
+            out[k++] = b;
+        }
+        for (let j = steps; j >= 0; j--) {
+            out[k++] = x0 + (slot * j) / steps;
+            out[k++] = t;
+        }
+    }
+    plane.place({ data: out, stride: 2, count: n * per }, series.firstAxis, series.secondAxis);
+    return { data: out, perShape: per, count: n };
+}
+/**
+ * The stem of every bar: a line from its foot to its value, two points each, as a `PolygonSet` of two-point shapes (so a
+ * hit measures the distance to the line). Straight on every plane, since a line along the value is a straight line (a
+ * spoke) on a polar one. Gaps leave NaN.
+ */
+export function stemLines(series, options = {}) {
+    const lay = layoutBars(series, options), plane = series.drawn?.plane;
+    if (!lay || !plane)
+        return null;
+    const { n, norm, shift } = lay;
+    const out = new Float64Array(n * 4);
+    for (let i = 0; i < n; i++) {
+        const x = norm[3 * i] + shift, from = norm[3 * i + 1], to = norm[3 * i + 2];
+        const bad = !Number.isFinite(x) || !Number.isFinite(from) || !Number.isFinite(to);
+        out[4 * i] = out[4 * i + 2] = bad ? NaN : x;
+        out[4 * i + 1] = bad ? NaN : clamp(from);
+        out[4 * i + 3] = bad ? NaN : clamp(to);
+    }
+    plane.place({ data: out, stride: 2, count: n * 2 }, series.firstAxis, series.secondAxis);
+    return { data: out, perShape: 2, count: n };
+}
+/**
+ * What every bar renderer shares: where bars start and how wide they are (`BarOptions`), that the value axis has to reach
+ * the baseline, and that a pointer hit is measured against the geometry it draws. A subclass says what that geometry is
+ * (`outline`) and how to draw it.
+ */
+export class BarRenderer extends SeriesRenderer {
+    get includes() { return [this.attrs.baseline ?? 0]; }
+    /** Half of a bar's room: its width, in the gaps between points (a band's own bars fit it already). */
+    get spans() { return (this.attrs.width ?? 0.8) / 2; }
+    get hitMode() { return 'shape'; }
+    shapes() { return this.outline(); }
+}
+/** One path holding every bar of the series: the cost of a bar chart is its path text, not a node for each bar. */
+export class BarPath extends BarRenderer {
+    look() {
+        const a = this.attrs;
+        return this.styleFor(['seriesBar', 'shape'], { fill: a.fill, stroke: a.stroke, strokeWidth: a.strokeWidth, opacity: a.opacity }, { fill: this.requireParent().accentColor });
+    }
+    get swatch() { return this.look().fill; }
+    outline() { return barShapes(this.requireParent(), this.attrs); }
+    sample(s, parent, key, width, height) { paintBox(s, parent, key, width, height, this.look()); }
+    draw() {
+        const counters = this.counters, s = this.surface, a = this.attrs;
+        if (a.bind)
+            notImplemented('BarPath bindings');
+        const look = this.look();
+        const t0 = performance.now();
+        const shapes = this.outline();
+        let d = '';
+        if (shapes) {
+            const { data, perShape, count } = shapes;
+            for (let i = 0, k = 0; i < count; i++, k += perShape * 2) {
+                const x = data[k], y = data[k + 1];
+                if (!Number.isFinite(x) || !Number.isFinite(y))
+                    continue;
+                d += 'M' + f2(x) + ' ' + f2(y) + 'L';
+                for (let j = 1; j < perShape; j++)
+                    d += (j > 1 ? ' ' : '') + f2(data[k + 2 * j]) + ' ' + f2(data[k + 2 * j + 1]);
+                d += 'Z';
+            }
+        }
+        counters.stages.path += performance.now() - t0;
+        counters.pathBytes += d.length;
+        const n = s.node('bars', 'path');
+        s.set(n, 'd', d);
+        s.set(n, 'fill', look.fill);
+        s.set(n, 'stroke', look.stroke);
+        s.set(n, 'stroke-width', look.strokeWidth);
+        s.set(n, 'stroke-linejoin', 'round');
+        s.set(n, 'opacity', look.opacity);
+    }
+}
+/**
+ * Bars as lines: each is a stem from the foot to the value, stroked rather than filled, in one path. The width is the
+ * stroke's, so it stays the same however many bars there are, which is what makes it the answer for dense data where
+ * filled bars would be slivers. The look is the line's (`seriesLine`), with the series' colour as its stroke; give the
+ * series a marker as well for a lollipop.
+ */
+export class BarLinePath extends BarRenderer {
+    look() {
+        const a = this.attrs;
+        return this.styleFor(['seriesLine', 'line'], { color: a.stroke, width: a.strokeWidth, opacity: a.opacity }, { color: this.requireParent().accentColor });
+    }
+    get swatch() { return this.look().color; }
+    outline() { return stemLines(this.requireParent(), this.attrs); }
+    /** Three stems of different heights, as wide as the stroke says. */
+    sample(s, parent, key, width, height) {
+        const look = this.look(), n = s.node(key, 'path', { parent });
+        let d = '';
+        for (const [at, up] of STEM_SAMPLE)
+            d += `M${f2(width * at)} ${f2(height)}V${f2(height * (1 - up))}`;
+        s.set(n, 'd', d);
+        s.set(n, 'fill', 'none');
+        s.set(n, 'stroke', look.color);
+        s.set(n, 'stroke-width', look.width);
+        s.set(n, 'stroke-linecap', this.attrs.cap ?? 'butt');
+        s.set(n, 'opacity', look.opacity);
+        s.set(n, 'stroke-dasharray', look.dash);
+    }
+    draw() {
+        const counters = this.counters, s = this.surface, a = this.attrs;
+        if (a.bind)
+            notImplemented('BarLinePath bindings');
+        const look = this.look();
+        const t0 = performance.now();
+        const stems = this.outline();
+        let d = '';
+        if (stems) {
+            const { data, count } = stems;
+            for (let i = 0, k = 0; i < count; i++, k += 4) {
+                const x = data[k], y = data[k + 1];
+                if (!Number.isFinite(x) || !Number.isFinite(y))
+                    continue;
+                d += 'M' + f2(x) + ' ' + f2(y) + 'L' + f2(data[k + 2]) + ' ' + f2(data[k + 3]);
+            }
+        }
+        counters.stages.path += performance.now() - t0;
+        counters.pathBytes += d.length;
+        const n = s.node('stems', 'path');
+        s.set(n, 'd', d);
+        s.set(n, 'fill', 'none');
+        s.set(n, 'stroke', look.color);
+        s.set(n, 'stroke-width', look.width);
+        s.set(n, 'stroke-linecap', a.cap ?? 'butt');
+        s.set(n, 'opacity', look.opacity);
+        s.set(n, 'stroke-dasharray', look.dash);
+    }
+}

package/dist/boxplot.d.ts

@@ -0,0 +1,57 @@
+import { type BarOptions } from './bars.ts';
+import type { HitMode } from './hit.ts';
+import type { PlatformNode } from './platform.ts';
+import { type PolygonSet, SeriesRenderer, type SeriesRendererAttributes, type Spread, type SpreadView } from './renderer.ts';
+import type { Series } from './series.ts';
+import type { Surface } from './surface.ts';
+export interface BoxPathAttributes extends Omit<SeriesRendererAttributes, 'bind'>, Omit<BarOptions, 'baseline'> {
+    /** The channel of the lower whisker's end. Default 'min'. */
+    low?: string;
+    /** The channel of the first quartile (the foot of the box). Default 'q1'. */
+    q1?: string;
+    /** The channel of the median. Default: the series' own value, which is what a data source's `value` names. */
+    median?: string;
+    /** The channel of the third quartile (the top of the box). Default 'q3'. */
+    q3?: string;
+    /** The channel of the upper whisker's end. Default 'max'. */
+    high?: string;
+    /** Width of the cap on each whisker, as a fraction of the box's width; 0 for none. Default 0.5. */
+    capWidth?: number;
+}
+export declare class BoxPath extends SeriesRenderer<BoxPathAttributes> {
+    #private;
+    static attrTypes: {
+        fill: 1;
+        maxNodes: 2;
+        stroke: 1;
+        strokeWidth: 2;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+        low: 1;
+        q1: 1;
+        median: 1;
+        q3: 1;
+        high: 1;
+        capWidth: 2;
+        width: 2;
+    };
+    private get names();
+    get channelNames(): readonly string[];
+    /** Half the width of a box, in the gaps between points, which the domain axis leaves room for. */
+    get spans(): number;
+    get hitMode(): HitMode;
+    spread(view: SpreadView): Spread | null;
+    limit(series: Series): Spread | null;
+    private box;
+    private line;
+    get swatch(): string;
+    sample(s: Surface, parent: PlatformNode, key: string, width: number, height: number): void;
+    /** Where everything goes, in plot pixels; made again only when the series has been projected again. */
+    private geometry;
+    shapes(): PolygonSet | null;
+    protected draw(): void;
+}

package/dist/boxplot.js

@@ -0,0 +1,177 @@
+/**
+ * Box and whisker: the five numbers that summarise a spread, one box for each point of a series.
+ *
+ *   <DomainSeries>
+ *     <ObjectDataSource source={rows} domain="group" value="median" channels={{ min: 'lo', q1: 'q1', q3: 'q3', max: 'hi' }} />
+ *     <BoxPath />
+ *   </DomainSeries>
+ *
+ * The box runs from the first to the third quartile with a line at the median, and whiskers go from it to the lowest and
+ * highest values. The median is the series' own value (what a source's `value` names), and the other four come from **channels** of
+ * the data called `min`, `q1`, `q3` and `max`, unless the `low`, `q1`, `q3` and `high` attributes name others (`median` can name a
+ * channel too), so numbers worked out elsewhere can be drawn as they are.
+ * `BoxStats` (stats.ts) is the other way to get them: a transform that works the five numbers out from the samples, with
+ * the points outside the whiskers as a second output to plot as markers.
+ *
+ * It is drawn in the plane's own terms like bars, so the domain on the vertical axis gives horizontal boxes and a polar plane
+ * gives wedges. A box is hit as a shape. The value axis reaches the whiskers; the width of a box is a band's own, else
+ * `width` (default 0.8) of the gap between points, and boxes in a `Stack` in 'group' mode sit side by side.
+ */
+/* 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 { NUMBER, STRING } from './attrs.js';
+import { layoutBars } from './bars.js';
+import { f2 } from './geometry.js';
+import { SeriesRenderer, paintBox } from './renderer.js';
+const REACH = 2;
+const MAX_ARC = 16;
+const clamp = (v) => (v < -REACH ? -REACH : v > 1 + REACH ? 1 + REACH : v);
+export class BoxPath extends SeriesRenderer {
+    static attrTypes = { ...SeriesRenderer.attrTypes, low: STRING, q1: STRING, median: STRING, q3: STRING, high: STRING, capWidth: NUMBER, width: NUMBER };
+    #geometry = null;
+    get names() {
+        const a = this.attrs;
+        return { low: a.low ?? 'min', q1: a.q1 ?? 'q1', median: a.median, q3: a.q3 ?? 'q3', high: a.high ?? 'max' };
+    }
+    get channelNames() { const n = this.names; return [...new Set([n.low, n.q1, ...(n.median ? [n.median] : []), n.q3, n.high])]; }
+    /** Half the width of a box, in the gaps between points, which the domain axis leaves room for. */
+    get spans() { return (this.attrs.width ?? 0.8) / 2; }
+    get hitMode() { return 'shape'; }
+    spread(view) {
+        const n = this.names, lo = view.channelColumn(n.low), hi = view.channelColumn(n.high);
+        let min = Infinity, max = -Infinity;
+        for (let i = 0; i < view.count; i++) {
+            const a = view.raw[i * view.stride + lo], b = view.raw[i * view.stride + hi];
+            if (Number.isFinite(a) && a < min)
+                min = a;
+            if (Number.isFinite(b) && b > max)
+                max = b;
+        }
+        return min <= max ? { second: { min, max } } : null;
+    }
+    limit(series) {
+        const n = this.names, lo = series.data.channelExtent(n.low), hi = series.data.channelExtent(n.high);
+        return lo && hi ? { second: { min: Math.min(lo.min, hi.min), max: Math.max(lo.max, hi.max) } } : null;
+    }
+    box() {
+        const a = this.attrs;
+        return this.styleFor(['seriesBox', 'shape'], { fill: a.fill, stroke: a.stroke, strokeWidth: a.strokeWidth, opacity: a.opacity }, { fill: this.requireParent().accentColor, stroke: this.requireParent().accentColor });
+    }
+    line() {
+        const a = this.attrs;
+        return this.styleFor(['boxLine', 'line'], { color: a.stroke, width: a.strokeWidth }, { color: this.requireParent().accentColor });
+    }
+    get swatch() { return this.box().fill; }
+    sample(s, parent, key, width, height) {
+        paintBox(s, parent, key, width, height, this.box());
+        const look = this.line(), m = s.node(`${key}/median`, 'path', { parent });
+        s.set(m, 'd', `M0 ${height / 2}H${width}`);
+        s.set(m, 'fill', 'none');
+        s.set(m, 'stroke', look.color);
+        s.set(m, 'stroke-width', look.width * 1.5);
+    }
+    /** Where everything goes, in plot pixels; made again only when the series has been projected again. */
+    geometry() {
+        const series = this.requireParent(), d = series.drawn, plane = d?.plane;
+        if (!d || !plane)
+            return null;
+        if (this.#geometry && this.#geometry.projection === series.projection)
+            return this.#geometry;
+        const lay = layoutBars(series, this.attrs);
+        if (!lay)
+            return null;
+        const names = this.names, n = lay.n, rs = d.stride, base = rs - d.channels.length;
+        const col = (name) => base + d.channels.indexOf(name);
+        const cols = [col(names.low), col(names.q1), names.median ? col(names.median) : d.secondColumn, col(names.q3), col(names.high)];
+        // The five values of each row on the value axis, as fractions.
+        const v = new Float64Array(n * 5);
+        for (let i = 0; i < n; i++)
+            for (let k = 0; k < 5; k++)
+                v[i * 5 + k] = d.raw[i * rs + cols[k]];
+        series.secondAxis.normalize(v, n * 5, 1, 0);
+        const steps = plane.curved ? Math.min(MAX_ARC, Math.max(2, Math.ceil(lay.slot * 64))) : 1, per = 2 * (steps + 1), median = steps + 1;
+        const cap = Math.max(0, this.attrs.capWidth ?? 0.5);
+        const total = n * (per + median + 8), out = new Float64Array(total * 2);
+        const boxAt = 0, medianAt = n * per, whiskerAt = medianAt + n * median, capAt = whiskerAt + n * 4;
+        for (let i = 0; i < n; i++) {
+            const x = lay.norm[3 * i] + lay.shift, x0 = x - lay.slot / 2;
+            const lo = v[i * 5], q1 = v[i * 5 + 1], med = v[i * 5 + 2], q3 = v[i * 5 + 3], hi = v[i * 5 + 4];
+            const bad = !Number.isFinite(x) || !Number.isFinite(lo) || !Number.isFinite(q1) || !Number.isFinite(med) || !Number.isFinite(q3) || !Number.isFinite(hi);
+            const put = (at, f, s) => { out[2 * at] = f; out[2 * at + 1] = bad ? NaN : Number.isFinite(f) ? clamp(s) : NaN; };
+            let k = boxAt + i * per;
+            for (let j = 0; j <= steps; j++)
+                put(k++, x0 + (lay.slot * j) / steps, q1);
+            for (let j = steps; j >= 0; j--)
+                put(k++, x0 + (lay.slot * j) / steps, q3);
+            k = medianAt + i * median;
+            for (let j = 0; j <= steps; j++)
+                put(k++, x0 + (lay.slot * j) / steps, med);
+            k = whiskerAt + i * 4;
+            put(k++, x, q3);
+            put(k++, x, hi);
+            put(k++, x, q1);
+            put(k, x, lo);
+            k = capAt + i * 4;
+            const c = (lay.slot * cap) / 2;
+            put(k++, x - c, hi);
+            put(k++, x + c, hi);
+            put(k++, x - c, lo);
+            put(k, x + c, lo);
+        }
+        // `put` clamps the value but the domain half of an outline is exact; NaN is already in the second coordinate of a bad row, so mirror it.
+        for (let i = 0; i < total; i++)
+            if (!Number.isFinite(out[2 * i + 1]))
+                out[2 * i] = NaN;
+        plane.place({ data: out, stride: 2, count: total }, series.firstAxis, series.secondAxis);
+        return (this.#geometry = { projection: series.projection, n, per, steps, data: out });
+    }
+    shapes() {
+        const g = this.geometry();
+        return g ? { data: g.data.subarray(0, g.n * g.per * 2), perShape: g.per, count: g.n } : null;
+    }
+    draw() {
+        const s = this.surface, g = this.geometry(), box = this.box(), line = this.line();
+        let boxes = '', medians = '', whiskers = '';
+        if (g) {
+            const path = (from, count, close) => {
+                let d = '';
+                for (let j = 0; j < count; j++) {
+                    const x = g.data[2 * (from + j)], y = g.data[2 * (from + j) + 1];
+                    if (!(Number.isFinite(x) && Number.isFinite(y)))
+                        return '';
+                    d += `${j === 0 ? 'M' : 'L'}${f2(x)} ${f2(y)}`;
+                }
+                return d + (close ? 'Z' : '');
+            };
+            const { n, per, steps } = g, median = steps + 1, medianAt = n * per, whiskerAt = medianAt + n * median, capAt = whiskerAt + n * 4;
+            for (let i = 0; i < n; i++) {
+                const b = path(i * per, per, true);
+                if (!b)
+                    continue;
+                boxes += b;
+                medians += path(medianAt + i * median, median, false);
+                whiskers += path(whiskerAt + i * 4, 2, false) + path(whiskerAt + i * 4 + 2, 2, false);
+                if ((this.attrs.capWidth ?? 0.5) > 0)
+                    whiskers += path(capAt + i * 4, 2, false) + path(capAt + i * 4 + 2, 2, false);
+            }
+        }
+        const whisker = s.node('whiskers', 'path');
+        s.set(whisker, 'd', whiskers);
+        s.set(whisker, 'fill', 'none');
+        s.set(whisker, 'stroke', line.color);
+        s.set(whisker, 'stroke-width', line.width);
+        s.set(whisker, 'opacity', line.opacity);
+        const b = s.node('boxes', 'path');
+        s.set(b, 'd', boxes);
+        s.set(b, 'fill', box.fill);
+        s.set(b, 'fill-opacity', box.opacity);
+        s.set(b, 'stroke', box.stroke);
+        s.set(b, 'stroke-width', box.strokeWidth);
+        s.set(b, 'stroke-linejoin', 'round');
+        const m = s.node('medians', 'path');
+        s.set(m, 'd', medians);
+        s.set(m, 'fill', 'none');
+        s.set(m, 'stroke', line.color);
+        s.set(m, 'stroke-width', line.width * 1.5);
+        s.set(m, 'opacity', line.opacity);
+    }
+}

package/dist/boxzoom.d.ts

@@ -0,0 +1,39 @@
+import { Axis } from './axis.ts';
+import { type BaseAttributes, ChartElement, type ElementRef } from './element.ts';
+import { inputOf } from './input.ts';
+import { type ChartEvent } from './events.ts';
+import type { Plane } from './plane.ts';
+export interface BoxZoomAttributes extends BaseAttributes {
+    /** The axes it may zoom, as elements or ids. Default: all of the plane's that can be followed along (not the rim of a polar plane). */
+    axes?: readonly ElementRef<Axis>[];
+    /** When a drag makes a box: with Shift held (the default), so a plain drag can pan, or always. */
+    activate?: 'shift' | 'always';
+    /** Which axes the box zooms. Default 'xy'. */
+    mode?: 'xy' | 'x' | 'y' | 'auto';
+    /** Smallest side of a box, in pixels, along an axis it zooms; below that the box does nothing. Default 8. */
+    minSize?: number;
+    /** Called after a zoom, with the box in plot pixels. */
+    onZoom?: (box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => void;
+}
+export declare class BoxZoom extends ChartElement<Plane, [], BoxZoomAttributes> {
+    #private;
+    static takesInput: typeof inputOf;
+    static attrTypes: {
+        minSize: 2;
+        onZoom: 0;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** True while a box is being drawn. */
+    get selecting(): boolean;
+    onEvent(ev: ChartEvent): void;
+}

package/dist/boxzoom.js

@@ -0,0 +1,138 @@
+/**
+ * Box zoom: drag a rectangle on the plot and the axes zoom to it.
+ *
+ *   new CartesianPlane({}, x, y, series, new BoxZoom(), new PanZoom())
+ *
+ * It is a plane child like `PanZoom`, and the two share the plane: by default (`activate: 'shift'`) the box is drawn with
+ * Shift held and a plain drag still pans. With `activate: 'always'` every drag is a box, which suits a chart whose `PanZoom`
+ * has `pan: false`. A box takes a press, so it has to come **before** `PanZoom` in the plane (as a `PointerListener` does).
+ *
+ * `mode` is which axes the box zooms: both, only the horizontal ones, only the vertical ones, or 'auto', which takes the one
+ * direction the box is much longer in (a wide, flat box zooms x alone) and both otherwise. It sets the same view ranges
+ * `PanZoom` does, so a pinch, a reset and `setViewRange(null)` all undo it. A box smaller than `minSize` pixels is not a box
+ * and does nothing, which is how to take one back: drag it small again before letting go. It looks as `selection` says (a shape).
+ *
+ * A touch makes no box: two fingers pinch. A rim (polar or radar plane) cannot be boxed.
+ */
+import { AUTO, NUMBER } from './attrs.js';
+import { Axis } from './axis.js';
+import { ChartElement, fail, resolveRef } from './element.js';
+import { inputOf } from './input.js';
+import { EVENT_ATTACH, EVENT_PAINT, EVENT_POINTER } from './events.js';
+import { f2 } from './geometry.js';
+export class BoxZoom extends ChartElement {
+    static takesInput = inputOf;
+    static attrTypes = { ...ChartElement.attrTypes, minSize: NUMBER, onZoom: AUTO };
+    #from = null;
+    #to = { x: 0, y: 0 };
+    /** True while a box is being drawn. */
+    get selecting() { return this.#from !== null; }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_ATTACH: {
+                const plane = this.requireParent();
+                for (const sibling of plane) {
+                    if (sibling === this)
+                        break;
+                    if (sibling.claimsPress)
+                        fail('add a BoxZoom before PanZoom in a plane: the box has to see a press first to take it');
+                }
+                return;
+            }
+            case EVENT_PAINT:
+                this.#paint();
+                return;
+            case EVENT_POINTER:
+                this.#pointer(ev);
+                return;
+        }
+    }
+    #pointer(ev) {
+        if (ev.pointerType === 'touch' || ev.kind === 'wheel' || ev.kind === 'pinch')
+            return;
+        const plane = this.requireParent(), a = this.attrs, r = plane.rect;
+        const clampX = (x) => Math.min(r.width, Math.max(0, x)), clampY = (y) => Math.min(r.height, Math.max(0, y));
+        switch (ev.kind) {
+            case 'down':
+                if (ev.handled || ev.outside || !(ev.buttons & 1) || !plane.covers(ev.x, ev.y))
+                    return;
+                if ((a.activate ?? 'shift') === 'shift' && !ev.shift)
+                    return;
+                this.#from = this.#to = { x: ev.x, y: ev.y };
+                this.chart?.platform?.setCursor?.('crosshair');
+                this.invalidate();
+                ev.handled = true;
+                return;
+            case 'move':
+                if (!this.#from)
+                    return;
+                if (!(ev.buttons & 1)) {
+                    this.#cancel();
+                    return;
+                }
+                this.#to = { x: clampX(ev.x), y: clampY(ev.y) };
+                this.invalidate();
+                ev.handled = true;
+                return;
+            case 'up': {
+                const from = this.#from;
+                if (!from)
+                    return;
+                const to = { x: clampX(ev.x), y: clampY(ev.y) };
+                this.#cancel();
+                this.#zoom(from, to);
+                ev.handled = true;
+                return;
+            }
+            case 'leave':
+                return;
+        }
+    }
+    #cancel() {
+        this.#from = null;
+        this.chart?.platform?.setCursor?.('');
+        this.invalidate();
+    }
+    /** The axes this may zoom. */
+    #axes() {
+        const a = this.attrs;
+        const axes = a.axes ? a.axes.map((ref) => resolveRef(ref, this, Axis)) : [...this.requireParent().axes];
+        return axes.filter((axis) => axis.ruler.fractionAt);
+    }
+    #zoom(from, to) {
+        const w = Math.abs(to.x - from.x), h = Math.abs(to.y - from.y), min = this.attrs.minSize ?? 8, mode = this.attrs.mode ?? 'xy';
+        // 'auto': a box much longer one way than the other is a zoom along that way only.
+        const only = mode === 'auto' ? (w > 3 * h ? 'x' : h > 3 * w ? 'y' : 'xy') : mode;
+        const alongX = only !== 'y', alongY = only !== 'x';
+        if ((alongX && w < min) || (alongY && h < min))
+            return;
+        for (const axis of this.#axes()) {
+            const ruler = axis.ruler, at = ruler.fractionAt;
+            if (!at || (ruler.horizontal ? !alongX : !alongY))
+                continue; // `#axes` keeps only rulers that have one
+            const v0 = axis.denormalize(at.call(ruler, from.x, from.y)), v1 = axis.denormalize(at.call(ruler, to.x, to.y));
+            if (v0 !== v0 || v1 !== v1 || v0 === v1)
+                continue;
+            axis.setViewRange({ min: Math.min(v0, v1), max: Math.max(v0, v1) });
+        }
+        this.attrs.onZoom?.({ x: Math.min(from.x, to.x), y: Math.min(from.y, to.y), width: w, height: h });
+    }
+    #paint() {
+        const s = this.surface, from = this.#from;
+        if (!from) {
+            s.remove('box');
+            return;
+        }
+        const look = this.styleFor(['selection', 'shape']), to = this.#to;
+        const node = s.node('box', 'rect', { above: true });
+        s.set(node, 'x', f2(Math.min(from.x, to.x)));
+        s.set(node, 'y', f2(Math.min(from.y, to.y)));
+        s.set(node, 'width', f2(Math.abs(to.x - from.x)));
+        s.set(node, 'height', f2(Math.abs(to.y - from.y)));
+        s.set(node, 'fill', look.fill);
+        s.set(node, 'stroke', look.stroke);
+        s.set(node, 'stroke-width', look.strokeWidth);
+        s.set(node, 'opacity', look.opacity);
+        s.set(node, 'pointer-events', 'none');
+    }
+}