inkplot 0.0.1-placeholder.0 → 1.0.0-beta.1

package/dist/panzoom.js

@@ -0,0 +1,467 @@
+/** Pan and zoom: pointer input turned into a change of view on a plane's axes. */
+/* 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, BOOLEAN } from './attrs.js';
+import { writeAria } from './aria.js';
+import { Axis } from './axis.js';
+import { ChartElement, resolveRef } from './element.js';
+import { inputOf } from './input.js';
+import { EVENT_FOCUS, EVENT_KEY, EVENT_PAINT, EVENT_POINTER } from './events.js';
+import { drawFocusRing, makeTabStop } from './focus.js';
+/**
+ * The keys it answers to unless told otherwise. Arrows move the view a step; with Shift, or the Page keys, a page. `+` and `-`
+ * (with the `=` and `_` that share their keys) zoom about the middle, and `0` or Home puts the view back.
+ */
+export const DEFAULT_PANZOOM_KEYS = {
+    left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'],
+    pageLeft: [], pageRight: [], pageUp: ['PageUp'], pageDown: ['PageDown'],
+    zoomIn: ['+', '='], zoomOut: ['-', '_'], reset: ['0', 'Home'],
+};
+/** For each moving action: along a horizontal axis or not, which way along it (+1 towards higher values), and whether it is a page. */
+const MOVES = {
+    left: [true, -1, false], right: [true, 1, false], up: [false, 1, false], down: [false, -1, false],
+    pageLeft: [true, -1, true], pageRight: [true, 1, true], pageUp: [false, 1, true], pageDown: [false, -1, true],
+};
+/** Fractions of the view moved by an arrow, and by a page. */
+const KEY_STEP = 0.1;
+const KEY_PAGE = 0.5;
+const KEY_ZOOM = 1.25;
+/** Least distance in pixels between two fingers along an axis for the pinch to zoom it; closer than that it only pans along. */
+const PINCH_MIN_SPAN = 24;
+/** Zoom per pixel of a trackpad pinch (a wheel turn with Ctrl held), as a natural-log factor. */
+const PINCH_SPEED = 0.02;
+/** A flick: it counts if the finger moved within `FLICK_REST` ms of letting go, at least `FLICK_MIN` px/ms measured over the last `FLICK_WINDOW` ms; speed falls by 1/e every `FLICK_TAU` ms down to `FLICK_STOP`. */
+const FLICK_REST = 80, FLICK_WINDOW = 100, FLICK_MIN = 0.15, FLICK_TAU = 325, FLICK_STOP = 0.02;
+/**
+ * Pan and zoom for the plane it sits in: a plane child that turns pointer input into view ranges on axes.
+ * Everything is worked out in the fractions of the scale, so it behaves the same on a linear axis, an inverted one,
+ * one on the far side, or one with a different scale: the value under the pointer stays under the pointer.
+ *
+ * It does not know what a plane looks like. Each axis' `Ruler` says how far along it a plot position is (`fractionAt`),
+ * so dragging along a spoke or a rectangle's edge is the same code; an axis whose ruler cannot say (the rim) is left alone.
+ */
+export class PanZoom extends ChartElement {
+    static takesInput = inputOf;
+    static attrTypes = { ...ChartElement.attrTypes, keyStep: NUMBER, keyZoom: NUMBER, pinchSpeed: NUMBER, inertia: BOOLEAN, axisZoom: BOOLEAN, resetOnDoubleClick: BOOLEAN, zoomSpeed: NUMBER, keys: { pageLeft: AUTO, pageRight: AUTO, pageUp: AUTO, pageDown: AUTO, zoomIn: AUTO, zoomOut: AUTO } };
+    // The drag in progress, with each axis' range as it was at the start; and the last press, for double-click detection.
+    #drag = null;
+    /** A flick in progress: stopped by the next touch, wheel or reset. */
+    #coast = null;
+    #touches = new Map();
+    #pinch = null;
+    #lastDown = { time: -Infinity, x: 0, y: 0 };
+    /** Put every controlled axis back to the range its data asks for. */
+    reset() {
+        this.#stopCoast();
+        for (const { axis } of this.controlled())
+            axis.setViewRange(null);
+    }
+    /** Marks it for `PointerListener`, which must come before it: it takes presses, so what it claims is not ours. */
+    claimsPress = true;
+    #focusNode = null;
+    #ring = false;
+    #lastKeys = '';
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_PAINT:
+                this.#paintFocus();
+                if (this.attrs.pan !== false || this.attrs.zoom !== false)
+                    this.chart?.platform?.setTouchMode?.(this.attrs.touch === 'always' ? 'always' : 'two-finger');
+                return;
+            case EVENT_KEY:
+                this.#key(ev);
+                return;
+            case EVENT_FOCUS:
+                if (ev.focused) {
+                    this.#focusNode = ev.node;
+                    this.#ring = ev.visible;
+                }
+                else if (this.#focusNode === ev.node) {
+                    this.#focusNode = null;
+                    this.#ring = false;
+                }
+                this.invalidate();
+                return;
+        }
+        if (ev.type !== EVENT_POINTER)
+            return;
+        const a = this.attrs, platform = this.chart?.platform;
+        // An element ahead of this one (a `PointerListener`) may already have used a press or claimed the cursor.
+        if (ev.handled && (ev.kind === 'down' || ev.kind === 'move') && !this.#drag && !this.#pinch)
+            return;
+        // Beside the plot, over an axis, only when asked: with `axisZoom` off the axes are inert.
+        if (ev.outside && a.axisZoom === false && !this.#drag && !this.#pinch)
+            return;
+        if (ev.pointerType === 'touch' && ev.kind !== 'wheel' && ev.kind !== 'pinch') {
+            this.#touch(ev);
+            return;
+        }
+        switch (ev.kind) {
+            case 'down': {
+                if (!(ev.buttons & 1))
+                    break;
+                if (this.#doubleClick(ev))
+                    break;
+                if (a.pan === false)
+                    break;
+                this.#drag = { id: ev.id, x: ev.x, y: ev.y, moves: this.targets(ev.axis) };
+                platform?.setCursor?.('grabbing');
+                ev.handled = true;
+                break;
+            }
+            case 'move': {
+                const drag = this.#drag;
+                if (!drag) {
+                    if (a.pan !== false)
+                        platform?.setCursor?.('grab');
+                    break;
+                }
+                if (!(ev.buttons & 1)) {
+                    this.#drag = null;
+                    platform?.setCursor?.('grab');
+                    break;
+                }
+                for (const { axis, at, snap } of drag.moves)
+                    this.apply(axis, { snap, scale: 1, anchor: 0, shift: at(drag.x, drag.y) - at(ev.x, ev.y) });
+                ev.handled = true;
+                break;
+            }
+            case 'up':
+                if (this.#drag) {
+                    this.#drag = null;
+                    platform?.setCursor?.('grab');
+                    ev.handled = true;
+                }
+                break;
+            case 'leave':
+                platform?.setCursor?.('');
+                break;
+            case 'wheel': {
+                this.#stopCoast();
+                const targets = this.targets(ev.axis);
+                if (targets.length === 0)
+                    break;
+                // A turn that is mostly sideways moves the view along (a trackpad's two-finger swipe, or Shift and the wheel).
+                if (!ev.ctrl && Math.abs(ev.deltaX) > Math.abs(ev.deltaY)) {
+                    if (a.pan === false)
+                        break;
+                    for (const { axis, at, snap } of targets) {
+                        if (axis.ruler.horizontal)
+                            this.apply(axis, { snap, scale: 1, anchor: 0, shift: at(ev.x + ev.deltaX, ev.y) - at(ev.x, ev.y) });
+                    }
+                    ev.handled = true;
+                    break;
+                }
+                if (a.zoom === false || ev.deltaY === 0)
+                    break;
+                // A pinch on a trackpad arrives as a wheel turn with Ctrl held, in much smaller steps than a wheel's notch: it gets its own speed.
+                const speed = ev.ctrl ? (a.pinchSpeed ?? PINCH_SPEED) : (a.zoomSpeed ?? 0.002);
+                const scale = Math.exp(ev.deltaY * speed);
+                for (const { axis, at, snap } of targets)
+                    this.apply(axis, { snap, scale, anchor: at(ev.x, ev.y), shift: 0 });
+                ev.handled = true;
+                break;
+            }
+            case 'pinch': {
+                // A gesture the platform recognised (Safari): the fingers spread by `scale`, so the view shrinks by it.
+                const targets = this.targets(ev.axis);
+                if (a.zoom === false || targets.length === 0 || !(ev.scale > 0))
+                    break;
+                for (const { axis, at, snap } of targets)
+                    this.apply(axis, { snap, scale: 1 / ev.scale, anchor: at(ev.x, ev.y), shift: 0 });
+                ev.handled = true;
+                break;
+            }
+        }
+    }
+    /** Two presses close together reset the axis under them, or all of them. True when this press was the second. */
+    #doubleClick(ev) {
+        const now = performance.now(), last = this.#lastDown;
+        if (this.attrs.resetOnDoubleClick !== false && now - last.time < 350 && Math.hypot(ev.x - last.x, ev.y - last.y) < 6) {
+            this.#lastDown = { time: -Infinity, x: 0, y: 0 };
+            for (const { axis } of this.targets(ev.axis))
+                axis.setViewRange(null);
+            ev.handled = true;
+            return true;
+        }
+        this.#lastDown = { time: now, x: ev.x, y: ev.y };
+        return false;
+    }
+    /**
+     * Touch: one finger pans (unless `touch` is 'two-finger', where the page keeps it for scrolling) and two fingers pinch.
+     * A pinch keeps the content under each finger under it, so it zooms and pans in the same movement; on an axis along which
+     * the fingers are barely apart it only pans, so a level pinch zooms the horizontal axes alone and a plumb one the vertical.
+     */
+    #touch(ev) {
+        const a = this.attrs, always = a.touch === 'always', touches = this.#touches;
+        switch (ev.kind) {
+            case 'down': {
+                this.#stopCoast();
+                touches.set(ev.id, { x: ev.x, y: ev.y, axis: ev.axis });
+                if (touches.size === 2 && a.zoom !== false) {
+                    this.#drag = null;
+                    this.#startPinch();
+                    ev.handled = true;
+                }
+                else if (touches.size === 1) {
+                    if (this.#doubleClick(ev))
+                        break;
+                    if (always && a.pan !== false) {
+                        this.#drag = { id: ev.id, x: ev.x, y: ev.y, moves: this.targets(ev.axis), samples: [{ t: performance.now(), x: ev.x, y: ev.y }] };
+                        ev.handled = true;
+                    }
+                }
+                break;
+            }
+            case 'move': {
+                const t = touches.get(ev.id);
+                if (!t)
+                    break;
+                t.x = ev.x;
+                t.y = ev.y;
+                if (this.#pinch) {
+                    this.#movePinch();
+                    ev.handled = true;
+                    break;
+                }
+                const drag = this.#drag;
+                if (drag && drag.id === ev.id) {
+                    for (const { axis, at, snap } of drag.moves)
+                        this.apply(axis, { snap, scale: 1, anchor: 0, shift: at(drag.x, drag.y) - at(ev.x, ev.y) });
+                    drag.samples?.push({ t: performance.now(), x: ev.x, y: ev.y });
+                    if (drag.samples && drag.samples.length > 8)
+                        drag.samples.shift();
+                    ev.handled = true;
+                }
+                break;
+            }
+            case 'up': {
+                touches.delete(ev.id);
+                if (this.#drag?.id === ev.id) {
+                    const drag = this.#drag;
+                    this.#drag = null;
+                    if (a.inertia !== false && !this.#pinch)
+                        this.#flick(drag);
+                }
+                if (this.#pinch) {
+                    this.#pinch = null;
+                    // In 'always' the finger that is left carries on as a pan from where it is.
+                    const [rest] = [...touches];
+                    if (always && a.pan !== false && rest) {
+                        this.#drag = { id: rest[0], x: rest[1].x, y: rest[1].y, moves: this.targets(rest[1].axis) };
+                    }
+                }
+                ev.handled = true;
+                break;
+            }
+        }
+    }
+    #stopCoast() {
+        this.#coast?.cancel();
+        this.#coast = null;
+    }
+    /** The finger left while moving: carry on at its speed, slowing as a flick does, a frame at a time until it is slow enough to stop. */
+    #flick(drag) {
+        const platform = this.chart?.platform, samples = drag.samples;
+        if (!platform?.schedule || !samples || samples.length < 2)
+            return;
+        const now = performance.now(), last = samples[samples.length - 1];
+        if (now - last.t > FLICK_REST)
+            return; // it stopped before it let go
+        const first = samples.find((p) => last.t - p.t <= FLICK_WINDOW) ?? last;
+        const dt = Math.max(last.t - first.t, 1);
+        let vx = (last.x - first.x) / dt, vy = (last.y - first.y) / dt;
+        if (Math.hypot(vx, vy) < FLICK_MIN)
+            return;
+        // Virtual finger position, advanced by the speed each frame; the view follows it the way a drag would.
+        let x = last.x, y = last.y, then = now, stop = null, live = true;
+        const tick = () => {
+            stop = null;
+            const p = this.chart?.platform;
+            if (!live || !p?.schedule)
+                return;
+            const t = performance.now(), step = Math.min(t - then, 64);
+            then = t;
+            x += vx * step;
+            y += vy * step;
+            const decay = Math.exp(-step / FLICK_TAU);
+            vx *= decay;
+            vy *= decay;
+            for (const { axis, at, snap } of drag.moves)
+                this.apply(axis, { snap, scale: 1, anchor: 0, shift: at(drag.x, drag.y) - at(x, y) });
+            if (Math.hypot(vx, vy) < FLICK_STOP) {
+                this.#coast = null;
+                return;
+            }
+            stop = p.schedule(tick);
+        };
+        this.#coast = { cancel: () => { live = false; stop?.(); } };
+        stop = platform.schedule(tick);
+    }
+    #startPinch() {
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- the size of `#touches` was checked as two just above
+        const [[id1, p1], [id2, p2]] = [...this.#touches];
+        // Both fingers on one axis' strip: that axis alone.
+        const over = p1.axis && p1.axis === p2.axis && this.attrs.axisZoom !== false ? p1.axis : null;
+        const moves = this.targets(over).map((m) => ({ ...m, a1: m.at(p1.x, p1.y), a2: m.at(p2.x, p2.y), length: m.axis.ruler.length }));
+        this.#pinch = { ids: [id1, id2], moves };
+    }
+    #movePinch() {
+        const pinch = this.#pinch;
+        if (!pinch)
+            return;
+        const p1 = this.#touches.get(pinch.ids[0]), p2 = this.#touches.get(pinch.ids[1]);
+        if (!p1 || !p2)
+            return;
+        for (const m of pinch.moves) {
+            const b1 = m.at(p1.x, p1.y), b2 = m.at(p2.x, p2.y), span = m.a2 - m.a1, now = b2 - b1;
+            if (Math.abs(span) * m.length >= PINCH_MIN_SPAN && Math.abs(now) * m.length >= 1) {
+                const k = span / now;
+                this.apply(m.axis, { snap: m.snap, scale: k, anchor: 0, shift: m.a1 - b1 * k });
+            }
+            else {
+                this.apply(m.axis, { snap: m.snap, scale: 1, anchor: 0, shift: (m.a1 + m.a2) / 2 - (b1 + b2) / 2 });
+            }
+        }
+    }
+    /** The axes a gesture at an axis' strip moves: that axis alone (`axisZoom`), or everything it controls. */
+    targets(over) {
+        const all = this.controlled();
+        return over && this.attrs.axisZoom !== false ? all.filter((m) => m.axis === over) : all;
+    }
+    /** The keys in force: the defaults with the ones asked for laid over them, or none. */
+    get keyMap() {
+        const k = this.attrs.keys;
+        return k === false ? null : { ...DEFAULT_PANZOOM_KEYS, ...k };
+    }
+    /** The plot as a tab stop with the application role, which is what tells a screen reader to pass the arrow keys on to it. */
+    #paintFocus() {
+        const s = this.surface, plane = this.requireParent(), map = this.keyMap;
+        if (!map) {
+            s.removePrefix('focus');
+            s.remove('ring');
+            this.#lastKeys = '';
+            return;
+        }
+        const r = plane.rect, node = s.node('focus', 'rect', { above: true });
+        s.set(node, 'x', 0);
+        s.set(node, 'y', 0);
+        s.set(node, 'width', r.width);
+        s.set(node, 'height', r.height);
+        s.set(node, 'fill', 'none');
+        s.set(node, 'pointer-events', 'none');
+        makeTabStop(s, node);
+        writeAria(s, node, this.attrs.meta ?? (plane.attrs.meta?.title !== undefined ? { title: plane.attrs.meta.title } : undefined), { role: 'application' });
+        const shortcuts = [...new Set(Object.values(map).flat())].map((k) => (k === '+' ? 'Plus' : k === ' ' ? 'Space' : k)).join(' ');
+        if (shortcuts !== this.#lastKeys) {
+            this.#lastKeys = shortcuts;
+            s.set(node, 'aria-keyshortcuts', shortcuts);
+        }
+        inputOf(this.requireChart()).focusable(this, node);
+        this.#node = node;
+        drawFocusRing(s, 'ring', this.styleFor(['focusRing', 'line']), this.#ring ? { x: 3, y: 3, width: Math.max(0, r.width - 6), height: Math.max(0, r.height - 6) } : null);
+    }
+    #node = null;
+    /** Move the view by a fraction of itself along the way an action points, or zoom it about its middle, or reset it. */
+    #key(ev) {
+        const map = this.keyMap;
+        if (!map || ev.kind !== 'down' || ev.node !== this.#node || ev.ctrl || ev.alt)
+            return;
+        let action;
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- `for…in` gives `string`; the keys of `map` are `PanZoomAction`s
+        for (const name in map)
+            if (map[name].includes(ev.key)) {
+                action = name;
+                break;
+            }
+        if (!action)
+            return;
+        ev.handled = true;
+        const a = this.attrs;
+        if (action === 'reset') {
+            this.reset();
+            return;
+        }
+        if (action === 'zoomIn' || action === 'zoomOut') {
+            const k = a.keyZoom ?? KEY_ZOOM, scale = action === 'zoomIn' ? 1 / k : k;
+            for (const { axis, snap } of this.controlled())
+                this.apply(axis, { snap, scale, anchor: 0.5, shift: 0 });
+            return;
+        }
+        const [horizontal, sign, page] = MOVES[action];
+        const step = page || ev.shift ? Math.min(KEY_PAGE, 5 * (a.keyStep ?? KEY_STEP)) : (a.keyStep ?? KEY_STEP);
+        for (const { axis, snap } of this.controlled()) {
+            if (axis.ruler.horizontal === horizontal)
+                this.apply(axis, { snap, scale: 1, anchor: 0, shift: sign * step });
+        }
+    }
+    /** The axes this will move, as of now: the chosen ones (or all the plane's) that can be followed along and fit `direction`. */
+    controlled() {
+        const a = this.attrs, only = a.direction ?? 'both';
+        const axes = a.axes ? a.axes.map((ref) => resolveRef(ref, this, Axis)) : [...this.requireParent().axes];
+        const out = [];
+        for (const axis of axes) {
+            const at = axis.ruler.fractionAt;
+            if (at && (only === 'both' || axis.ruler.horizontal === (only === 'horizontal'))) {
+                out.push({ axis, at: at.bind(axis.ruler), snap: { ...(axis.viewRange ?? axis.range) } });
+            }
+        }
+        return out;
+    }
+    /**
+     * What the limit is measured against: the range all of the data on this axis asks for, not the part in view.
+     * (If it were the part in view, zooming one axis would move the limit of the other under your hand.)
+     */
+    limitFor(axis) {
+        let lo = Infinity, hi = -Infinity;
+        for (const series of this.requireParent().series) {
+            const extent = series.extentFor(axis);
+            if (extent) {
+                if (extent.min < lo)
+                    lo = extent.min;
+                if (extent.max > hi)
+                    hi = extent.max;
+            }
+        }
+        return axis.fit(lo, hi);
+    }
+    /** Applies the change and sets the axis' view range; a view that covers the natural range is recorded as no view at all. */
+    apply(axis, change) {
+        const view = this.viewFor(axis, change);
+        if (view !== null)
+            axis.setViewRange(view === 'natural' ? null : view);
+    }
+    /**
+     * The new range, 'natural' if the change ends up covering all of it, or null to leave things as they are.
+     * A display fraction `d` along the axis is `u` in the scale's own fractions, flipped when the axis is inverted.
+     */
+    viewFor(axis, { snap, scale: k, anchor, shift }) {
+        const scale = axis.scale, inverted = axis.attrs.inverted === true;
+        const map = (u) => {
+            const d = inverted ? 1 - u : u;
+            const moved = anchor + (d - anchor) * k + shift;
+            return inverted ? 1 - moved : moved;
+        };
+        let u0 = map(0), u1 = map(1);
+        if (this.attrs.limit !== false) {
+            const wanted = this.limitFor(axis);
+            const natural = new Float64Array([wanted.min, wanted.max]);
+            scale.normalize(natural, 2, 1, 0, snap);
+            const lo = Math.min(natural[0], natural[1]), hi = Math.max(natural[0], natural[1]);
+            if (u1 - u0 >= hi - lo)
+                return 'natural';
+            if (u0 < lo) {
+                u1 += lo - u0;
+                u0 = lo;
+            }
+            else if (u1 > hi) {
+                u0 -= u1 - hi;
+                u1 = hi;
+            }
+        }
+        const min = scale.denormalize(u0, snap), max = scale.denormalize(u1, snap);
+        // Past the precision of a double there is nothing left to zoom into.
+        if (!(max - min > 1e-12 * Math.max(1, Math.abs(min), Math.abs(max))))
+            return null;
+        return { min, max };
+    }
+}

