inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/png.js

@@ -0,0 +1,71 @@
+/**
+ * A chart as a PNG in the browser: `toPng(chart)` for one on the page, `svgToPng(svg)` for an SVG string you already have.
+ *
+ *   const blob = await toPng(chart, { scale: 2, background: '#fff' });
+ *
+ * It draws the chart's SVG into a canvas, which is the one thing a browser does that node does not, so it lives apart from
+ * the core and costs nothing unless imported. For a chart on the page it takes the SVG that is showing, so the picture is
+ * what the person sees; for one not attached it renders a copy with `toSvgString` and leaves the chart as it was.
+ * `scale` multiplies the pixel size (2 for a sharp picture on a dense screen). Fonts the page loaded are not
+ * available to an SVG drawn as an image, so text falls back to the system's; names a system has (the default
+ * `system-ui`) come out right. A transparent background stays transparent unless `background` says otherwise. On a server use a WASM
+ * renderer instead: see the recipe "Make a PNG on a server".
+ */
+import { toSvgString } from './chart.js';
+import { StringPlatform } from './platform.js';
+const browserHost = () => ({
+    loadImage: (url) => new Promise((resolve, reject) => {
+        const image = new Image();
+        image.onload = () => resolve({ width: image.naturalWidth, height: image.naturalHeight, image });
+        image.onerror = () => reject(new Error('toPng: the browser could not draw this SVG'));
+        image.src = url;
+    }),
+    canvas: (width, height) => {
+        if (typeof OffscreenCanvas !== 'undefined') {
+            const c = new OffscreenCanvas(width, height);
+            // oxlint-disable-next-line typescript/consistent-type-assertions -- the canvas context is handed to the renderer as the one type it draws on
+            return { context: c.getContext('2d'), blob: () => c.convertToBlob({ type: 'image/png' }) };
+        }
+        const c = document.createElement('canvas');
+        c.width = width;
+        c.height = height;
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- the canvas context is handed to the renderer as the one type it draws on
+        return { context: c.getContext('2d'), blob: () => new Promise((resolve, reject) => c.toBlob((b) => (b ? resolve(b) : reject(new Error('toPng: the canvas gave no image'))), 'image/png')) };
+    },
+});
+/** An SVG document as a PNG. Its own `width` and `height` give the size, else `options.size`. */
+export async function svgToPng(svg, options = {}, host = browserHost()) {
+    const scale = options.scale ?? 1;
+    if (!(scale > 0))
+        throw new Error('toPng: scale must be above 0');
+    const url = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg);
+    const { width: w, height: h, image } = await host.loadImage(url);
+    const width = Math.max(1, Math.round((options.size?.width ?? w) * scale)), height = Math.max(1, Math.round((options.size?.height ?? h) * scale));
+    const { context, blob } = host.canvas(width, height);
+    if (options.background) {
+        context.fillStyle = options.background;
+        context.fillRect(0, 0, width, height);
+    }
+    context.drawImage(image, 0, 0, width, height);
+    return blob();
+}
+/** The chart as a PNG: what is showing if it is on the page, else a rendering of it. */
+export function toPng(chart, options = {}, host) {
+    // A real SVG element is serialised as XML, which puts its namespace on it (outerHTML does not, and an image needs it).
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- the platform root is opaque; it is checked with `instanceof` on the same line
+    const platform = chart.platform, root = platform?.root, element = typeof XMLSerializer !== 'undefined' && typeof Element !== 'undefined' && root instanceof Element ? root : null;
+    if (element)
+        chart.flush(); // what is showing includes anything still waiting to be drawn
+    const live = element ? new XMLSerializer().serializeToString(element) : null;
+    if (live && platform) {
+        return svgToPng(live, { ...options, size: options.size ?? platform.size() }, host);
+    }
+    if (chart.platform) {
+        // On a string platform the SVG is already in hand; on anything else there is nothing to draw it from.
+        if (!(chart.platform instanceof StringPlatform))
+            throw new Error('toPng: the chart is attached to a platform that is not a DOM one');
+        return svgToPng(chart.platform.toString(), { ...options, size: options.size ?? chart.platform.size() }, host);
+    }
+    const a = chart.attrs, size = options.size ?? { width: a.width ?? 640, height: a.height ?? 400 };
+    return svgToPng(toSvgString(chart, size), { ...options, size }, host);
+}

