inkplot 0.0.0-stage → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neofox Solutions LLP and Hamish Milne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# inkplot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small chart library for the web and for servers. A chart is a **tree of elements you keep** (`Chart` → plane → axes and series → data and renderers) that draws SVG through a platform. It is tree-shakeable, has no dependencies, and a minimal chart is about 15 KB gzipped, growing only with the features you import.
+
+> **Beta.** `1.0.0-beta.1` is feature-complete and is out for user testing. Install it with the `beta` tag.
+
+```sh
+npm install inkplot@beta
+```
+
+```tsx
+import { Axis, CartesianPlane, Chart, DomainSeries, FlatDataSource, LinePath, LinearCurve, LinearScale, lightTheme } from 'inkplot';
+
+const chart = (
+  <Chart theme={lightTheme}>
+    <CartesianPlane>
+      <Axis orientation="bottom"><LinearScale /></Axis>
+      <Axis orientation="left"><LinearScale /></Axis>
+      <DomainSeries name="Load">
+        <FlatDataSource data={[3, 5, 4, 8, 6, 9]} regularDomain-start={0} regularDomain-step={1} />
+        <LinePath><LinearCurve /></LinePath>
+      </DomainSeries>
+    </CartesianPlane>
+  </Chart>
+);
+```
+
+The same chart can be written without JSX (`new Chart(attrs, ...children)`), and there are adapters for React (`inkplot/react`) and custom elements (`inkplot/web-components`).
+
+## Documentation
+
+- [Quick start](https://github.com/neofox-solutions/inkplot/blob/main/docs/start/quick-start.md): install, your first chart, and the three ways to write one.
+- [Concepts](https://github.com/neofox-solutions/inkplot/blob/main/docs/start/concepts.md) and [recipes](https://github.com/neofox-solutions/inkplot/blob/main/docs/start/recipes.md).
+- [All the docs](https://github.com/neofox-solutions/inkplot/blob/main/docs/README.md): guide, extending and reference.
+- [SKILL.md](https://github.com/neofox-solutions/inkplot/blob/main/docs/SKILL.md): a brief for an LLM that writes inkplot code.
+
+## inkplot-scratch
+
+`inkplot-scratch` is a command-line tool for turning a module that exports inkplot charts into SVG, PNG, JSON facts or a single-file interactive HTML page, with a skill for agents doing data work. To use it in Claude, download `inkplot-data-charts-<version>.zip` from the [latest release](https://github.com/neofox-solutions/inkplot/releases) and upload it under Customize → Skills. See [scratch/](https://github.com/neofox-solutions/inkplot/tree/main/scratch).
+
+## Developing
+
+Node 26 or later. `npm ci`, then `npm run all` runs the type check, lint, tests, docs checks, and the browser, PNG and packaging tests that CI runs.
+
+## Licence
+
+MIT

package/dist/adapt.d.ts

@@ -0,0 +1,10 @@
+/** What the adapters (React, Web Components) share: writing only the attributes that differ. */
+import { expandAttributes } from './attrs.ts';
+type Plain = Record<string, unknown>;
+/** Same value, or same content for plain objects and arrays (not typed arrays, elements or anything else with an identity). */
+export declare function same(a: unknown, b: unknown): boolean;
+/** What to change to get from `prev` to `next`: changed values, and `undefined` for what is gone. Null when nothing differs. */
+export declare function difference(prev: Plain, next: Plain): Plain | null;
+/** The element's attributes from props: nested names expanded, and what is `undefined` left out. */
+export declare function attributesOf(props: Plain, options?: Parameters<typeof expandAttributes>[1]): Plain;
+export {};

package/dist/adapt.js

@@ -0,0 +1,34 @@
+/** What the adapters (React, Web Components) share: writing only the attributes that differ. */
+import { expandAttributes } from './attrs.js';
+const isPlain = (v) => typeof v === 'object' && v !== null && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+/** Same value, or same content for plain objects and arrays (not typed arrays, elements or anything else with an identity). */
+export function same(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((v, i) => same(v, b[i]));
+    if (isPlain(a) && isPlain(b)) {
+        const keys = Object.keys(a);
+        return keys.length === Object.keys(b).length && keys.every((k) => Object.hasOwn(b, k) && same(a[k], b[k]));
+    }
+    return false;
+}
+/** What to change to get from `prev` to `next`: changed values, and `undefined` for what is gone. Null when nothing differs. */
+export function difference(prev, next) {
+    let patch = null;
+    for (const k of Object.keys(next))
+        if (!same(prev[k], next[k]))
+            (patch ??= {})[k] = next[k];
+    for (const k of Object.keys(prev))
+        if (!(k in next))
+            (patch ??= {})[k] = undefined;
+    return patch;
+}
+/** The element's attributes from props: nested names expanded, and what is `undefined` left out. */
+export function attributesOf(props, options) {
+    const attrs = expandAttributes(props, options);
+    for (const k of Object.keys(attrs))
+        if (attrs[k] === undefined)
+            delete attrs[k];
+    return attrs;
+}

package/dist/annotation.d.ts

@@ -0,0 +1,120 @@
+import { Axis } from './axis.ts';
+import { type BaseAttributes, ChartElement, type ElementRef } from './element.ts';
+import { type ChartEvent } from './events.ts';
+import { type Rect } from './geometry.ts';
+import type { Plane } from './plane.ts';
+export interface LineAnnotationCommon extends BaseAttributes {
+    /** Default: the plane's first axis, as for a series. */
+    domainAxis?: ElementRef<Axis>;
+    /** Default: the plane's second axis. */
+    valueAxis?: ElementRef<Axis>;
+    /** Text beside the line. Where along the line it sits is the style property `align` of `annotationLabel`. */
+    label?: string;
+    /** Line colour: the same as `style: { annotationLine: { color } }`, set directly. */
+    stroke?: string;
+    /** Line width in pixels: the same as `style: { annotationLine: { width } }`, set directly. */
+    strokeWidth?: number;
+    /** A horizontal line at this value (give one of `value`, `domain`, or `from` and `to`). */
+    value?: number;
+    /** A vertical line at this domain (give one of `value`, `domain`, or `from` and `to`). */
+    domain?: number;
+    /** One end of a diagonal line, as `[domain, value]` (with `to`). */
+    from?: readonly [domain: number, value: number];
+    /** The other end of a diagonal line, as `[domain, value]` (with `from`). */
+    to?: readonly [domain: number, value: number];
+}
+/**
+ * Which line: give one of
+ *  - `value`: constant value across the whole domain (horizontal on a rectangle);
+ *  - `domain`: constant domain across the whole value range (vertical on a rectangle, a spoke on a radial plane);
+ *  - `from` and `to`: straight between two `[domain, value]` points in data space (diagonal).
+ */
+export type LineAnnotationAttributes = LineAnnotationCommon & ({
+    value: number;
+    domain?: undefined;
+    from?: undefined;
+    to?: undefined;
+} | {
+    domain: number;
+    value?: undefined;
+    from?: undefined;
+    to?: undefined;
+} | {
+    from: readonly [domain: number, value: number];
+    to: readonly [domain: number, value: number];
+    value?: undefined;
+    domain?: undefined;
+});
+/**
+ * A reference line in data space: a target, a threshold, a trend. It is traced as a polyline through the plane, with as
+ * few points as the plane allows: two when the line stays straight (anything axis-aligned on a rectangle, a diagonal
+ * between linear scales), enough to follow the curve otherwise, and for a radar just the corners, at its spokes. The line is clipped to the plot; its label is not.
+ */
+export declare class LineAnnotation extends ChartElement<Plane, [], LineAnnotationAttributes> {
+    #private;
+    static attrTypes: {
+        domainAxis: 1;
+        label: 1;
+        stroke: 1;
+        strokeWidth: 2;
+        valueAxis: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** The line as placed points in plot pixels, `[x, y]` per row, in order along the line; NaN where there is none. */
+    private trace;
+    onEvent(ev: ChartEvent): void;
+}
+export interface CalloutAnnotationAttributes extends BaseAttributes {
+    /** Default: the plane's first axis. */
+    domainAxis?: ElementRef<Axis>;
+    /** Default: the plane's second axis. */
+    valueAxis?: ElementRef<Axis>;
+    /** The point being called out, in data space. */
+    domain: number;
+    /** The value of the point being called out. */
+    value: number;
+    /** What it says. A '\n' starts another line; `align` (style) says how the lines sit in the box. */
+    text: string;
+    /**
+     * Where the middle of the box is, in pixels from the point. Leave both out to have it placed automatically, in the
+     * emptiest nearby spot; give either (the other is 0) to place it yourself.
+     */
+    dx?: number;
+    /** Pixels down from the point to the text box (negative is up). */
+    dy?: number;
+}
+/**
+ * A note attached to a data point by an arm. Its look is four selectors (the text, the box, the arm and the callout's
+ * own metrics), and `outline` (in `callout`) chooses between a full border, only the edge the arm meets, or none.
+ *
+ * Placement: with no offset given, the box is tried in the eight directions round the point and the spot with the least
+ * trouble wins: parts of the box outside the plot, series points under it, and earlier callouts it would cover, with a
+ * slight preference for the upper right. It is a heuristic, which is why `dx` and `dy` exist.
+ */
+export declare class CalloutAnnotation extends ChartElement<Plane, [], CalloutAnnotationAttributes> {
+    #private;
+    static attrTypes: {
+        domainAxis: 1;
+        text: 1;
+        valueAxis: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** Where the box was drawn, in plot pixels; null while it is not (point out of view). Later callouts keep clear of it. */
+    get box(): Readonly<Rect> | null;
+    /** The data point in plot pixels, or null when it is off the plot. */
+    private locate;
+    /** How bad a box is as a place for a callout: lower is better. */
+    private trouble;
+    onEvent(ev: ChartEvent): void;
+    private paint;
+}

package/dist/annotation.js

@@ -0,0 +1,267 @@
+/**
+ * Annotations: marks that sit in a plane and are positioned in *data* space.
+ *
+ * Why data space: an annotation says "the target is 40" or "this point is interesting", not "pixel 212". So both kinds
+ * here take values on the plane's axes and ask the plane where they are: the axes turn values into fractions, and the
+ * plane's `place` turns fractions into pixels, exactly as for a series. Nothing here knows what shape the plane is, so a
+ * line at a constant value is a horizontal line on a rectangle, a circle on a polar plane, and a polygon on a radar.
+ *
+ * Both are children of the plane, drawn after the series (so over them) and redrawn every flush, which is what keeps them
+ * on their data while the view pans and zooms.
+ */
+/* oxlint-disable typescript/no-non-null-assertion -- flat [x, y] buffers walked in steps of two; every index is bounded by the buffer length */
+import { STRING, NUMBER } from './attrs.js';
+import { Axis } from './axis.js';
+import { ChartElement, fail, resolveRef } from './element.js';
+import { EVENT_ATTACH, EVENT_PAINT } from './events.js';
+import { f2 } from './geometry.js';
+import { calloutSize, clearCallout, paintCallout } from './callout.js';
+import { applyText } from './text.js';
+/** Points used to trace a line that has to bend with the plane (a circle, a diagonal on a log axis), per sweep. */
+const CURVE_STEPS = 96;
+/** Space between a line and its label, in pixels. */
+const LABEL_GAP = 4;
+/** Where a pair of axes comes from: named by the annotation, or the plane's own first and second. */
+function axesOf(element, plane, domainAxis, valueAxis) {
+    return [
+        resolveRef(domainAxis, element, Axis) ?? plane.defaultAxis('first') ?? fail('plane has no axis for the domain'),
+        resolveRef(valueAxis, element, Axis) ?? plane.defaultAxis('second') ?? fail('plane has no axis for the value'),
+    ];
+}
+/**
+ * A reference line in data space: a target, a threshold, a trend. It is traced as a polyline through the plane, with as
+ * few points as the plane allows: two when the line stays straight (anything axis-aligned on a rectangle, a diagonal
+ * between linear scales), enough to follow the curve otherwise, and for a radar just the corners, at its spokes. The line is clipped to the plot; its label is not.
+ */
+export class LineAnnotation extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, domainAxis: STRING, label: STRING, stroke: STRING, strokeWidth: NUMBER, valueAxis: STRING };
+    #label = false;
+    /** The line as placed points in plot pixels, `[x, y]` per row, in order along the line; NaN where there is none. */
+    trace(plane, first, second) {
+        const a = this.attrs;
+        let fractions, buf;
+        if (a.value !== undefined) {
+            // Constant value: run along the first axis. Where the plane bends, sample it, and put a point on every corner.
+            const f = second.fractionOf(a.value);
+            if (!(Number.isFinite(f)))
+                return null;
+            fractions = plane.curved ? along(first, plane) : [0, 1];
+            buf = new Float64Array(fractions.length * 2);
+            fractions.forEach((t, i) => { buf[2 * i] = t; buf[2 * i + 1] = f; });
+        }
+        else if (a.domain !== undefined) {
+            const f = first.fractionOf(a.domain);
+            if (!(Number.isFinite(f)))
+                return null;
+            buf = new Float64Array([f, 0, f, 1]);
+        }
+        else if (a.from && a.to) {
+            // Straight in data space, so interpolate there; it only stays straight on the page if nothing bends it.
+            const [d0, v0] = a.from, [d1, v1] = a.to;
+            const n = plane.curved || !first.scale.isLinear || !second.scale.isLinear ? CURVE_STEPS + 1 : 2;
+            buf = new Float64Array(n * 2);
+            for (let i = 0; i < n; i++) {
+                const t = i / (n - 1);
+                buf[2 * i] = d0 + t * (d1 - d0);
+                buf[2 * i + 1] = v0 + t * (v1 - v0);
+            }
+            first.normalize(buf, n, 2, 0);
+            second.normalize(buf, n, 2, 1);
+        }
+        else {
+            return null; // the attribute type allows nothing else; a hand-built JSON spec with none of them draws nothing
+        }
+        plane.place({ data: buf, stride: 2, count: buf.length / 2 }, first, second);
+        return buf;
+    }
+    onEvent(ev) {
+        if (ev.type !== EVENT_PAINT)
+            return;
+        const plane = this.requireParent(), s = this.surface, a = this.attrs;
+        const [first, second] = axesOf(this, plane, a.domainAxis, a.valueAxis);
+        const pts = this.trace(plane, first, second);
+        const look = this.styleFor(['annotationLine', 'line'], { color: a.stroke, width: a.strokeWidth });
+        let d = '', pen = false;
+        if (pts)
+            for (let i = 0; i < pts.length; i += 2) {
+                const x = pts[i], y = pts[i + 1];
+                if (!(Number.isFinite(x) && Number.isFinite(y))) {
+                    pen = false;
+                    continue;
+                }
+                d += (pen ? 'L' : 'M') + f2(x) + ' ' + f2(y);
+                pen = true;
+            }
+        const line = s.node('line', '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);
+        s.set(line, 'clip-path', plane.clipUrl ?? 'none');
+        if (!a.label || !pts) {
+            if (this.#label) {
+                s.remove('label');
+                this.#label = false;
+            }
+            return;
+        }
+        const text = this.styleFor(['annotationLabel', 'annotationLine', 'text'], { color: a.stroke });
+        const at = pointAlong(pts, text.align === 'start' ? 0 : text.align === 'middle' ? 0.5 : 1);
+        if (!at)
+            return;
+        // The label sits on the side of the line that faces up (or, for a vertical line, right), which on a circle is outwards.
+        let nx = at.ty, ny = -at.tx;
+        if (ny > 1e-6 || (Math.abs(ny) <= 1e-6 && nx < 0)) {
+            nx = -nx;
+            ny = -ny;
+        }
+        const n = s.node('label', 'text');
+        this.#label = true;
+        applyText(s, n, text, Math.abs(nx) > 0.5 ? (nx > 0 ? 'start' : 'end') : text.align);
+        s.set(n, 'x', f2(at.x + nx * LABEL_GAP));
+        s.set(n, 'y', f2(at.y + ny * LABEL_GAP + (ny > 0.3 ? text.size * 0.8 : ny < -0.3 ? 0 : text.size * 0.35)));
+        s.text(n, a.label);
+    }
+}
+/**
+ * Fractions along an axis to trace a line that runs along it at. A plane that says where it bends (a radar) is straight
+ * between those places, so they are all that is needed and the line is exact; any other curved plane is sampled evenly.
+ */
+function along(axis, plane) {
+    const out = new Set([0, 1]);
+    const corners = plane.breaks(axis);
+    if (corners.length > 0)
+        for (const b of corners) {
+            if (b >= 0 && b <= 1)
+                out.add(Math.round(b * 1e9) / 1e9);
+        }
+    else
+        for (let i = 1; i < CURVE_STEPS; i++)
+            out.add(i / CURVE_STEPS);
+    return [...out].sort((p, q) => p - q);
+}
+/** The point a fraction of the way along a polyline's length, and the direction it is heading there. Null without two real points. */
+function pointAlong(pts, fraction) {
+    const n = pts.length / 2, real = (i) => Number.isFinite(pts[2 * i]) && Number.isFinite(pts[2 * i + 1]);
+    let total = 0;
+    for (let i = 1; i < n; i++)
+        if (real(i) && real(i - 1))
+            total += Math.hypot(pts[2 * i] - pts[2 * i - 2], pts[2 * i + 1] - pts[2 * i - 1]);
+    if (!(total > 0))
+        return null;
+    let target = fraction * total;
+    for (let i = 1; i < n; i++) {
+        if (!real(i) || !real(i - 1))
+            continue;
+        const x0 = pts[2 * i - 2], y0 = pts[2 * i - 1], dx = pts[2 * i] - x0, dy = pts[2 * i + 1] - y0, len = Math.hypot(dx, dy);
+        if (target <= len || i === n - 1) {
+            const t = len > 0 ? Math.min(1, target / len) : 0;
+            return { x: x0 + t * dx, y: y0 + t * dy, tx: len > 0 ? dx / len : 1, ty: len > 0 ? dy / len : 0 };
+        }
+        target -= len;
+    }
+    return null;
+}
+/** The eight places an automatically placed box may go, as the direction from the point, in order of preference. */
+const DIRECTIONS = [[1, -1], [-1, -1], [1, 0], [-1, 0], [1, 1], [-1, 1], [0, -1], [0, 1]];
+/** The most series points looked at when judging a spot: more are skipped evenly. */
+const MAX_PROBES = 2000;
+/**
+ * A note attached to a data point by an arm. Its look is four selectors (the text, the box, the arm and the callout's
+ * own metrics), and `outline` (in `callout`) chooses between a full border, only the edge the arm meets, or none.
+ *
+ * Placement: with no offset given, the box is tried in the eight directions round the point and the spot with the least
+ * trouble wins: parts of the box outside the plot, series points under it, and earlier callouts it would cover, with a
+ * slight preference for the upper right. It is a heuristic, which is why `dx` and `dy` exist.
+ */
+export class CalloutAnnotation extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, domainAxis: STRING, text: STRING, valueAxis: STRING };
+    #box = null;
+    #lines = 0;
+    /** Where the box was drawn, in plot pixels; null while it is not (point out of view). Later callouts keep clear of it. */
+    get box() { return this.#box; }
+    /** The data point in plot pixels, or null when it is off the plot. */
+    locate(plane, first, second) {
+        const a = this.attrs, buf = new Float64Array([a.domain, a.value]);
+        first.normalize(buf, 1, 2, 0);
+        second.normalize(buf, 1, 2, 1);
+        plane.place({ data: buf, stride: 2, count: 1 }, first, second);
+        const [x, y] = [buf[0], buf[1]], r = plane.rect;
+        return x >= 0 && x <= r.width && y >= 0 && y <= r.height ? [x, y] : null;
+    }
+    /** How bad a box is as a place for a callout: lower is better. */
+    trouble(plane, box, order) {
+        const r = plane.rect;
+        // Outside the plot: by how much of its area.
+        const inX = Math.max(0, Math.min(box.x + box.width, r.width) - Math.max(box.x, 0));
+        const inY = Math.max(0, Math.min(box.y + box.height, r.height) - Math.max(box.y, 0));
+        let score = (1 - (inX * inY) / (box.width * box.height)) * 1000;
+        // Series points under it.
+        for (const s of plane.series) {
+            const { data, count, stride } = s.points, step = Math.max(1, Math.ceil(count / MAX_PROBES));
+            for (let i = 0; i < count; i += step) {
+                const x = data[i * stride], y = data[i * stride + 1];
+                if (x >= box.x - 2 && x <= box.x + box.width + 2 && y >= box.y - 2 && y <= box.y + box.height + 2)
+                    score += step;
+            }
+        }
+        // Earlier callouts: much worse than a point.
+        for (const c of plane) {
+            if (c === this)
+                break;
+            const o = c instanceof CalloutAnnotation ? c.box : null;
+            if (o && box.x < o.x + o.width && box.x + box.width > o.x && box.y < o.y + o.height && box.y + box.height > o.y)
+                score += 500;
+        }
+        return score + order * 0.01;
+    }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_ATTACH:
+                this.surface.wrapper(); // carries the text style, which every line inherits
+                break;
+            case EVENT_PAINT:
+                this.paint();
+                break;
+        }
+    }
+    paint() {
+        const plane = this.requireParent(), s = this.surface, a = this.attrs;
+        const [first, second] = axesOf(this, plane, a.domainAxis, a.valueAxis);
+        const at = this.locate(plane, first, second);
+        if (!at) {
+            // Off the plot (panned away): draw nothing, and take up no room.
+            clearCallout(s, this.#lines);
+            this.#lines = 0;
+            this.#box = null;
+            return;
+        }
+        const [px, py] = at;
+        const look = {
+            metrics: this.styleFor(['callout']), text: this.styleFor(['calloutText', 'text']),
+            box: this.styleFor(['calloutBox', 'shape']), arm: this.styleFor(['calloutArm', 'line']),
+        };
+        const { metrics } = look, { width: w, height: h } = calloutSize(this.requireChart().measureText, a.text, look);
+        const place = (cx, cy) => ({ x: cx - w / 2, y: cy - h / 2, width: w, height: h });
+        let box;
+        if (a.dx !== undefined || a.dy !== undefined) {
+            box = place(px + (a.dx ?? 0), py + (a.dy ?? 0));
+        }
+        else {
+            let best = Infinity;
+            box = place(px, py);
+            DIRECTIONS.forEach(([ux, uy], i) => {
+                const candidate = place(px + ux * (w / 2 + metrics.offset), py + uy * (h / 2 + metrics.offset));
+                const score = this.trouble(plane, candidate, i);
+                if (score < best) {
+                    best = score;
+                    box = candidate;
+                }
+            });
+        }
+        this.#box = box;
+        this.#lines = paintCallout(s, a.text, box, [px, py], look, this.#lines);
+    }
+}

package/dist/aria.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Accessibility attributes from an element's `meta`.
+ *
+ * The core carries no words of its own: whatever a screen reader says comes from `meta` (a `title` is the accessible name,
+ * a `description` the longer description) or from an opt-in component such as `ChartSummary`, which is where the
+ * language-specific text lives. This module only turns `meta` into attributes on a node.
+ */
+import type { Meta } from './element.ts';
+import type { PlatformNode } from './platform.ts';
+import type { Surface } from './surface.ts';
+/** What an element supplies when its `meta` says nothing: a role that fits what it is, and a name it knows. */
+export interface AriaDefaults {
+    role?: string;
+    label?: string;
+    description?: string;
+}
+/**
+ * Write the node's role, name, description and any other ARIA attributes. `meta.aria` wins over everything: its keys are
+ * attribute names (the `aria-` prefix is optional) and its values are written as they are.
+ * A role is only written when there is something to name: an unnamed `group` is noise to a screen reader.
+ */
+export declare function writeAria(surface: Surface, node: PlatformNode, meta: Meta | undefined, defaults?: AriaDefaults): void;
+/** Keep a decorative node (gridlines, tick labels, a swatch) out of the accessibility tree. */
+export declare function hideFromAssistive(surface: Surface, node: PlatformNode): void;

package/dist/aria.js

@@ -0,0 +1,31 @@
+/**
+ * Write the node's role, name, description and any other ARIA attributes. `meta.aria` wins over everything: its keys are
+ * attribute names (the `aria-` prefix is optional) and its values are written as they are.
+ * A role is only written when there is something to name: an unnamed `group` is noise to a screen reader.
+ */
+export function writeAria(surface, node, meta, defaults = {}) {
+    const extra = meta?.aria;
+    const label = extra?.['aria-label'] ?? extra?.['label'] ?? meta?.title ?? defaults.label;
+    const description = meta?.description ?? defaults.description;
+    const role = meta?.role ?? defaults.role;
+    if (role !== undefined && (label !== undefined || description !== undefined || meta?.role !== undefined))
+        surface.set(node, 'role', role);
+    if (label !== undefined)
+        surface.set(node, 'aria-label', String(label));
+    if (description !== undefined)
+        surface.set(node, 'aria-description', description);
+    if (extra) {
+        for (const key in extra) {
+            if (key === 'label')
+                continue;
+            const name = key.startsWith('aria-') ? key : `aria-${key}`;
+            if (name === 'aria-label')
+                continue;
+            surface.set(node, name, String(extra[key]));
+        }
+    }
+}
+/** Keep a decorative node (gridlines, tick labels, a swatch) out of the accessibility tree. */
+export function hideFromAssistive(surface, node) {
+    surface.set(node, 'aria-hidden', 'true');
+}

package/dist/attrs.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Attribute names and types for the places that only have strings and flat names: XML-like syntaxes (JSX, HTML).
+ *
+ * Two jobs, both small:
+ *
+ * 1. `expandAttributes` turns hyphenated names into nested objects, because those syntaxes carry only primitives:
+ *    `meta-title="Sales"` is `{ meta: { title: 'Sales' } }`. Having both an object and nested names for one key is an error.
+ * 2. Every element class lists, in `static attrTypes`, the attributes an HTML parser would get wrong: names with capitals
+ *    (HTML lowercases them, so `strokewidth` must find `strokeWidth`) and text that looks like something else (a title
+ *    of `2024` must stay text). Attributes that hold objects list their parts the same way, nested:
+ *    `{ meta: { title: STRING }, padding: { topSide: NUMBER } }`. Everything else is left to automatic coercion.
+ *    The compiler enforces the list (`AttrTypesFor`), so a new attribute cannot be forgotten.
+ *
+ * Only the Web Components adapter reads `attrTypes`; the classes carry them as plain data, which costs a few bytes each.
+ */
+import type { AnyElement } from './element.ts';
+import type { Theme } from './theme.ts';
+/** How an HTML attribute's text becomes a value. AUTO: `true`/`false` and numbers convert, `[…]` and `{…}` are JSON, the rest is text. */
+export declare const AUTO = 0;
+/** Always text: titles, names, ids, colours. Needed wherever the text might look like a number or a boolean. */
+export declare const STRING = 1;
+/** A number, whatever it looks like. */
+export declare const NUMBER = 2;
+/** A boolean: present with no value, or `true`, is true; `false` is false. */
+export declare const BOOLEAN = 3;
+export type Coerce = typeof AUTO | typeof STRING | typeof NUMBER | typeof BOOLEAN;
+/** How one attribute's text becomes a value, or, for an attribute that holds an object, the same for each part of it. */
+export type AttrType = Coerce | AttrTypes;
+/** An element class' attribute types by name, as in `{ strokeWidth: NUMBER, padding: { topSide: NUMBER } }`. Inherited ones are repeated by spreading the parent's. */
+export interface AttrTypes {
+    readonly [name: string]: AttrType;
+}
+declare const opaque: unique symbol;
+/** Marks an attribute that holds an object which only code can supply (a library namespace), so it has no nested spec. */
+export type Opaque<T> = T & {
+    readonly [opaque]?: never;
+};
+/** The plain object an attribute type holds (what a nested spec describes), or never: not functions, arrays, data, elements, dates or the style theme. */
+type Inner<T> = NonNullable<T> extends infer N ? N extends (...args: never[]) => unknown ? never : typeof opaque extends keyof N ? never : N extends readonly unknown[] | ArrayLike<unknown> | AnyElement | Date | Theme | string | number | boolean ? never : N extends object ? (string extends keyof N ? never : N) : never : never;
+/** A text-only type: the AUTO guess could turn its text into a number or a boolean. */
+type TextOnly<T> = string extends NonNullable<T> ? number extends NonNullable<T> ? never : boolean extends NonNullable<T> ? never : true : never;
+/**
+ * The attributes of `A` that must be listed in `attrTypes`: those with a capital in the name; those that are text and
+ * nothing else (not also a number or a boolean), because AUTO could turn their text into one of those; and those that hold an
+ * object with parts that need one of the two (`meta` has a `title`), which are listed with a nested spec.
+ */
+export type NeededAttrs<A> = {
+    [K in keyof A & string]-?: [Inner<A[K]>] extends [never] ? (K extends Lowercase<K> ? ([TextOnly<A[K]>] extends [never] ? never : K) : K) : (K extends Lowercase<K> ? ([NeededAttrs<Inner<A[K]>>] extends [never] ? never : K) : K);
+}[keyof A & string];
+type SpecFor<T> = [Inner<T>] extends [never] ? Coerce : [NeededAttrs<Inner<T>>] extends [never] ? Coerce | AttrTypes : AttrTypesFor<Inner<T>>;
+/** What `static attrTypes` must satisfy for an element whose attributes are `A`: every needed name, each with a type (or a nested spec). */
+export type AttrTypesFor<A> = {
+    readonly [K in NeededAttrs<A>]: SpecFor<A[K]>;
+} & AttrTypes;
+type Obj = Record<string, unknown>;
+/** What `expandAttributes` can be told. Both are for the Web Components adapter; JSX and React pass names as written. */
+export interface ExpandOptions {
+    /** The real name for a path segment, given the segments above it (HTML hands over lowercase). Default: as written. */
+    name?: (segment: string, parents: readonly string[]) => string;
+    /** The value for the attribute at `path` (HTML hands over text). Default: as given. */
+    value?: (path: readonly string[], value: unknown) => unknown;
+}
+/**
+ * The attributes an element takes, from a flat set of names and values in which hyphens mean nesting.
+ * Names without hyphens pass through, and values are never copied, so objects and functions stay the same objects.
+ * An attribute whose value is `undefined` counts as not given for conflicts, but stays in the result when nothing else claims the key.
+ * Throws when one key is given both as a value and as a path to nested values (`meta` and `meta-title`, or `a-b` and `a-b-c`),
+ * when a name has an empty part (`a--b`), or for `__proto__`.
+ */
+export declare function expandAttributes(flat: Readonly<Obj>, options?: ExpandOptions): Obj;
+/** The hyphenated names of nested attributes in a props type (`meta-title`, `style-tickLabel-size`), which are checked as leaves. */
+export type NestedProps = {
+    [name: `${string}-${string}`]: string | number | boolean | undefined;
+};
+/** A child as written: an element, nothing (a skipped condition), or a list of those. */
+export type JsxChild<E> = E | null | undefined | boolean | readonly JsxChild<E>[];
+/** Receives the element made for a JSX tag. */
+export type JsxRef<E> = ((element: E) => void) | {
+    current: E | null;
+};
+export {};