inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/serialize.js

@@ -0,0 +1,321 @@
+/**
+ * Elements to and from plain JSON. Attributes are already plain data and children are ordered, so a tree maps directly to
+ * `{ type, attrs, children }`, which is what lets adapters, saved configs and an editor share one format.
+ *
+ *     const json = toJSON(chart, registry);              // JSON.stringify-able
+ *     const copy = fromJSON(json, registry);             // a new, unattached tree
+ *     applyJSON(chart, editedJson, registry);            // the same tree, changed to match
+ *
+ * The registry
+ * ────────────
+ * `type` is the name a class is registered under (`registry.ts` has all of the library's). An element is written under the
+ * name its exact class has, so a class of your own is one more entry: `{ ...registry, MyScale }`. Naming a class that is
+ * not in the registry is an error that says so, with the place in the tree.
+ *
+ * What an attribute may hold
+ * ──────────────────────────
+ *  - Plain data goes through as it is: strings, booleans, finite numbers, arrays, plain objects (themes, `style`, bindings).
+ *  - A number that is not finite (`NaN`, `Infinity`) is `{ "$number": "NaN" }`, since JSON has no such thing.
+ *  - A typed array is `{ "$typed": "Float64Array", "data": [...] }` with `null` for NaN, so a gap in the data survives.
+ *  - An element is its `id` (which is what every attribute that takes an element accepts), so it must have one.
+ *  - Anything else JSON cannot hold, which is chiefly code (a `format` function, an `onClick`) and big or live data (an
+ *    array of rows you go on editing), is `{ "$ref": "name" }`, and `name` is looked up in the `Refs` you give when reading.
+ *
+ * Refs
+ * ────
+ * A `Refs` is a table of names for objects and functions. Writing looks values up in it by identity, so a theme you named
+ * `lightTheme` is written as `{ "$ref": "lightTheme" }` rather than spelled out. With `auto: true` it names what it is
+ * asked about and does not know (`onFlush`, `format2`…), so any chart can be written; without it, an unnamed function is an
+ * error that tells you what to name. Arrays longer than `inlineLimit` (default 1000) count as data too and go by reference:
+ * that is the line between a chart's configuration and its data. Reading needs the same table.
+ *
+ * `applyJSON` changes a live tree to match edited JSON, in place: an attribute that already reads the same is left alone
+ * (so a ref'd array keeps its identity, and a decimator its cache), one that differs is set, one that is gone is removed, and
+ * children are matched by position and type, replaced if the type changed. It works out everything first and changes
+ * nothing if the JSON turns out to be unreadable, so a bad edit leaves the chart as it was.
+ */
+import { ChartElement, fail } from './element.js';
+/** Maps `type` names to classes, and back: an element is written under the name its class is registered by. */
+/** The text of anything thrown: a constructor or a refs lookup may throw a value that is not an Error. */
+const messageOf = (e) => e instanceof Error ? e.message : String(e);
+/** Names for objects and functions that JSON cannot hold, so that writing can point at them and reading can find them again. */
+export class Refs {
+    #byName = new Map();
+    #byValue = new Map();
+    /** Name whatever is asked about and not yet named, after the attribute it was found in. */
+    auto;
+    constructor(values = {}, options = {}) {
+        this.auto = options.auto ?? false;
+        for (const [name, value] of Object.entries(values))
+            this.set(name, value);
+    }
+    /** Name a value. The name must be free; a value that already has a name keeps it first and answers to both on reading. */
+    set(name, value) {
+        if (value === null || (typeof value !== 'object' && typeof value !== 'function'))
+            fail(`ref "${name}": only objects and functions can be named`);
+        if (this.#byName.has(name) && this.#byName.get(name) !== value)
+            fail(`ref "${name}" already names something else`);
+        this.#byName.set(name, value);
+        if (!this.#byValue.has(value))
+            this.#byValue.set(value, name);
+        return this;
+    }
+    has(name) { return this.#byName.has(name); }
+    get(name) {
+        if (!this.#byName.has(name))
+            fail(`no ref named "${name}"` + (this.#byName.size ? ` (known: ${[...this.#byName.keys()].slice(0, 12).join(', ')})` : ' (there are none)'));
+        return this.#byName.get(name);
+    }
+    /** The name a value goes by, if it has one. */
+    nameOf(value) { return this.#byValue.get(value); }
+    /** Give a value a name of its own, built on `hint` and made unique. Returns the one it has already, if so. */
+    adopt(value, hint = 'ref') {
+        const known = this.nameOf(value);
+        if (known !== undefined)
+            return known;
+        let name = hint, n = 1;
+        while (this.#byName.has(name))
+            name = hint + ++n;
+        this.set(name, value);
+        return name;
+    }
+    get names() { return [...this.#byName.keys()]; }
+}
+// ─── Names ───
+const names = new WeakMap();
+function nameOf(ctor, registry, path) {
+    let map = names.get(registry);
+    if (!map) {
+        map = new Map();
+        for (const [name, c] of Object.entries(registry))
+            if (!map.has(c))
+                map.set(c, name);
+        names.set(registry, map);
+    }
+    const name = map.get(ctor);
+    if (name === undefined)
+        fail(`${at(path)}${ctor.name || 'an anonymous class'} is not in the registry: add it, as in { ...registry, ${ctor.name || 'Mine'} }`);
+    return name;
+}
+const at = (path) => (path ? `${path}: ` : '');
+// ─── Writing ───
+const TYPED = ['Float64Array', 'Float32Array', 'Int8Array', 'Int16Array', 'Int32Array', 'Uint8Array', 'Uint16Array', 'Uint32Array', 'Uint8ClampedArray'];
+/** What a value is called when it is the attribute `path` names, for a ref that has to be made up. */
+const hintOf = (path) => /([A-Za-z_]\w*)(?:\[\d+\])*$/.exec(path)?.[1] ?? 'ref';
+function byReference(value, path, w, what) {
+    if (w.refs?.auto)
+        return { $ref: w.refs.adopt(value, hintOf(path)) };
+    fail(`${at(path)}${what}, which JSON cannot hold: name it in \`refs\` (a Refs with \`auto: true\` names whatever it meets)`);
+}
+function encode(v, path, w) {
+    if (v !== null && (typeof v === 'object' || typeof v === 'function')) {
+        const named = w.refs?.nameOf(v);
+        if (named !== undefined)
+            return { $ref: named };
+    }
+    switch (typeof v) {
+        case 'string':
+        case 'boolean': return v;
+        case 'number': return Number.isFinite(v) ? v : { $number: String(v) };
+        case 'undefined': return null;
+        case 'function': return byReference(v, path, w, 'a function');
+        case 'bigint':
+        case 'symbol': return fail(`${at(path)}a ${typeof v} cannot be written as JSON`);
+    }
+    if (v === null)
+        return null;
+    if (v instanceof ChartElement) {
+        const id = v.attrs.id;
+        if (typeof id !== 'string')
+            fail(`${at(path)}refers to a ${v.constructor.name} that has no id: give it one so JSON can name it`);
+        return id;
+    }
+    if (ArrayBuffer.isView(v)) {
+        const type = v.constructor.name, a = v;
+        if (!TYPED.includes(type))
+            return byReference(v, path, w, `a ${type}`);
+        if (a.length > w.limit)
+            return byReference(v, path, w, `${type} of ${a.length} numbers (the inline limit is ${w.limit})`);
+        return { $typed: type, data: Array.from(a, (n) => (Number.isFinite(n) ? n : n !== n ? null : String(n))) };
+    }
+    if (Array.isArray(v)) {
+        if (v.length > w.limit)
+            return byReference(v, path, w, `an array of ${v.length} values (the inline limit is ${w.limit})`);
+        return v.map((x, i) => encode(x, `${path}[${i}]`, w));
+    }
+    const object = v, proto = Object.getPrototypeOf(object);
+    if (proto === Object.prototype || proto === null) {
+        const out = {};
+        for (const key of Object.keys(object)) {
+            const x = object[key];
+            if (x === undefined)
+                continue;
+            if (key.startsWith('$'))
+                fail(`${at(path)}the key "${key}" is reserved: JSON marks references and special values with a leading $`);
+            out[key] = encode(x, path ? `${path}.${key}` : key, w);
+        }
+        return out;
+    }
+    return byReference(v, path, w, `a ${v.constructor?.name ?? 'object'}`);
+}
+function write(element, path, w) {
+    const json = { type: nameOf(element.constructor, w.registry, path) };
+    const attrs = {};
+    for (const key of Object.keys(element.attrs)) {
+        const value = element.attrs[key];
+        if (value !== undefined)
+            attrs[key] = encode(value, `${path ? path + '.' : ''}attrs.${key}`, w);
+    }
+    if (Object.keys(attrs).length)
+        json.attrs = attrs;
+    const children = [...element].map((c, i) => write(c, `${path ? path + '.' : ''}children[${i}]`, w));
+    if (children.length)
+        json.children = children;
+    return json;
+}
+/** An element and everything below it as JSON. See the top of this file for what an attribute may hold. */
+export function toJSON(element, registry, options = {}) {
+    return write(element, '', { registry, refs: options.refs, limit: options.inlineLimit ?? 1000 });
+}
+// ─── Reading ───
+function decode(v, path, refs) {
+    if (Array.isArray(v))
+        return v.map((x, i) => decode(x, `${path}[${i}]`, refs));
+    if (v === null || typeof v !== 'object')
+        return v;
+    const o = v;
+    if ('$ref' in o) {
+        if (typeof o.$ref !== 'string')
+            fail(`${at(path)}a $ref has to be the name of a ref`);
+        if (!refs)
+            fail(`${at(path)}refers to "${o.$ref}", and no refs were given to look it up in`);
+        try {
+            return refs.get(o.$ref);
+        }
+        catch (e) {
+            return fail(`${at(path)}${messageOf(e)}`);
+        }
+    }
+    if ('$number' in o) {
+        const n = { NaN, Infinity, '-Infinity': -Infinity }[String(o.$number)];
+        if (n === undefined)
+            fail(`${at(path)}$number has to be "NaN", "Infinity" or "-Infinity"`);
+        return n;
+    }
+    if ('$typed' in o) {
+        const type = String(o.$typed);
+        if (!TYPED.includes(type) || !Array.isArray(o.data))
+            fail(`${at(path)}a $typed value is { "$typed": one of ${TYPED.join(', ')}, "data": [numbers] }`);
+        // 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 Ctor = globalThis[type];
+        return new Ctor(o.data.map((n) => (n === null ? NaN : n === 'Infinity' ? Infinity : n === '-Infinity' ? -Infinity : n)));
+    }
+    const out = {};
+    for (const key of Object.keys(o)) {
+        if (key.startsWith('$'))
+            fail(`${at(path)}unknown marker "${key}"`);
+        out[key] = decode(o[key], path ? `${path}.${key}` : key, refs);
+    }
+    return out;
+}
+function lookup(type, registry, path) {
+    if (typeof type !== 'string')
+        fail(`${at(path)}every element needs a "type", the name of a class`);
+    if (!Object.hasOwn(registry, type)) {
+        const near = Object.keys(registry).filter((n) => n.toLowerCase().includes(type.toLowerCase()) || type.toLowerCase().includes(n.toLowerCase()));
+        fail(`${at(path)}unknown type "${type}"` + (near.length ? ` (did you mean ${near.slice(0, 4).join(', ')}?)` : ` (the registry has ${Object.keys(registry).length} types)`));
+    }
+    // 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
+    return registry[type];
+}
+function build(json, registry, refs, path) {
+    if (json === null || typeof json !== 'object')
+        fail(`${at(path)}an element is an object { type, attrs?, children? }`);
+    const Ctor = lookup(json.type, registry, path);
+    const attrs = json.attrs === undefined ? {} : decode(json.attrs, `${path ? path + '.' : ''}attrs`, refs);
+    if (attrs === null || typeof attrs !== 'object' || Array.isArray(attrs))
+        fail(`${at(path)}"attrs" has to be an object`);
+    if (json.children !== undefined && !Array.isArray(json.children))
+        fail(`${at(path)}"children" has to be an array`);
+    const children = (json.children ?? []).map((c, i) => build(c, registry, refs, `${path ? path + '.' : ''}children[${i}]`));
+    try {
+        return new Ctor(attrs, ...children);
+    }
+    catch (e) {
+        return fail(`${at(path)}${json.type}: ${messageOf(e)}`);
+    }
+}
+/** A new, unattached element tree from JSON. `refs` is where the `$ref`s are found. */
+export function fromJSON(json, registry, options = {}) {
+    return build(json, registry, options.refs, '');
+}
+// ─── Changing a live tree ───
+/** Deep equality of two JSON values, however their keys are ordered. */
+function same(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length)
+        return false;
+    return ka.every((k) => Object.hasOwn(b, k) && same(a[k], b[k]));
+}
+function plan(el, json, path, w, ops) {
+    const here = path ? path + '.' : '';
+    const want = json.attrs === undefined ? {} : decode(json.attrs, `${here}attrs`, w.refs);
+    const wantJson = json.attrs ?? {}, have = el.attrs, patch = {};
+    let changed = false;
+    for (const key of Object.keys(wantJson)) {
+        // Compare in JSON form, so an inline value that is unchanged is not replaced by a fresh copy of itself.
+        const now = have[key] === undefined ? undefined : encode(have[key], `${here}attrs.${key}`, w);
+        if (now !== undefined && same(now, wantJson[key]))
+            continue;
+        patch[key] = want[key];
+        changed = true;
+    }
+    for (const key of Object.keys(have))
+        if (have[key] !== undefined && !Object.hasOwn(wantJson, key)) {
+            patch[key] = undefined;
+            changed = true;
+        }
+    if (changed)
+        ops.push(() => el.setAttributes(patch));
+    const kids = [...el], wanted = json.children ?? [];
+    if (!Array.isArray(wanted))
+        fail(`${at(path)}"children" has to be an array`);
+    wanted.forEach((child, i) => {
+        const at = `${here}children[${i}]`, existing = kids[i];
+        if (existing && typeof child === 'object' && child && nameOf(existing.constructor, w.registry, at) === child.type) {
+            plan(existing, child, at, w, ops);
+            return;
+        }
+        const fresh = build(child, w.registry, w.refs, at);
+        if (existing)
+            ops.push(() => { el.insertBefore(fresh, existing); el.remove(existing); });
+        else
+            ops.push(() => el.insertBefore(fresh, null));
+    });
+    // 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 = wanted.length; i < kids.length; i++) {
+        const gone = kids[i];
+        ops.push(() => el.remove(gone));
+    }
+}
+/**
+ * Change a live tree to match JSON, in place, so state it holds (a zoom, a data source's identity) is kept wherever the JSON
+ * does not say otherwise. Nothing is changed unless all of the JSON reads; the root's type has to be the same.
+ */
+export function applyJSON(element, json, registry, options = {}) {
+    const w = { registry, refs: options.refs, limit: options.inlineLimit ?? 1000 };
+    if (json === null || typeof json !== 'object')
+        fail('an element is an object { type, attrs?, children? }');
+    if (nameOf(element.constructor, registry, '') !== json.type)
+        fail(`the root is a ${element.constructor.name}: JSON for a "${String(json.type)}" cannot be applied to it`);
+    const ops = [];
+    plan(element, json, '', w, ops);
+    for (const op of ops)
+        op();
+}

package/dist/series.d.ts

@@ -0,0 +1,304 @@
+import { Axis } from './axis.ts';
+import { type DataNode, type PlanContext, type PointBuffer } from './data.ts';
+import { type AnyElement, type BaseAttributes, ChartElement, type ElementRef } from './element.ts';
+import { type ChartEvent } from './events.ts';
+import type { Extent, Size } from './geometry.ts';
+import type { Plane } from './plane.ts';
+import type { PlatformNode } from './platform.ts';
+import type { Surface } from './surface.ts';
+import { type AnySeriesRenderer, type PolygonSet, type Trace } from './renderer.ts';
+import type { HitOptions, HitMode } from './hit.ts';
+export interface SeriesAttributes extends BaseAttributes {
+    /** What the series is called where it is named: a tooltip's heading. */
+    name?: string;
+    /**
+     * How pointer hits find this series: a mode name, options, or `false` for a series that should never be hit (a
+     * selection overlay, a reference line). Only the series knows what its renderers draw, so this is set here and not
+     * guessed: a line series that should be grabbable anywhere along the line says `'line'`, a filled one `'area'`.
+     */
+    hit?: false | HitMode | HitOptions;
+    /**
+     * What a missing value (NaN, or infinite) means. 'break' (default): nothing is there, so a line stops and starts again
+     * and an area splits. 'connect': the line goes straight across to the next value there is. 'zero': the value is 0 (and
+     * the axis reaches it). Markers and bars draw nothing at a gap whichever; and the readings of a tooltip and a drag
+     * stay the data's own. In a `Stack`, 'zero' is not applied: a gap there leaves its layer out.
+     */
+    gaps?: 'break' | 'connect' | 'zero';
+}
+/**
+ * Where a `Stack` puts one of its series: the value each row starts from and the one it is plotted at, in the value
+ * axis' own units, and which place it takes beside the others when they sit side by side. Rows line up with the series'
+ * own rows. `additive` says the plotted value is the series' own plus a shift, so an edit can be undone back to the own.
+ */
+export interface StackLayer {
+    readonly base: Float64Array;
+    readonly top: Float64Array;
+    readonly slot: {
+        readonly index: number;
+        readonly count: number;
+    };
+    readonly additive: boolean;
+    /** The extent of everything the stack plots in the value axis' units, for what is limited by the data's extent. */
+    readonly extent: Extent | null;
+}
+/** The rows a series draws from: its own fill, or what a stack made of them to line them up with the others. */
+export interface Rows {
+    readonly raw: Float64Array;
+    readonly count: number;
+    readonly stride: number;
+    readonly rowOf: ((index: number) => number) | null;
+}
+/** A plane child that holds series of its own (a `Stack`): the plane sees through it, and hands it their loading. */
+export interface SeriesGroup {
+    readonly members: readonly Series[];
+    load(estimate: Size): void;
+}
+/** A plane child that holds series of its own (a stack), or null. Recognised by what it offers, so this file need not import every kind of group. */
+export declare function groupOf(child: unknown): (SeriesGroup & AnyElement) | null;
+/** The series a plane child stands for: itself, the members of a group, or none. */
+export declare function seriesOf(child: unknown): readonly Series[];
+/** One data source, then any number of renderers. */
+export type SeriesChildren<Channel extends string = string> = [data: DataNode<Channel>, ...renderers: AnySeriesRenderer[]];
+/**
+ * What `Series.drawn` hands out: the plane, the points in plot pixels (`points`), and the data values they were made
+ * from (`raw`, `stride` numbers to a row, the two coordinates at `firstColumn` and `secondColumn`, the bound channels
+ * last, in the order of `channels`). `rowOf` names the source row of a drawn point, when they are the source's.
+ */
+export interface Drawn {
+    readonly plane: Plane;
+    readonly points: Readonly<PointBuffer>;
+    readonly raw: Float64Array;
+    readonly stride: number;
+    readonly firstColumn: number;
+    readonly secondColumn: number;
+    readonly channels: readonly string[];
+    readonly rowOf: ((index: number) => number) | null;
+    readonly alongDomain: boolean;
+    /** In a stack: where each row starts and is plotted, and the series' place beside the others. Null otherwise. */
+    readonly base: Float64Array | null;
+    readonly top: Float64Array | null;
+    readonly slot: {
+        readonly index: number;
+        readonly count: number;
+    };
+    /** The plotted value is the own value plus a shift (see `StackLayer`). */
+    readonly additive: boolean;
+}
+/** The shared pipeline: raw fill (cached), column gather, normalise, place. Subclasses say which columns and axes. */
+export declare abstract class Series<A extends SeriesAttributes = SeriesAttributes, Channel extends string = string> extends ChartElement<Plane | (SeriesGroup & AnyElement), SeriesChildren<Channel>, A> {
+    #private;
+    static attrTypes: {
+        name: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** The plane this series is drawn on, which is its parent unless a stack sits between them. */
+    get plane(): Plane;
+    /** The rows drawn from: a stack's lined-up table when it made one, else the series' own fill. */
+    protected rows(): Rows;
+    /** Engine protocol for a `Stack`: the series' own fill as it stands (call after `prepare`). */
+    ownRows(): Rows;
+    /** Engine protocol for a `Stack`: take a place in a stack, with rows lined up to its others'. Null for both leaves it. */
+    join(layer: StackLayer | null, rows: Rows | null): void;
+    /** What a stack has made of this series, if it is in one. */
+    get layer(): StackLayer | null;
+    get data(): DataNode<Channel>;
+    /**
+     * Every channel its renderers bind or ask for (`channelNames`): what a renderer can ask for by name. In `points` they follow the two coordinates
+     * in this order, so a channel's column is `2 + channels.indexOf(name)`.
+     */
+    get channels(): readonly string[];
+    /**
+     * The colour this series takes from the theme's palette: by its position among the plane's series, round again when
+     * there are more series than colours. It is only a default: a renderer's own colour attribute or any `style` beats it.
+     */
+    get accentColor(): string;
+    /** Whether the series is on show: `visible` is not false. One that is not takes no part: it is not drawn, does not set the axes' ranges, and is not hit. */
+    get shown(): boolean;
+    /**
+     * Draw a sample of what this series looks like into `parent`, `width` by `height` from its top left corner: each renderer's
+     * own sample (a line, a box, a marker), one over another in drawing order, in the look the renderer resolves from the
+     * theme and its attributes. A legend and a tooltip use it. Nodes are keyed `key/…` in `surface`.
+     */
+    sample(surface: Surface, parent: PlatformNode, key: string, width: number, height: number): void;
+    /**
+     * The colour that stands for this series: what its first renderer says (its line, its fill, a marker's colour),
+     * else the palette colour. A key or tooltip shows it beside the name.
+     */
+    get color(): string;
+    /** What the first renderer that has an opinion says a hit on this series should measure: bars say the shapes they draw. */
+    get hitHint(): HitMode | undefined;
+    /** The shapes the series draws, as polygons in plot pixels, if a renderer draws any (bars): what a 'shape' hit is inside. */
+    shapes(): PolygonSet | null;
+    /** The path the series' renderer draws, if it draws other than straight lines through the points (steps, curves): what a line hit or a reading follows. */
+    trace(): Trace | null;
+    /** How many times the series has been projected: a renderer that works something out from the points can tell whether they have changed. */
+    get projection(): number;
+    /** The last projected points, in plot pixels: `[first, second, ...channels]` in each row of `points.stride` numbers. */
+    get points(): Readonly<PointBuffer>;
+    onEvent(ev: ChartEvent): void;
+    /**
+     * The last projection, as the series holds it, for what reads a drawn series back: hit testing (hit.ts), which is
+     * kept out of the series so that a chart that never hit-tests does not carry it. Null before the first projection.
+     */
+    get drawn(): Drawn | null;
+    /** Whether the first coordinate is a position along the line, so that a value can be read between two points. */
+    protected get alongDomain(): boolean;
+    /** The axis the first coordinate rides on, which a plane places along its first role. */
+    abstract get firstAxis(): Axis;
+    /** The axis the second coordinate rides on. */
+    abstract get secondAxis(): Axis;
+    /** Which column of the data (domain 0, value 1, channels from 2) is the first coordinate. */
+    protected abstract get firstColumn(): number;
+    /** Which column of the data is the second coordinate. */
+    protected abstract get secondColumn(): number;
+    /** Pick the axes, from attributes or else the plane's. */
+    abstract resolveAxes(plane: Plane): void;
+    /** Report what is known of the domain before any data is read, so that fills can depend on it. */
+    abstract contributeDomain(): void;
+    /** Settle whatever `contributeDomain` fed, once every series has contributed. */
+    abstract resolveDomain(): void;
+    /** Read the data, and report every extent it has to the axes. `estimate` is the room the plot is expected to have. */
+    abstract load(estimate: Size): void;
+    /** The extent all of the data asks of an axis, not the part in view: what zooming is limited by. Null if it uses none of it. */
+    abstract extentFor(axis: Axis): Extent | null;
+    /**
+     * Fill the raw buffer, or reuse it when nothing it depends on has changed. Returns every column's extent: the
+     * domain, the value, then each requested channel.
+     */
+    protected fill(ctx: PlanContext): readonly Extent[];
+    /**
+     * Ask both axes for the room the renderers draw beyond the places of the points (a marker's radius), before the ranges
+     * are settled. It is pixels, which an axis turns into data by its length.
+     */
+    protected contributeReach(): void;
+    /** The largest `spans` of the renderers: how far they draw beyond a point along the domain, as a fraction of the gap between points. */
+    protected get spans(): number;
+    /**
+     * Widen the range of every mapped dimension a renderer binds to cover the whole of its channel. This is the whole
+     * of the data and not the part in view, so colours and sizes stay put while you zoom.
+     */
+    protected contributeChannels(): void;
+    /** The rows as a renderer's `spread` sees them. */
+    private spreadView;
+    /** The extent the data alone asks of the first (`'first'`) or second axis, over all of it: no renderer's spread in it. */
+    abstract ownExtent(role: 'first' | 'second'): Extent | null;
+    /** An axis' natural extent: the data's, widened by what the renderers draw beyond it. Zooming is held to this. */
+    protected widened(axis: Axis, base: Extent | null): Extent | null;
+    /**
+     * Normalize and place into plot pixels. The raw buffer is left alone, so a re-projection needs no refill.
+     * The result is `[first, second, ...bound channels]` whatever order the data held them in.
+     */
+    project(plane: Plane): void;
+    /**
+     * The line the series is measured from, as placed points: one for each drawn point, in the same place along the first
+     * coordinate, with the second held at `value` (kept inside its axis' range). Gaps stay gaps. The plane places it
+     * exactly as it places the data, so a renderer that fills between the two needs to know nothing about the plane:
+     * the data forward and this backward is a closed shape on a rectangle and on a circle alike.
+     */
+    baseline(value: number): Readonly<PointBuffer>;
+}
+export interface DomainSeriesAttributes extends SeriesAttributes {
+    /** Default: the plane's first axis (a Cartesian plane's horizontal one, a polar plane's angle). */
+    domainAxis?: ElementRef<Axis>;
+    /** Default: the plane's second axis (the vertical one, the radius). */
+    valueAxis?: ElementRef<Axis>;
+}
+/**
+ * A value at every position along a domain, drawn against two axes. The source delivers ascending in the domain and only
+ * the visible part is read, so a view that zooms in refills from the full data, and the value axis fits what is in view.
+ */
+export declare class DomainSeries extends Series<DomainSeriesAttributes> {
+    #private;
+    static attrTypes: {
+        name: 1;
+        domainAxis: 1;
+        valueAxis: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    get domainAxis(): Axis;
+    get valueAxis(): Axis;
+    get firstAxis(): Axis;
+    get secondAxis(): Axis;
+    protected get firstColumn(): number;
+    protected get secondColumn(): number;
+    protected get alongDomain(): boolean;
+    resolveAxes(plane: Plane): void;
+    contributeDomain(): void;
+    resolveDomain(): void;
+    load(estimate: Size): void;
+    /** Engine protocol for a `Stack`: read the data (the first half of `load`) and give the rows, leaving the extents to the stack. */
+    prepare(estimate: Size): Rows;
+    /** Engine protocol for a `Stack`: the rest of `load`, with the value extent the stack worked out for its stacked values. */
+    settle(extent: Extent | null): void;
+    ownExtent(role: 'first' | 'second'): Extent | null;
+    extentFor(axis: Axis): Extent | null;
+}
+export interface XYSeriesAttributes<Channel extends string = string> extends SeriesAttributes {
+    /**
+     * The channel of the source that is x. The source's `value` is y, and its domain is only the order the points are
+     * drawn in. The type checker confirms the source offers this channel when its channels are spelled out.
+     */
+    x: Channel;
+    /** Default: the plane's first axis (a Cartesian plane's horizontal one). */
+    xAxis?: ElementRef<Axis>;
+    /** Default: the plane's second axis (the vertical one). */
+    yAxis?: ElementRef<Axis>;
+}
+/**
+ * Two values per point, one on each axis, joined in the order the source holds them: a scatter, a trajectory, a loop.
+ *
+ * The source's domain is only the sequence (leave `domain` out and it is the row's index), and its `value` is y. x
+ * is a channel, named by the `x` attribute. Because order is all the domain means:
+ *  - every point is always read, whatever the view: there is nothing to window by;
+ *  - a `Decimator` refuses it, since kernels thin by pixel column of the domain; draw it undecimated (markers already
+ *    leave out what is off the plot);
+ *  - an axis fits all the data, and zooming one axis does not refit the other to the points in view: with no order
+ *    along x, finding those would be a scan of every point on every change.
+ */
+export declare class XYSeries<Channel extends string = string> extends Series<XYSeriesAttributes<Channel>, Channel> {
+    #private;
+    static attrTypes: {
+        name: 1;
+        xAxis: 1;
+        yAxis: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    get xAxis(): Axis;
+    get yAxis(): Axis;
+    get firstAxis(): Axis;
+    get secondAxis(): Axis;
+    protected get firstColumn(): number;
+    protected get secondColumn(): number;
+    resolveAxes(plane: Plane): void;
+    contributeDomain(): void;
+    resolveDomain(): void;
+    load(estimate: Size): void;
+    ownExtent(role: 'first' | 'second'): Extent | null;
+    extentFor(axis: Axis): Extent | null;
+}
+/** What `paintSample` remembers of each group it draws: whose sample it holds and of how many renderers. */
+export type SampleCache = Map<string, {
+    series: Series;
+    renderers: number;
+}>;
+/**
+ * A sample of `series` in a group of `surface` keyed `key`, set at (x, y), `width` by `height`. A group that last held another
+ * series (a tooltip line that now reads another one) is made afresh, so nothing of the old one is left; `cache` is what the
+ * caller keeps between calls. Returns the group, for what the caller wants to do to it (dim it).
+ */
+export declare function paintSample(surface: Surface, key: string, series: Series, x: number, y: number, width: number, height: number, cache: SampleCache): PlatformNode;