inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/errors.js

@@ -0,0 +1,237 @@
+/**
+ * Error bars and bands: how far each value may be from what was measured.
+ *
+ *   <DomainSeries>
+ *     <ObjectDataSource source={rows} domain="t" value="mean" channels={{ sd: 'sd' }} />
+ *     <LinePath><LinearCurve /></LinePath>
+ *     <ErrorBars error="sd" />
+ *   </DomainSeries>
+ *
+ * Both are renderers that take a **channel** of the data beside each point: `error` is how far above the value, and
+ * `negativeError` how far below (left out, it is the same distance, so one channel gives a symmetric bar). `mode` says what
+ * the number means: 'absolute' (the default: in the unit of the value) or 'relative' (a fraction of the value, so 0.1 is
+ * plus or minus 10%). A gap in the value or in either error leaves that point without a bar.
+ *
+ * `ErrorBars` draws a whisker with a cap at each end; `ErrorBand` fills the region between the lower and upper ends, with
+ * straight edges, which suits a dense series. They work on any plane (the whisker is a spoke on a polar one), sit on top of a
+ * stack's layers (an error in the stack's unit; not with a 'normalize' stack, which has no unit) and on bars in a group,
+ * and the axes leave room for them, so the range shows every bar. Neither is hit, and neither can be on a series with a
+ * `Decimator` (channels cannot go through one).
+ *
+ * `along` is which way the error runs: 'value' (the default), or 'domain', which on an `XYSeries` is horizontal error
+ * (the axis for x is fitted to it; on a `DomainSeries` the domain is settled first, so give that axis a range).
+ */
+/* oxlint-disable typescript/no-non-null-assertion -- numeric kernels over flat typed-array buffers (stride-addressed rows): every index is bounded by the row count, which `noUncheckedIndexedAccess` cannot see */
+import { NUMBER, STRING } from './attrs.js';
+import { barShift } from './bars.js';
+import { f2 } from './geometry.js';
+import { SeriesRenderer } from './renderer.js';
+/** How far the normalised position may stray outside the axis before it is held there: only to keep the numbers sane, the clip does the rest. */
+const REACH = 2;
+/** The step along the cap's direction, as a fraction of its axis, used to find which way that is on the plane. */
+const TANGENT = 1e-4;
+/** The error of one row: above and below, as non-negative distances, or NaN where either is missing. */
+function distances(view, i, error, negative, relative, value) {
+    const row = i * view.stride, up = view.raw[row + view.channelColumn(error)], down = view.raw[row + view.channelColumn(negative)];
+    const k = relative ? Math.abs(value) : 1;
+    return [Math.abs(up) * k, Math.abs(down) * k];
+}
+/** What error renderers share: the channels, the rows' spread, and the placed ends. */
+class ErrorRenderer extends SeriesRenderer {
+    get channelNames() {
+        const a = this.attrs;
+        return a.negativeError && a.negativeError !== a.error ? [a.error, a.negativeError] : [a.error];
+    }
+    get negative() { return this.attrs.negativeError ?? this.attrs.error; }
+    spread(view) {
+        const a = this.attrs, relative = a.mode === 'relative';
+        let lo = Infinity, hi = -Infinity;
+        for (let i = 0; i < view.count; i++) {
+            const row = i * view.stride, own = view.raw[row + (a.along === 'domain' ? view.firstColumn : view.secondColumn)];
+            const at = view.top && a.along !== 'domain' ? view.top[i] : own;
+            const [up, down] = distances(view, i, a.error, this.negative, relative, view.raw[row + view.secondColumn]);
+            if (!Number.isFinite(at) || !Number.isFinite(up) || !Number.isFinite(down))
+                continue;
+            if (at - down < lo)
+                lo = at - down;
+            if (at + up > hi)
+                hi = at + up;
+        }
+        if (lo > hi)
+            return null;
+        return a.along === 'domain' ? { first: { min: lo, max: hi } } : { second: { min: lo, max: hi } };
+    }
+    limit(series) {
+        const a = this.attrs, relative = a.mode === 'relative', domain = a.along === 'domain';
+        const own = series.ownExtent(domain ? 'first' : 'second'), up = series.data.channelExtent(a.error), down = series.data.channelExtent(this.negative);
+        const values = series.ownExtent('second');
+        if (!own || !up || !down || !values)
+            return null;
+        const most = Math.max(Math.abs(values.min), Math.abs(values.max)), k = relative ? most : 1;
+        const e = { min: own.min - Math.max(Math.abs(down.min), Math.abs(down.max)) * k, max: own.max + Math.max(Math.abs(up.min), Math.abs(up.max)) * k };
+        return domain ? { first: e } : { second: e };
+    }
+    /**
+     * The places in plot pixels of the lower end, the upper end, and a point a little further along the cap's direction from
+     * each (which says which way the cap runs on this plane), for every row: `[lo, hi, loAlong, hiAlong]` of one row after another,
+     * NaN for a row with no bar.
+     */
+    ends(series) {
+        const d = series.drawn;
+        if (!d)
+            return null;
+        const a = this.attrs, relative = a.mode === 'relative', domain = a.along === 'domain', first = series.firstAxis, second = series.secondAxis;
+        const n = d.points.count, rs = d.stride, bound = d.channels.length, base = rs - bound;
+        const colError = base + d.channels.indexOf(a.error), colNeg = base + d.channels.indexOf(this.negative);
+        const pts = new Float64Array(n * 8), held = new Uint8Array(n);
+        for (let i = 0; i < n; i++) {
+            const row = i * rs, x = d.raw[row + d.firstColumn], own = d.raw[row + d.secondColumn];
+            const centre = domain ? x : d.top ? d.top[i] : own;
+            const k = relative ? Math.abs(own) : 1, up = Math.abs(d.raw[row + colError]) * k, down = Math.abs(d.raw[row + colNeg]) * k;
+            const bad = !Number.isFinite(centre) || !Number.isFinite(up) || !Number.isFinite(down) || (domain ? !Number.isFinite(own) : !Number.isFinite(x));
+            const lo = bad ? NaN : centre - down, hi = bad ? NaN : centre + up, k8 = i * 8;
+            // A lower end at or below zero has no place on a log axis: it is held at the edge (below).
+            if (!bad && lo <= 0 && centre > 0)
+                held[i] = 1;
+            // Four points, each as first coordinate then second.
+            const put = (slot, f, sc) => { pts[k8 + slot * 2] = f; pts[k8 + slot * 2 + 1] = sc; };
+            if (domain) {
+                put(0, lo, own);
+                put(1, hi, own);
+                put(2, lo, own);
+                put(3, hi, own);
+            }
+            else {
+                put(0, x, lo);
+                put(1, x, hi);
+                put(2, x, lo);
+                put(3, x, hi);
+            }
+        }
+        first.normalize(pts, n * 4, 2, 0);
+        second.normalize(pts, n * 4, 2, 1);
+        const shift = domain ? 0 : barShift(series);
+        const clamp = (v) => (v < -REACH ? -REACH : v > 1 + REACH ? 1 + REACH : v);
+        for (let i = 0; i < n; i++) {
+            for (const slot of [0, 2]) {
+                const k = i * 8 + slot * 2 + (domain ? 0 : 1);
+                if (held[i] && !Number.isFinite(pts[k]))
+                    pts[k] = -REACH;
+            }
+            for (let slot = 0; slot < 4; slot++) {
+                const k = i * 8 + slot * 2;
+                pts[k] = clamp(pts[k]);
+                pts[k + 1] = clamp(pts[k + 1]);
+                if (!domain)
+                    pts[k] = pts[k] + shift;
+            }
+            // The two along points step the cap's way: along the domain for a value error, along the value for a domain one.
+            for (const slot of [2, 3]) {
+                const k = i * 8 + slot * 2;
+                if (domain)
+                    pts[k + 1] = pts[k + 1] + TANGENT;
+                else
+                    pts[k] = pts[k] + TANGENT;
+            }
+        }
+        d.plane.place({ data: pts, stride: 2, count: n * 4 }, first, second);
+        return { n, pts };
+    }
+}
+/** A whisker from the lower end to the upper, with a cap across each, as one path. */
+export class ErrorBars extends ErrorRenderer {
+    static attrTypes = { ...SeriesRenderer.attrTypes, error: STRING, negativeError: STRING, capWidth: NUMBER, mode: STRING, along: STRING };
+    /** Neutral by default (the theme's line colour), so that it can be seen on the bars it goes with. */
+    look() {
+        const a = this.attrs;
+        return this.styleFor(['errorBar', 'line'], { color: a.stroke, width: a.strokeWidth, opacity: a.opacity });
+    }
+    get reach() { return (this.attrs.capWidth ?? 8) / 2; }
+    sample(s, parent, key, width, height) {
+        const look = this.look(), n = s.node(key, 'path', { parent }), x = width / 2, cap = Math.min(width, this.attrs.capWidth ?? 8) / 2;
+        s.set(n, 'd', `M${x} 1V${height - 1}M${x - cap} 1H${x + cap}M${x - cap} ${height - 1}H${x + cap}`);
+        s.set(n, 'fill', 'none');
+        s.set(n, 'stroke', look.color);
+        s.set(n, 'stroke-width', look.width);
+        s.set(n, 'opacity', look.opacity);
+    }
+    draw() {
+        const s = this.surface, series = this.requireParent(), look = this.look(), cap = (this.attrs.capWidth ?? 8) / 2;
+        const e = this.ends(series);
+        let d = '';
+        if (e) {
+            const p = e.pts;
+            for (let i = 0; i < e.n; i++) {
+                const k = i * 8, lx = p[k], ly = p[k + 1], hx = p[k + 2], hy = p[k + 3];
+                if (!(Number.isFinite(lx) && Number.isFinite(ly) && Number.isFinite(hx) && Number.isFinite(hy)))
+                    continue;
+                d += `M${f2(lx)} ${f2(ly)}L${f2(hx)} ${f2(hy)}`;
+                if (cap > 0) {
+                    for (const [x, y, ax, ay] of [[lx, ly, p[k + 4], p[k + 5]], [hx, hy, p[k + 6], p[k + 7]]]) {
+                        const tx = ax - x, ty = ay - y, len = Math.hypot(tx, ty);
+                        if (!(len > 0))
+                            continue;
+                        const ux = (tx / len) * cap, uy = (ty / len) * cap;
+                        d += `M${f2(x - ux)} ${f2(y - uy)}L${f2(x + ux)} ${f2(y + uy)}`;
+                    }
+                }
+            }
+        }
+        const n = s.node('bars', 'path');
+        s.set(n, 'd', d);
+        s.set(n, 'fill', 'none');
+        s.set(n, 'stroke', look.color);
+        s.set(n, 'stroke-width', look.width);
+        s.set(n, 'stroke-linecap', 'butt');
+        s.set(n, 'opacity', look.opacity);
+    }
+}
+/** The region between the lower and the upper ends, as one path; a gap splits it. */
+export class ErrorBand extends ErrorRenderer {
+    static attrTypes = { ...SeriesRenderer.attrTypes, error: STRING, negativeError: STRING, mode: STRING, along: STRING };
+    look() {
+        const a = this.attrs;
+        return this.styleFor(['errorBand', 'shape'], { fill: a.fill, stroke: a.stroke, strokeWidth: a.strokeWidth, opacity: a.opacity }, { fill: this.requireParent().accentColor });
+    }
+    get swatch() { return this.look().fill; }
+    sample(s, parent, key, width, height) {
+        const look = this.look(), n = s.node(key, 'path', { parent });
+        s.set(n, 'd', `M0 ${height * 0.2}H${width}V${height * 0.8}H0Z`);
+        s.set(n, 'fill', look.fill);
+        s.set(n, 'fill-opacity', look.opacity);
+        s.set(n, 'stroke', look.stroke);
+        s.set(n, 'stroke-width', look.strokeWidth);
+    }
+    draw() {
+        const s = this.surface, series = this.requireParent(), look = this.look();
+        const e = this.ends(series);
+        let d = '';
+        if (e) {
+            const p = e.pts, ok = (i) => { const k = i * 8; return Number.isFinite(p[k]) && Number.isFinite(p[k + 1]) && Number.isFinite(p[k + 2]) && Number.isFinite(p[k + 3]); };
+            for (let i = 0; i < e.n;) {
+                if (!ok(i)) {
+                    i++;
+                    continue;
+                }
+                let j = i;
+                while (j < e.n && ok(j))
+                    j++;
+                // The run i..j-1: forward along the upper ends, back along the lower.
+                d += `M${f2(p[i * 8 + 2])} ${f2(p[i * 8 + 3])}`;
+                for (let r = i + 1; r < j; r++)
+                    d += `L${f2(p[r * 8 + 2])} ${f2(p[r * 8 + 3])}`;
+                for (let r = j - 1; r >= i; r--)
+                    d += `L${f2(p[r * 8])} ${f2(p[r * 8 + 1])}`;
+                d += 'Z';
+                i = j;
+            }
+        }
+        const n = s.node('band', 'path');
+        s.set(n, 'd', d);
+        s.set(n, 'fill', look.fill);
+        s.set(n, 'fill-opacity', look.opacity);
+        s.set(n, 'stroke', look.stroke);
+        s.set(n, 'stroke-width', look.strokeWidth);
+        s.set(n, 'stroke-linejoin', 'round');
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The events an element can receive, and the hit a pointer query returns.
+ *
+ * Why events rather than methods: the tree is heterogeneous and open (anyone can subclass an element), so the base class
+ * offers one `onEvent` and each subclass switches on what it cares about. Flow of one frame:
+ *   ATTACH   once, when the element joins a chart: create wrappers, subscribe.
+ *   MEASURE  parent → child, asking for a size range (the answer is written onto the event).
+ *   ARRANGE  parent → child, giving it its final rectangle.
+ *   PAINT    broadcast to everyone after layout: draw through the surface.
+ *   POINTER  platform → chart → elements under the pointer (in their own coordinates); `handled` suppresses browser defaults.
+ *   HOVER    chart → elements that asked (`Chart.watchPointer`), after each POINTER move, with the pointer's place in the
+ *            plane it is over, or that it has left. For things outside the plane that follow the pointer (a tooltip);
+ *            what is under it is theirs to ask (hit.ts), so the chart does no hit testing.
+ *   KEY      platform → chart → the element that owns the focused node (see `Chart.focusable`). `handled` keeps the browser
+ *            from also acting on the key (scrolling the page on an arrow, say).
+ *   FOCUS    chart → the owner of a node that gained or lost focus, and whether a ring should show (keyboard focus does).
+ */
+import type { Axis } from './axis.ts';
+import type { AnyElement } from './element.ts';
+import type { LayoutRequest, Rect, Size } from './geometry.ts';
+import type { Platform, PlatformNode } from './platform.ts';
+import type { Plane } from './plane.ts';
+import type { Series } from './series.ts';
+/** Numeric (not string) types so dispatch is a cheap `switch` and the event union discriminates on `type`. */
+export declare const EVENT_ATTACH = 1;
+export declare const EVENT_MEASURE = 2;
+export declare const EVENT_ARRANGE = 3;
+export declare const EVENT_PAINT = 4;
+export declare const EVENT_POINTER = 5;
+export declare const EVENT_HOVER = 6;
+export declare const EVENT_KEY = 7;
+export declare const EVENT_FOCUS = 8;
+/** What every event has. Concrete events are this plus the fields of their interface, copied on with Object.assign. */
+export declare class EventBase<T extends number = number> {
+    readonly type: T;
+    readonly target: AnyElement;
+    constructor(target: AnyElement);
+}
+export interface AttachEvent extends EventBase<typeof EVENT_ATTACH> {
+    readonly platform: Platform;
+}
+export interface MeasureEvent extends EventBase<typeof EVENT_MEASURE> {
+    readonly available: Size;
+    /** The element writes its answer here. Defaults to "needs nothing". */
+    request: LayoutRequest;
+}
+export interface ArrangeEvent extends EventBase<typeof EVENT_ARRANGE> {
+    readonly rect: Rect;
+}
+/** An element draws through its own surface, so the event carries nothing. */
+export interface PaintEvent extends EventBase<typeof EVENT_PAINT> {
+}
+export interface ChartPointerEvent extends EventBase<typeof EVENT_POINTER> {
+    readonly kind: 'move' | 'down' | 'up' | 'leave' | 'wheel' | 'pinch';
+    /** Coordinates in the receiving element's own space (a plane receives plot-area pixels). */
+    readonly x: number;
+    readonly y: number;
+    readonly buttons: number;
+    readonly deltaY: number;
+    /** Sideways wheel travel in pixels. */
+    readonly deltaX: number;
+    /** For `pinch`: the factor by which the fingers spread since the last event. 1 otherwise. */
+    readonly scale: number;
+    /** Which finger or device this is: 0 for a mouse. */
+    readonly id: number;
+    readonly pointerType: 'mouse' | 'touch' | 'pen';
+    /** The axis the pointer is over, for a plane: set where it is on the strip an axis takes beside the plot. Null over the plot and everywhere else. */
+    readonly axis: Axis | null;
+    /** True when the pointer is beside the plot (over an axis) and not on it. Elements that work on what is plotted ignore such events. */
+    readonly outside: boolean;
+    readonly shift: boolean;
+    readonly ctrl: boolean;
+    /** An element sets this when it used the input, which keeps the browser from also acting on it. */
+    handled: boolean;
+}
+export interface HoverEvent extends EventBase<typeof EVENT_HOVER> {
+    /** The plane the pointer is over (or has just left, when `x` is NaN). */
+    readonly plane: Plane;
+    /** The pointer in the plane's plot pixels; NaN once it has left. */
+    readonly x: number;
+    readonly y: number;
+    readonly buttons: number;
+}
+export interface ChartKeyEvent extends EventBase<typeof EVENT_KEY> {
+    readonly kind: 'down' | 'up';
+    /** The key as the browser names it (`KeyboardEvent.key`): 'ArrowLeft', 'Enter', ' ', '+'. */
+    readonly key: string;
+    readonly shift: boolean;
+    readonly ctrl: boolean;
+    readonly alt: boolean;
+    /** True for the repeats a held key sends after the first. */
+    readonly repeat: boolean;
+    /** The focused node, which an element with several focus targets tells apart. */
+    readonly node: PlatformNode;
+    handled: boolean;
+}
+export interface FocusEvent extends EventBase<typeof EVENT_FOCUS> {
+    readonly node: PlatformNode;
+    readonly focused: boolean;
+    /** True when focus should be shown: it came by keyboard, not by a click. */
+    readonly visible: boolean;
+}
+export type ChartEvent = AttachEvent | MeasureEvent | ArrangeEvent | PaintEvent | ChartPointerEvent | HoverEvent | ChartKeyEvent | FocusEvent;
+/** `Omit` applied to each member of a union, so the init of every event keeps its own fields. */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type ChartEventInit = DistributiveOmit<ChartEvent, keyof EventBase>;
+/** One allocation per event: the init fields are copied onto a fresh base, so subclasses add fields without classes. */
+export declare function makeEvent(init: ChartEventInit, target: AnyElement): ChartEvent;
+/**
+ * What a series reports when the pointer is near it. A hit is always one of the series' drawn points, whatever the
+ * `hit` mode measured the distance against: for a line it is the end of the nearest segment that is nearer.
+ */
+export interface Hit {
+    readonly series: Series;
+    readonly plane: Plane;
+    /** Index in the drawn points (the series' `points`). */
+    readonly index: number;
+    /**
+     * The point's row in the source's own storage, which stays the same when edits re-sort the points: edit by this.
+     * Absent when the drawn points are not the source's (a `Decimator` made them), so such a hit can be shown but not edited.
+     */
+    readonly row?: number;
+    /** The point's two coordinates in data terms: what the series' first and second axis read. */
+    readonly first: number;
+    readonly second: number;
+    /** Its bound channels' values, by name. */
+    readonly channels: Readonly<Record<string, number>>;
+    /** Where the point is drawn, in plot pixels. */
+    readonly px: number;
+    readonly py: number;
+    /**
+     * In a stack: how far the point is plotted from its own value (the layers below it), so a pointer's value less this
+     * is the layer's own. Absent outside a stack, and where the stack scales the values (normalized), which an edit cannot undo.
+     */
+    readonly lift?: number;
+    /** How far the pointer is, in pixels, by the series' `hit` mode (0 inside an area, and for an interpolated hit, which is on the line by construction). */
+    readonly distance: number;
+    /**
+     * Set on a hit made by `Series.interpolate`: `first` and `second` are a place on the line, not a point of the data,
+     * and `index` and `row` are those of the nearer of the two points it lies between.
+     */
+    readonly interpolated?: boolean;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,19 @@
+/** Numeric (not string) types so dispatch is a cheap `switch` and the event union discriminates on `type`. */
+export const EVENT_ATTACH = 1;
+export const EVENT_MEASURE = 2;
+export const EVENT_ARRANGE = 3;
+export const EVENT_PAINT = 4;
+export const EVENT_POINTER = 5;
+export const EVENT_HOVER = 6;
+export const EVENT_KEY = 7;
+export const EVENT_FOCUS = 8;
+/** What every event has. Concrete events are this plus the fields of their interface, copied on with Object.assign. */
+export class EventBase {
+    target;
+    constructor(target) { this.target = target; }
+}
+/** One allocation per event: the init fields are copied onto a fresh base, so subclasses add fields without classes. */
+export function makeEvent(init, target) {
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- the event is built up from a base and an `init` of the event type's fields, which the event union cannot express generically
+    return Object.assign(new EventBase(target), init);
+}

package/dist/focus.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Keyboard focus, shared by everything that can be reached with Tab: the ring that shows where focus is, and the keys a
+ * button answers to.
+ *
+ * An element that wants focus does three things: give a node a `tabindex` and tell the chart it owns it
+ * (`chart.focusable(this, node)`), draw the ring while it has focus (EVENT_FOCUS says when, and whether a ring is wanted:
+ * only for keyboard focus, as the browser's own controls do), and answer EVENT_KEY.
+ */
+import { type ChartKeyEvent } from './events.ts';
+import type { Rect } from './geometry.ts';
+import type { PlatformNode } from './platform.ts';
+import type { LineProps } from './theme.ts';
+import type { Surface } from './surface.ts';
+/** Draw the focus ring round `rect`, or take it away when `rect` is null. The `look` is the theme's `focusRing`. */
+export declare function drawFocusRing(surface: Surface, key: string, look: LineProps, rect: Rect | null, parent?: PlatformNode): void;
+/** Make a node a tab stop. The browser's own focus outline is turned off because the ring is drawn instead. */
+export declare function makeTabStop(surface: Surface, node: PlatformNode, order?: number): void;
+/**
+ * Whether a key event presses a button, as a browser's own button does: Enter on the way down, Space on the way up (so it can
+ * be cancelled by moving away, and the page does not scroll). The keys are marked handled, and a held key does not repeat.
+ */
+export declare function pressesButton(ev: ChartKeyEvent): boolean;

package/dist/focus.js

@@ -0,0 +1,51 @@
+/**
+ * Keyboard focus, shared by everything that can be reached with Tab: the ring that shows where focus is, and the keys a
+ * button answers to.
+ *
+ * An element that wants focus does three things: give a node a `tabindex` and tell the chart it owns it
+ * (`chart.focusable(this, node)`), draw the ring while it has focus (EVENT_FOCUS says when, and whether a ring is wanted:
+ * only for keyboard focus, as the browser's own controls do), and answer EVENT_KEY.
+ */
+import {} from './events.js';
+/** Room between the thing and its ring, in pixels. */
+const RING_GAP = 2;
+/** Draw the focus ring round `rect`, or take it away when `rect` is null. The `look` is the theme's `focusRing`. */
+export function drawFocusRing(surface, key, look, rect, parent) {
+    const ring = surface.node(key, 'rect', { above: true, ...(parent && { parent }) });
+    if (!rect) {
+        surface.set(ring, 'display', 'none');
+        return;
+    }
+    surface.set(ring, 'display', 'inline');
+    surface.set(ring, 'x', rect.x - RING_GAP);
+    surface.set(ring, 'y', rect.y - RING_GAP);
+    surface.set(ring, 'width', rect.width + 2 * RING_GAP);
+    surface.set(ring, 'height', rect.height + 2 * RING_GAP);
+    surface.set(ring, 'rx', 3);
+    surface.set(ring, 'fill', 'none');
+    surface.set(ring, 'stroke', look.color);
+    surface.set(ring, 'stroke-width', look.width);
+    surface.set(ring, 'pointer-events', 'none');
+}
+/** Make a node a tab stop. The browser's own focus outline is turned off because the ring is drawn instead. */
+export function makeTabStop(surface, node, order = 0) {
+    surface.set(node, 'tabindex', order);
+    surface.set(node, 'style', 'outline:none');
+}
+/**
+ * Whether a key event presses a button, as a browser's own button does: Enter on the way down, Space on the way up (so it can
+ * be cancelled by moving away, and the page does not scroll). The keys are marked handled, and a held key does not repeat.
+ */
+export function pressesButton(ev) {
+    if (ev.ctrl || ev.alt)
+        return false;
+    if (ev.key === 'Enter') {
+        ev.handled = true;
+        return ev.kind === 'down' && !ev.repeat;
+    }
+    if (ev.key === ' ' || ev.key === 'Spacebar') {
+        ev.handled = true;
+        return ev.kind === 'up';
+    }
+    return false;
+}

package/dist/furniture.d.ts

@@ -0,0 +1,70 @@
+import type { Chart } from './chart.ts';
+import type { Cursor, CursorChild } from './cursor.ts';
+import { type BaseAttributes, ChartElement } from './element.ts';
+import { type ChartEvent, type Hit } from './events.ts';
+/** What a `ChartTitle` is: the heading, the line under it, or the note at the foot. */
+export type TitleRole = 'title' | 'subtitle' | 'caption';
+export interface ChartTitleAttributes extends BaseAttributes {
+    /** The words. A '\n' starts another line. */
+    text: string;
+    /** What it is, which decides its look and (unless `side` says) where it goes. Default 'title'. */
+    role?: TitleRole;
+    /** The edge it spans. Default: the top, except for a caption, which goes at the bottom. */
+    side?: 'top' | 'bottom';
+}
+/**
+ * Text across the top or bottom of the chart. One element serves every role: a title, a subtitle, a caption or a
+ * footnote differ only in their `role` (and so their look) and `side`. Several on one edge stack outwards from it in the
+ * order they were added, so a title followed by a subtitle puts the subtitle underneath.
+ *
+ * Where the text sits along its band is the style property `align` (`style: { chartTitle: { align: 'middle' } }`).
+ */
+export declare class ChartTitle extends ChartElement<Chart, [], ChartTitleAttributes> {
+    #private;
+    static attrTypes: {
+        text: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    private get role();
+    private get side();
+    private get look();
+    onEvent(ev: ChartEvent): void;
+}
+export interface ChartTooltipAttributes extends BaseAttributes {
+    /**
+     * Whether the box moves with the cursor, with no arm, or is set beside what is read, with an arm to it. Default: moves with
+     * the cursor when the cursor is 'shared' (there is no one point to be beside), else set beside the point.
+     */
+    follow?: boolean;
+    /** A sample of the series (its line, box or marker, as drawn on the plot) before its name, or without one before its first line. Default false. */
+    swatch?: boolean;
+    /** The text for one hit. Default: the series name, then each coordinate (with its axis' title if it has one) and the channels. */
+    format?: (hit: Hit) => string;
+    /**
+     * Tell a screen reader what the box says when the cursor is moved by keyboard (see `Platform.announce`), so it can be read
+     * without seeing it. Default true. The text is the box's own, which this element does not translate: `format` words it.
+     */
+    announce?: boolean;
+}
+/**
+ * Shows what the cursor reads, in a box styled like a callout. It is a child of a `Cursor`, which finds the reading (the
+ * nearest point, or every series at the cursor's place) from the pointer or the keyboard; this only draws it, above whatever
+ * comes before it in the cursor, so put a `Crosshair` first to have the lines under the box. It takes no room of its own.
+ *
+ * It looks like a callout (`tooltipBox`, `tooltipText` and `tooltip` metrics, each falling back to the callout's own), so a
+ * theme that styles callouts styles tooltips too. Touch has no hover, so it shows while a finger is down. It hides while
+ * a button is held, which is when something is being dragged.
+ */
+export declare class ChartTooltip extends ChartElement<Cursor, [], ChartTooltipAttributes> implements CursorChild {
+    #private;
+    /** Moves with the cursor when it has no arm. */
+    get follows(): boolean;
+    onEvent(ev: ChartEvent): void;
+    private look;
+    private paint;
+}