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

package/dist/element.js

@@ -0,0 +1,414 @@
+import { EVENT_ARRANGE, EVENT_ATTACH, EVENT_MEASURE, EVENT_PAINT, makeEvent } from './events.js';
+import { resolveStyle } from './theme.js';
+import { Surface } from './surface.js';
+import { STRING } from './attrs.js';
+/** The answer of an element that did not respond to MEASURE: it wants nothing and can take anything. */
+const NO_REQUEST = { min: { width: 0, height: 0 }, max: { width: Infinity, height: Infinity } };
+/**
+ * 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 class ChartElement {
+    /** 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 = null;
+    static attrTypes = { id: STRING, meta: { title: STRING, description: STRING, role: STRING } };
+    #attrs;
+    #parent = null;
+    #first = null;
+    #next = null;
+    #surface = null;
+    #ctx = null;
+    #hidden = false;
+    /**
+     * `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) {
+        const list = args;
+        let i = 0;
+        const first = list[0];
+        if (first === undefined || (typeof first === 'object' && first !== null && !(first instanceof ChartElement))) {
+            this.#attrs = { ...first };
+            i = 1;
+        }
+        else {
+            this.#attrs = {};
+        }
+        for (; i < list.length; i++)
+            this.link(list[i], null);
+    }
+    /** Read-only view; change attributes through `setAttribute(s)` so the chart learns it is stale. */
+    get attrs() { return this.#attrs; }
+    get parent() { return this.#parent; }
+    get firstChild() { return this.#first; }
+    get nextSibling() { return this.#next; }
+    /** For elements that only make sense inside a parent (an axis in a plane): fails loudly rather than returning null. */
+    requireParent() {
+        if (!this.#parent)
+            fail(`${this.constructor.name} has no parent`);
+        return this.#parent;
+    }
+    /** The root chart, if this element is in a tree that has one. */
+    get chart() { return this.#parent ? this.#parent.chart : null; }
+    /** Like `chart`, for code that only runs inside a chart (painting, input): fails loudly rather than returning null. */
+    requireChart() { return this.chart ?? fail(`${this.constructor.name} is not in a chart`); }
+    get isAttached() { return this.#ctx !== null; }
+    /** The children in order. Do not remove the element you are on and the one after it while iterating. */
+    *[Symbol.iterator]() {
+        for (let c = this.#first; c;) {
+            const next = c.#next;
+            yield c;
+            c = next;
+        }
+    }
+    /**
+     * How `console.log`, `util.inspect` and a failing `assert` print an element: its class, id and child count, not the tree, the
+     * platform and everything else it can reach. Without this, one failed `assert.equal(thing, null)` on an object that holds an
+     * element (a plane in a hit, a cursor state) prints the whole chart and can run a test out of memory.
+     */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        let n = 0;
+        for (let c = this.#first; c; c = c.#next)
+            n++;
+        const id = this.#attrs.id;
+        return `${this.constructor.name}${id ? `#${id}` : ''}${n ? `(${n})` : ''}`;
+    }
+    /**
+     * 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(index, ...classes) {
+        const found = this.nth(index);
+        const names = classes.map((k) => k.name || 'a different class').join(' or ');
+        if (!found)
+            fail(`${this.constructor.name}: has no child ${index} (it needs ${names})`);
+        if (!classes.some((k) => found instanceof k))
+            fail(`${this.constructor.name}: child ${index} should be ${names}, but is ${found.constructor.name}`);
+        return found;
+    }
+    nth(index) {
+        let c = this.#first;
+        for (let i = 0; c && i < index; i++)
+            c = c.#next;
+        return c;
+    }
+    /** What this element draws with. Created on first use, so an element that draws nothing costs nothing. */
+    get surface() {
+        const ctx = this.#ctx ?? fail(`${this.constructor.name} is not attached`);
+        if (!this.#surface) {
+            this.#surface = new Surface(ctx.platform, ctx.counters, {
+                container: () => this.container(),
+                end: () => this.end(),
+                childrenFirst: () => this.firstOfChildren(),
+            });
+            if (this.#hidden)
+                this.#surface.setHidden(true);
+        }
+        return this.#surface;
+    }
+    /** The flush counters if attached, else null: for code that also runs when a node is read outside a chart. */
+    get countersOrNull() { return this.#ctx?.counters ?? null; }
+    /** The chart's flush counters. Only valid between attach and detach. */
+    get counters() {
+        return (this.#ctx ?? fail(`${this.constructor.name} is not attached`)).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.
+     */
+    styleFor(chain, local, accent) {
+        const chart = this.chart ?? fail(`${this.constructor.name} is not in a chart`);
+        const scopes = [];
+        // oxlint-disable-next-line typescript/no-this-alias -- a walk up the parent chain that starts at this element
+        for (let e = this; e; e = e.#parent)
+            scopes.push(e.#attrs.style);
+        return resolveStyle(chain, scopes, chart.attrs.theme, local, accent);
+    }
+    getAttribute(name) { return this.#attrs[name]; }
+    setAttribute(name, value) {
+        if (this.put(name, value))
+            this.invalidate();
+        return this;
+    }
+    setAttributes(patch) {
+        let changed = false;
+        for (const name of Object.keys(patch))
+            changed = this.put(name, patch[name]) || changed;
+        if (changed)
+            this.invalidate();
+        return this;
+    }
+    put(name, value) {
+        if (this.#attrs[name] === value)
+            return false;
+        if (value === undefined)
+            delete this.#attrs[name];
+        else
+            this.#attrs[name] = value;
+        return true;
+    }
+    /** Put `child` in front of `before` (null: at the end). Finding the place walks the siblings. */
+    link(child, before) {
+        if (child.#parent)
+            fail('element already has a parent');
+        let prev = null;
+        for (let c = this.#first; c && c !== before; c = c.#next)
+            prev = c;
+        child.#parent = this;
+        child.#next = before;
+        if (prev)
+            prev.#next = child;
+        else
+            this.#first = child;
+    }
+    unlink(child) {
+        let prev = null;
+        let c = this.#first;
+        for (; c && c !== child; c = c.#next)
+            prev = c;
+        if (!c)
+            fail('element is not a child of this element');
+        if (prev)
+            prev.#next = child.#next;
+        else
+            this.#first = child.#next;
+        child.#next = child.#parent = null;
+    }
+    /**
+     * 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) {
+        for (const c of children)
+            this.insertBefore(c, null);
+        return this;
+    }
+    /** Exactly `Node.insertBefore`: `before` is one of this element's children, or null to add at the end. */
+    insertBefore(child, before) {
+        this.link(child, before);
+        if (this.#ctx)
+            child.mount(this.#ctx);
+        this.invalidate();
+        return this;
+    }
+    remove(child) {
+        child.unmount(true);
+        this.unlink(child);
+        this.invalidate();
+        return this;
+    }
+    /** Swap one of the fixed children for another of the same kind. */
+    setChild(index, child) {
+        const old = this.nth(index) ?? fail(`${this.constructor.name}: has no child ${index} to replace`);
+        this.link(child, old);
+        old.unmount(true);
+        this.unlink(old);
+        if (this.#ctx)
+            child.mount(this.#ctx);
+        this.invalidate();
+        return this;
+    }
+    /** Convenience for `parent.remove(this)` when the caller holds only the child. */
+    detachFromParent() {
+        this.#parent?.remove(this);
+        return 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() {
+        this.#parent?.invalidate();
+    }
+    /** The single extension point. Switch on `event.type`; ignore what you don't handle. */
+    onEvent(_event) { }
+    /** Deliver an event to `root` (default: this element) and everything beneath it, parents first. */
+    broadcast(init, root = this) {
+        const ev = makeEvent(init, root);
+        root.cascade(ev);
+        return ev;
+    }
+    /** Parents are visited before their children, so a parent can set up state its children read in the same event. */
+    cascade(ev) {
+        this.receive(ev);
+        for (let c = this.#first; c;) {
+            const next = c.#next;
+            c.cascade(ev);
+            c = next;
+        }
+    }
+    /** Ask a child how much space it needs. */
+    measureChild(child, available) {
+        const ev = makeEvent({ type: EVENT_MEASURE, available, request: NO_REQUEST }, child);
+        child.receive(ev);
+        return ev.request;
+    }
+    /** Tell a child where it is. */
+    arrangeChild(child, rect) {
+        child.receive(makeEvent({ type: EVENT_ARRANGE, rect }, child));
+    }
+    /** The one entry point for events: the base class handles what every element shares, then the subclass sees it. */
+    receive(ev) {
+        switch (ev.type) {
+            case EVENT_PAINT: {
+                // Visibility is the one thing every element draws, so the base class owns it.
+                const hidden = this.isHidden();
+                if (hidden !== this.#hidden) {
+                    this.#hidden = hidden;
+                    this.#surface?.setHidden(hidden);
+                }
+                break;
+            }
+        }
+        this.onEvent(ev);
+    }
+    /** Put this tree on the platform. The root calls it; elements added later are mounted by their parent. */
+    mount(ctx) {
+        this.#ctx = ctx;
+        const takes = this.constructor.takesInput, chart = this.chart;
+        if (takes && chart)
+            takes(chart);
+        this.receive(makeEvent({ type: EVENT_ATTACH, platform: ctx.platform }, this));
+        for (let c = this.#first; c; c = c.#next)
+            c.mount(ctx);
+    }
+    /**
+     * `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.
+     */
+    unmount(removeNodes) {
+        const ownsWrapper = !!this.#surface?.wrapperRoot;
+        for (let c = this.#first; c; c = c.#next)
+            c.unmount(removeNodes && !ownsWrapper);
+        if (!this.#ctx)
+            return;
+        if (removeNodes)
+            this.#surface?.dispose();
+        this.#surface = null;
+        this.#ctx = null;
+    }
+    // ─── Placement: where nodes go, worked out from the live tree (see the class comment) ───
+    /** The first node of this element's content, or null if it and everything below it has drawn nothing. */
+    first() {
+        const s = this.#surface;
+        return s?.wrapperRoot ?? s?.firstBelow ?? this.firstOfChildren() ?? s?.firstAbove ?? null;
+    }
+    firstOfChildren() {
+        for (let c = this.#first; c; c = c.#next) {
+            const node = c.first();
+            if (node)
+                return node;
+        }
+        return null;
+    }
+    /** The node this element's content ends before: whatever the next element that has drawn starts with. */
+    end() {
+        for (let s = this.#next; s; s = s.#next) {
+            const node = s.first();
+            if (node)
+                return node;
+        }
+        const p = this.#parent;
+        if (!p)
+            return null;
+        return p.#surface?.wrapperRoot ? null : p.end();
+    }
+    /** The node this element's own nodes go into when it has no wrapper. */
+    container() {
+        for (let p = this.#parent; p; p = p.#parent) {
+            const wrapper = p.#surface?.wrapperRoot;
+            if (wrapper)
+                return wrapper;
+        }
+        return (this.#ctx ?? fail('element is not attached')).platform.root;
+    }
+    /** Hidden if it, or an ancestor without a wrapper to hide for it, says `visible: false`. */
+    isHidden() {
+        // oxlint-disable-next-line typescript/no-this-alias -- a walk up the parent chain that starts at this element
+        for (let e = this; e; e = e.#parent) {
+            if (e.#attrs.visible === false)
+                return e === this || !e.#surface?.wrapperRoot;
+            if (e !== this && e.#surface?.wrapperRoot)
+                return false;
+        }
+        return false;
+    }
+}
+// ─── Tree utilities ───
+// Plain functions rather than methods so unused ones tree-shake away.
+/** Depth-first, parents before children. Returning `false` from `visit` skips that element's subtree. */
+export function walk(root, visit, depth = 0) {
+    if (visit(root, depth) === false)
+        return;
+    for (const c of root)
+        walk(c, visit, depth + 1);
+}
+/** The first element under `root` (or `root` itself) with this id. */
+export function findById(root, id) {
+    let found;
+    walk(root, (e) => { if (found)
+        return false; if (e.attrs.id === id) {
+        found = e;
+        return false;
+    } });
+    return found;
+}
+/** Every element below `root` of a class, in tree order. */
+export function descendantsOfType(root, type) {
+    const out = [];
+    walk(root, (e) => { if (e !== root && e instanceof type)
+        out.push(e); });
+    return out;
+}
+/** The first element below `root` of a class, stopping the walk as soon as it is found. */
+export function firstDescendantOfType(root, type) {
+    let found;
+    walk(root, (e) => { if (found)
+        return false; if (e !== root && e instanceof type) {
+        found = e;
+        return false;
+    } });
+    return found;
+}
+/** The direct children of a class; use it when the parent's children are mixed (an axis next to series). */
+export function childrenOfType(parent, type) {
+    return [...parent].filter((c) => c instanceof type);
+}
+/** The nearest enclosing element of a class: how a child finds "its" plane or chart without being handed one. */
+export function closestAncestorOfType(from, type) {
+    for (let e = from.parent; e; e = e.parent)
+        if (e instanceof type)
+            return e;
+    return undefined;
+}
+export function resolveRef(ref, from, type) {
+    if (ref === undefined)
+        return undefined;
+    let el;
+    if (typeof ref === 'string') {
+        let root = from;
+        while (root.parent)
+            root = root.parent;
+        el = findById(root, ref);
+        if (!el)
+            fail(`no element with id "${ref}"`);
+    }
+    else {
+        el = ref;
+    }
+    if (type && !(el instanceof type)) {
+        fail(`element "${typeof ref === 'string' ? ref : ref.attrs.id ?? '?'}" is not a ${type.name}`);
+    }
+    return el;
+}
+/** `throw` as an expression, so a missing value can be reported inline: `x ?? fail('no x')`. */
+export function fail(message) { throw new Error(message); }

package/dist/errors.d.ts

@@ -0,0 +1,85 @@
+import { SeriesRenderer, type SeriesRendererAttributes, type Spread, type SpreadView } from './renderer.ts';
+import type { Series } from './series.ts';
+import type { Surface } from './surface.ts';
+import type { PlatformNode } from './platform.ts';
+export interface ErrorAttributes extends Omit<SeriesRendererAttributes, 'bind'> {
+    /** The channel with how far above the value each point may be. Required. */
+    error: string;
+    /** The channel with how far below. Default: the same as `error`. */
+    negativeError?: string;
+    /** What the numbers mean: units of the value (default), or a fraction of it. */
+    mode?: 'absolute' | 'relative';
+    /** Which way the error runs. Default 'value'. */
+    along?: 'value' | 'domain';
+}
+export interface ErrorBarsAttributes extends ErrorAttributes {
+    /** Width in pixels of the cap at each end of a whisker; 0 for none. Default 8. */
+    capWidth?: number;
+}
+export interface ErrorBandAttributes extends ErrorAttributes {
+}
+/** What error renderers share: the channels, the rows' spread, and the placed ends. */
+declare abstract class ErrorRenderer<A extends ErrorAttributes> extends SeriesRenderer<A> {
+    get channelNames(): readonly string[];
+    private get negative();
+    spread(view: SpreadView): Spread | null;
+    limit(series: Series): Spread | null;
+    /**
+     * The places in plot pixels of the lower end, the upper end, and a point a little further along the cap's direction from
+     * each (which says which way the cap runs on this plane), for every row: `[lo, hi, loAlong, hiAlong]` of one row after another,
+     * NaN for a row with no bar.
+     */
+    protected ends(series: Series): {
+        n: number;
+        pts: Float64Array;
+    } | null;
+}
+/** A whisker from the lower end to the upper, with a cap across each, as one path. */
+export declare class ErrorBars extends ErrorRenderer<ErrorBarsAttributes> {
+    static attrTypes: {
+        fill: 1;
+        maxNodes: 2;
+        stroke: 1;
+        strokeWidth: 2;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+        error: 1;
+        negativeError: 1;
+        capWidth: 2;
+        mode: 1;
+        along: 1;
+    };
+    /** Neutral by default (the theme's line colour), so that it can be seen on the bars it goes with. */
+    private look;
+    get reach(): number;
+    sample(s: Surface, parent: PlatformNode, key: string, width: number, height: number): void;
+    protected draw(): void;
+}
+/** The region between the lower and the upper ends, as one path; a gap splits it. */
+export declare class ErrorBand extends ErrorRenderer<ErrorBandAttributes> {
+    static attrTypes: {
+        fill: 1;
+        maxNodes: 2;
+        stroke: 1;
+        strokeWidth: 2;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+        error: 1;
+        negativeError: 1;
+        mode: 1;
+        along: 1;
+    };
+    private look;
+    get swatch(): string;
+    sample(s: Surface, parent: PlatformNode, key: string, width: number, height: number): void;
+    protected draw(): void;
+}
+export {};