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

package/dist/input.js

@@ -0,0 +1,166 @@
+import { EVENT_FOCUS, EVENT_HOVER, EVENT_KEY, EVENT_POINTER } from './events.js';
+import { contains } from './geometry.js';
+import { Plane } from './plane.js';
+export class InputHost {
+    /** True while the last pointer input came from a finger, which hits use to be more forgiving. */
+    coarse = false;
+    #chart;
+    #subscriptions = [];
+    // Pointer capture: the plane a drag started on keeps receiving events even when the pointer leaves it.
+    #pressed = null;
+    #hovered = null;
+    // Elements that want HOVER events: the tree walk to deliver one is only made when someone asked.
+    #pointerWatchers = new Set();
+    #inputWatchers = new Set();
+    // Which element owns each focusable node, so keys and focus changes reach the right one.
+    #focusOwners = new WeakMap();
+    constructor(chart) { this.#chart = chart; }
+    /** Listen to the chart's platform. Called by `inputOf`; a platform with no input of a kind simply gives none. */
+    start() {
+        const platform = this.#chart.platform;
+        if (!platform || this.#subscriptions.length)
+            return;
+        for (const u of [
+            platform.onPointer?.((p) => this.route(p)),
+            platform.onKey?.((k, node) => this.routeKey(k, node)),
+            platform.onFocus?.((f) => this.routeFocus(f)),
+        ])
+            if (u)
+                this.#subscriptions.push(u);
+    }
+    /** Stop listening and forget everything held: `Chart.detach()` calls it. */
+    stop() {
+        for (const u of this.#subscriptions.splice(0))
+            u();
+        this.#pressed = this.#hovered = null;
+        this.#pointerWatchers.clear();
+        this.#inputWatchers.clear();
+    }
+    /**
+     * Ask for HOVER events (where the pointer is in a plane) for as long as the returned function has not been called.
+     * Elements outside the plane that follow the pointer (a tooltip) subscribe when they attach.
+     */
+    watchPointer(element) {
+        this.#pointerWatchers.add(element);
+        return () => { this.#pointerWatchers.delete(element); };
+    }
+    /**
+     * Ask for POINTER events in the chart's own pixels (not a plane's), for elements that are not in a plane and take
+     * input of their own: a legend's entries. Set `handled` on one to keep the planes from also acting on it. Returns the
+     * way to stop.
+     */
+    watchInput(element) {
+        this.#inputWatchers.add(element);
+        return () => { this.#inputWatchers.delete(element); };
+    }
+    /**
+     * Make a node reachable by keyboard: give it a `tabindex` (0 for a place in the tab order, -1 to be focusable by script
+     * only) and say which element it belongs to, which then gets its KEY and FOCUS events. Call again with the same node
+     * freely.
+     */
+    focusable(element, node) {
+        this.#focusOwners.set(node, element);
+    }
+    /** Say something to a screen reader, if the platform has one to tell. */
+    speak(text) { this.#chart.platform?.announce?.(text); }
+    /** Move keyboard focus to a node an element made `focusable`. Does nothing on a platform without focus. */
+    focus(node) { this.#chart.platform?.focus?.(node); }
+    /** One raw pointer: to what listens outside planes first, then to the plane it is over. True when something used it. */
+    route(p) {
+        const chart = this.#chart;
+        if (p.kind !== 'leave' && p.kind !== 'wheel' && p.kind !== 'pinch')
+            this.coarse = p.pointerType === 'touch';
+        // Whatever outside a plane listens (a legend) is told first, in the chart's own pixels; an element that uses the input keeps it from the planes.
+        let taken = false;
+        for (const w of this.#inputWatchers) {
+            if (w.chart !== chart) {
+                this.#inputWatchers.delete(w);
+                continue;
+            }
+            // oxlint-disable-next-line typescript/consistent-type-assertions -- `deliver` returns the event union; a pointer event comes back as one
+            const ev = chart.deliver({
+                type: EVENT_POINTER, kind: p.kind, x: p.x, y: p.y, buttons: p.buttons, deltaY: p.deltaY, deltaX: p.deltaX ?? 0, scale: p.scale ?? 1,
+                id: p.id ?? 0, pointerType: p.pointerType ?? 'mouse', axis: null, outside: false, shift: p.shift, ctrl: p.ctrl, handled: false,
+            }, w);
+            if (ev.handled)
+                taken = true;
+        }
+        if (taken)
+            return true;
+        let at = this.#pressed;
+        // A pointer reaches the plane it is over: its plot, or the strip an axis takes beside it.
+        if (!at && p.kind !== 'leave') {
+            for (const c of chart) {
+                if (!(c instanceof Plane))
+                    continue;
+                if (contains(c.rect, p.x, p.y) || c.axisAt(p.x - c.rect.x, p.y - c.rect.y)) {
+                    at = c;
+                    break;
+                }
+            }
+        }
+        const send = (plane, kind) => {
+            const r = plane.rect, x = p.x - r.x, y = p.y - r.y;
+            // oxlint-disable-next-line typescript/consistent-type-assertions -- `deliver` returns the event union; a pointer event comes back as one
+            return chart.deliver({
+                type: EVENT_POINTER, kind, x, y, buttons: p.buttons, deltaY: p.deltaY, deltaX: p.deltaX ?? 0, scale: p.scale ?? 1,
+                // oxlint-disable-next-line typescript/consistent-type-assertions -- `axisAt` returns an element, and the axis it found is an `Axis` or null
+                id: p.id ?? 0, pointerType: p.pointerType ?? 'mouse', axis: kind === 'leave' ? null : plane.axisAt(x, y), outside: kind !== 'leave' && !contains(r, p.x, p.y),
+                shift: p.shift, ctrl: p.ctrl, handled: false,
+            }, plane).handled;
+        };
+        if (this.#hovered && this.#hovered !== at) {
+            send(this.#hovered, 'leave');
+            this.#announce(this.#hovered, NaN, NaN, 0);
+        }
+        this.#hovered = p.kind === 'leave' ? null : at;
+        if (!at)
+            return false;
+        if (p.kind === 'down')
+            this.#pressed = at;
+        const handled = p.kind === 'leave' ? false : send(at, p.kind);
+        if (p.kind === 'move' || p.kind === 'down' || p.kind === 'up') {
+            // Over an axis the pointer is not on the plot, so what follows the pointer over the plot (a tooltip) is told it has left.
+            const away = !contains(at.rect, p.x, p.y);
+            this.#announce(at, away ? NaN : p.x - at.rect.x, away ? NaN : p.y - at.rect.y, away ? 0 : p.buttons);
+        }
+        if (p.kind === 'up')
+            this.#pressed = null;
+        return handled;
+    }
+    /** A key on a focused node, to the element that made the node focusable. */
+    routeKey(k, node) {
+        const owner = this.#focusOwners.get(node);
+        if (!owner || owner.chart !== this.#chart)
+            return false;
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- `deliver` returns the event union; a key event comes back as one
+        return this.#chart.deliver({
+            type: EVENT_KEY, kind: k.kind, key: k.key, shift: k.shift, ctrl: k.ctrl, alt: k.alt, repeat: k.repeat, node, handled: false,
+        }, owner).handled;
+    }
+    /** Focus entering or leaving a node, to its owner. */
+    routeFocus(f) {
+        const owner = this.#focusOwners.get(f.node);
+        if (!owner || owner.chart !== this.#chart)
+            return;
+        this.#chart.deliver({ type: EVENT_FOCUS, node: f.node, focused: f.focused, visible: f.visible }, owner);
+    }
+    /** Tell every element where the pointer is in `plane` (NaN: it has gone). */
+    #announce(plane, x, y, buttons) {
+        for (const w of this.#pointerWatchers)
+            if (w.chart !== this.#chart)
+                this.#pointerWatchers.delete(w); // taken out of the tree
+        if (this.#pointerWatchers.size === 0)
+            return;
+        this.#chart.deliver({ type: EVENT_HOVER, plane, x, y, buttons });
+    }
+}
+/** The chart's input host, made and started on the first ask. Elements that take input call this as they attach. */
+export function inputOf(chart) {
+    let host = chart.input;
+    if (!host) {
+        host = chart.input = new InputHost(chart);
+        host.start();
+    }
+    return host;
+}

package/dist/jsx-dev-runtime.d.ts

@@ -0,0 +1,9 @@
+import type { AnyElement } from './element.ts';
+import { type JsxType } from './jsx-runtime.ts';
+export { Fragment, type JSX, type JsxType, jsxs } from './jsx-runtime.ts';
+export interface JsxSource {
+    fileName?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+}
+export declare function jsxDEV(type: JsxType, props: Record<string, unknown>, key?: unknown, _isStatic?: boolean, source?: JsxSource): AnyElement;

package/dist/jsx-dev-runtime.js

@@ -0,0 +1,13 @@
+import { jsx } from './jsx-runtime.js';
+export { Fragment, jsxs } from './jsx-runtime.js';
+export function jsxDEV(type, props, key, _isStatic, source) {
+    try {
+        return jsx(type, props, key);
+    }
+    catch (error) {
+        if (error instanceof Error && source?.fileName && !error.message.includes(source.fileName)) {
+            error.message += ` (${source.fileName}:${source.lineNumber}:${source.columnNumber})`;
+        }
+        throw error;
+    }
+}

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A JSX runtime for building charts as element trees: use it with `jsxImportSource` and write
+ *
+ *     /** @jsxImportSource inkplot *\/
+ *     const chart = (
+ *       <Chart theme={lightTheme}>
+ *         <CartesianPlane>
+ *           <Axis meta-title="Time"><LinearScale /></Axis>
+ *           <DomainSeries><ObjectDataSource source={rows} domain="t" value="v" /><LinePath><LinearCurve /></LinePath></DomainSeries>
+ *         </CartesianPlane>
+ *       </Chart>
+ *     );
+ *
+ * Every tag makes the element at once, so the result is the same `Chart` you would have written with `new`, and can
+ * be attached to a platform, serialized, or handed to the React adapter. Runtimes can be mixed per file.
+ *
+ * - Attribute names with hyphens are nested: `meta-title="x"` is `meta={{ title: 'x' }}` (see attrs.ts).
+ * - Children go to the constructor in order. A parent's fixed children (an axis' scale, a series' data) come first and in
+ *   the order its documentation gives; they cannot be checked by the types, because JSX does not type children one by one.
+ *   `null`, `undefined` and `false` (a skipped `{cond && <X />}`) are dropped, so a fixed child cannot be skipped.
+ * - `ref` receives the element (a function, or an object with `current`), to keep hold of it.
+ * - A function can stand in for a tag to make a reusable piece: it is called with the props, `children` included, and returns an element.
+ * - The text of a tag (`<ChartTitle>Sales</ChartTitle>`) is not supported: write `text="Sales"`.
+ */
+import { type AnyArgs, type AnyElement } from './element.ts';
+import { type JsxRef } from './attrs.ts';
+type Props = Record<string, unknown>;
+type ElementConstructor = abstract new (...args: AnyArgs) => AnyElement;
+/** A tag: a chart element class, or a function making an element (or several, as a fragment). */
+export type JsxType = ElementConstructor | ((props: never) => AnyElement | readonly AnyElement[]);
+/** The JSX factory: one call per tag, with the children already made. `key` has no meaning for a retained tree and is ignored. */
+export declare function jsx(type: JsxType, props: Props, _key?: unknown): AnyElement;
+/** Several children given as a list of literals rather than written out: the same as `jsx`. */
+export declare const jsxs: typeof jsx;
+/** `<>…</>`: the children, so that a function tag or a parent can take several elements at once. */
+export declare function Fragment(props: {
+    children?: unknown;
+}): AnyElement[];
+/** The types TypeScript reads to check JSX. A tag is a chart element class; `$props` on it says what it takes. */
+export declare namespace JSX {
+    type Element = AnyElement;
+    interface ElementClass extends AnyElement {
+    }
+    interface ElementAttributesProperty {
+        $props: {};
+    }
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+    interface IntrinsicElements {
+    }
+    interface IntrinsicAttributes {
+        key?: string | number | null;
+    }
+    interface IntrinsicClassAttributes<T> {
+        ref?: JsxRef<T>;
+    }
+}
+export {};

package/dist/jsx-runtime.js

@@ -0,0 +1,81 @@
+/**
+ * A JSX runtime for building charts as element trees: use it with `jsxImportSource` and write
+ *
+ *     /** @jsxImportSource inkplot *\/
+ *     const chart = (
+ *       <Chart theme={lightTheme}>
+ *         <CartesianPlane>
+ *           <Axis meta-title="Time"><LinearScale /></Axis>
+ *           <DomainSeries><ObjectDataSource source={rows} domain="t" value="v" /><LinePath><LinearCurve /></LinePath></DomainSeries>
+ *         </CartesianPlane>
+ *       </Chart>
+ *     );
+ *
+ * Every tag makes the element at once, so the result is the same `Chart` you would have written with `new`, and can
+ * be attached to a platform, serialized, or handed to the React adapter. Runtimes can be mixed per file.
+ *
+ * - Attribute names with hyphens are nested: `meta-title="x"` is `meta={{ title: 'x' }}` (see attrs.ts).
+ * - Children go to the constructor in order. A parent's fixed children (an axis' scale, a series' data) come first and in
+ *   the order its documentation gives; they cannot be checked by the types, because JSX does not type children one by one.
+ *   `null`, `undefined` and `false` (a skipped `{cond && <X />}`) are dropped, so a fixed child cannot be skipped.
+ * - `ref` receives the element (a function, or an object with `current`), to keep hold of it.
+ * - A function can stand in for a tag to make a reusable piece: it is called with the props, `children` included, and returns an element.
+ * - The text of a tag (`<ChartTitle>Sales</ChartTitle>`) is not supported: write `text="Sales"`.
+ */
+import { ChartElement } from './element.js';
+import { expandAttributes } from './attrs.js';
+function flatten(children, into, tag) {
+    if (children == null || children === false)
+        return into;
+    if (Array.isArray(children)) {
+        for (const c of children)
+            flatten(c, into, tag);
+    }
+    else if (children instanceof ChartElement) {
+        into.push(children);
+    }
+    else {
+        throw new TypeError(`<${tag}>: a child must be a chart element, not ${typeof children === 'object' ? 'an object' : `${typeof children} ${JSON.stringify(children)}`}`);
+    }
+    return into;
+}
+const nameOf = (type) => type.name || 'anonymous';
+/** The JSX factory: one call per tag, with the children already made. `key` has no meaning for a retained tree and is ignored. */
+export function jsx(type, props, _key) {
+    const { children, ref, ...rest } = props;
+    const tag = nameOf(type);
+    let element;
+    const isClass = type.prototype instanceof ChartElement;
+    if (isClass) {
+        const attrs = expandAttributes(rest);
+        for (const k of Object.keys(attrs))
+            if (attrs[k] === undefined)
+                delete attrs[k];
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- JSX tags are either classes or function components: a class is told apart by `isClass` above
+        element = new type(attrs, ...flatten(children, [], tag));
+    }
+    else {
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- JSX tags are either classes or function components: a function is told apart by `isClass` above
+        const made = type(children === undefined ? rest : { ...rest, children });
+        // A list (a fragment, or a function returning several elements) is passed on as it is; the parent flattens it.
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- a function component may return an array of elements, which `flatten` turns into one element
+        if (Array.isArray(made))
+            element = flatten(made, [], tag);
+        else if (made instanceof ChartElement)
+            element = made;
+        else
+            throw new TypeError(`<${tag}>: a function used as a tag must return a chart element`);
+    }
+    if (typeof ref === 'function')
+        ref(element);
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- a `ref` is an object with `current`, or a callback, which is handled on the line above
+    else if (ref)
+        ref.current = element;
+    return element;
+}
+/** Several children given as a list of literals rather than written out: the same as `jsx`. */
+export const jsxs = jsx;
+/** `<>…</>`: the children, so that a function tag or a parent can take several elements at once. */
+export function Fragment(props) {
+    return flatten(props.children, [], 'Fragment');
+}

package/dist/key.d.ts

@@ -0,0 +1,118 @@
+import type { Chart } from './chart.ts';
+import { type BaseAttributes, ChartElement, type ElementRef } from './element.ts';
+import { type ChartEvent } from './events.ts';
+import { type Side } from './geometry.ts';
+import type { ColorAxis, MappedDimension, SizeAxis } from './mapped.ts';
+import type { PlatformNode } from './platform.ts';
+export type KeyOrientation = 'vertical' | 'horizontal';
+/** Options common to all keys. */
+export interface KeyAttributes<Dimension extends MappedDimension<unknown>> extends BaseAttributes {
+    /** The dimension this key shows, or its id. A colour key takes a colour dimension, a size key a size one. */
+    dimension: ElementRef<Dimension>;
+    /** The edge of the chart it sits along. Default 'right'. */
+    side?: Side;
+    /** Which way its scale runs. Default: along its side, so vertical on the left and right, horizontal on the top and bottom. */
+    orientation?: KeyOrientation;
+    /** Default: the dimension's own title. */
+    title?: string;
+    /** Length of the scale in pixels. Default 140. */
+    length?: number;
+    /** Width of a vertical key: the scale and its labels. Default 72. */
+    breadth?: number;
+}
+/** Where things go in a key; passed to the drawing methods so they do not each recompute it. Everything is measured from the key's own top left corner. */
+interface Layout {
+    vertical: boolean;
+    /** Pixels taken by the title. */
+    top: number;
+    length: number;
+    /** Room at the ends of the scale for what is drawn there, such as the biggest circle of a size key. */
+    inset: number;
+    /** Where a horizontal scale starts, leaving room for the first label to overhang. */
+    left: number;
+}
+/** A tick of a key: its label, how far along the dimension it is, and where that is on the scale. */
+interface Tick {
+    text: string;
+    fraction: number;
+    at: number;
+}
+/**
+ * The shared frame of a key: reserves a strip along a chart edge, draws the title, and offers the scale-drawing helpers
+ * (`along`, `ticks`, `paintTicks`) that subclasses use. A subclass says only what its scale looks like.
+ *
+ * Layout: the chart asks the key how big it wants to be (MEASURE answers with `side`), carves a strip for it, and then
+ * arranges it into that strip. The key is a *chart* child rather than a plane's so one key can sit beside several planes.
+ */
+export declare abstract class Key<Dimension extends MappedDimension<unknown>, A extends KeyAttributes<Dimension> = KeyAttributes<Dimension>> extends ChartElement<Chart, [], A> {
+    #private;
+    static attrTypes: {
+        title: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** Room the scale needs past its ends. */
+    protected get inset(): number;
+    /** How thick the drawing is, across the scale: a colour bar, the biggest circle. */
+    protected abstract get thickness(): number;
+    /** How many ticks suit a scale this long, or undefined to leave it to the dimension. */
+    protected ticksFor(_length: number, _vertical: boolean): number | undefined;
+    /** Draw the scale, its ticks and labels. */
+    protected abstract paintScale(layout: Layout): void;
+    get dimension(): Dimension;
+    get side(): Side;
+    get vertical(): boolean;
+    private get title();
+    protected get length(): number;
+    /** The size of the labels, which the layout is built on. */
+    protected get fontSize(): number;
+    /** Put the key's line look (ticks, circles) on a node. */
+    protected strokeLine(node: PlatformNode): void;
+    onEvent(ev: ChartEvent): void;
+    /** Position along the scale, in key pixels, of a fraction 0..1 of the dimension. Low is at the bottom or the left. */
+    protected along(l: Layout, fraction: number): number;
+    /** The dimension's ticks, each with its fraction of the dimension and its place along the scale. Ticks outside the range are left out. */
+    protected ticks(l: Layout): Tick[];
+    /**
+     * Labels, and optionally a mark for each tick. `markAt` is the line across the scale the marks start from, and
+     * `labelAt` is where the labels go on it: their left edge on a vertical scale, their baseline on a horizontal one.
+     */
+    protected paintTicks(l: Layout, ticks: readonly Tick[], markAt: number, labelAt: number, marks: boolean): void;
+}
+export interface ColorKeyAttributes extends KeyAttributes<ColorAxis> {
+    /** Thickness of the colour bar in pixels. Default 14. */
+    thickness?: number;
+}
+/** A bar of the dimension's colours, low to high, with its ticks. */
+export declare class ColorKey extends Key<ColorAxis, ColorKeyAttributes> {
+    #private;
+    static attrTypes: {
+        title: 1;
+        dimension: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    private readonly gradientId;
+    protected get thickness(): number;
+    protected paintScale(l: Layout): void;
+}
+/** No options of its own beyond the common ones. */
+export interface SizeKeyAttributes extends KeyAttributes<SizeAxis> {
+}
+/** Circles at the dimension's tick values, each as big as the size it stands for. */
+export declare class SizeKey extends Key<SizeAxis, SizeKeyAttributes> {
+    protected get inset(): number;
+    protected get thickness(): number;
+    /** Circles as big as the biggest need room: no more ticks than fit without piling up. */
+    protected ticksFor(length: number): number;
+    protected paintScale(l: Layout): void;
+}
+export {};

package/dist/key.js

@@ -0,0 +1,199 @@
+/**
+ * Keys: what a mapped dimension means, drawn beside the plots.
+ *
+ * A key is an element of its own, a child of the chart that refers to the dimension it shows:
+ *
+ *   new Chart({}, plane, heat, new ColorKey({ dimension: heat, title: 'Pressure' }))
+ *
+ * The dimension says what the colours are (ramp, scale, range); the key says where and how to draw them (side,
+ * orientation, length). Different keys can show one dimension, and a dimension needs none.
+ */
+import { STRING } from './attrs.js';
+import { ChartElement, resolveRef } from './element.js';
+import { EVENT_ARRANGE, EVENT_ATTACH, EVENT_MEASURE, EVENT_PAINT } from './events.js';
+import { circlePath, f2 } from './geometry.js';
+import { applyText } from './text.js';
+// Fixed metrics in pixels: keys are small furniture, so these are constants rather than options.
+const TITLE_BLOCK = 18;
+const LABEL_OVERHANG = 14;
+const round2 = (n) => Math.round(n * 100) / 100;
+/**
+ * The shared frame of a key: reserves a strip along a chart edge, draws the title, and offers the scale-drawing helpers
+ * (`along`, `ticks`, `paintTicks`) that subclasses use. A subclass says only what its scale looks like.
+ *
+ * Layout: the chart asks the key how big it wants to be (MEASURE answers with `side`), carves a strip for it, and then
+ * arranges it into that strip. The key is a *chart* child rather than a plane's so one key can sit beside several planes.
+ */
+export class Key extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, title: STRING };
+    /** Room the scale needs past its ends. */
+    get inset() { return 0; }
+    /** How many ticks suit a scale this long, or undefined to leave it to the dimension. */
+    ticksFor(_length, _vertical) { return undefined; }
+    #rect = { x: 0, y: 0, width: 0, height: 0 };
+    #labels = 0;
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- `resolveRef` returns an element; the attribute type says it is a dimension
+    get dimension() { return resolveRef(this.attrs.dimension, this); }
+    get side() { return this.attrs.side ?? 'right'; }
+    get vertical() {
+        return (this.attrs.orientation ?? (this.side === 'left' || this.side === 'right' ? 'vertical' : 'horizontal')) === 'vertical';
+    }
+    get title() { return this.attrs.title ?? this.dimension.attrs.title; }
+    get length() { return this.attrs.length ?? 140; }
+    /** The size of the labels, which the layout is built on. */
+    get fontSize() { return this.styleFor(['keyLabel', 'key', 'text']).size; }
+    /** Put the key's line look (ticks, circles) on a node. */
+    strokeLine(node) {
+        const look = this.styleFor(['keyLine', 'key', 'line']), s = this.surface;
+        s.set(node, 'stroke', look.color);
+        s.set(node, 'stroke-width', look.width);
+        s.set(node, 'opacity', look.opacity);
+    }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_ATTACH:
+                this.surface.wrapper();
+                break;
+            case EVENT_MEASURE: {
+                const title = this.title ? TITLE_BLOCK : 0, length = this.length, inset = this.inset;
+                const size = this.vertical
+                    ? { width: this.attrs.breadth ?? 72, height: title + 2 * inset + length + 12 }
+                    : { width: LABEL_OVERHANG + 2 * inset + length + LABEL_OVERHANG, height: title + this.thickness + 4 + this.fontSize * 1.4 };
+                ev.request = { min: size, max: size, side: this.side };
+                break;
+            }
+            case EVENT_ARRANGE:
+                this.#rect = ev.rect;
+                break;
+            case EVENT_PAINT: {
+                const s = this.surface, root = s.wrapper(), vertical = this.vertical, title = this.title;
+                s.set(root, 'transform', `translate(${f2(this.#rect.x)} ${f2(this.#rect.y)})`);
+                applyText(s, root, this.styleFor(['keyLabel', 'key', 'text']), vertical ? 'start' : 'middle');
+                if (title) {
+                    const t = s.node('title', 'text');
+                    applyText(s, t, this.styleFor(['keyTitle', 'key', 'text']), 'start');
+                    s.set(t, 'y', this.fontSize);
+                    s.text(t, title);
+                }
+                else {
+                    s.remove('title');
+                }
+                this.paintScale({ vertical, top: title ? TITLE_BLOCK : 0, length: this.length, inset: this.inset, left: LABEL_OVERHANG });
+                break;
+            }
+        }
+    }
+    /** Position along the scale, in key pixels, of a fraction 0..1 of the dimension. Low is at the bottom or the left. */
+    along(l, fraction) {
+        return l.vertical ? l.top + l.inset + (1 - fraction) * l.length : l.left + l.inset + fraction * l.length;
+    }
+    /** The dimension's ticks, each with its fraction of the dimension and its place along the scale. Ticks outside the range are left out. */
+    ticks(l) {
+        const dim = this.dimension, out = [];
+        for (const t of dim.getTicks(l.length, this.ticksFor(l.length, l.vertical))) {
+            const fraction = dim.fractionOf(t.value);
+            if (fraction >= -1e-9 && fraction <= 1 + 1e-9)
+                out.push({ text: t.label, fraction, at: round2(this.along(l, fraction)) });
+        }
+        return out;
+    }
+    /**
+     * Labels, and optionally a mark for each tick. `markAt` is the line across the scale the marks start from, and
+     * `labelAt` is where the labels go on it: their left edge on a vertical scale, their baseline on a horizontal one.
+     */
+    paintTicks(l, ticks, markAt, labelAt, marks) {
+        const s = this.surface;
+        if (marks) {
+            let d = '';
+            for (const t of ticks)
+                d += l.vertical ? `M${markAt} ${t.at}h3` : `M${t.at} ${markAt}v3`;
+            const node = s.node('ticks', 'path');
+            s.set(node, 'd', d);
+            this.strokeLine(node);
+            s.set(node, 'fill', 'none');
+        }
+        ticks.forEach((t, i) => {
+            const n = s.node(`label-${i}`, 'text');
+            s.set(n, 'x', l.vertical ? labelAt : t.at);
+            s.set(n, 'y', l.vertical ? round2(t.at + this.fontSize * 0.35) : labelAt);
+            s.text(n, t.text);
+        });
+        for (let i = ticks.length; i < this.#labels; i++)
+            s.remove(`label-${i}`);
+        this.#labels = ticks.length;
+    }
+}
+// Module-level so gradient ids stay unique across keys and charts on one page.
+let gradientCounter = 0;
+/** A bar of the dimension's colours, low to high, with its ticks. */
+export class ColorKey extends Key {
+    static attrTypes = { ...Key.attrTypes, dimension: STRING };
+    gradientId = `grad${++gradientCounter}`;
+    #stops = 0;
+    get thickness() { return this.attrs.thickness ?? 14; }
+    paintScale(l) {
+        const s = this.surface, dim = this.dimension, thickness = this.thickness;
+        // One rect filled by a gradient. A stepped dimension gets hard stops, so the bands stay bands.
+        const grad = s.node('gradient', 'linearGradient', { parent: s.node('defs', 'defs') });
+        s.set(grad, 'id', this.gradientId);
+        s.set(grad, 'x1', 0);
+        s.set(grad, 'y1', l.vertical ? 1 : 0);
+        s.set(grad, 'x2', l.vertical ? 0 : 1);
+        s.set(grad, 'y2', 0);
+        const stops = [];
+        if (dim.attrs.interpolation === 'step') {
+            const n = dim.stops.length;
+            // 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; i < n; i++) {
+                const c = dim.stops[i];
+                stops.push([i / n, c], [(i + 1) / n, c]);
+            }
+        }
+        else {
+            const n = Math.max(2, Math.min(24, dim.stops.length * 2));
+            for (let i = 0; i < n; i++)
+                stops.push([i / (n - 1), dim.valueAt(i / (n - 1))]);
+        }
+        stops.forEach(([offset, color], i) => {
+            const n = s.node(`stop-${i}`, 'stop', { parent: grad });
+            s.set(n, 'offset', Math.round(offset * 1000) / 1000);
+            s.set(n, 'stop-color', color);
+        });
+        for (let i = stops.length; i < this.#stops; i++)
+            s.remove(`stop-${i}`);
+        this.#stops = stops.length;
+        const bar = s.node('bar', 'rect');
+        s.set(bar, 'x', l.vertical ? 0 : l.left);
+        s.set(bar, 'y', l.top);
+        s.set(bar, 'width', l.vertical ? thickness : l.length);
+        s.set(bar, 'height', l.vertical ? l.length : thickness);
+        s.set(bar, 'fill', `url(#${this.gradientId})`);
+        this.paintTicks(l, this.ticks(l), l.vertical ? thickness : l.top + thickness, l.vertical ? thickness + 6 : l.top + thickness + 3 + this.fontSize, true);
+    }
+}
+/** Circles at the dimension's tick values, each as big as the size it stands for. */
+export class SizeKey extends Key {
+    get inset() { return this.dimension.output[1]; }
+    get thickness() { return 2 * this.dimension.output[1]; }
+    /** Circles as big as the biggest need room: no more ticks than fit without piling up. */
+    ticksFor(length) {
+        return Math.max(2, Math.floor(length / (2 * this.dimension.output[1] + 4)));
+    }
+    paintScale(l) {
+        const s = this.surface, dim = this.dimension, hi = dim.output[1];
+        const ticks = this.ticks(l);
+        // The circles sit on a line through their centres: down the key, or along it.
+        const centre = hi + 1;
+        let d = '';
+        for (const t of ticks) {
+            const r = dim.valueAt(t.fraction);
+            const [cx, cy] = l.vertical ? [centre, t.at] : [t.at, l.top + hi];
+            d += circlePath(cx, cy, r);
+        }
+        const circles = s.node('circles', 'path');
+        s.set(circles, 'd', d);
+        s.set(circles, 'fill', 'none');
+        this.strokeLine(circles);
+        this.paintTicks(l, ticks, 0, l.vertical ? centre + hi + 6 : l.top + 2 * hi + 3 + this.fontSize, false);
+    }
+}