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

package/dist/brush.d.ts

@@ -0,0 +1,60 @@
+import { Axis } from './axis.ts';
+import { type BaseAttributes, ChartElement, type ElementRef } from './element.ts';
+import { inputOf } from './input.ts';
+import { type ChartEvent } from './events.ts';
+import type { Plane } from './plane.ts';
+/** What a brush covers on one axis, in that axis' own values. */
+export interface BrushRange {
+    axis: Axis;
+    min: number;
+    max: number;
+}
+/** What `onBrush` hears: every axis covered, with the first horizontal and first vertical ones' ranges also by name. */
+export interface BrushSelection {
+    ranges: readonly BrushRange[];
+    x?: {
+        min: number;
+        max: number;
+    };
+    y?: {
+        min: number;
+        max: number;
+    };
+}
+export interface BrushAttributes extends BaseAttributes {
+    /** The axes it may cover, as elements or ids. Default: all of the plane's that can be followed along. */
+    axes?: readonly ElementRef<Axis>[];
+    /** When a drag brushes: always (the default) or with Shift held, to leave a plain drag to `PanZoom`. */
+    activate?: 'shift' | 'always';
+    /** Which axes it covers. Default 'xy'. */
+    mode?: 'xy' | 'x' | 'y';
+    /** Smallest side of a brush, in pixels, along an axis it covers; below that a drag only clears. Default 4. */
+    minSize?: number;
+    /** Call `onBrush` while dragging too. Default false. */
+    live?: boolean;
+    /** Called with the selection, or null when it is cleared. */
+    onBrush?: (selection: BrushSelection | null) => void;
+}
+export declare class Brush extends ChartElement<Plane, [], BrushAttributes> {
+    #private;
+    static takesInput: typeof inputOf;
+    static attrTypes: {
+        minSize: 2;
+        live: 3;
+        onBrush: 0;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** True while a box is being dragged. */
+    get selecting(): boolean;
+    /** What is brushed now, or null. */
+    get selection(): BrushSelection | null;
+    /** Brushes these ranges (as if dragged), or clears with an empty list. */
+    select(ranges: readonly BrushRange[]): void;
+    clear(): void;
+    onEvent(ev: ChartEvent): void;
+}

package/dist/brush.js

@@ -0,0 +1,185 @@
+/**
+ * Brush: drag a rectangle on the plot to pick a range of the data, and say what was picked. It zooms nothing.
+ *
+ *   new CartesianPlane({}, x, y, series, new Brush({ mode: 'x', onBrush: (b) => filter(b?.ranges) }), new PanZoom())
+ *
+ * It is the other half of `BoxZoom`: the same drag, but the rectangle stays drawn (and follows the axes as they pan and
+ * zoom, since it is held in data terms) and the ranges it covers go to `onBrush`, for the app to filter a table, link another
+ * chart or total a selection. A click (a box under `minSize`) or `clear()` takes it away and calls `onBrush(null)`.
+ *
+ * `mode` is which axes the brush covers: 'xy', or 'x' / 'y' for a band across the plot (a time range). By default
+ * (`activate: 'always'`) every drag brushes, so give a plane that also pans `activate: 'shift'`; like `BoxZoom` it has to come
+ * **before** `PanZoom` to see a press first. With `live`, `onBrush` is called as the box is dragged and not only at the end.
+ * A touch brushes only with `activate: 'always'` and the plane taking every touch; a rim (polar) cannot be brushed.
+ * `select()` sets it from code, which is how two charts follow one another.
+ */
+import { AUTO, BOOLEAN, NUMBER } from './attrs.js';
+import { Axis } from './axis.js';
+import { ChartElement, fail, resolveRef } from './element.js';
+import { inputOf } from './input.js';
+import { EVENT_ATTACH, EVENT_PAINT, EVENT_POINTER } from './events.js';
+import { f2 } from './geometry.js';
+export class Brush extends ChartElement {
+    static takesInput = inputOf;
+    static attrTypes = { ...ChartElement.attrTypes, minSize: NUMBER, live: BOOLEAN, onBrush: AUTO };
+    #from = null;
+    #to = { x: 0, y: 0 };
+    #ranges = [];
+    /** True while a box is being dragged. */
+    get selecting() { return this.#from !== null; }
+    /** What is brushed now, or null. */
+    get selection() { return this.#ranges.length ? this.#describe(this.#ranges) : null; }
+    /** Brushes these ranges (as if dragged), or clears with an empty list. */
+    select(ranges) {
+        this.#ranges = ranges.map((r) => ({ axis: r.axis, min: Math.min(r.min, r.max), max: Math.max(r.min, r.max) }));
+        this.invalidate();
+        this.attrs.onBrush?.(this.selection);
+    }
+    clear() {
+        if (!this.#ranges.length)
+            return;
+        this.#ranges = [];
+        this.invalidate();
+        this.attrs.onBrush?.(null);
+    }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_ATTACH: {
+                const plane = this.requireParent();
+                for (const sibling of plane) {
+                    if (sibling === this)
+                        break;
+                    if (sibling.claimsPress)
+                        fail('add a Brush before PanZoom in a plane: the brush has to see a press first to take it');
+                }
+                return;
+            }
+            case EVENT_PAINT:
+                this.#paint();
+                return;
+            case EVENT_POINTER:
+                this.#pointer(ev);
+                return;
+        }
+    }
+    #describe(ranges) {
+        const out = { ranges };
+        for (const r of ranges) {
+            const key = r.axis.ruler.horizontal ? 'x' : 'y';
+            out[key] ??= { min: r.min, max: r.max };
+        }
+        return out;
+    }
+    #axes() {
+        const a = this.attrs, mode = a.mode ?? 'xy';
+        const axes = a.axes ? a.axes.map((ref) => resolveRef(ref, this, Axis)) : [...this.requireParent().axes];
+        return axes.filter((axis) => axis.ruler.fractionAt && (mode === 'xy' || (mode === 'x') === axis.ruler.horizontal));
+    }
+    /** The ranges a box from `from` to `to` covers. */
+    #cover(from, to) {
+        const out = [];
+        for (const axis of this.#axes()) {
+            const ruler = axis.ruler, at = ruler.fractionAt;
+            if (!at)
+                continue; // `#axes` keeps only rulers that have one
+            const v0 = axis.denormalize(at.call(ruler, from.x, from.y)), v1 = axis.denormalize(at.call(ruler, to.x, to.y));
+            if (v0 !== v0 || v1 !== v1)
+                continue;
+            out.push({ axis, min: Math.min(v0, v1), max: Math.max(v0, v1) });
+        }
+        return out;
+    }
+    #pointer(ev) {
+        const a = this.attrs, always = (a.activate ?? 'always') === 'always';
+        if ((ev.pointerType === 'touch' && !always) || ev.kind === 'wheel' || ev.kind === 'pinch')
+            return;
+        const plane = this.requireParent(), r = plane.rect, min = a.minSize ?? 4, mode = a.mode ?? 'xy';
+        const clampX = (x) => Math.min(r.width, Math.max(0, x)), clampY = (y) => Math.min(r.height, Math.max(0, y));
+        // A box a pixel or two across is a click; along an axis it does not cover its size does not count.
+        const small = (from, to) => (mode !== 'y' && Math.abs(to.x - from.x) < min) || (mode !== 'x' && Math.abs(to.y - from.y) < min);
+        switch (ev.kind) {
+            case 'down':
+                if (ev.handled || ev.outside || !(ev.buttons & 1) || !plane.covers(ev.x, ev.y))
+                    return;
+                if (!always && !ev.shift)
+                    return;
+                this.#from = this.#to = { x: ev.x, y: ev.y };
+                this.chart?.platform?.setCursor?.('crosshair');
+                ev.handled = true;
+                return;
+            case 'move': {
+                if (!this.#from)
+                    return;
+                if (!(ev.buttons & 1)) {
+                    this.#abandon();
+                    return;
+                }
+                this.#to = { x: clampX(ev.x), y: clampY(ev.y) };
+                this.invalidate();
+                if (a.live && !small(this.#from, this.#to))
+                    a.onBrush?.(this.#describe(this.#cover(this.#from, this.#to)));
+                ev.handled = true;
+                return;
+            }
+            case 'up': {
+                const from = this.#from;
+                if (!from)
+                    return;
+                const to = { x: clampX(ev.x), y: clampY(ev.y) };
+                this.#abandon();
+                if (small(from, to))
+                    this.clear();
+                else
+                    this.select(this.#cover(from, to));
+                ev.handled = true;
+                return;
+            }
+            case 'leave':
+                return;
+        }
+    }
+    #abandon() {
+        this.#from = null;
+        this.chart?.platform?.setCursor?.('');
+        this.invalidate();
+    }
+    /** The rectangle in plot pixels for the box being dragged, else for what is brushed (which follows the axes). */
+    #rect() {
+        const r = this.requireParent().rect;
+        if (this.#from)
+            return { x0: Math.min(this.#from.x, this.#to.x), y0: Math.min(this.#from.y, this.#to.y), x1: Math.max(this.#from.x, this.#to.x), y1: Math.max(this.#from.y, this.#to.y) };
+        if (!this.#ranges.length)
+            return null;
+        let x0 = 0, x1 = r.width, y0 = 0, y1 = r.height;
+        for (const { axis, min, max } of this.#ranges) {
+            const ruler = axis.ruler, p = ruler.at(axis.fractionOf(min)), q = ruler.at(axis.fractionOf(max));
+            if (ruler.horizontal) {
+                x0 = Math.min(p[0], q[0]);
+                x1 = Math.max(p[0], q[0]);
+            }
+            else {
+                y0 = Math.min(p[1], q[1]);
+                y1 = Math.max(p[1], q[1]);
+            }
+        }
+        return { x0: Math.max(0, x0), y0: Math.max(0, y0), x1: Math.min(r.width, x1), y1: Math.min(r.height, y1) };
+    }
+    #paint() {
+        const s = this.surface, box = this.#rect();
+        if (!box || box.x1 - box.x0 !== box.x1 - box.x0 || box.y1 - box.y0 !== box.y1 - box.y0) {
+            s.remove('brush');
+            return;
+        }
+        const look = this.styleFor(['selection', 'shape']);
+        const node = s.node('brush', 'rect', { above: true });
+        s.set(node, 'x', f2(box.x0));
+        s.set(node, 'y', f2(box.y0));
+        s.set(node, 'width', f2(box.x1 - box.x0));
+        s.set(node, 'height', f2(box.y1 - box.y0));
+        s.set(node, 'fill', look.fill);
+        s.set(node, 'stroke', look.stroke);
+        s.set(node, 'stroke-width', look.strokeWidth);
+        s.set(node, 'opacity', look.opacity);
+        s.set(node, 'pointer-events', 'none');
+    }
+}

package/dist/bucket.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Grouping by look: what renderers that vary a style by data (markers, heat map cells) share.
+ *
+ * Each stylistic binding is quantized into a few steps, a shape's look is the combination of its steps (its `key`), and
+ * every shape with the same key joins one path. The number of paths is then bounded by `maxNodes`, not by the data.
+ */
+import { resolveRef } from './element.ts';
+import type { ResolvedBinding } from './renderer.ts';
+/** The bound properties of `attrs.bind` with their dimensions resolved from `from`. */
+export declare function resolveBindings(bind: unknown, from: Parameters<typeof resolveRef>[1], isGeometric: (property: string) => boolean): ResolvedBinding[];
+/** How many steps each of the stylistic bindings is quantized to so that the combinations stay within `maxNodes`; 0 for none. */
+export declare function stepsFor(bindings: readonly ResolvedBinding[], maxNodes: number): number;
+/** A binding's channel as a column of 0..1 positions along its dimension. `column` is where the channel sits in each row. */
+export declare function fractionsOf(b: ResolvedBinding, data: ArrayLike<number>, column: number, stride: number, count: number): Float64Array;
+/** Which look a shape has: one step along each bound style, the last step meaning "no value". */
+export declare function lookKey(styled: readonly {
+    f: Float64Array;
+}[], i: number, steps: number): number;
+/** Undo `lookKey`: the value each bound style has for that key (the middle of its step), handed to `write` by property. */
+export declare function lookValues(key: number, styled: readonly {
+    b: ResolvedBinding;
+}[], steps: number, write: (property: string, value: string | number) => void): void;

package/dist/bucket.js

@@ -0,0 +1,62 @@
+/**
+ * Grouping by look: what renderers that vary a style by data (markers, heat map cells) share.
+ *
+ * Each stylistic binding is quantized into a few steps, a shape's look is the combination of its steps (its `key`), and
+ * every shape with the same key joins one path. The number of paths is then bounded by `maxNodes`, not by the data.
+ */
+import { fail, resolveRef } from './element.js';
+/** The bound properties of `attrs.bind` with their dimensions resolved from `from`. */
+export function resolveBindings(bind, from, isGeometric) {
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- the `bind` attribute, typed here as the shape this element reads
+    const map = bind;
+    if (!map)
+        return [];
+    const out = [];
+    for (const property in map) {
+        const b = map[property];
+        if (b)
+            out.push({ property, channel: b.channel, axis: resolveRef(b.axis, from), stylistic: !isGeometric(property) });
+    }
+    return out;
+}
+/** How many steps each of the stylistic bindings is quantized to so that the combinations stay within `maxNodes`; 0 for none. */
+export function stepsFor(bindings, maxNodes) {
+    const k = bindings.reduce((n, b) => n + (b.stylistic ? 1 : 0), 0);
+    if (k === 0)
+        return 0;
+    // The last step of each binding is kept for data with no value, so a binding colours with one fewer.
+    const steps = Math.floor(maxNodes ** (1 / k) + 1e-9);
+    if (steps < 2)
+        fail(`maxNodes ${maxNodes} leaves fewer than 2 steps for ${k} bound styles`);
+    return steps;
+}
+/** A binding's channel as a column of 0..1 positions along its dimension. `column` is where the channel sits in each row. */
+export function fractionsOf(b, data, column, stride, count) {
+    const f = new Float64Array(count);
+    // 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
+    for (let i = 0, j = column; i < count; i++, j += stride)
+        f[i] = data[j];
+    b.axis.normalize(f, count, 1, 0);
+    return f;
+}
+/** Which look a shape has: one step along each bound style, the last step meaning "no value". */
+export function lookKey(styled, i, steps) {
+    let key = 0, mult = 1;
+    for (const { f } of styled) {
+        // 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 p = f[i];
+        key += (p >= -1e-9 && p <= 1 + 1e-9 ? Math.min(steps - 2, Math.floor((p < 0 ? 0 : p) * (steps - 1))) : steps - 1) * mult;
+        mult *= steps;
+    }
+    return key;
+}
+/** Undo `lookKey`: the value each bound style has for that key (the middle of its step), handed to `write` by property. */
+export function lookValues(key, styled, steps, write) {
+    let rest = key;
+    for (const { b } of styled) {
+        const step = rest % steps;
+        rest = (rest - step) / steps;
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- an axis hands back `string | number` for a property the attribute types vouch for
+        write(b.property, (step === steps - 1 ? b.axis.missing : b.axis.valueAt((step + 0.5) / (steps - 1))));
+    }
+}

package/dist/callout.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Drawing a callout: a box of text, optionally joined by an arm to the point it is about. Shared by the annotation and
+ * the tooltip, which differ in where the box goes and when it is there, not in what it looks like.
+ */
+import type { Rect, Size } from './geometry.ts';
+import type { TextMeasurer } from './platform.ts';
+import { type SampleCache, type Series } from './series.ts';
+import type { Surface } from './surface.ts';
+import type { CalloutMetrics, LineProps, ShapeProps, TextProps } from './theme.ts';
+/** Everything a callout's look takes from the theme, resolved by the element that draws it (whose chains differ). */
+export interface CalloutLook {
+    metrics: CalloutMetrics;
+    text: TextProps;
+    box: ShapeProps;
+    arm: LineProps;
+}
+/** How big the box is for `text`: the text's block and the padding all round, and room for a column of series samples if `swatches`. */
+export declare function calloutSize(measure: TextMeasurer, text: string, look: CalloutLook, swatches?: boolean): Size;
+/**
+ * Draw the box at `box`. With an `anchor`, an arm runs from the middle of the edge the anchor is furthest beyond to it
+ * (measured in half-sides, so a wide box does not always pick its top and bottom), and the 'edge' outline draws that
+ * edge alone. Needs a surface whose wrapper carries the text style. Returns the lines drawn, to pass back next time.
+ *
+ * `swatches` gives a series for each line that starts with a sample of it (null for one that does not): its line, box or
+ * marker as drawn on the plot. The text then starts after a column the width of a sample, which `calloutSize` must have been
+ * told of. `samples` is what is remembered of them between calls (see `paintSample`).
+ */
+export declare function paintCallout(s: Surface, text: string, box: Rect, anchor: readonly [number, number] | null, look: CalloutLook, lines: number, swatches?: readonly (Series | null)[], samples?: SampleCache): number;
+/** Take a callout off the surface. */
+export declare function clearCallout(s: Surface, lines: number, samples?: SampleCache): void;

package/dist/callout.js

@@ -0,0 +1,98 @@
+import { circlePath, f2 } from './geometry.js';
+import { paintSample } from './series.js';
+import { LINE_HEIGHT, applyText, measureBlock, paintLines } from './text.js';
+/** A sample of a series before a line of text: as wide as a short line, and as tall as the lowercase letters. */
+const sampleWidth = (look) => Math.round(look.text.size * 1.4);
+const sampleHeight = (look) => Math.max(5, Math.round(look.text.size * 0.7));
+/** The room a column of samples takes at the start of the text: a sample and the gap after it. */
+const swatchIndent = (look) => sampleWidth(look) + 5;
+/** How big the box is for `text`: the text's block and the padding all round, and room for a column of series samples if `swatches`. */
+export function calloutSize(measure, text, look, swatches = false) {
+    const size = measureBlock(measure, text, look.text), pad = 2 * look.metrics.padding;
+    return { width: size.width + pad + (swatches ? swatchIndent(look) : 0), height: size.height + pad };
+}
+/**
+ * Draw the box at `box`. With an `anchor`, an arm runs from the middle of the edge the anchor is furthest beyond to it
+ * (measured in half-sides, so a wide box does not always pick its top and bottom), and the 'edge' outline draws that
+ * edge alone. Needs a surface whose wrapper carries the text style. Returns the lines drawn, to pass back next time.
+ *
+ * `swatches` gives a series for each line that starts with a sample of it (null for one that does not): its line, box or
+ * marker as drawn on the plot. The text then starts after a column the width of a sample, which `calloutSize` must have been
+ * told of. `samples` is what is remembered of them between calls (see `paintSample`).
+ */
+export function paintCallout(s, text, box, anchor, look, lines, swatches, samples) {
+    const { metrics, box: boxLook, arm } = look, w = box.width, h = box.height;
+    const cx = box.x + w / 2, cy = box.y + h / 2;
+    const rect = s.node('box', 'path');
+    s.set(rect, 'd', `M${f2(box.x)} ${f2(box.y)}h${f2(w)}v${f2(h)}h${f2(-w)}z`);
+    s.set(rect, 'fill', boxLook.fill);
+    s.set(rect, 'fill-opacity', boxLook.opacity);
+    s.set(rect, 'stroke', metrics.outline === 'box' ? boxLook.stroke : 'none');
+    s.set(rect, 'stroke-width', boxLook.strokeWidth);
+    if (anchor) {
+        const [px, py] = anchor;
+        const rx = (px - cx) / (w / 2), ry = (py - cy) / (h / 2);
+        const horizontal = Math.abs(rx) >= Math.abs(ry), sign = (horizontal ? rx : ry) < 0 ? -1 : 1;
+        const [ex1, ey1, ex2, ey2] = horizontal
+            ? [cx + sign * w / 2, box.y, cx + sign * w / 2, box.y + h]
+            : [box.x, cy + sign * h / 2, box.x + w, cy + sign * h / 2];
+        const [ax, ay] = horizontal ? [cx + sign * w / 2, cy] : [cx, cy + sign * h / 2];
+        if (metrics.outline === 'edge') {
+            const edge = s.node('edge', 'path');
+            s.set(edge, 'd', `M${f2(ex1)} ${f2(ey1)}L${f2(ex2)} ${f2(ey2)}`);
+            s.set(edge, 'fill', 'none');
+            s.set(edge, 'stroke', boxLook.stroke);
+            s.set(edge, 'stroke-width', boxLook.strokeWidth);
+        }
+        else {
+            s.remove('edge');
+        }
+        const armNode = s.node('arm', 'path');
+        s.set(armNode, 'd', `M${f2(px)} ${f2(py)}L${f2(ax)} ${f2(ay)}`);
+        s.set(armNode, 'fill', 'none');
+        s.set(armNode, 'stroke', arm.color);
+        s.set(armNode, 'stroke-width', arm.width);
+        s.set(armNode, 'stroke-dasharray', arm.dash);
+        s.set(armNode, 'opacity', arm.opacity);
+        if (metrics.pointer > 0) {
+            const dot = s.node('dot', 'path');
+            s.set(dot, 'd', circlePath(px, py, metrics.pointer));
+            s.set(dot, 'fill', arm.color);
+            s.set(dot, 'stroke', 'none');
+        }
+        else {
+            s.remove('dot');
+        }
+    }
+    else {
+        for (const key of ['edge', 'arm', 'dot'])
+            s.remove(key);
+    }
+    applyText(s, s.wrapper(), look.text);
+    const pad = metrics.padding, align = look.text.align, indent = swatches ? swatchIndent(look) : 0;
+    const x = align === 'start' ? box.x + pad + indent : align === 'middle' ? cx + indent / 2 : box.x + w - pad;
+    const drawn = paintLines(s, 'line-', text, x, box.y + pad, look.text, lines);
+    const size = look.text.size, sw = sampleWidth(look), sh = sampleHeight(look);
+    for (let i = 0; i < Math.max(drawn, lines); i++) {
+        const series = swatches?.[i];
+        if (series && samples && i < drawn) {
+            // The middle of the x-height of the line: its baseline is at 0.85 of the size down.
+            paintSample(s, `sw-${i}`, series, box.x + pad, box.y + pad + size * (0.85 - 0.32 + LINE_HEIGHT * i) - sh / 2, sw, sh, samples);
+        }
+        else {
+            s.removePrefix(`sw-${i}`);
+            samples?.delete(`sw-${i}`);
+        }
+    }
+    return drawn;
+}
+/** Take a callout off the surface. */
+export function clearCallout(s, lines, samples) {
+    for (const key of ['box', 'edge', 'arm', 'dot'])
+        s.remove(key);
+    for (let i = 0; i < lines; i++) {
+        s.remove(`line-${i}`);
+        s.removePrefix(`sw-${i}`);
+        samples?.delete(`sw-${i}`);
+    }
+}

package/dist/chart.d.ts

@@ -0,0 +1,126 @@
+import { type AnyElement, type BaseAttributes, ChartElement } from './element.ts';
+import { type ChartEvent, type ChartEventInit } from './events.ts';
+import type { InputHost } from './input.ts';
+import type { ChartTitle } from './furniture.ts';
+import type { Cursor } from './cursor.ts';
+import { type Insets } from './geometry.ts';
+import type { ColorAxis, SizeAxis } from './mapped.ts';
+import type { ColorKey, SizeKey } from './key.ts';
+import type { Legend } from './legend.ts';
+import type { ChartSummary } from './summary.ts';
+import { Plane } from './plane.ts';
+import type { BaseTheme } from './theme.ts';
+import { type Platform, type TextMeasurer } from './platform.ts';
+import { type StageName } from './surface.ts';
+/** What one flush did and cost: the numbers the playground shows, and what tests assert caching against. */
+export interface FlushStats {
+    readonly total: number;
+    readonly stages: Readonly<Record<StageName, number>>;
+    readonly filled: number;
+    readonly fillsCached: number;
+    readonly projected: number;
+    readonly attributeWrites: number;
+    readonly attributeWritesSkipped: number;
+    readonly attributesWritten: readonly string[];
+    readonly pointsIn: number;
+    readonly pointsDrawn: number;
+    readonly pathBytes: number;
+}
+/**
+ * A chart child that words what the chart shows, for a screen reader. The words are its own (so the core has none, and a
+ * chart in another language supplies its own), and the chart uses them when `meta.description` says nothing.
+ */
+export interface Describer {
+    describe(): {
+        description: string;
+        roleDescription?: string;
+    };
+}
+export interface ChartAttributes extends BaseAttributes {
+    /** Every default look: required, so a chart bundles exactly the theme it names (`lightTheme`, `darkTheme`, or your own). */
+    theme: BaseTheme;
+    /** Width of the drawing. Default: whatever the platform reports, followed as it changes. */
+    width?: number;
+    /** Height of the drawing. Default: whatever the platform reports. When set on the chart it beats the size a platform reports, including the one given to `toSvgString`. */
+    height?: number;
+    /** Margin around everything, in pixels: one number for all sides, or any subset of the four. Default 10. */
+    padding?: number | Partial<Insets>;
+    /** Replaces the platform's text measurement, e.g. to match a font the platform cannot see. */
+    measureText?: TextMeasurer;
+    /**
+     * A BCP 47 tag (`'de'`, `'fr-CA'`) for how numbers and dates are written: digit grouping, the decimal mark, month names.
+     * Axes and time scales that have no `locale` of their own use it. Default: numbers as plain digits with a point, and the
+     * runtime's own locale for dates. The words the library says (a summary, a tooltip's labels) are not translated by this; those
+     * come from the components that say them, which take your words.
+     */
+    locale?: string;
+    /** Called after every flush with its statistics. */
+    onFlush?: (stats: FlushStats) => void;
+}
+/** Open for augmentation, like PlaneChildMap. */
+export interface ChartChildMap {
+    plane: Plane;
+    title: ChartTitle;
+    cursor: Cursor;
+    colorAxis: ColorAxis;
+    sizeAxis: SizeAxis;
+    colorKey: ColorKey;
+    sizeKey: SizeKey;
+    legend: Legend;
+    summary: ChartSummary;
+}
+export type ChartChildren = ChartChildMap[keyof ChartChildMap][];
+/** The root: the only element that knows about the platform lifecycle (attach, flush, detach). */
+export declare class Chart extends ChartElement<null, ChartChildren, ChartAttributes> {
+    #private;
+    static attrTypes: {
+        measureText: 0;
+        onFlush: 0;
+        locale: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    get chart(): Chart;
+    private readonly counts;
+    private unschedule;
+    private readonly subscriptions;
+    /** The input host, once something in the chart has asked for it (see `inputOf`): null on a chart nothing listens to. */
+    input: InputHost | null;
+    get platform(): Platform | null;
+    get lastFlush(): FlushStats | null;
+    /** 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(): number;
+    /** True from any invalidation until the next flush. */
+    get needsFlush(): boolean;
+    /** Construction has no side effects; this makes the chart live. */
+    attach(platform: Platform): this;
+    /** Undo `attach`: unsubscribe, take the nodes out of the platform. The tree is kept, so the chart can be attached again. */
+    detach(): this;
+    /** The request has reached the root: note it, and on a scheduling platform arrange a flush. */
+    invalidate(): void;
+    /** Put every axis of every plane back to the range its data asks for. */
+    resetViews(): void;
+    /** Send an event through the tree from `root` (default the chart). For the input host, which lives outside this class. */
+    deliver(init: ChartEventInit, root?: AnyElement): ChartEvent;
+    /** Preference order: the chart's own, the platform's (real fonts), then a deliberately wide estimate. */
+    get measureText(): TextMeasurer;
+    /** Run layout and paint now. The only way to render on a platform with no `schedule`. */
+    flush(): FlushStats;
+}
+/** What `toSvgString` takes: a size for what the chart's own `width` and `height` leave open (else 640 x 400), and how to name the ids inside the picture. */
+export interface SvgOptions {
+    width?: number;
+    height?: number;
+    /**
+     * Starts every `id` in the SVG (clip paths, gradients) and every `url(#…)` that points at one. Default: `ink` and eight hex digits of a
+     * hash of the picture itself, so two different charts never share an id (a page that holds several SVGs has one namespace for ids) while the
+     * same chart always gives the same text.
+     */
+    idPrefix?: string;
+}
+/** One-shot export: attach a StringPlatform, flush, detach. */
+export declare function toSvgString(chart: Chart, options?: SvgOptions): string;