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

package/dist/marker.js

@@ -0,0 +1,213 @@
+import { fractionsOf, lookKey, lookValues, resolveBindings, stepsFor } from './bucket.js';
+import { EVENT_ATTACH } from './events.js';
+import { circlePath, f2 } from './geometry.js';
+import { SeriesRenderer } from './renderer.js';
+/** Points further than this outside the plot are skipped when a bound size cannot say how far a marker reaches. */
+const CULL_MARGIN = 16;
+/** Writes a bound value onto the style by property name: bindings are keyed by string, the style is a typed record. */
+const writeProperty = (v, property, value) => {
+    v[property] = value;
+};
+/**
+ * The common work of all markers: cull what is off the plot, work out each point's look from its bindings, and group
+ * points that look alike into one path.
+ *
+ * Why grouping: a scatter of 100k points as 100k nodes is slow to build and to render. Instead each bound style is
+ * quantized into a few steps, a point's look is the combination of its steps (the `key`), and every point with the same
+ * key joins a single path. The number of nodes is then bounded by `maxNodes`, not by the data. Geometry (a bubble's
+ * radius) is not quantized: it goes straight into the path data, which costs the same however it varies.
+ */
+export class Marker extends SeriesRenderer {
+    /** Its fill (or its stroke, for a marker that is only a stroke), unless that is bound to data. */
+    get swatch() {
+        const a = this.attrs, series = this.requireParent(), bind = a.bind;
+        if (bind?.fill || bind?.stroke)
+            return null;
+        const look = this.styleFor([this.kind, 'marker', 'shape'], { stroke: a.stroke, strokeWidth: a.strokeWidth, fill: a.fill, opacity: a.opacity }, this.accent(series.accentColor));
+        return look.fill && look.fill !== 'none' ? look.fill : look.stroke && look.stroke !== 'none' ? look.stroke : null;
+    }
+    /**
+     * One marker in the middle of the box, as big as it is on the plot (no bigger than the box). What is bound to data takes
+     * the value at the middle of its dimension, since a sample stands for no point in particular.
+     */
+    sample(s, parent, key, width, height) {
+        const a = this.attrs, series = this.requireParent();
+        const look = this.styleFor([this.kind, 'marker', 'shape'], { stroke: a.stroke, strokeWidth: a.strokeWidth, fill: a.fill, opacity: a.opacity }, this.accent(series.accentColor));
+        const v = { ...look, size: this.styleFor([this.kind, 'marker'], { size: a.size }).size };
+        for (const b of this.bindings)
+            writeProperty(v, b.property, b.axis.valueAt(0.5));
+        v.size = Math.min(v.size, width / 2, height / 2);
+        const n = s.node(key, 'path', { parent });
+        s.set(n, 'd', this.shape(width / 2, height / 2, v.size));
+        this.style(s, n, v);
+    }
+    /** Its size, or the largest a bound size gives, and a pixel for the stroke round it. */
+    get reach() {
+        const size = this.bindings.find((b) => !this.isGeometric(b.property) ? false : b.property === 'size');
+        const output = size?.axis?.output;
+        const r = output ? Math.max(output[0], output[1]) : this.styleFor([this.kind, 'marker'], { size: this.attrs.size }).size;
+        return r + 1;
+    }
+    // Which grouped nodes (by look key) and how many per-point nodes exist now, so the ones no longer used can be removed.
+    #keys = new Set();
+    #separate = 0;
+    /** The bound properties with their dimensions resolved. A property is stylistic unless the marker puts it in the path. */
+    get bindings() {
+        return resolveBindings(this.attrs.bind, this, (p) => this.isGeometric(p));
+    }
+    /** How many steps each stylistic binding is quantized to, so that the combinations stay within `maxNodes`. 0 when not grouping. */
+    get stepsPerBinding() {
+        return this.attrs.merge === false ? 0 : stepsFor(this.bindings, this.attrs.maxNodes ?? 1000);
+    }
+    onEvent(ev) {
+        if (ev.type === EVENT_ATTACH)
+            void this.stepsPerBinding; // throws now rather than at the first paint
+        super.onEvent(ev);
+    }
+    /**
+     * Three phases: (1) turn each bound channel into a column of 0..1 positions along its dimension; (2) walk the points,
+     * dropping gaps and those off the plot, building each marker's path data and choosing its node; (3) write the nodes
+     * and remove those that no longer have any marker.
+     */
+    draw(points) {
+        const series = this.requireParent(), plane = series.plane;
+        const a = this.attrs, s = this.surface, counters = this.counters;
+        const t0 = performance.now();
+        const { data, count, stride } = points;
+        const w = plane.rect.width, h = plane.rect.height;
+        const merge = a.merge !== false;
+        const local = { stroke: a.stroke, strokeWidth: a.strokeWidth, fill: a.fill, opacity: a.opacity };
+        const look = this.styleFor([this.kind, 'marker', 'shape'], local, this.accent(series.accentColor));
+        const base = { ...look, size: this.styleFor([this.kind, 'marker'], { size: a.size }).size };
+        // Each binding becomes a column of positions along its dimension, 0..1.
+        const channels = series.channels;
+        const bindings = this.bindings;
+        const fractions = bindings.map((b) => fractionsOf(b, data, 2 + channels.indexOf(b.channel), stride, count));
+        const styled = bindings.flatMap((b, i) => (b.stylistic ? [{ b, f: fractions[i] }] : []));
+        const geometric = bindings.flatMap((b, i) => (b.stylistic ? [] : [{ b, f: fractions[i] }]))[0];
+        const steps = this.stepsPerBinding;
+        let bytes = 0;
+        const paths = new Map(); // look key → the path data of every marker with that look
+        let separate = 0;
+        const v = { ...base };
+        // The style handed to `style()` starts from the constants each time, then has the bound values written over it.
+        const reset = () => Object.assign(v, base);
+        for (let i = 0; i < count; i++) {
+            const x = data[i * stride], y = data[i * stride + 1];
+            if (!Number.isFinite(x) || !Number.isFinite(y))
+                continue;
+            const r = geometric ? geometric.b.axis.valueAt(geometric.f[i]) : base.size;
+            if (!(r >= 0))
+                continue;
+            const reach = geometric || !styled.length ? r : CULL_MARGIN + r;
+            if (x < -reach || x > w + reach || y < -reach || y > h + reach)
+                continue;
+            const d = this.shape(x, y, r);
+            bytes += d.length;
+            if (merge) {
+                const key = lookKey(styled, i, steps);
+                paths.set(key, (paths.get(key) ?? '') + d);
+            }
+            else {
+                reset();
+                for (const { b, f } of styled)
+                    writeProperty(v, b.property, b.axis.valueAt(f[i]));
+                const node = s.node(`p${separate++}`, 'path');
+                s.set(node, 'd', d);
+                this.style(s, node, v);
+            }
+        }
+        counters.stages.path += performance.now() - t0;
+        counters.pathBytes += bytes;
+        if (merge) {
+            for (const key of this.#keys)
+                if (!paths.has(key))
+                    s.remove(`m${key}`);
+            for (let i = 0; i < this.#separate; i++)
+                s.remove(`p${i}`);
+            this.#separate = 0;
+            this.#keys = new Set(paths.keys());
+            for (const [key, d] of paths) {
+                reset();
+                lookValues(key, styled, steps, (property, value) => writeProperty(v, property, value));
+                const node = s.node(`m${key}`, 'path');
+                s.set(node, 'd', d);
+                this.style(s, node, v);
+            }
+        }
+        else {
+            for (const key of this.#keys)
+                s.remove(`m${key}`);
+            this.#keys.clear();
+            for (let i = separate; i < this.#separate; i++)
+                s.remove(`p${i}`);
+            this.#separate = separate;
+        }
+    }
+}
+/**
+ * A dot is a stroke with no length, as wide as the dot is: the cheapest marker, and the one a dense scatter wants.
+ * Since its size is a stroke width, a bound `size` is one of the quantized styles, unlike on the other markers.
+ */
+export class DotMarker extends Marker {
+    kind = 'dotMarker';
+    accent(color) { return { stroke: color }; }
+    shape(x, y) { return `M${f2(x)} ${f2(y)}h0`; }
+    isGeometric() { return false; }
+    style(s, n, v) {
+        s.set(n, 'fill', 'none');
+        s.set(n, 'stroke', v.stroke);
+        s.set(n, 'stroke-width', f2(2 * v.size));
+        s.set(n, 'stroke-linecap', this.attrs.cap ?? 'round');
+        s.set(n, 'opacity', Math.round(v.opacity * 1000) / 1000);
+    }
+}
+/** Shapes made of strokes. The size is in the path data, so it varies per point at no cost. */
+export class LineMarker extends Marker {
+    kind = 'lineMarker';
+    accent(color) { return { stroke: color }; }
+    isGeometric(property) { return property === 'size'; }
+    style(s, n, v) {
+        s.set(n, 'fill', 'none');
+        s.set(n, 'stroke', v.stroke);
+        s.set(n, 'stroke-width', f2(v.strokeWidth));
+        s.set(n, 'stroke-linecap', 'round');
+        s.set(n, 'opacity', Math.round(v.opacity * 1000) / 1000);
+    }
+}
+/** ×: two diagonals, `size` from the centre to each end. */
+export class CrossMarker extends LineMarker {
+    shape(x, y, r) {
+        return `M${f2(x - r)} ${f2(y - r)}l${f2(2 * r)} ${f2(2 * r)}M${f2(x - r)} ${f2(y + r)}l${f2(2 * r)} ${f2(-2 * r)}`;
+    }
+}
+/** +: a horizontal and a vertical stroke. */
+export class PlusMarker extends LineMarker {
+    shape(x, y, r) {
+        return `M${f2(x - r)} ${f2(y)}h${f2(2 * r)}M${f2(x)} ${f2(y - r)}v${f2(2 * r)}`;
+    }
+}
+/** Closed shapes, filled and stroked. The most flexible markers: stroke, stroke width, fill, opacity and size are all bindable. */
+export class ShapeMarker extends Marker {
+    kind = 'shapeMarker';
+    accent(color) { return { fill: color }; }
+    isGeometric(property) { return property === 'size'; }
+    style(s, n, v) {
+        s.set(n, 'fill', v.fill);
+        s.set(n, 'stroke', v.stroke);
+        s.set(n, 'stroke-width', f2(v.strokeWidth));
+        s.set(n, 'opacity', Math.round(v.opacity * 1000) / 1000);
+    }
+}
+/** A filled circle. A bubble series is this with `size` bound to a channel. */
+export class CircleMarker extends ShapeMarker {
+    shape(x, y, r) {
+        return circlePath(x, y, r);
+    }
+}
+/** A square, `size` from the centre to each side. */
+export class SquareMarker extends ShapeMarker {
+    shape(x, y, r) {
+        return `M${f2(x - r)} ${f2(y - r)}h${f2(2 * r)}v${f2(2 * r)}h${f2(-2 * r)}z`;
+    }
+}

package/dist/panzoom.d.ts

@@ -0,0 +1,119 @@
+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';
+/** What a key can do. */
+export type PanZoomAction = 'left' | 'right' | 'up' | 'down' | 'pageLeft' | 'pageRight' | 'pageUp' | 'pageDown' | 'zoomIn' | 'zoomOut' | 'reset';
+/** Keys, by `KeyboardEvent.key`, for each action. An action left out has the default keys; an empty list turns it off. */
+export type PanZoomKeys = Partial<Record<PanZoomAction, readonly string[]>>;
+/**
+ * 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 declare const DEFAULT_PANZOOM_KEYS: Readonly<Record<PanZoomAction, readonly string[]>>;
+export interface PanZoomAttributes extends BaseAttributes {
+    /** The axes it may move, as elements or ids. Default: all of the plane's that can be dragged along: not the rim of a polar or radar plane. */
+    axes?: readonly ElementRef<Axis>[];
+    /**
+     * Which way things may move. Default 'both'. Along one direction only, the other axes keep fitting what is in view.
+     * A radius axis counts as vertical.
+     */
+    direction?: 'both' | 'horizontal' | 'vertical';
+    /** Drag with the primary button to pan. Default true. */
+    pan?: boolean;
+    /** Turn the wheel to zoom about the pointer. Default true. */
+    zoom?: boolean;
+    /** Keep the view inside the natural range of each axis, so there is no panning off the data or zooming out past it. Default true. */
+    limit?: boolean;
+    /** Zoom per wheel pixel, as a natural-log factor. Default 0.002, which is about 20% for one notch of a typical wheel. */
+    zoomSpeed?: number;
+    /**
+     * With the pointer (or both fingers) over an axis, a wheel turn, a pinch or a drag moves that axis alone. Default true. Off,
+     * the axes beside the plot take no input and a gesture always moves every axis, about the pointer.
+     */
+    axisZoom?: boolean;
+    /** Zoom per pixel of a pinch on a trackpad, which browsers report as small wheel turns with Ctrl held. Default 0.02, ten times the wheel's step per pixel. */
+    pinchSpeed?: number;
+    /**
+     * What a touch does. 'two-finger' (the default): one finger scrolls the page as usual, and two pinch and pan the chart.
+     * 'always': one finger pans the chart too, and the page cannot be scrolled from it.
+     */
+    touch?: 'two-finger' | 'always';
+    /**
+     * A finger that lets go while still moving carries the view on, slowing to a stop (a flick). Default true. Only a touch
+     * flicks, and only where one finger pans (`touch: 'always'`); a mouse drag stops where it is released.
+     */
+    inertia?: boolean;
+    /** Two quick presses put every axis back to its natural range. Default true. */
+    resetOnDoubleClick?: boolean;
+    /**
+     * The keys, once the plot has keyboard focus. It is a tab stop, so Tab reaches it. Give the keys for the actions to change
+     * (`{ zoomIn: ['i'], reset: ['r'] }`; the others keep their defaults, see `DEFAULT_PANZOOM_KEYS`), or `false` for no keyboard
+     * control and no tab stop. Name the plot with `meta.title` (on this, or on its plane), which is what a screen reader says
+     * on arriving.
+     */
+    keys?: PanZoomKeys | false;
+    /** How far an arrow moves the view, as a fraction of it. Default 0.1. A page is five times that, up to half. */
+    keyStep?: number;
+    /** The factor of one press of a zoom key. Default 1.25. */
+    keyZoom?: number;
+}
+/**
+ * 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 declare class PanZoom extends ChartElement<Plane, [], PanZoomAttributes> {
+    #private;
+    static takesInput: typeof inputOf;
+    static attrTypes: {
+        keyStep: 2;
+        keyZoom: 2;
+        pinchSpeed: 2;
+        inertia: 3;
+        axisZoom: 3;
+        resetOnDoubleClick: 3;
+        zoomSpeed: 2;
+        keys: {
+            pageLeft: 0;
+            pageRight: 0;
+            pageUp: 0;
+            pageDown: 0;
+            zoomIn: 0;
+            zoomOut: 0;
+        };
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** Put every controlled axis back to the range its data asks for. */
+    reset(): void;
+    /** Marks it for `PointerListener`, which must come before it: it takes presses, so what it claims is not ours. */
+    readonly claimsPress = true;
+    onEvent(ev: ChartEvent): void;
+    /** The axes a gesture at an axis' strip moves: that axis alone (`axisZoom`), or everything it controls. */
+    private targets;
+    /** The keys in force: the defaults with the ones asked for laid over them, or none. */
+    get keyMap(): PanZoomKeys | null;
+    /** The axes this will move, as of now: the chosen ones (or all the plane's) that can be followed along and fit `direction`. */
+    private controlled;
+    /**
+     * 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.)
+     */
+    private limitFor;
+    /** Applies the change and sets the axis' view range; a view that covers the natural range is recorded as no view at all. */
+    private apply;
+    /**
+     * 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.
+     */
+    private viewFor;
+}