inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/chart.js

@@ -0,0 +1,257 @@
+/**
+ * The chart: the root element. Owns the platform, schedules flushes and routes input to planes.
+ *
+ * One flush, in order (the layout pass the rest of the library is built around):
+ *   1. Furniture (keys, titles: anything that is not a plane) is measured; those that name a `side` take a strip there.
+ *   2. Planes are arranged into what is left. Arranging a plane is where it fits its axes and series, negotiates the
+ *      plot rectangle with its axes' sizes, and projects the data (see Plane.fit and CartesianPlane).
+ *   3. Furniture is arranged into its strip, now that the planes (and the mapped scales they fed) are settled.
+ *   4. PAINT is broadcast and every element draws through its Surface.
+ * Each flush re-runs all of it; Surface's write cache and the series' fill cache are what make that cheap.
+ * Mapped dimensions (ColorAxis/SizeAxis) are children of the chart rather than a plane, so they use `flushCount` to
+ * recognise a new pass and reset what they gathered from the planes.
+ */
+import { AUTO, STRING } from './attrs.js';
+import { writeAria } from './aria.js';
+import { ChartElement, fail } from './element.js';
+import { EVENT_PAINT } from './events.js';
+import {} from './geometry.js';
+import { Plane } from './plane.js';
+import { StringPlatform, estimateTextWidth } from './platform.js';
+import { newCounters } from './surface.js';
+/** Space between the plots and the furniture at their edges. */
+const FURNITURE_GAP = 8;
+/** Space between stacked bands, such as a title and its subtitle. */
+const BAND_GAP = 2;
+// oxlint-disable-next-line typescript/consistent-type-assertions -- a type guard: probing an element for an optional `describe`
+const isDescriber = (e) => typeof e.describe === 'function';
+/** The root: the only element that knows about the platform lifecycle (attach, flush, detach). */
+export class Chart extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, measureText: AUTO, onFlush: AUTO, locale: STRING };
+    get chart() { return this; }
+    #platform = null;
+    #lastFlush = null;
+    #needsFlush = false;
+    #flushCount = 0;
+    counts = newCounters();
+    unschedule = null;
+    subscriptions = [];
+    /** The input host, once something in the chart has asked for it (see `inputOf`): null on a chart nothing listens to. */
+    input = null;
+    get platform() { return this.#platform; }
+    get lastFlush() { return this.#lastFlush; }
+    /** How many flushes have begun. Elements that belong to the chart rather than a plane use it to tell a new pass from the same one. */
+    get flushCount() { return this.#flushCount; }
+    /** True from any invalidation until the next flush. */
+    get needsFlush() { return this.#needsFlush; }
+    /** Construction has no side effects; this makes the chart live. */
+    attach(platform) {
+        if (this.platform)
+            fail('chart is already attached');
+        this.#platform = platform;
+        this.mount({ platform, counters: this.counts });
+        const resize = platform.onResize?.(() => this.invalidate());
+        if (resize)
+            this.subscriptions.push(resize);
+        this.invalidate();
+        return this;
+    }
+    /** Undo `attach`: unsubscribe, take the nodes out of the platform. The tree is kept, so the chart can be attached again. */
+    detach() {
+        if (!this.platform)
+            return this;
+        this.unschedule?.();
+        this.unschedule = null;
+        for (const u of this.subscriptions.splice(0))
+            u();
+        this.input?.stop();
+        this.input = null;
+        this.unmount(true);
+        this.#platform = null;
+        this.#needsFlush = false;
+        return this;
+    }
+    /** The request has reached the root: note it, and on a scheduling platform arrange a flush. */
+    invalidate() {
+        super.invalidate();
+        const p = this.platform;
+        if (!p)
+            return;
+        this.#needsFlush = true;
+        if (p.schedule && !this.unschedule) {
+            this.unschedule = p.schedule(() => { this.unschedule = null; this.flush(); });
+        }
+    }
+    /** Put every axis of every plane back to the range its data asks for. */
+    resetViews() { for (const c of this)
+        if (c instanceof Plane)
+            c.resetViews(); }
+    /** Send an event through the tree from `root` (default the chart). For the input host, which lives outside this class. */
+    deliver(init, root = this) { return this.broadcast(init, root); }
+    /** Preference order: the chart's own, the platform's (real fonts), then a deliberately wide estimate. */
+    get measureText() {
+        return this.attrs.measureText ?? this.platform?.measureText ?? estimateTextWidth;
+    }
+    /** Run layout and paint now. The only way to render on a platform with no `schedule`. */
+    flush() {
+        const platform = this.platform;
+        if (!platform)
+            fail('chart is not attached');
+        const t0 = performance.now();
+        this.#flushCount++;
+        const c = this.counts;
+        // Reset in place: every Surface holds this object, so replacing it would orphan them.
+        c.writes = c.skipped = c.filled = c.cached = c.projected = c.pointsIn = c.pointsDrawn = c.pathBytes = 0;
+        c.names.clear();
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- `Object.keys` is `string[]`; these are the keys of `stages`
+        for (const k of Object.keys(c.stages))
+            c.stages[k] = 0;
+        const a = this.attrs, surface = this.surface;
+        const size = platform.size();
+        const width = a.width ?? size.width, height = a.height ?? size.height;
+        const root = platform.root;
+        surface.set(root, 'width', width);
+        surface.set(root, 'height', height);
+        surface.set(root, 'viewBox', `0 0 ${width} ${height}`);
+        surface.set(root, 'font-family', this.styleFor(['text']).family);
+        // The background is optional, so it is not a root: nearest `style` first, then the theme.
+        const background = a.style?.chart?.background ?? a.theme.chart?.background;
+        if (background) {
+            const bg = surface.node('background', 'rect');
+            surface.set(bg, 'width', width);
+            surface.set(bg, 'height', height);
+            surface.set(bg, 'fill', background);
+        }
+        else
+            surface.remove('background');
+        // Content area: the drawing minus the margin. Never below 1px so downstream divisions stay finite.
+        const pad = typeof a.padding === 'number'
+            ? { top: a.padding, right: a.padding, bottom: a.padding, left: a.padding }
+            : { top: 10, right: 10, bottom: 10, left: 10, ...a.padding };
+        const content = {
+            x: pad.left, y: pad.top,
+            width: Math.max(1, width - pad.left - pad.right),
+            height: Math.max(1, height - pad.top - pad.bottom),
+        };
+        // Everything that is not a plane and asks for a side takes room along that edge, sized by what it asked for, and the
+        // planes get what is left. Bands (titles, captions) span the edge and stack outwards from it, and come first; the
+        // rest (keys) take a strip inside the bands, where several on one side stack along it.
+        const furniture = [];
+        const bands = [];
+        const bandSize = { top: 0, right: 0, bottom: 0, left: 0 };
+        const strip = { top: 0, right: 0, bottom: 0, left: 0 };
+        for (const child of this) {
+            if (child instanceof Plane || child.attrs.visible === false)
+                continue;
+            const request = this.measureChild(child, { width: content.width, height: content.height });
+            const side = request.side;
+            if (!side)
+                continue;
+            if (request.band) {
+                bands.push({ child, request, side });
+                bandSize[side] += request.min.height + (bandSize[side] ? BAND_GAP : 0);
+                continue;
+            }
+            furniture.push({ child, request, side });
+            const across = side === 'left' || side === 'right' ? request.min.width : request.min.height;
+            strip[side] = Math.max(strip[side], across);
+        }
+        // What the bands leave. Everything below is laid out inside it.
+        const bandGap = (side) => (bandSize[side] ? FURNITURE_GAP : 0);
+        const inner = {
+            x: content.x,
+            y: content.y + bandSize.top + bandGap('top'),
+            width: content.width,
+            height: Math.max(1, content.height - bandSize.top - bandSize.bottom - bandGap('top') - bandGap('bottom')),
+        };
+        const gap = (side) => (strip[side] ? FURNITURE_GAP : 0);
+        const plotArea = {
+            x: inner.x + strip.left + gap('left'),
+            y: inner.y + strip.top + gap('top'),
+            width: Math.max(1, inner.width - strip.left - strip.right - gap('left') - gap('right')),
+            height: Math.max(1, inner.height - strip.top - strip.bottom - gap('top') - gap('bottom')),
+        };
+        const edge = { top: content.y, bottom: content.y + content.height };
+        for (const { child, request, side } of bands) {
+            const height = request.min.height;
+            if (side === 'top') {
+                this.arrangeChild(child, { x: content.x, y: edge.top, width: content.width, height });
+                edge.top += height + BAND_GAP;
+            }
+            else {
+                edge.bottom -= height;
+                this.arrangeChild(child, { x: content.x, y: edge.bottom, width: content.width, height });
+                edge.bottom -= BAND_GAP;
+            }
+        }
+        for (const child of this)
+            if (child instanceof Plane)
+                this.arrangeChild(child, plotArea);
+        const along = { top: inner.x, bottom: inner.x, left: inner.y, right: inner.y };
+        for (const { child, request, side } of furniture) {
+            const { width, height } = request.min;
+            const vertical = side === 'left' || side === 'right';
+            const rect = vertical
+                ? { x: side === 'left' ? inner.x : inner.x + inner.width - strip.right, y: along[side], width: strip[side], height }
+                : { x: along[side], y: side === 'top' ? inner.y : inner.y + inner.height - strip.bottom, width, height: strip[side] };
+            this.arrangeChild(child, rect);
+            along[side] += (vertical ? height : width) + FURNITURE_GAP;
+        }
+        // What a screen reader is told of the chart as a whole: `meta` first, then what a describer child makes of it, which needs the layout to have settled.
+        let said;
+        for (const child of this)
+            if (isDescriber(child) && child.attrs.visible !== false) {
+                said = child.describe();
+                break;
+            }
+        writeAria(surface, root, a.meta, { role: 'group', ...(said && { description: said.description }) });
+        if (said?.roleDescription !== undefined && !a.meta?.aria?.['aria-roledescription'] && !a.meta?.aria?.['roledescription']) {
+            surface.set(root, 'aria-roledescription', said.roleDescription);
+        }
+        this.broadcast({ type: EVENT_PAINT });
+        this.#needsFlush = false;
+        const stats = {
+            total: performance.now() - t0,
+            stages: { ...c.stages },
+            filled: c.filled,
+            fillsCached: c.cached,
+            projected: c.projected,
+            attributeWrites: c.writes,
+            attributeWritesSkipped: c.skipped,
+            attributesWritten: [...c.names],
+            pointsIn: c.pointsIn,
+            pointsDrawn: c.pointsDrawn,
+            pathBytes: c.pathBytes,
+        };
+        this.#lastFlush = stats;
+        a.onFlush?.(stats);
+        return stats;
+    }
+}
+/** FNV-1a over the UTF-16 units of a string, as eight hex digits. */
+function fnv(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++)
+        h = Math.imul(h ^ text.charCodeAt(i), 0x01000193);
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+/** Rename every id in an SVG to `${prefix}-${n}`, n by first appearance, so the text does not depend on how many charts were drawn before. */
+function scopeIds(svg, prefix) {
+    // 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
+    const ids = [...new Set([...svg.matchAll(/\sid="([^"]+)"/g)].map((m) => m[1]))];
+    if (ids.length === 0)
+        return svg;
+    const number = new Map(ids.map((id, i) => [id, i + 1]));
+    const swap = (text, head) => text.replace(/(\sid="|url\(#)([^")]+)/g, (whole, lead, id) => number.has(id) ? `${lead}${head}${number.get(id)}` : whole);
+    return swap(svg, `${prefix ?? `ink${fnv(swap(svg, ''))}`}-`);
+}
+/** One-shot export: attach a StringPlatform, flush, detach. */
+export function toSvgString(chart, options) {
+    const a = chart.attrs;
+    const platform = new StringPlatform({ width: options?.width ?? a.width ?? 640, height: options?.height ?? a.height ?? 400 });
+    // The chart's own width and height attributes beat the platform's size (see `layout`), so a size given here only matters for what they leave out.
+    chart.attach(platform).flush();
+    const svg = platform.toString();
+    chart.detach();
+    return scopeIds(svg, options?.idPrefix);
+}

package/dist/crosshair.d.ts

@@ -0,0 +1,28 @@
+import { type BaseAttributes, ChartElement } from './element.ts';
+import { type ChartEvent } from './events.ts';
+import type { Cursor, CursorChild } from './cursor.ts';
+export interface CrosshairAttributes extends BaseAttributes {
+    /** Which guide: the line of constant first coordinate (across a line chart: vertical), of the second, or both. Default 'both'. */
+    lines?: 'first' | 'second' | 'both';
+    /** A dot in the series' colour on each reading under the cursor. Default false. */
+    dots?: boolean;
+    /** Radius of those dots, in pixels. Default 4. */
+    dotSize?: number;
+    /** Put the lines through the first reading (a point) rather than through the cursor itself. Default false. */
+    snap?: boolean;
+}
+export declare class Crosshair extends ChartElement<Cursor, [], CrosshairAttributes> implements CursorChild {
+    #private;
+    static attrTypes: {
+        dotSize: 2;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** At the pointer's own place unless it is snapped to a reading. */
+    get follows(): boolean;
+    onEvent(ev: ChartEvent): void;
+}

package/dist/crosshair.js

@@ -0,0 +1,78 @@
+/**
+ * The crosshair: guide lines through the cursor, and optionally a dot on each reading.
+ *
+ *   new Cursor({}, new Crosshair())                                   // both lines, following the pointer
+ *   new Cursor({ mode: 'shared' }, new Crosshair({ lines: 'first', dots: true }), new ChartTooltip())
+ *
+ * The lines are lines of constant value, as the plane draws its own gridlines: a vertical and a horizontal line on a
+ * rectangular plane, but a spoke (the angle) and a circle (the radius) on a polar one, and a spoke and a polygon on a radar.
+ * `lines` chooses which. They are clipped to the plot.
+ *
+ * It looks as `crosshair` says (a line look), falling back to `line`.
+ */
+import { NUMBER } from './attrs.js';
+import { ChartElement } from './element.js';
+import { EVENT_ATTACH, EVENT_PAINT } from './events.js';
+import { circlePath, f2 } from './geometry.js';
+export class Crosshair extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, dotSize: NUMBER };
+    #dots = 0;
+    /** At the pointer's own place unless it is snapped to a reading. */
+    get follows() { return this.attrs.snap !== true; }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_ATTACH:
+                this.surface.wrapper();
+                break;
+            case EVENT_PAINT:
+                this.#paint();
+                break;
+        }
+    }
+    #paint() {
+        const s = this.surface, root = s.wrapper(), state = this.requireParent().state, a = this.attrs;
+        if (!state) {
+            s.remove('guide');
+            for (let i = 0; i < this.#dots; i++)
+                s.remove(`dot-${i}`);
+            this.#dots = 0;
+            return;
+        }
+        const { plane, hits } = state, r = plane.rect;
+        s.set(root, 'transform', `translate(${f2(r.x)} ${f2(r.y)})`);
+        const clip = plane.clipUrl;
+        if (clip)
+            s.set(root, 'clip-path', clip);
+        // 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
+        const snapped = a.snap === true && hits.length > 0 ? hits[0] : null;
+        const x = snapped ? snapped.px : state.x, y = snapped ? snapped.py : state.y;
+        const first = plane.defaultAxis('first'), second = plane.defaultAxis('second');
+        let d = '';
+        if (first && second) {
+            const at = plane.unplace(x, y, first, second), which = a.lines ?? 'both';
+            if (which !== 'second')
+                d += plane.guide('first', at[0]);
+            if (which !== 'first')
+                d += plane.guide('second', at[1]);
+        }
+        const look = this.styleFor(['crosshair', 'line']);
+        const line = s.node('guide', 'path');
+        s.set(line, 'd', d);
+        s.set(line, 'fill', 'none');
+        s.set(line, 'stroke', look.color);
+        s.set(line, 'stroke-width', look.width);
+        s.set(line, 'stroke-dasharray', look.dash);
+        s.set(line, 'opacity', look.opacity);
+        const halo = this.styleFor(['calloutBox', 'shape']).fill, size = a.dotSize ?? 4, shown = a.dots ? hits : [];
+        shown.forEach((hit, i) => {
+            const dot = s.node(`dot-${i}`, 'path');
+            s.set(dot, 'd', circlePath(hit.px, hit.py, size));
+            s.set(dot, 'fill', hit.series.color);
+            s.set(dot, 'stroke', halo);
+            s.set(dot, 'stroke-width', 1.5);
+        });
+        for (let i = shown.length; i < this.#dots; i++)
+            s.remove(`dot-${i}`);
+        this.#dots = shown.length;
+    }
+}

package/dist/cursor.d.ts

@@ -0,0 +1,76 @@
+import type { Chart } from './chart.ts';
+import { type BaseAttributes, ChartElement, type ElementRef } from './element.ts';
+import { inputOf } from './input.ts';
+import { type ChartEvent, type Hit } from './events.ts';
+import { Plane } from './plane.ts';
+import type { Series } from './series.ts';
+import type { ChartTooltip } from './furniture.ts';
+import type { Crosshair } from './crosshair.ts';
+/** What the keyboard can do to the cursor. */
+export type CursorAction = 'next' | 'previous' | 'nextSeries' | 'previousSeries' | 'first' | 'last' | 'jumpNext' | 'jumpPrevious' | 'clear';
+/** Keys, by `KeyboardEvent.key`, for each action. An action left out has the default keys; an empty list turns it off. */
+export type CursorKeys = Partial<Record<CursorAction, readonly string[]>>;
+export declare const DEFAULT_CURSOR_KEYS: Readonly<Record<CursorAction, readonly string[]>>;
+export interface CursorAttributes extends BaseAttributes {
+    /** What it finds: the 'nearest' point, or every series 'shared' at its place along the first axis. Default 'nearest'. */
+    mode?: 'nearest' | 'shared';
+    /** Read the line between its two points at the cursor instead of reporting a point. Domain series only; others keep their nearest point. Default false. */
+    interpolate?: boolean;
+    /** The plane it works in. Default: the plane the pointer is over, and the first plane for the keyboard. */
+    plane?: ElementRef<Plane>;
+    /** Keys for moving it from the keyboard, or `false` for none (and no tab stop). */
+    keys?: CursorKeys | false;
+}
+/** Where the cursor is and what is there. */
+export interface CursorState {
+    readonly plane: Plane;
+    /** The cursor in the plane's plot pixels: the pointer's place, or the point stepped to with the keyboard. */
+    readonly x: number;
+    readonly y: number;
+    /** Which of the two moved it last. */
+    readonly source: 'pointer' | 'keyboard';
+    /** What is there under the cursor's mode, topmost series first; none when the pointer is over nothing. */
+    readonly hits: readonly Hit[];
+}
+/** What an element inside a cursor says about itself. */
+export interface CursorChild {
+    /** True when it is drawn at the pointer's own place, so the cursor must redraw for each movement and not only for a change of hit. */
+    readonly follows: boolean;
+}
+export interface CursorChildMap {
+    crosshair: Crosshair;
+    tooltip: ChartTooltip;
+}
+export type CursorChildren = CursorChildMap[keyof CursorChildMap][];
+export declare class Cursor extends ChartElement<Chart, CursorChildren, CursorAttributes> {
+    #private;
+    static takesInput: typeof inputOf;
+    static attrTypes: {
+        plane: 1;
+        keys: {
+            nextSeries: 0;
+            previousSeries: 0;
+            jumpNext: 0;
+            jumpPrevious: 0;
+        };
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** The keys in force: the defaults with the ones asked for laid over them, or none. */
+    get keyMap(): CursorKeys | null;
+    /**
+     * Where the cursor is and what is there, or null when it is nowhere: the pointer is off the plot (or on its corner, for a
+     * round plot), a button is held (a drag), or the keyboard has put it away. Worked out afresh after each flush, since
+     * the data may have been edited, or the view panned, under a pointer that has not moved.
+     */
+    get state(): CursorState | null;
+    /** The plane the cursor is tied to by `plane`, else the first. */
+    get plane(): Plane | null;
+    /** Put the keyboard cursor on a point of a series, as if stepped to, and show it. */
+    select(series: Series, index: number): void;
+    onEvent(ev: ChartEvent): void;
+}