package/dist/plane.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Planes: a coordinate space that owns axes and series, lays them out and routes pointer input.
+ *
+ * How a plane, its axes and its series cooperate (the part that is hardest to see from any one file)
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * Sizes depend on ranges (wider tick labels need more margin) and ranges depend on sizes (decimation reads as many
+ * points as there are pixels). The plane breaks the circle by working in passes, in `arrange`:
+ *   1. Estimate the plot size (the available rectangle less a typical margin) and fit with it: `Plane.fit` has the
+ *      series declare their domain, load their data, and contribute value extents, then settles every axis' range.
+ *   2. With ranges known, the axes are measured (their tick labels give thickness) and the real plot rectangle is the
+ *      available area less those, with `insets` overriding.
+ *   3. With the real size known, the axes get their final `Ruler`s and each series is `project`ed: data → fractions
+ *      through the axes → pixels through the plane's `place`.
+ * The plane alone knows what the two axes *mean* spatially (`place`, and rulers), the axes alone know values ↔ fractions,
+ * and the series alone know data. That separation is why a radar chart only needs a new plane and the same series.
+ *
+ * A `Ruler` is the one thing an axis draws against: a line in plot pixels that maps a fraction 0..1 to a position and
+ * a normal. Straight edges, floating axes and radial spokes are all just different rulers, so Axis has no per-shape code.
+ */
+import { Axis, type AxisOrientation } from './axis.ts';
+import type { Chart } from './chart.ts';
+import type { PointBuffer } from './data.ts';
+import { type BaseAttributes, ChartElement } from './element.ts';
+import { type ChartEvent } from './events.ts';
+import type { CalloutAnnotation, LineAnnotation } from './annotation.ts';
+import { type Insets, type Rect, type Size } from './geometry.ts';
+import type { BoxZoom } from './boxzoom.ts';
+import type { Brush } from './brush.ts';
+import type { PanZoom } from './panzoom.ts';
+import type { PointerListener } from './pointer.ts';
+import type { PlatformNode } from './platform.ts';
+import { Series } from './series.ts';
+import type { Stack } from './stack.ts';
+import type { LineProps } from './theme.ts';
+export interface PlaneAttributes extends BaseAttributes {
+    /** Fixed margins round the plot (room for axes). Any side left out is sized to fit its axes. */
+    insets?: Partial<Insets>;
+}
+/** Open for augmentation: `declare module 'inkplot' { interface PlaneChildMap { mine: MyAnnotation } }`. */
+export interface PlaneChildMap {
+    axis: Axis;
+    series: Series;
+    stack: Stack;
+    lineAnnotation: LineAnnotation;
+    calloutAnnotation: CalloutAnnotation;
+    panZoom: PanZoom;
+    boxZoom: BoxZoom;
+    brush: Brush;
+    pointerListener: PointerListener;
+}
+export type PlaneChildren = PlaneChildMap[keyof PlaneChildMap][];
+/** What every plane does the same way: owns the axes and series among its children and runs the fit. */
+export declare abstract class Plane<A extends PlaneAttributes = PlaneAttributes> extends ChartElement<Chart, PlaneChildren, A> {
+    #private;
+    /** The allocated plot area, in the chart's coordinates. Valid after arrange. */
+    get rect(): Readonly<Rect>;
+    /** Subclasses record the plot area they settle on. */
+    protected setRect(rect: Rect): void;
+    get axes(): readonly Axis[];
+    /** Every series on the plane, in drawing order, those inside a `Stack` included, whether shown or not: the order that gives each its palette colour. */
+    get allSeries(): readonly Series[];
+    /** The series that are on show (`visible` is not false): the ones that are drawn, fit the axes and are hit. */
+    get series(): readonly Series[];
+    /**
+     * The axis a series uses when it does not name one, for the axis its first or its second coordinate rides on. What
+     * those are is up to the plane: a Cartesian plane's horizontal and vertical axes, a radial plane's angle and radius.
+     */
+    abstract defaultAxis(role: 'first' | 'second'): Axis | undefined;
+    /**
+     * Whether a line that is straight in the plane's own terms (constant value, say) comes out curved. False for a
+     * rectangle, true for anything with an angle. Annotations use it to decide how many points to trace a line with.
+     */
+    abstract get curved(): boolean;
+    /**
+     * Fractions of `axis` at which a line running along it changes direction, ascending, for planes that are not smooth
+     * (a radar's spokes). A line traced through these is exact where sampling evenly would cut the corners. Default none.
+     */
+    breaks(_axis: Axis): readonly number[];
+    /**
+     * About how long `axis` will be drawn, in pixels, given the room estimated for the plot, so that a series' reach in
+     * pixels can be turned into room in the axis' range. 0 where that has no meaning (the default, and any axis round a circle).
+     */
+    protected axisLength(_axis: Axis, _estimate: Size): number;
+    /** CSS reference to this plane's clip region, for children to clip themselves with. `null` when not clipped. */
+    abstract get clipUrl(): string | null;
+    /**
+     * The first two columns of `points`, normalized (0..1) through `first` and `second`, to plot-area pixels, in place.
+     * The plane decides what the two axes mean spatially: a Cartesian plane looks at their sides.
+     */
+    abstract place(points: PointBuffer, first: Axis, second: Axis): void;
+    /**
+     * The inverse of `place` for one position: what a spot in plot pixels is in data terms, as the values `first` and
+     * `second` read there. It is what turns a dragged pointer into an edit. A position outside the plot gives values
+     * outside the axes' ranges; an angle that wraps comes back inside the range.
+     */
+    abstract unplace(x: number, y: number, first: Axis, second: Axis): readonly [first: number, second: number];
+    /** Put every axis of the plane back to the range its data asks for, undoing pan, zoom and box zoom. */
+    resetViews(): void;
+    /** Whether `axis` comes back round to where it started, so that its two ends are the same place (the angle of a full turn). Default no. */
+    cyclic(_axis: Axis): boolean;
+    /**
+     * The axis whose strip beside the plot a position (in plot pixels) is on, or null: the strip is where its line, ticks and labels
+     * are. This is what lets a wheel turn or a drag over an axis act on that axis alone. Default: none, so only the plot itself takes input.
+     */
+    axisAt(_x: number, _y: number): Axis | null;
+    /** Whether a position in plot pixels is on the plot: inside the rectangle, and for a circular plot inside the circle. Default: inside the rectangle. */
+    covers(x: number, y: number): boolean;
+    /**
+     * The line along which the first (or second) coordinate has the data value `value`, across the whole plot, as path data in
+     * plot pixels: a vertical line for a horizontal first axis, a spoke for an angle, a circle for a radius. It is what a
+     * crosshair draws, and is as the plane draws its own gridlines. Empty when the plane has no such axis.
+     */
+    guide(role: 'first' | 'second', value: number): string;
+    /**
+     * Give every axis an orientation and a stack slot: its own `orientation` attribute if it has one, else the next of
+     * `defaults` in child order. `check` rejects an orientation this kind of plane does not have. The slot counts how
+     * many axes share an orientation, so they can be stacked outwards.
+     */
+    protected assignAxes<O extends AxisOrientation>(defaults: readonly O[], check: (o: AxisOrientation) => O): void;
+    /** Put a resolved line look on a node of this plane (gridlines, frame). */
+    protected strokeWith(node: PlatformNode, look: LineProps): void;
+    /**
+     * The first half of every layout: start the axes, let the series name theirs, agree the domain before any data is
+     * read, then fill every series (which gives the value extents) and settle every range. `estimate` is how much room the
+     * plot is expected to have, which sizes decimation; the real plot is only known once the axes have been measured.
+     */
+    protected fit(estimate: Size): void;
+}
+export interface CartesianPlaneAttributes extends PlaneAttributes {
+    /** Lines at the first horizontal and first vertical axis' ticks. Default true. */
+    gridlines?: boolean;
+    /** Draw a border round the plot area, above the series. */
+    frame?: boolean;
+    /** Clip series to the plot area. Default true. */
+    clip?: boolean;
+}
+/** A fresh id for a plane's clip region, unique within the page. */
+export declare const nextClipId: () => string;
+/** The least room left round a plot, whatever the axes need. */
+export declare const MIN_INSET = 8;
+/** x/y plane: horizontal and vertical axes on its edges (or floating across it), clipped, with gridlines at the first axes' ticks. */
+export declare class CartesianPlane extends Plane<CartesianPlaneAttributes> {
+    private readonly clipId;
+    get clipUrl(): string | null;
+    get curved(): boolean;
+    protected axisLength(axis: Axis, estimate: Size): number;
+    /** The first coordinate is on the horizontal axis, the second on the vertical one. */
+    defaultAxis(role: 'first' | 'second'): Axis | undefined;
+    /**
+     * Fractions to pixels. The 'first' coordinate goes on whichever axis is horizontal, so a series' first/second
+     * columns need no knowledge of orientation (swapping axis sides transposes the plot).
+     */
+    place(points: PointBuffer, first: Axis, second: Axis): void;
+    unplace(x: number, y: number, first: Axis, second: Axis): readonly [number, number];
+    axisAt(x: number, y: number): Axis | null;
+    onEvent(ev: ChartEvent): void;
+    /**
+     * Where a floating axis crosses, as a fraction of the plot across the crossing axis (0 at the left or bottom, 1 at
+     * the right or top), or null for an axis fixed to a side. A position out of range is held at the nearest edge.
+     */
+    private crossing;
+    /** Whether an axis takes room round the plot: one fixed to a side does, and so does one held at the edge it faces. */
+    private reserves;
+    /**
+     * Every axis gets its place in a plot `w` by `h`: a fixed side, stacked outwards by the axes before it, or across the
+     * plot. Titles that are not on an axis line go outside everything else at their edge, one after another.
+     */
+    private setRulers;
+    /** Negotiates ranges, lays out the axes, projects every series. */
+    private arrange;
+    /** Clip region, gridlines (from the first horizontal and vertical axis) and frame. */
+    private paint;
+}