inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/dom-platform.js

@@ -0,0 +1,190 @@
+import { SVG_NS, estimateTextWidth } from './platform.js';
+/* oxlint-disable typescript/consistent-type-assertions -- the opaque `PlatformNode` handle is a DOM `Element` here, and DOM event targets are loosely typed: the casts sit at this one boundary */
+/**
+ * A platform node is the library's opaque handle; in this platform it is always a DOM element. These views are the only places the
+ * handle is converted (the library's types do not mention DOM types, so they cannot say so themselves).
+ */
+const element = (node) => node;
+const fromElement = (node) => node;
+/**
+ * Draws into a live `<svg>` appended to a container, and reports the container's size and pointer input on it.
+ * The container needs a height of its own; without one the platform assumes 600 wide by 300 high.
+ * Pointer events are captured while a button is down. Once something in the chart listens for the pointer (the chart then
+ * subscribes through `onPointer`) the svg sets `touch-action: none`, so a drag or a wheel turn over the chart belongs to the
+ * chart (`setTouchMode('two-finger')` lets one finger scroll the page instead); until then it sets none, and the chart is a picture.
+ */
+export class DOMPlatform {
+    name = 'dom';
+    root;
+    schedule;
+    measureText;
+    #container;
+    #svg;
+    #fixed;
+    /** The container's document, seen with DOM types (`DOMContainer` keeps them out of the public signature). */
+    get #document() { return this.#container.ownerDocument; }
+    #cleanups = new Set();
+    constructor(container, options = {}) {
+        this.#container = container;
+        this.#fixed = options.size ?? null;
+        this.#svg = container.ownerDocument.createElementNS(SVG_NS, 'svg');
+        this.root = fromElement(this.#svg);
+        this.#svg.style.display = 'block';
+        this.#svg.style.userSelect = 'none';
+        container.appendChild(this.#svg);
+        switch (options.schedule ?? 'frame') {
+            case 'frame':
+                this.schedule = (cb) => { const id = requestAnimationFrame(() => cb()); return () => cancelAnimationFrame(id); };
+                break;
+            case 'microtask':
+                this.schedule = (cb) => { let live = true; queueMicrotask(() => live && cb()); return () => { live = false; }; };
+                break;
+            case 'manual':
+                break;
+            default:
+                this.schedule = options.schedule;
+        }
+        if (options.preciseText !== false) {
+            let context;
+            this.measureText = (text, font) => {
+                // One shared canvas context: measuring is the hot path of tick layout, and creating contexts is slow. A page with no
+                // canvas to measure on (jsdom, a locked-down browser) gets the estimate rather than a chart that cannot be drawn.
+                if (context === undefined)
+                    context = this.#document.createElement('canvas').getContext('2d') ?? null;
+                if (!context)
+                    return estimateTextWidth(text, font);
+                context.font = `${font.weight ?? 400} ${font.size}px ${font.family}`;
+                return { width: context.measureText(text).width, height: font.size * 1.2 };
+            };
+        }
+    }
+    /** `|| 600` / `|| 300`: a container that has not been laid out yet reports 0, which would give an unusable chart. */
+    size() {
+        return this.#fixed ?? { width: this.#container.clientWidth || 600, height: this.#container.clientHeight || 300 };
+    }
+    createNode(tag) { return fromElement(this.#svg.ownerDocument.createElementNS(SVG_NS, tag)); }
+    setAttribute(node, name, value) { element(node).setAttribute(name, String(value)); }
+    setText(node, text) { element(node).textContent = text; }
+    insertBefore(parent, node, before) { element(parent).insertBefore(element(node), before && element(before)); }
+    remove(node) { element(node).remove(); }
+    setCursor(cursor) { this.#svg.style.cursor = cursor; }
+    #touchMode = 'always';
+    #listening = false;
+    setTouchMode(mode) {
+        this.#touchMode = mode;
+        this.#applyTouchAction();
+    }
+    /** A chart that listens for pointer input takes the touches on it; one that does not is a picture, and the page keeps its scrolling. */
+    #applyTouchAction() {
+        this.#svg.style.touchAction = !this.#listening ? '' : this.#touchMode === 'always' ? 'none' : 'pan-x pan-y';
+    }
+    onResize(callback) {
+        if (this.#fixed)
+            return () => { };
+        const observer = new ResizeObserver(() => callback(this.size()));
+        observer.observe(this.#container);
+        return this.#track(() => observer.disconnect());
+    }
+    onPointer(callback) {
+        const svg = this.#svg;
+        // Coordinates are made relative to the svg here so no element needs to know where the chart sits on the page.
+        const send = (e, kind, extra = {}) => {
+            const box = svg.getBoundingClientRect();
+            return callback({
+                kind, x: e.clientX - box.left, y: e.clientY - box.top, buttons: e.buttons, deltaY: 0,
+                id: e.pointerId ?? 0, pointerType: e.pointerType === 'pen' || e.pointerType === 'touch' ? e.pointerType : 'mouse',
+                shift: e.shiftKey, ctrl: e.ctrlKey || e.metaKey, ...extra,
+            });
+        };
+        // Safari reports a trackpad pinch as gesture events (not as wheel events with ctrlKey, as other browsers do): each carries the
+        // total scale since the gesture began, which is turned here into the factor since the last event.
+        let gestureScale = 1;
+        // Handlers are typed by the event they are registered for; the table is widened to `Event` at its one point of use, below.
+        const listeners = [
+            ['pointermove', (e) => send(e, 'move')],
+            ['pointerdown', (e) => { svg.setPointerCapture(e.pointerId); send(e, 'down'); }],
+            ['pointerup', (e) => send(e, 'up')],
+            ['pointercancel', (e) => send(e, 'up')],
+            ['pointerleave', (e) => send(e, 'leave')],
+            ['wheel', (e) => {
+                    // Wheel deltas arrive in lines or pages on some devices; normalise to pixels so zoom speed is consistent.
+                    const unit = e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? this.size().height : 1;
+                    if (send(e, 'wheel', { deltaY: e.deltaY * unit, deltaX: e.deltaX * unit }))
+                        e.preventDefault();
+                }, { passive: false }],
+            ['gesturestart', (e) => { gestureScale = 1; e.preventDefault(); }],
+            ['gesturechange', (e) => {
+                    const scale = e.scale / gestureScale;
+                    gestureScale = e.scale;
+                    send(e, 'pinch', { scale });
+                    e.preventDefault();
+                }, { passive: false }],
+            // With one finger the page scrolls (touch-action allows it); a second finger down means the chart has taken the gesture.
+            ['touchmove', (e) => { if (this.#touchMode === 'two-finger' && e.touches.length > 1 && e.cancelable)
+                    e.preventDefault(); }, { passive: false }],
+        ];
+        for (const [type, handler, options] of listeners)
+            svg.addEventListener(type, handler, options);
+        this.#listening = true;
+        this.#applyTouchAction();
+        return this.#track(() => {
+            for (const [type, handler, options] of listeners)
+                svg.removeEventListener(type, handler, options);
+            this.#listening = false;
+            this.#applyTouchAction();
+        });
+    }
+    onKey(callback) {
+        const svg = this.#svg;
+        const handler = (kind) => (e) => {
+            // The browser's own shortcuts (copy, reload, switch tab) are never the chart's to take.
+            if (e.metaKey || (e.ctrlKey && e.key.length === 1))
+                return;
+            const used = callback({ kind, key: e.key, shift: e.shiftKey, ctrl: e.ctrlKey, alt: e.altKey, repeat: e.repeat }, fromElement(e.target));
+            if (used)
+                e.preventDefault();
+        };
+        const down = handler('down'), up = handler('up');
+        svg.addEventListener('keydown', down);
+        svg.addEventListener('keyup', up);
+        return this.#track(() => { svg.removeEventListener('keydown', down); svg.removeEventListener('keyup', up); });
+    }
+    onFocus(callback) {
+        const svg = this.#svg;
+        const into = (e) => callback({ node: fromElement(e.target), focused: true, visible: !!e.target?.matches?.(':focus-visible') });
+        const out = (e) => callback({ node: fromElement(e.target), focused: false, visible: false });
+        svg.addEventListener('focusin', into);
+        svg.addEventListener('focusout', out);
+        return this.#track(() => { svg.removeEventListener('focusin', into); svg.removeEventListener('focusout', out); });
+    }
+    /** A visually hidden live region beside the chart: SVG text is not reliably announced when it changes, an HTML status is. */
+    announce(text) {
+        if (!this.#live) {
+            const live = this.#document.createElement('div');
+            live.setAttribute('role', 'status');
+            live.setAttribute('aria-live', 'polite');
+            live.setAttribute('aria-atomic', 'true');
+            live.style.cssText = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0';
+            this.#container.appendChild(live);
+            this.#live = live;
+        }
+        this.#live.textContent = text;
+    }
+    #live = null;
+    focus(node) { element(node).focus({ focusVisible: true }); }
+    dispose() {
+        // oxlint-disable-next-line unicorn/no-useless-spread -- a snapshot: each cleanup removes itself from the set while we walk it
+        for (const cleanup of [...this.#cleanups])
+            cleanup();
+        this.#svg.remove();
+        this.#live?.remove();
+        this.#live = null;
+    }
+    /** Registers a cleanup so `dispose()` releases every listener even if the caller never unsubscribed. */
+    #track(cleanup) {
+        const once = () => { if (this.#cleanups.delete(once))
+            cleanup(); };
+        this.#cleanups.add(once);
+        return once;
+    }
+}

package/dist/element.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The element base class: a retained tree with three links per node, typed children, events and tree utilities.
+ *
+ * How the pieces fit together
+ * ───────────────────────────
+ * Elements form one tree (Chart → Plane → Axis/Series → data/renderers). Three systems live on top of it:
+ *
+ * 1. Events. A parent never calls a child's methods to lay it out or draw it; it sends an event (`measureChild`,
+ *    `arrangeChild`, or `broadcast` for ATTACH/PAINT/POINTER/HOVER) and the child's `onEvent` answers. One extension
+ *    point means subclasses stay small, and the same tree can be driven by tests, by an adapter, or by the real chart.
+ * 2. Drawing. Each element draws through its own `Surface` (created lazily, so non-drawing elements cost nothing),
+ *    which keeps its platform nodes keyed and skips attribute writes that did not change. Elements do not know where
+ *    their nodes sit among the others' — see "Placement" below.
+ * 3. Invalidation. Any change calls `invalidate()`, which walks to the root; the chart there schedules a flush that
+ *    re-runs layout and paint over the whole tree. Re-running everything is cheap because Surface caches the output.
+ *
+ * Placement: the document order of SVG nodes must follow tree order (so a later sibling paints over an earlier one),
+ * yet elements are mounted, drawn and removed independently. Rather than store positions, each Surface asks the live
+ * tree on demand: `container()` (the nearest ancestor wrapper `<g>`, else the platform root) and `end()` (the first
+ * node of whatever element draws next). Because the answer is derived from the tree, inserting or removing an element
+ * anywhere cannot leave a stale position behind.
+ */
+import type { Chart } from './chart.ts';
+import { type ChartEvent, type ChartEventInit } from './events.ts';
+import type { LayoutRequest, Rect, Size } from './geometry.ts';
+import type { Platform } from './platform.ts';
+import type { Roots, SelectorName, Theme } from './theme.ts';
+import { type Counters, Surface } from './surface.ts';
+import { type JsxChild } from './attrs.ts';
+/**
+ * Naming for an element, for people who cannot see it. `title` is its accessible name and `description` a longer account
+ * of it. `role` overrides the ARIA role the element would have, and `aria` sets any other ARIA attributes by name
+ * (`{ 'aria-roledescription': 'sparkline' }`, or `{ roledescription: 'sparkline' }`). See aria.ts.
+ */
+export interface Meta {
+    title?: string;
+    description?: string;
+    role?: string;
+    aria?: Record<string, string | number | boolean>;
+}
+/** What every element accepts. */
+export interface BaseAttributes {
+    /** Lets other elements (and JSON/adapter configs) refer to this one by name; see `resolveRef`. */
+    id?: string;
+    meta?: Meta;
+    /** False hides the element and everything inside it without removing it, so toggling is cheap and keeps state. */
+    visible?: boolean;
+    /**
+     * Looks for this element and everything below it, by selector (see theme.ts). Nearer blocks beat farther ones, and every
+     * block beats the chart's base theme. The element's own attributes that share a style property's name (`stroke`, `fill`…)
+     * are the same thing set directly, and beat any block.
+     */
+    style?: Theme;
+}
+/**
+ * Any element, whatever its children and attributes. `any` is required here: element types are invariant in their children
+ * (they appear in both the constructor and `children`) and in their attributes, so no concrete type, not even `unknown`, accepts every element.
+ */
+export type AnyElement = ChartElement<any, any, any>;
+/**
+ * The parameter list of "any constructor". Constructor parameters are contravariant, so `unknown[]` would reject every class with a typed
+ * parameter; `never[]` would make the class uncallable. `any[]` is the only list every constructor accepts.
+ */
+export type AnyArgs = any[];
+/**
+ * Attributes first, then the children as declared by the parent. A parent declares them as a tuple type:
+ * `[Scale]` is exactly one scale, `[DataNode, ...SeriesRenderer[]]` is one source then any renderers,
+ * `Axis[]` is any number. Attributes may be left out when none are required.
+ */
+export type ElementArgs<A, Children extends readonly AnyElement[]> = [attrs: A, ...children: Children] | ({} extends A ? [...children: Children] : never);
+export type ElementClass<T extends AnyElement = AnyElement> = abstract new (...args: AnyArgs) => T;
+/** A class whose instances are (some of) `T`: for a union, a class of any one member. */
+export type ClassFor<T> = T extends unknown ? abstract new (...args: AnyArgs) => T : never;
+/** An element, or the id of one. Vanilla code passes the variable; adapters and JSON pass the id. */
+export type ElementRef<T extends AnyElement = AnyElement> = T | string;
+/** What an attached element needs from the chart: where to draw, and the counters Surface reports into. */
+interface MountContext {
+    platform: Platform;
+    counters: Counters;
+}
+/**
+ * The element type of a parent's variadic tail: the children that may come and go.
+ * `[Scale]` has none, `[DataNode, ...SeriesRenderer[]]` has SeriesRenderer, `Axis[]` has Axis.
+ */
+export type VariadicChild<C extends readonly unknown[]> = C extends readonly [unknown, ...infer Rest] ? VariadicChild<Rest> : C extends readonly (infer E)[] ? E : never;
+/** The positions of a parent's fixed children, which are always present and can only be replaced. */
+export type FixedIndex<C extends readonly unknown[], Seen extends unknown[] = []> = C extends readonly [unknown, ...infer Rest] ? Seen['length'] | FixedIndex<Rest, [...Seen, unknown]> : never;
+/**
+ * A node with three links: its parent, its first child, and its next sibling. Nothing else is stored, so
+ * finding a predecessor or the tail walks the siblings, which is cheap at the sizes charts have.
+ */
+export declare abstract class ChartElement<Parent extends AnyElement | null = AnyElement | null, Children extends readonly AnyElement[] = [], Attrs extends BaseAttributes = BaseAttributes> {
+    #private;
+    /** How HTML attributes of this element become values; see attrs.ts. Subclasses repeat these by spreading and add their own. */
+    /**
+     * For an element that takes pointer, key or focus input: set this to `inputOf` (from input.ts), and the chart is made to listen for
+     * input as the element joins it, before the element's own ATTACH handler runs. It is the function and not a flag so that
+     * declaring it brings the input code into a bundle, which a chart with no such element never carries.
+     */
+    static takesInput: ((chart: Chart) => unknown) | null;
+    static attrTypes: {
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /**
+     * Types only, nothing at run time: what a JSX tag for this class accepts (see jsx-runtime.ts): the attributes and children if
+     * there are any (hyphenated names such as `meta-title` are not checked: TypeScript lets any through). Which children, and in what
+     * order, cannot be checked, because TypeScript gives every JSX tag the same type; the class' documentation says.
+     */
+    readonly $props: Attrs & {
+        children?: [Children[number]] extends [never] ? JsxChild<never> : JsxChild<AnyElement>;
+    };
+    /**
+     * `new X(attrs?, ...children)`. The attrs object is recognised by not being an element, and is copied so that
+     * the caller's object is never mutated by later `setAttribute` calls.
+     */
+    constructor(...args: ElementArgs<Attrs, Children>);
+    /** Read-only view; change attributes through `setAttribute(s)` so the chart learns it is stale. */
+    get attrs(): Readonly<Attrs>;
+    get parent(): Parent | null;
+    get firstChild(): AnyElement | null;
+    get nextSibling(): AnyElement | null;
+    /** For elements that only make sense inside a parent (an axis in a plane): fails loudly rather than returning null. */
+    requireParent(): Parent & AnyElement;
+    /** The root chart, if this element is in a tree that has one. */
+    get chart(): Chart | null;
+    /** Like `chart`, for code that only runs inside a chart (painting, input): fails loudly rather than returning null. */
+    requireChart(): Chart;
+    /** True for an element that takes a pointer press (PanZoom): one that must see the press first (a BoxZoom, a Brush) is placed before it. */
+    readonly claimsPress?: boolean;
+    get isAttached(): boolean;
+    /** The children in order. Do not remove the element you are on and the one after it while iterating. */
+    [Symbol.iterator](): Generator<Children[number]>;
+    /**
+     * A fixed child, by position, checked where it is used: it has to be one of `classes` (an instance of any, subclasses
+     * included). The classes must be ones the declared child type allows, so a wrong one is a compile error; a wrong or missing child
+     * is a run-time error that says what was expected and what was found, wherever the tree was built (`new`, JSX, React, markup).
+     */
+    child<I extends FixedIndex<Children> & keyof Children>(index: I, ...classes: [ClassFor<Children[I]>, ...ClassFor<Children[I]>[]]): Children[I];
+    private nth;
+    /** What this element draws with. Created on first use, so an element that draws nothing costs nothing. */
+    protected get surface(): Surface;
+    /** The flush counters if attached, else null: for code that also runs when a node is read outside a chart. */
+    protected get countersOrNull(): Counters | null;
+    /** The chart's flush counters. Only valid between attach and detach. */
+    protected get counters(): Counters;
+    /** Setting `undefined` removes the attribute, so defaults apply again. Unchanged values do not invalidate. */
+    /**
+     * This element's look for a chain of selectors, most specific first, ending in a root: all of that root's properties,
+     * settled (see theme.ts for the order). `local` is the element's own attributes that are style properties; `accent` is
+     * a default colour from the palette that anything named in a theme beats.
+     */
+    protected styleFor<R extends keyof Roots>(chain: readonly [...SelectorName[], R], local?: Partial<Roots[R]>, accent?: Partial<Roots[R]>): Roots[R];
+    getAttribute<K extends keyof Attrs>(name: K): Attrs[K];
+    setAttribute<K extends keyof Attrs>(name: K, value: Attrs[K]): this;
+    setAttributes(patch: Partial<Attrs>): this;
+    private put;
+    /** Put `child` in front of `before` (null: at the end). Finding the place walks the siblings. */
+    private link;
+    private unlink;
+    /**
+     * Add children that can come and go. Fixed children (an axis' scale, a series' data) are given to the
+     * constructor and replaced with `setChild`; the types do not allow adding or removing them.
+     */
+    append(...children: VariadicChild<Children>[]): this;
+    /** Exactly `Node.insertBefore`: `before` is one of this element's children, or null to add at the end. */
+    insertBefore(child: VariadicChild<Children>, before: Children[number] | null): this;
+    remove(child: VariadicChild<Children>): this;
+    /** Swap one of the fixed children for another of the same kind. */
+    setChild<I extends FixedIndex<Children> & keyof Children>(index: I, child: Children[I]): this;
+    /** Convenience for `parent.remove(this)` when the caller holds only the child. */
+    detachFromParent(): this;
+    /**
+     * Something about this element is stale. The request travels to the root, where a chart on a
+     * scheduling platform arranges a flush. Each flush re-runs layout; fills are cached and unchanged
+     * attribute writes skipped, which is where the saving is.
+     */
+    invalidate(): void;
+    /** The single extension point. Switch on `event.type`; ignore what you don't handle. */
+    onEvent(_event: ChartEvent): void;
+    /** Deliver an event to `root` (default: this element) and everything beneath it, parents first. */
+    protected broadcast(init: ChartEventInit, root?: AnyElement): ChartEvent;
+    /** Parents are visited before their children, so a parent can set up state its children read in the same event. */
+    private cascade;
+    /** Ask a child how much space it needs. */
+    protected measureChild(child: AnyElement, available: Size): LayoutRequest;
+    /** Tell a child where it is. */
+    protected arrangeChild(child: AnyElement, rect: Rect): void;
+    /** The one entry point for events: the base class handles what every element shares, then the subclass sees it. */
+    private receive;
+    /** Put this tree on the platform. The root calls it; elements added later are mounted by their parent. */
+    protected mount(ctx: MountContext): void;
+    /**
+     * `removeNodes` is false once an ancestor's wrapper is being removed: everything inside goes with it.
+     * Without a wrapper, an element's nodes sit in a shared container and have to be taken out one by one.
+     */
+    protected unmount(removeNodes: boolean): void;
+    /** The first node of this element's content, or null if it and everything below it has drawn nothing. */
+    private first;
+    private firstOfChildren;
+    /** The node this element's content ends before: whatever the next element that has drawn starts with. */
+    private end;
+    /** The node this element's own nodes go into when it has no wrapper. */
+    private container;
+    /** Hidden if it, or an ancestor without a wrapper to hide for it, says `visible: false`. */
+    private isHidden;
+}
+/** Depth-first, parents before children. Returning `false` from `visit` skips that element's subtree. */
+export declare function walk(root: AnyElement, visit: (element: AnyElement, depth: number) => boolean | void, depth?: number): void;
+/** The first element under `root` (or `root` itself) with this id. */
+export declare function findById<T extends AnyElement = AnyElement>(root: AnyElement, id: string): T | undefined;
+/** Every element below `root` of a class, in tree order. */
+export declare function descendantsOfType<T extends AnyElement>(root: AnyElement, type: ElementClass<T>): T[];
+/** The first element below `root` of a class, stopping the walk as soon as it is found. */
+export declare function firstDescendantOfType<T extends AnyElement>(root: AnyElement, type: ElementClass<T>): T | undefined;
+/** The direct children of a class; use it when the parent's children are mixed (an axis next to series). */
+export declare function childrenOfType<T extends AnyElement>(parent: AnyElement, type: ElementClass<T>): T[];
+/** The nearest enclosing element of a class: how a child finds "its" plane or chart without being handed one. */
+export declare function closestAncestorOfType<T extends AnyElement>(from: AnyElement, type: ElementClass<T>): T | undefined;
+/**
+ * Turns an `ElementRef` into the element: ids are looked up from the root of `from`'s tree, elements pass through.
+ * With `type`, a mismatch is reported by name, which is the useful error when a config points at the wrong thing.
+ */
+export declare function resolveRef<T extends AnyElement>(ref: ElementRef<T>, from: AnyElement, type?: ElementClass<T>): T;
+export declare function resolveRef<T extends AnyElement>(ref: ElementRef<T> | undefined, from: AnyElement, type?: ElementClass<T>): T | undefined;
+/** `throw` as an expression, so a missing value can be reported inline: `x ?? fail('no x')`. */
+export declare function fail(message: string): never;
+export {};