package/dist/pointer.d.ts

@@ -0,0 +1,54 @@
+import { type BaseAttributes, ChartElement } from './element.ts';
+import { inputOf } from './input.ts';
+import { type ChartEvent, type Hit } from './events.ts';
+import type { Plane } from './plane.ts';
+/** What every callback is told. */
+export interface PointerInfo {
+    readonly plane: Plane;
+    /** The pointer in plot pixels. */
+    readonly x: number;
+    readonly y: number;
+    /**
+     * Where that is in data terms, on the axes of the hit's series, or else the plane's first and second axes. While
+     * dragging it is where the grabbed point is to go: the pointer's position carrying the grab's offset, so the point
+     * does not jump to be under the pointer's tip.
+     */
+    readonly first: number;
+    readonly second: number;
+    /** The point under the pointer (for a drag, the one being dragged, as it was when grabbed); null over nothing. */
+    readonly hit: Hit | null;
+    readonly shift: boolean;
+    readonly ctrl: boolean;
+}
+/** A drag always has a point. `phase` is 'start' on the first movement past the threshold, 'end' on release. */
+export interface DragInfo extends PointerInfo {
+    readonly hit: Hit;
+    readonly phase: 'start' | 'move' | 'end';
+}
+export interface PointerListenerAttributes extends BaseAttributes {
+    /** The pointer came onto a point, left it, or moved to another: `info.hit` is the new one, null for none. */
+    onHover?: (info: PointerInfo) => void;
+    /** A press and release in the same place: on a point, or `info.hit` null on empty plot. */
+    onClick?: (info: PointerInfo) => void;
+    /** A drag that began on a point. The listener claims such presses, so they do not pan. */
+    onDrag?: (info: DragInfo) => void;
+    /** How far in pixels the pointer must travel before a press is a drag and no longer a click. Default 3. */
+    dragThreshold?: number;
+}
+export declare class PointerListener extends ChartElement<Plane, [], PointerListenerAttributes> {
+    #private;
+    static takesInput: typeof inputOf;
+    static attrTypes: {
+        dragThreshold: 2;
+        onClick: 0;
+        onDrag: 0;
+        onHover: 0;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    onEvent(ev: ChartEvent): void;
+}

package/dist/pointer.js

@@ -0,0 +1,132 @@
+/**
+ * PointerListener: what a user reaches for to react to the pointer over a plane, without handling raw pointer events.
+ *
+ * It sits in a plane, like `PanZoom`, and turns the plane's pointer input into three things people actually want:
+ * which point the pointer is over (`onHover`), a click on a point or on empty plot (`onClick`), and a point being
+ * dragged (`onDrag`). Each callback gets one `PointerInfo`, which carries the hit, where the pointer is in plot pixels
+ * and what that is in data terms, so an edit is a line or two:
+ *
+ *     new PointerListener({ onDrag: ({ hit, first, second }) => { rows[hit.row!].x = first; rows[hit.row!].y = second; source.invalidate(); } })
+ *
+ * What "over" means is decided by each series' own `hit` setting (see hit.ts); the listener only asks the plane.
+ *
+ * Sharing the plane with `PanZoom`
+ * ────────────────────────────────
+ * Both want a press on the plot. A listener claims the press only when it has something to do with it: a drag that starts
+ * on a point (when `onDrag` is set). Anything else, including a press on empty plot, goes on to `PanZoom`, so dragging
+ * the background still pans. The claim works by order: a plane's children receive input in the order they were added, and
+ * `PanZoom` skips what is already handled, so the listener has to come first. Adding it after a `PanZoom` is an error.
+ */
+import { AUTO, NUMBER } from './attrs.js';
+import { ChartElement, fail } from './element.js';
+import { inputOf } from './input.js';
+import { EVENT_ATTACH, EVENT_POINTER } from './events.js';
+import { hitPlane } from './hit.js';
+/** Same point as before? A row is the identity that survives re-sorting; without one the drawn index will do. */
+const same = (a, b) => a === b || (!!a && !!b && a.series === b.series && (a.row ?? a.index) === (b.row ?? b.index));
+export class PointerListener extends ChartElement {
+    static takesInput = inputOf;
+    static attrTypes = { ...ChartElement.attrTypes, dragThreshold: NUMBER, onClick: AUTO, onDrag: AUTO, onHover: AUTO };
+    #hover = null;
+    // A press in progress: where it began, the point under it, and the offset from the pointer to that point.
+    #press = null;
+    onEvent(ev) {
+        if (ev.type === EVENT_ATTACH) {
+            const plane = this.requireParent();
+            for (const sibling of plane) {
+                if (sibling === this)
+                    break;
+                if (sibling.claimsPress)
+                    fail('add a PointerListener before PanZoom in a plane: the listener has to see a press first to claim it');
+            }
+            return;
+        }
+        if (ev.type !== EVENT_POINTER)
+            return;
+        const a = this.attrs, plane = this.requireParent(), platform = this.chart?.platform;
+        // Over an axis the pointer is not over anything plotted. (A press that began on the plot goes on being ours until it ends.)
+        if (ev.outside && !this.#press && ev.kind !== 'leave') {
+            if (this.#hover && ev.kind === 'move') {
+                this.#hover = null;
+                a.onHover?.({ plane, x: ev.x, y: ev.y, first: NaN, second: NaN, hit: null, shift: ev.shift, ctrl: ev.ctrl });
+            }
+            return;
+        }
+        if (ev.kind === 'wheel' || ev.kind === 'pinch')
+            return;
+        const threshold = a.dragThreshold ?? 3;
+        const info = (hit, x, y, dx = 0, dy = 0) => {
+            const first = hit ? hit.series.firstAxis : plane.defaultAxis('first'), second = hit ? hit.series.secondAxis : plane.defaultAxis('second');
+            const at = first && second ? plane.unplace(x + dx, y + dy, first, second) : [NaN, NaN];
+            // In a stack the pointer reads the stacked height: the layer's own value is that less what it sits on.
+            return { plane, x, y, first: at[0], second: at[1] - (hit?.lift ?? 0), hit, shift: ev.shift, ctrl: ev.ctrl };
+        };
+        switch (ev.kind) {
+            case 'down': {
+                if (!(ev.buttons & 1))
+                    break;
+                const hit = hitPlane(plane, ev.x, ev.y);
+                const claimed = !!hit && !!a.onDrag;
+                this.#press = { x: ev.x, y: ev.y, hit, dx: hit ? hit.px - ev.x : 0, dy: hit ? hit.py - ev.y : 0, claimed, dragging: false };
+                if (claimed)
+                    ev.handled = true;
+                break;
+            }
+            case 'move': {
+                const press = this.#press;
+                if (press) {
+                    if (!(ev.buttons & 1)) {
+                        this.#press = null;
+                        break;
+                    }
+                    if (!press.dragging && Math.hypot(ev.x - press.x, ev.y - press.y) < threshold)
+                        break;
+                    const first = !press.dragging;
+                    press.dragging = true;
+                    if (press.claimed && press.hit && a.onDrag) {
+                        a.onDrag({ ...info(press.hit, ev.x, ev.y, press.dx, press.dy), hit: press.hit, phase: first ? 'start' : 'move' });
+                        platform?.setCursor?.('grabbing');
+                        ev.handled = true;
+                    }
+                    break;
+                }
+                if (!a.onHover && !a.onDrag && !a.onClick)
+                    break;
+                const hit = hitPlane(plane, ev.x, ev.y);
+                if (!same(hit, this.#hover)) {
+                    this.#hover = hit;
+                    a.onHover?.(info(hit, ev.x, ev.y));
+                }
+                // Over a point the cursor says what it can do. Handled, so that `PanZoom` does not put its own over it.
+                if (hit) {
+                    platform?.setCursor?.(a.onDrag ? 'grab' : 'pointer');
+                    ev.handled = true;
+                }
+                else if (!a.onDrag)
+                    platform?.setCursor?.('');
+                break;
+            }
+            case 'up': {
+                const press = this.#press;
+                this.#press = null;
+                if (!press)
+                    break;
+                if (press.dragging && press.claimed && press.hit && a.onDrag) {
+                    a.onDrag({ ...info(press.hit, ev.x, ev.y, press.dx, press.dy), hit: press.hit, phase: 'end' });
+                    ev.handled = true;
+                }
+                else if (!press.dragging) {
+                    a.onClick?.(info(press.hit, ev.x, ev.y));
+                }
+                break;
+            }
+            case 'leave':
+                this.#press = null;
+                if (this.#hover) {
+                    this.#hover = null;
+                    a.onHover?.(info(null, ev.x, ev.y));
+                }
+                break;
+        }
+    }
+}

package/dist/quantile.d.ts

@@ -0,0 +1,3 @@
+/** Quantiles of sorted numbers, shared by the statistics that need them (`BoxStats`, `Density`). */
+/** The p-th quantile of ascending `v`, by the inclusive rule (rank p(n-1)) or the exclusive one (rank p(n+1)-1, held to the ends). */
+export declare function quantile(v: ArrayLike<number>, p: number, method?: 'inclusive' | 'exclusive'): number;

package/dist/quantile.js

@@ -0,0 +1,11 @@
+/** Quantiles of sorted numbers, shared by the statistics that need them (`BoxStats`, `Density`). */
+/** The p-th quantile of ascending `v`, by the inclusive rule (rank p(n-1)) or the exclusive one (rank p(n+1)-1, held to the ends). */
+export function quantile(v, p, method = 'inclusive') {
+    const n = v.length;
+    if (n === 0)
+        return NaN;
+    const h = method === 'exclusive' ? Math.min(n - 1, Math.max(0, p * (n + 1) - 1)) : p * (n - 1);
+    const lo = Math.floor(h), hi = Math.ceil(h);
+    // oxlint-disable-next-line typescript/no-non-null-assertion -- in range: the index comes from a loop bound or a length checked in the same function
+    return v[lo] + (h - lo) * (v[hi] - v[lo]);
+}

package/dist/radial.d.ts

@@ -0,0 +1,116 @@
+import { Axis } from './axis.ts';
+import type { PointBuffer } from './data.ts';
+import { type ChartEvent } from './events.ts';
+import { Plane, type PlaneAttributes } from './plane.ts';
+export interface RadialPlaneAttributes extends PlaneAttributes {
+    /** Radians clockwise from twelve o'clock. Default 0. */
+    startAngle?: number;
+    /** Radians swept by the angle axis, clockwise; negative runs the other way. Default 2π. */
+    sweep?: number;
+    /** Fraction of the radius left empty in the middle. Default 0. */
+    innerRadius?: number;
+    /** Rings at the radius axis' ticks and spokes at the angle axis'. Default true. */
+    gridlines?: boolean;
+    /** Clip series to the plot's outline. Default true. */
+    clip?: boolean;
+}
+/**
+ * The shared machinery of radial planes: layout in a circle, rulers for both axes, clip, gridlines, and `place`.
+ * Subclasses supply only the geometry (`locate`, `ring`, `outerRadius`, `prepare`).
+ */
+export declare abstract class RadialPlane<A extends RadialPlaneAttributes = RadialPlaneAttributes> extends Plane<A> {
+    #private;
+    static attrTypes: {
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+        innerRadius: 2;
+        startAngle: 2;
+    };
+    private readonly clipId;
+    get clipUrl(): string | null;
+    get curved(): boolean;
+    get startAngle(): number;
+    get sweep(): number;
+    get innerRadius(): number;
+    /** The outer radius in plot pixels. Valid after arrange. */
+    get radius(): number;
+    protected get cx(): number;
+    protected get cy(): number;
+    /** The line of constant value at pixel radius `r`, from the start of the sweep to its end (or back), as path data starting with M. */
+    protected abstract ring(r: number, reverse?: boolean): string;
+    /** Where a fraction of the way along the angle axis is, at pixel radius `r`. Writes x then y into `out`. */
+    protected abstract locate(fraction: number, r: number, out: Float64Array): void;
+    /** Distance from the middle to the outer edge of the plot in the direction (dx, dy): where the ray from the middle meets the rim. */
+    protected abstract outerRadius(dx: number, dy: number): number;
+    /** How far round the angle axis the direction (dx, dy) from the middle is, as a fraction of its sweep (wrapped into 0..1 for a full turn). */
+    protected abstract angleFraction(dx: number, dy: number): number;
+    /** Called when the circle is settled, before any series is projected. */
+    protected prepare(): void;
+    cyclic(axis: Axis): boolean;
+    /** On the plot when inside the rim in that direction, outside the hole, and (for a part of a turn) within the sweep. */
+    covers(x: number, y: number): boolean;
+    /** A radius is a ring (round, or a polygon on a radar); an angle is a spoke, which the plane's own way of placing gives. */
+    guide(role: 'first' | 'second', value: number): string;
+    /** The first coordinate is the angle, the second the radius. */
+    defaultAxis(role: 'first' | 'second'): Axis | undefined;
+    /** Pixels along an axis: what its ticks have to fit into. */
+    protected lengthOf(axis: Axis): number;
+    /** The fractions 0..1 of an axis' ticks that fall inside its range. */
+    protected tickFractions(axis: Axis | undefined): number[];
+    unplace(x: number, y: number, first: Axis, second: Axis): readonly [number, number];
+    place(points: PointBuffer, first: Axis, second: Axis): void;
+    onEvent(ev: ChartEvent): void;
+    /**
+     * Every axis gets the curve it runs along: the rim for the angle, a spoke at the start angle for the radius. The line
+     * is worked out when it is drawn, since a radar's depends on ticks that are only settled by then.
+     */
+    private setRulers;
+    /**
+     * Same three passes as a Cartesian plane (estimate → fit → measure → final size → project), except that the plot is
+     * the largest circle in what is left, and the only margin that matters is what the angle axis' labels need around it.
+     */
+    private arrange;
+    /** What the plot covers: the whole outline for a full turn (less the hole), a sector for part of one. */
+    private region;
+    /** Clip region, then spokes at the angle axis' ticks and rings at the radius axis' ticks. */
+    private paint;
+}
+/** No options of its own beyond the shared radial ones. */
+export interface PolarPlaneAttributes extends RadialPlaneAttributes {
+}
+/** A continuous plane: the angle is an angle, so lines of constant value are circles. */
+export declare class PolarPlane extends RadialPlane<PolarPlaneAttributes> {
+    protected locate(fraction: number, r: number, out: Float64Array): void;
+    protected outerRadius(): number;
+    protected angleFraction(dx: number, dy: number): number;
+    protected ring(r: number, reverse?: boolean): string;
+}
+/** No options of its own beyond the shared radial ones. */
+export interface RadarPlaneAttributes extends RadialPlaneAttributes {
+}
+/**
+ * A plane with a spoke at every tick of the angle axis, the ends of the sweep too, and straight lines between them.
+ * Between two spokes a point is on the chord between where its radius is on each, so a ring is a polygon, a line
+ * through dense data follows the same chords, and an `AreaPath` fills a polygon without being told it is one.
+ *
+ * Give the angle axis a fixed `min` and `max` and a `tickCount` that puts a tick on each category (and `nice` off,
+ * or on only for integers); auto-ranging works, but the spokes move as the data does. A full turn ends where it began,
+ * so a closed shape needs the first point repeated at the end of the domain.
+ */
+export declare class RadarPlane extends RadialPlane<RadarPlaneAttributes> {
+    #private;
+    protected prepare(): void;
+    /** The spokes: a line along the angle axis bends at each. */
+    breaks(axis: Axis): readonly number[];
+    protected locate(fraction: number, r: number, out: Float64Array): void;
+    /** The wedge between two spokes that the direction (dx, dy) points into: the spoke before it, and how far round the sweep it is. */
+    private wedge;
+    protected outerRadius(dx: number, dy: number): number;
+    /** Where along the chord the pointer's ray crosses it, mapped to the fractions of the two spokes (not linear in the angle). */
+    protected angleFraction(dx: number, dy: number): number;
+    protected ring(r: number, reverse?: boolean): string;
+}