inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/plane.js

@@ -0,0 +1,370 @@
+/**
+ * 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.
+ */
+/* oxlint-disable typescript/no-non-null-assertion -- stride-addressed rows of the placed-point buffers: every index is bounded by the row count */
+import { Axis, cartesianSide, isHorizontal } from './axis.js';
+import { ChartElement, fail, resolveRef } from './element.js';
+import { writeAria } from './aria.js';
+import { EVENT_ARRANGE, EVENT_ATTACH, EVENT_PAINT } from './events.js';
+import { f2 } from './geometry.js';
+import { Series, groupOf, seriesOf } from './series.js';
+/** What every plane does the same way: owns the axes and series among its children and runs the fit. */
+export class Plane extends ChartElement {
+    #rect = { x: 0, y: 0, width: 1, height: 1 };
+    /** The allocated plot area, in the chart's coordinates. Valid after arrange. */
+    get rect() { return this.#rect; }
+    /** Subclasses record the plot area they settle on. */
+    setRect(rect) { this.#rect = rect; }
+    get axes() { return [...this].filter((c) => c instanceof 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() { return [...this].flatMap(seriesOf); }
+    /** The series that are on show (`visible` is not false): the ones that are drawn, fit the axes and are hit. */
+    get series() { return this.allSeries.filter((s) => s.shown); }
+    /**
+     * 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) { return []; }
+    /**
+     * 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).
+     */
+    axisLength(_axis, _estimate) { return 0; }
+    /** Put every axis of the plane back to the range its data asks for, undoing pan, zoom and box zoom. */
+    resetViews() { for (const axis of this.axes)
+        axis.setViewRange(null); }
+    /** 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) { return false; }
+    /**
+     * 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, _y) { return 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, y) { return x >= 0 && y >= 0 && x <= this.#rect.width && y <= this.#rect.height; }
+    /**
+     * 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, value) {
+        const a = this.defaultAxis('first'), b = this.defaultAxis('second');
+        if (!a || !b)
+            return '';
+        const f = (role === 'first' ? a : b).fractionOf(value);
+        if (!Number.isFinite(f))
+            return '';
+        const ends = new Float64Array(role === 'first' ? [f, 0, f, 1] : [0, f, 1, f]);
+        this.place({ data: ends, stride: 2, count: 2 }, a, b);
+        return `M${f2(ends[0])} ${f2(ends[1])}L${f2(ends[2])} ${f2(ends[3])}`;
+    }
+    /**
+     * 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.
+     */
+    assignAxes(defaults, check) {
+        const used = new Map();
+        let next = 0;
+        for (const a of this.axes) {
+            const o = check(a.attrs.orientation ?? defaults[next++] ?? fail('too many axes without an orientation'));
+            const slot = used.get(o) ?? 0;
+            used.set(o, slot + 1);
+            a.assign(o, slot);
+        }
+    }
+    /** Put a resolved line look on a node of this plane (gridlines, frame). */
+    strokeWith(node, look) {
+        const s = this.surface;
+        s.set(node, 'stroke', look.color);
+        s.set(node, 'stroke-width', look.width);
+        s.set(node, 'stroke-dasharray', look.dash);
+        s.set(node, 'opacity', look.opacity);
+    }
+    /**
+     * 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.
+     */
+    fit(estimate) {
+        const axes = this.axes, series = this.series;
+        for (const a of axes)
+            a.begin(this.axisLength(a, estimate));
+        for (const s of series)
+            s.resolveAxes(this);
+        for (const s of series)
+            s.contributeDomain();
+        for (const s of series)
+            s.resolveDomain();
+        // A group (a stack) loads its own members, since what they contribute depends on all of them.
+        for (const c of this) {
+            if (c instanceof Series) {
+                if (c.shown)
+                    c.load(estimate);
+            }
+            else
+                groupOf(c)?.load(estimate);
+        }
+        for (const a of axes)
+            a.resolve();
+    }
+}
+// Module-level so ids stay unique across charts sharing a page (clip ids live in the document's one namespace).
+let clipCounter = 0;
+/** A fresh id for a plane's clip region, unique within the page. */
+export const nextClipId = () => `clip${++clipCounter}`;
+/** Where axes go when they do not say, in the order they are added: the familiar x-below, y-left, then the mirrors. */
+const DEFAULT_SIDES = ['bottom', 'left', 'top', 'right'];
+/** The least room left round a plot, whatever the axes need. */
+export const MIN_INSET = 8;
+/** A point `offset` pixels outside the middle of an edge of a plot `w` by `h`: where a title there starts. */
+function edgeSpot(side, w, h, offset) {
+    switch (side) {
+        case 'bottom': return { x: w / 2, y: h + offset, nx: 0, ny: 1, beyond: false };
+        case 'top': return { x: w / 2, y: -offset, nx: 0, ny: -1, beyond: false };
+        case 'left': return { x: -offset, y: h / 2, nx: -1, ny: 0, beyond: false };
+        case 'right': return { x: w + offset, y: h / 2, nx: 1, ny: 0, beyond: false };
+    }
+}
+/**
+ * The ruler for an axis on `side` of a plot `w` by `h`, with its line `pos` pixels across: down for a horizontal axis,
+ * right for a vertical one. `title` says where its title goes, given the middle of the line.
+ */
+function rulerAt(side, w, h, pos, title) {
+    const horizontal = isHorizontal(side), sign = side === 'top' || side === 'left' ? -1 : 1;
+    if (horizontal) {
+        const at = (f) => [f * w, pos, 0, sign];
+        return { length: w, tickSpacing: 70, horizontal, line: `M0 ${f2(pos)}H${f2(w)}`, at, fractionAt: (px) => px / w, title: (p) => title(p, at(0.5)) };
+    }
+    const at = (f) => [pos, (1 - f) * h, sign, 0];
+    return { length: h, tickSpacing: 36, horizontal, line: `M${f2(pos)} 0V${f2(h)}`, at, fractionAt: (_px, py) => 1 - py / h, title: (p) => title(p, at(0.5)) };
+}
+/** x/y plane: horizontal and vertical axes on its edges (or floating across it), clipped, with gridlines at the first axes' ticks. */
+export class CartesianPlane extends Plane {
+    clipId = nextClipId();
+    get clipUrl() { return this.attrs.clip === false ? null : `url(#${this.clipId})`; }
+    get curved() { return false; }
+    axisLength(axis, estimate) { return isHorizontal(axis.orientation) ? estimate.width : estimate.height; }
+    /** The first coordinate is on the horizontal axis, the second on the vertical one. */
+    defaultAxis(role) {
+        return this.axes.find((a) => (role === 'first') === isHorizontal(a.orientation));
+    }
+    /**
+     * 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, first, second) {
+        if (isHorizontal(first.orientation) === isHorizontal(second.orientation)) {
+            fail('a series needs one horizontal and one vertical axis');
+        }
+        const { data, count, stride } = points;
+        const w = this.rect.width, h = this.rect.height;
+        switch (first.orientation) {
+            case 'bottom':
+            case 'top':
+                for (let k = 0, i = 0; k < count; k++, i += stride) {
+                    data[i] = data[i] * w;
+                    data[i + 1] = (1 - data[i + 1]) * h;
+                }
+                break;
+            case 'left':
+            case 'right':
+                for (let k = 0, i = 0; k < count; k++, i += stride) {
+                    const d = data[i];
+                    data[i] = data[i + 1] * w;
+                    data[i + 1] = (1 - d) * h;
+                }
+                break;
+            case 'angle':
+            case 'radius':
+                cartesianSide(first.orientation);
+        }
+    }
+    unplace(x, y, first, second) {
+        const across = x / this.rect.width, up = 1 - y / this.rect.height;
+        return isHorizontal(first.orientation) ? [first.denormalize(across), second.denormalize(up)] : [first.denormalize(up), second.denormalize(across)];
+    }
+    axisAt(x, y) {
+        const w = this.rect.width, h = this.rect.height;
+        for (const a of this.axes) {
+            if (!this.reserves(a) || a.thickness <= 0)
+                continue;
+            const at = a.ruler.at(0), horizontal = isHorizontal(a.orientation);
+            const pos = horizontal ? at[1] : at[0], sign = horizontal ? at[3] : at[2], far = pos + sign * a.thickness;
+            const lo = Math.min(pos, far), hi = Math.max(pos, far);
+            if (horizontal ? x >= 0 && x <= w && y >= lo && y <= hi : y >= 0 && y <= h && x >= lo && x <= hi)
+                return a;
+        }
+        return null;
+    }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_ATTACH:
+                this.surface.wrapper(); // carries the plot offset
+                break;
+            case EVENT_ARRANGE:
+                this.arrange(ev.rect);
+                break;
+            case EVENT_PAINT:
+                this.paint();
+                break;
+        }
+    }
+    /**
+     * 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.
+     */
+    crossing(axis) {
+        const at = axis.attrs.crossesAt;
+        if (at === undefined)
+            return null;
+        const horizontal = isHorizontal(axis.orientation);
+        const cross = resolveRef(axis.attrs.crossAxis, axis, Axis) ?? this.axes.find((a) => isHorizontal(a.orientation) !== horizontal)
+            ?? fail('a floating axis needs an axis on the other orientation to cross');
+        return Math.min(1, Math.max(0, cross.fractionOf(at)));
+    }
+    /** Whether an axis takes room round the plot: one fixed to a side does, and so does one held at the edge it faces. */
+    reserves(axis) {
+        const across = this.crossing(axis);
+        if (across === null)
+            return true;
+        switch (cartesianSide(axis.orientation)) {
+            case 'bottom':
+            case 'left': return across <= 1e-9;
+            case 'top':
+            case 'right': return across >= 1 - 1e-9;
+        }
+    }
+    /**
+     * 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.
+     */
+    setRulers(w, h) {
+        const stacked = { top: 0, right: 0, bottom: 0, left: 0 };
+        const titleAt = new Map();
+        for (const a of this.axes) {
+            const o = cartesianSide(a.orientation), across = this.crossing(a), reserves = this.reserves(a);
+            // A title belongs on the axis line when the axis is fixed there and the title is asked for on its own side.
+            const spot = (position, mid) => reserves && (position ?? o) === o
+                ? { x: mid[0], y: mid[1], nx: mid[2], ny: mid[3], beyond: true }
+                : edgeSpot(position ?? o, w, h, titleAt.get(a) ?? 0);
+            if (across !== null && !reserves) {
+                a.setRuler(rulerAt(o, w, h, isHorizontal(o) ? (1 - across) * h : across * w, spot));
+                continue;
+            }
+            const edge = o === 'bottom' ? h : o === 'right' ? w : 0, sign = o === 'top' || o === 'left' ? -1 : 1;
+            a.setRuler(rulerAt(o, w, h, edge + sign * stacked[o], spot));
+            stacked[o] += a.thickness;
+        }
+        for (const a of this.axes) {
+            if (a.titleThickness === 0)
+                continue;
+            titleAt.set(a, stacked[a.titleSide]);
+            stacked[a.titleSide] += a.titleThickness;
+        }
+    }
+    /** Negotiates ranges, lays out the axes, projects every series. */
+    arrange(available) {
+        const axes = this.axes, series = this.series;
+        this.assignAxes(DEFAULT_SIDES, cartesianSide);
+        // 80 and 40: roughly a y-axis's labels and an x-axis's labels. Only a guess for decimation; the real plot is set below.
+        const estimate = { width: Math.max(1, available.width - 80), height: Math.max(1, available.height - 40) };
+        this.setRulers(estimate.width, estimate.height);
+        this.fit(estimate);
+        this.setRulers(estimate.width, estimate.height); // ranges are settled now, which is what tells a floating axis from a fixed one
+        // Axes ask for space; what is left is the plot. Overhang is a horizontal axis' end labels poking past the plot sides.
+        // (The fixed-side thickness is summed per side, so stacked axes add up.)
+        const side = { top: 0, right: 0, bottom: 0, left: 0 };
+        let overhang = 0;
+        for (const a of axes) {
+            this.measureChild(a, estimate);
+            if (this.reserves(a))
+                side[cartesianSide(a.orientation)] += a.thickness;
+            side[a.titleSide] += a.titleThickness;
+            if (isHorizontal(a.orientation))
+                overhang = Math.max(overhang, a.labelOverhang);
+        }
+        const o = this.attrs.insets ?? {};
+        const insets = {
+            top: o.top ?? Math.max(MIN_INSET, side.top),
+            bottom: o.bottom ?? Math.max(MIN_INSET, side.bottom),
+            left: o.left ?? Math.max(MIN_INSET, side.left, Math.ceil(overhang)),
+            right: o.right ?? Math.max(MIN_INSET, side.right, Math.ceil(overhang)),
+        };
+        this.setRect({
+            x: available.x + insets.left,
+            y: available.y + insets.top,
+            width: Math.max(1, available.width - insets.left - insets.right),
+            height: Math.max(1, available.height - insets.top - insets.bottom),
+        });
+        // Now the plot is known, the axes can be placed along it, and the series projected.
+        this.setRulers(this.rect.width, this.rect.height);
+        for (const s of series)
+            s.project(this);
+    }
+    /** Clip region, gridlines (from the first horizontal and vertical axis) and frame. */
+    paint() {
+        const s = this.surface, r = this.rect, a = this.attrs;
+        s.set(s.wrapper(), 'transform', `translate(${f2(r.x)} ${f2(r.y)})`);
+        writeAria(s, s.wrapper(), a.meta, { role: 'group' });
+        if (a.clip !== false) {
+            const clip = s.node('clip', 'clipPath', { parent: s.node('defs', 'defs') });
+            s.set(clip, 'id', this.clipId);
+            const rect = s.node('clip-rect', 'rect', { parent: clip });
+            s.set(rect, 'width', f2(r.width));
+            s.set(rect, 'height', f2(r.height));
+        }
+        if (a.gridlines !== false) {
+            let d = '';
+            const horizontalAxis = this.axes.find((x) => isHorizontal(x.orientation));
+            const verticalAxis = this.axes.find((x) => !isHorizontal(x.orientation));
+            if (horizontalAxis) {
+                for (const t of horizontalAxis.getTicks(r.width)) {
+                    const f = horizontalAxis.fractionOf(t.value);
+                    if (f >= -1e-9 && f <= 1 + 1e-9)
+                        d += `M${f2(f * r.width)} 0V${f2(r.height)}`;
+                }
+            }
+            if (verticalAxis) {
+                for (const t of verticalAxis.getTicks(r.height)) {
+                    const f = verticalAxis.fractionOf(t.value);
+                    if (f >= -1e-9 && f <= 1 + 1e-9)
+                        d += `M0 ${f2((1 - f) * r.height)}H${f2(r.width)}`;
+                }
+            }
+            const grid = s.node('grid', 'path');
+            s.set(grid, 'd', d);
+            s.set(grid, 'fill', 'none');
+            this.strokeWith(grid, this.styleFor(['gridline', 'line']));
+        }
+        else {
+            s.remove('grid');
+        }
+        if (a.frame) {
+            const f = s.node('frame', 'rect', { above: true });
+            s.set(f, 'width', f2(r.width));
+            s.set(f, 'height', f2(r.height));
+            s.set(f, 'fill', 'none');
+            this.strokeWith(f, this.styleFor(['frame', 'line']));
+        }
+        else {
+            s.remove('frame');
+        }
+    }
+}

package/dist/platform.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The platform: everything the library needs from the outside world, and a string-backed implementation of it.
+ *
+ * Why an interface rather than the DOM: the element tree only ever talks to `Surface`, and `Surface` only ever talks to
+ * a `Platform`. That keeps the core free of `document`/`window`, so the same chart renders in a browser (DOMPlatform),
+ * in node or a serverless function (StringPlatform → SVG text), and in tests. Everything beyond node creation is
+ * optional: a platform with nothing to observe simply leaves `schedule`/`onResize`/`onPointer` out.
+ */
+import type { Size } from './geometry.ts';
+export declare const SVG_NS = "http://www.w3.org/2000/svg";
+export type SvgTag = 'svg' | 'g' | 'path' | 'rect' | 'line' | 'circle' | 'text' | 'clipPath' | 'defs' | 'title' | 'desc' | 'linearGradient' | 'stop';
+export interface PlatformNode {
+    readonly __platformNode: unique symbol;
+}
+export type Unsubscribe = () => void;
+export interface FontSpec {
+    family: string;
+    size: number;
+    weight?: number | string;
+}
+export type TextMeasurer = (text: string, font: FontSpec) => Size;
+/** Pointer input boiled down to what charts use, so every platform feeds the same events whatever its native ones look like. */
+export interface RawPointer {
+    /** `pinch` is a zoom gesture the platform recognised itself (a trackpad pinch in Safari): `scale` is its factor since the last one. */
+    kind: 'move' | 'down' | 'up' | 'leave' | 'wheel' | 'pinch';
+    x: number;
+    y: number;
+    buttons: number;
+    deltaY: number;
+    /** Sideways wheel travel, in pixels. Default 0. */
+    deltaX?: number;
+    /** For `pinch`: how much the fingers spread since the last event (above 1 spreads, below 1 closes). */
+    scale?: number;
+    /** Which finger or device, so that several touches can be told apart. Default 0. */
+    id?: number;
+    /** Default 'mouse'. */
+    pointerType?: 'mouse' | 'touch' | 'pen';
+    shift: boolean;
+    ctrl: boolean;
+}
+/** A key press or release on a focused node, boiled down like `RawPointer`. */
+export interface RawKey {
+    kind: 'down' | 'up';
+    key: string;
+    shift: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    repeat: boolean;
+}
+/** A node gaining or losing focus; `visible` is whether a ring is wanted (the browser's `:focus-visible`). */
+export interface RawFocus {
+    node: PlatformNode;
+    focused: boolean;
+    visible: boolean;
+}
+export interface Platform {
+    readonly name: string;
+    /** The node the chart draws into. */
+    readonly root: PlatformNode;
+    /** The drawing area in CSS pixels. */
+    size(): Size;
+    createNode(tag: SvgTag): PlatformNode;
+    setAttribute(node: PlatformNode, name: string, value: string | number): void;
+    setText(node: PlatformNode, text: string): void;
+    /** Exactly `Node.insertBefore`: `before` is a child of `parent`, or null to append. Moves the node if it is already placed. */
+    insertBefore(parent: PlatformNode, node: PlatformNode, before: PlatformNode | null): void;
+    /** Takes the node, and everything inside it, out of whatever it is in. */
+    remove(node: PlatformNode): void;
+    /** Present: the chart flushes itself after an invalidation. Absent: call `chart.flush()`. */
+    schedule?(callback: () => void): Unsubscribe;
+    /** Absent on a platform with nothing to observe. */
+    onResize?(callback: (size: Size) => void): Unsubscribe;
+    /** The callback returns true when the chart used the input; the platform then withholds the browser's own handling (page scroll on a wheel turn). */
+    onPointer?(callback: (pointer: RawPointer) => boolean | void): Unsubscribe;
+    /** Keys pressed while one of the chart's nodes has focus. The callback gets the node; true means the chart used the key. */
+    onKey?(callback: (key: RawKey, node: PlatformNode) => boolean | void): Unsubscribe;
+    /** Focus entering and leaving the chart's nodes. */
+    onFocus?(callback: (focus: RawFocus) => void): Unsubscribe;
+    /** Say something to a screen reader without showing it, politely (after what it is saying now). Absent on a platform with no one to hear. */
+    announce?(text: string): void;
+    /** Move focus to a node that has a `tabindex`. */
+    focus?(node: PlatformNode): void;
+    measureText?: TextMeasurer;
+    /** The mouse cursor over the chart, as a CSS cursor name; an empty string for the default. */
+    setCursor?(cursor: string): void;
+    /**
+     * What a touch on the chart may do. 'always': the chart takes every touch (the page cannot scroll from it).
+     * 'two-finger': a touch with one finger scrolls the page as usual and only two fingers belong to the chart.
+     */
+    setTouchMode?(mode: 'always' | 'two-finger'): void;
+    dispose(): void;
+}
+/** Errs wide, which costs a little margin and never a clipped label. */
+export declare const estimateTextWidth: TextMeasurer;
+/**
+ * Keeps the SVG as a plain in-memory tree and prints it with `toString()`. This is the platform for node, serverless and
+ * tests: no DOM, no timers, no observers, so a chart is flushed explicitly and the output is deterministic.
+ */
+export declare class StringPlatform implements Platform {
+    #private;
+    readonly name = "string";
+    readonly root: PlatformNode;
+    constructor(size?: Size);
+    size(): Size;
+    createNode(tag: SvgTag): PlatformNode;
+    setAttribute(node: PlatformNode, name: string, value: string | number): void;
+    setText(node: PlatformNode, text: string): void;
+    insertBefore(parent: PlatformNode, node: PlatformNode, before: PlatformNode | null): void;
+    remove(node: PlatformNode): void;
+    dispose(): void;
+    /** A standalone SVG document with literal attribute values, safe to embed or rasterize. */
+    toString(): string;
+}

package/dist/platform.js

@@ -0,0 +1,80 @@
+export const SVG_NS = 'http://www.w3.org/2000/svg';
+/** Errs wide, which costs a little margin and never a clipped label. */
+export const estimateTextWidth = (text, font) => ({
+    width: text.length * font.size * 0.6,
+    height: font.size * 1.2,
+});
+/** The library's handle for a node is opaque; here every handle is one of our own `StringNode`s, and these two are the only conversions. */
+// oxlint-disable-next-line typescript/consistent-type-assertions -- the one place an opaque handle becomes our own node, and back: every handle on this platform is a `StringNode`
+const nodeOf = (node) => node;
+// oxlint-disable-next-line typescript/consistent-type-assertions -- the one place an opaque handle becomes our own node, and back: every handle on this platform is a `StringNode`
+const handleOf = (node) => node;
+const escapeText = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escapeAttr = (s) => escapeText(s).replace(/"/g, '&quot;');
+/**
+ * Keeps the SVG as a plain in-memory tree and prints it with `toString()`. This is the platform for node, serverless and
+ * tests: no DOM, no timers, no observers, so a chart is flushed explicitly and the output is deterministic.
+ */
+export class StringPlatform {
+    name = 'string';
+    root;
+    #size;
+    #root;
+    constructor(size = { width: 640, height: 400 }) {
+        this.#size = size;
+        this.#root = { tag: 'svg', attrs: new Map(), children: [], text: null, parent: null };
+        this.#root.attrs.set('xmlns', 'http://www.w3.org/2000/svg');
+        this.root = handleOf(this.#root);
+    }
+    size() { return this.#size; }
+    createNode(tag) {
+        return handleOf({ tag, attrs: new Map(), children: [], text: null, parent: null });
+    }
+    setAttribute(node, name, value) {
+        nodeOf(node).attrs.set(name, value);
+    }
+    setText(node, text) { nodeOf(node).text = text; }
+    insertBefore(parent, node, before) {
+        const p = nodeOf(parent), n = nodeOf(node);
+        if (n.parent)
+            this.remove(node);
+        n.parent = p;
+        const at = before ? p.children.indexOf(nodeOf(before)) : -1;
+        if (at < 0)
+            p.children.push(n);
+        else
+            p.children.splice(at, 0, n);
+    }
+    remove(node) {
+        const n = nodeOf(node);
+        if (!n.parent)
+            return;
+        n.parent.children.splice(n.parent.children.indexOf(n), 1);
+        n.parent = null;
+    }
+    dispose() { }
+    /** A standalone SVG document with literal attribute values, safe to embed or rasterize. */
+    toString() {
+        const lines = [];
+        const visit = (n, depth) => {
+            const pad = '  '.repeat(depth);
+            let open = `${pad}<${n.tag}`;
+            for (const [k, v] of n.attrs)
+                open += ` ${k}="${escapeAttr(String(v))}"`;
+            if (n.text !== null) {
+                lines.push(`${open}>${escapeText(n.text)}</${n.tag}>`);
+                return;
+            }
+            if (n.children.length === 0) {
+                lines.push(`${open}/>`);
+                return;
+            }
+            lines.push(`${open}>`);
+            for (const c of n.children)
+                visit(c, depth + 1);
+            lines.push(`${pad}</${n.tag}>`);
+        };
+        visit(this.#root, 0);
+        return lines.join('\n') + '\n';
+    }
+}

package/dist/png.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { type Chart } from './chart.ts';
+import type { Size } from './geometry.ts';
+export interface PngOptions {
+    /** Pixels per CSS pixel. Default 1. */
+    scale?: number;
+    /** Colour painted behind the chart. Default none (transparent). */
+    background?: string;
+    /** Size in CSS pixels for a chart that is not attached or an SVG without one. Default: the chart's own `width` and `height`, else 640 by 400. */
+    size?: Size;
+}
+/** What `svgToPng` needs of the browser, so it can be tested without one. */
+export interface PngHost {
+    loadImage(url: string): Promise<{
+        width: number;
+        height: number;
+        image: unknown;
+    }>;
+    canvas(width: number, height: number): {
+        context: {
+            fillStyle: string;
+            fillRect(x: number, y: number, w: number, h: number): void;
+            drawImage(image: unknown, x: number, y: number, w: number, h: number): void;
+            scale(x: number, y: number): void;
+        };
+        blob(): Promise<Blob>;
+    };
+}
+/** An SVG document as a PNG. Its own `width` and `height` give the size, else `options.size`. */
+export declare function svgToPng(svg: string, options?: PngOptions, host?: PngHost): Promise<Blob>;
+/** The chart as a PNG: what is showing if it is on the page, else a rendering of it. */
+export declare function toPng(chart: Chart, options?: PngOptions, host?: PngHost): Promise<Blob>;