inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/renderer.js

@@ -0,0 +1,164 @@
+/**
+ * Series renderers: turn placed points into platform nodes.
+ *
+ * A renderer is a child of a series and is handed that series' projected points (plot pixels) on PAINT. It knows nothing
+ * of axes, planes or data: that is why one renderer works unchanged on a rectangle, a circle or a radar. Renderers that
+ * vary a look by data (markers) declare `bindings`, which the series reads to know which channels to request; the
+ * values themselves come from `MappedDimension`s (colour and size axes).
+ *
+ * Defaults come from the theme (see theme.ts); the attributes `stroke`, `strokeWidth`, `fill` and `opacity` are the same
+ * properties set directly. The colour a series gets from the palette is the lowest-priority default for its colour.
+ *
+ * A point that is NaN or infinite in either coordinate is a gap. `Number.isFinite` tests for it (it is as fast as
+ * any hand-rolled compare in V8, measured), so the hot loops use it.
+ */
+import { STRING, NUMBER } from './attrs.js';
+import { Curve } from './curve.js';
+import { ChartElement } from './element.js';
+import { EVENT_PAINT } from './events.js';
+import { notImplemented } from './stub.js';
+/** Draws a series' projected points into its own surface. */
+export class SeriesRenderer extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, fill: STRING, maxNodes: NUMBER, stroke: STRING, strokeWidth: NUMBER };
+    /**
+     * The one colour that stands for what this draws, for a key or a tooltip to show beside the series' name: its line, its
+     * fill. Null when it has none (the colour is bound to data, so there is not one).
+     */
+    get swatch() { return null; }
+    /**
+     * Draw a sample of what this draws into `parent` (a node of `surface`, the caller's), in a box `width` by `height` from
+     * its own top left corner: a short line for a line, a box for an area or bars, one marker for markers. It takes the look
+     * the renderer would draw with (theme, attributes, dashes), so a legend or a tooltip shows what is on the plot. Several
+     * renderers on a series draw their samples one over another. Nodes are keyed `key…` in `surface`. Default: a box of the
+     * `swatch` colour, or nothing for a renderer that has none.
+     */
+    sample(surface, parent, key, width, height) {
+        const colour = this.swatch;
+        if (!colour || colour === 'none') {
+            surface.remove(key);
+            return;
+        }
+        const n = surface.node(key, 'path', { parent });
+        surface.set(n, 'd', `M0 0H${width}V${height}H0Z`);
+        surface.set(n, 'fill', colour);
+        surface.set(n, 'stroke', 'none');
+    }
+    /** Values this renderer needs the value axis to reach whatever the data says: the baseline bars grow from. Default none. */
+    get includes() { return []; }
+    /**
+     * Pixels this draws beyond the places of its points (a marker's radius), which the axes leave room for so that a mark
+     * on the end of the data is not cut by the edge of the plot. Default 0.
+     */
+    get reach() { return 0; }
+    /** Half the width of what this draws along the domain, as a fraction of the gap between neighbouring points (bars), which the domain axis leaves room for. Default 0. */
+    get spans() { return 0; }
+    /** What a pointer hit on the series should measure by default, if this renderer knows: bars say 'shape'. Default no opinion. */
+    get hitMode() { return undefined; }
+    /**
+     * Channels of the data this needs as plain numbers beside each point (error bars: how far each value may be out), with no mapped
+     * axis to turn them into anything. The series requests them with the bound ones; in `points` they follow the two coordinates,
+     * raw, in the order of `Series.channels`. Default none.
+     */
+    get channelNames() { return []; }
+    /** Nothing is bound until bindings are written; a renderer that has some will report them here. */
+    get bindings() { return []; }
+    /** Buckets per stylistic binding, from `maxNodes`. 0 when nothing is stylistically bound. */
+    get stepsPerBinding() { return 0; }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_PAINT:
+                if (this.requireParent().shown)
+                    this.draw(this.requireParent().points);
+                break;
+        }
+    }
+}
+/** A box in the look of a filled shape: what an area and a bar are in a legend. */
+export function paintBox(s, parent, key, width, height, look) {
+    const n = s.node(key, 'path', { parent });
+    s.set(n, 'd', `M0 0H${width}V${height}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);
+    s.set(n, 'stroke-linejoin', 'round');
+}
+/**
+ * One path through the points, in the way its `Curve` says: straight lines (`LinearCurve`), a spline, steps. A gap in the
+ * data lifts the pen, or is crossed if the series says its `gaps` are 'connect'.
+ */
+export class LinePath extends SeriesRenderer {
+    /** How the points are joined. */
+    get curve() { return this.child(0, Curve); }
+    /** The series' palette colour is the default; a dash pattern is style only (`style: { seriesLine: { dash } }`). */
+    look() {
+        const a = this.attrs;
+        return this.styleFor(['seriesLine', 'line'], { color: a.stroke, width: a.strokeWidth, opacity: a.opacity }, { color: this.requireParent().accentColor });
+    }
+    get swatch() { return this.look().color; }
+    trace() { return this.curve.trace(this.requireParent(), null); }
+    sample(s, parent, key, width, height) {
+        const look = this.look(), n = s.node(key, 'path', { parent });
+        s.set(n, 'd', `M0 ${height / 2}H${width}`);
+        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);
+        s.set(n, 'stroke-dasharray', look.dash);
+    }
+    draw() {
+        const counters = this.counters, s = this.surface, a = this.attrs;
+        if (a.bind)
+            notImplemented('LinePath bindings');
+        const look = this.look();
+        const t0 = performance.now();
+        const d = this.curve.line(this.requireParent());
+        counters.stages.path += performance.now() - t0;
+        counters.pathBytes += d.length;
+        const n = s.node('line', '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-linejoin', 'round');
+        s.set(n, 'stroke-linecap', 'round');
+        s.set(n, 'opacity', look.opacity);
+        s.set(n, 'stroke-dasharray', look.dash);
+    }
+}
+/**
+ * The region between a line and a baseline, the line drawn in the way its `Curve` says. It is the data forward and the
+ * baseline backward, closed: the baseline is placed by the plane exactly as the data is, so on a rectangle this is the
+ * usual area under a line, and on a PolarPlane it is the ring or wedge between the curve and the baseline circle, with
+ * nothing here to say so. A gap in the data splits it into separate shapes. Outlines are off by default; give a `stroke`
+ * to draw one.
+ */
+export class AreaPath extends SeriesRenderer {
+    /** How the points are joined. */
+    get curve() { return this.child(0, Curve); }
+    look() {
+        const a = this.attrs;
+        return this.styleFor(['seriesArea', 'shape'], { fill: a.fill, stroke: a.stroke, strokeWidth: a.strokeWidth, opacity: a.opacity }, { fill: this.requireParent().accentColor });
+    }
+    get swatch() { return this.look().fill; }
+    trace() { return this.curve.trace(this.requireParent(), this.attrs.baseline ?? 0); }
+    sample(s, parent, key, width, height) { paintBox(s, parent, key, width, height, this.look()); }
+    draw() {
+        const counters = this.counters, s = this.surface, a = this.attrs;
+        if (a.bind)
+            notImplemented('AreaPath bindings');
+        const look = this.look();
+        const t0 = performance.now();
+        const d = this.curve.area(this.requireParent(), a.baseline ?? 0);
+        counters.stages.path += performance.now() - t0;
+        counters.pathBytes += d.length;
+        const n = s.node('area', '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/scale.d.ts

@@ -0,0 +1,37 @@
+/** The base of scales, which map a data range to 0..1 and back, and choose tick values. The scales themselves are in scales.ts. */
+import type { Dimension } from './dimension.ts';
+import { type BaseAttributes, ChartElement } from './element.ts';
+import type { Extent } from './geometry.ts';
+/** Shared with scales.ts. Trims binary noise (0.1 + 0.2) so tick values and labels come out as the decimals a person expects. */
+export declare const clean: (v: number) => number;
+/** Rounds a raw step up to 1, 2, 5 or 10 times a power of ten: the steps people read easily. The cut-offs favour fewer, rounder ticks. */
+export declare function niceStep(raw: number): number;
+/** No options of its own; subclasses add their parameters (a log base). */
+export interface ScaleAttributes extends BaseAttributes {
+}
+/**
+ * The maths of a dimension, as an element: the first (and only) child of an axis. Parameters are attributes,
+ * so a scale serializes like anything else, and a new transform is a new class with no change to axes.
+ */
+export declare abstract class Scale<A extends ScaleAttributes = ScaleAttributes> extends ChartElement<Dimension, [], A> {
+    /** Value to 0..1, in place over an interleaved buffer. Invalid input (log of a non-positive) becomes NaN. */
+    abstract normalize(buffer: Float64Array, count: number, stride: number, offset: number, range: Extent): void;
+    /** The inverse of `normalize` for one value: how pointer positions become data values. */
+    abstract denormalize(fraction: number, range: Extent): number;
+    /** Replaces ends the scale cannot represent (a log range reaching zero). */
+    abstract constrain(range: Extent): Extent;
+    /** Pull a raw range out to tidy ends. */
+    abstract nice(range: Extent): Extent;
+    /** Tick values inside the range, about `count` of them. */
+    abstract ticks(range: Extent, count: number): readonly number[];
+    /** True when equal steps in the data are equal steps along the axis, so a straight line in data is straight on the page. */
+    get isLinear(): boolean;
+    /** The text for a tick, when the scale knows better than a number does (a category name). Default: the axis formats the number. */
+    label?(value: number): string | undefined;
+    /**
+     * The labels for a whole set of ticks, when what a tick should say depends on the others (a time scale writes a new day
+     * as "Jun 11" and the minutes in it as "22:10"). Gets the values the axis chose, whoever chose them, in order. Beats `label` for ticks; an
+     * axis's own `format` beats both.
+     */
+    labels?(values: readonly number[], range: Extent): readonly string[];
+}

package/dist/scale.js

@@ -0,0 +1,19 @@
+import { ChartElement } from './element.js';
+/** Shared with scales.ts. Trims binary noise (0.1 + 0.2) so tick values and labels come out as the decimals a person expects. */
+export const clean = (v) => Number(v.toPrecision(12));
+/** Rounds a raw step up to 1, 2, 5 or 10 times a power of ten: the steps people read easily. The cut-offs favour fewer, rounder ticks. */
+export function niceStep(raw) {
+    if (!(raw > 0) || !isFinite(raw))
+        return 1;
+    const exp = Math.floor(Math.log10(raw));
+    const f = raw / 10 ** exp;
+    return (f < 1.5 ? 1 : f < 3 ? 2 : f < 7 ? 5 : 10) * 10 ** exp;
+}
+/**
+ * The maths of a dimension, as an element: the first (and only) child of an axis. Parameters are attributes,
+ * so a scale serializes like anything else, and a new transform is a new class with no change to axes.
+ */
+export class Scale extends ChartElement {
+    /** True when equal steps in the data are equal steps along the axis, so a straight line in data is straight on the page. */
+    get isLinear() { return false; }
+}

package/dist/scales.d.ts

@@ -0,0 +1,69 @@
+/** The scales: linear, logarithmic, square-root and category. The base class is in scale.ts. */
+import type { Extent } from './geometry.ts';
+import { Scale, type ScaleAttributes } from './scale.ts';
+/** Evenly spaced values: the default, and the only scale implemented so far. */
+export declare class LinearScale<A extends ScaleAttributes = ScaleAttributes> extends Scale<A> {
+    get isLinear(): boolean;
+    normalize(buf: Float64Array, count: number, stride: number, offset: number, range: Extent): void;
+    denormalize(f: number, r: Extent): number;
+    constrain(r: Extent): Extent;
+    nice(r: Extent): Extent;
+    ticks(r: Extent, count: number): readonly number[];
+}
+/**
+ * Powers of a base: equal ratios take equal distances, which is what spans of many orders of magnitude need.
+ * Values that are not positive have no place on it and come out NaN (a gap), and the range is kept positive.
+ */
+export interface LogScaleAttributes extends ScaleAttributes {
+    /** Default 10. */
+    base?: number;
+}
+export declare class LogScale extends Scale<LogScaleAttributes> {
+    private get base();
+    normalize(buf: Float64Array, count: number, stride: number, offset: number, range: Extent): void;
+    denormalize(f: number, r: Extent): number;
+    /**
+     * A range reaching zero or below cannot be drawn. Pull the low end up to three orders of magnitude under the high end
+     * (or the high end up from it, if both are bad): a choice, since there is no right answer, but a readable one.
+     */
+    constrain(r: Extent): Extent;
+    nice(r: Extent): Extent;
+    /** The powers of the base in range, thinned to about `count`; with only a few decades, 2 and 5 times each as well. */
+    ticks(r: Extent, count: number): readonly number[];
+}
+/**
+ * Square root: gives zero a place (unlike a log) while giving small values more room than a linear scale does, as for
+ * counts or areas. Negative values come out NaN.
+ */
+export declare class SqrtScale extends Scale {
+    #private;
+    normalize(buf: Float64Array, count: number, stride: number, offset: number, range: Extent): void;
+    denormalize(f: number, r: Extent): number;
+    /** The low end cannot go below zero. */
+    constrain(r: Extent): Extent;
+    nice(r: Extent): Extent;
+    ticks(r: Extent, count: number): readonly number[];
+}
+export interface BandScaleAttributes extends ScaleAttributes {
+    /** Category labels in order; the domain values are indexes into this list. */
+    categories: readonly string[];
+    /** Fraction of each band left empty between neighbours, 0..1. Default 0.2. */
+    gap?: number;
+}
+/**
+ * Categories: the domain values 0, 1, 2… are positions of equal bands, one per category, and a value is drawn at the
+ * middle of its band. The range is fixed by the categories (data cannot change it), the ticks are the categories, and
+ * every label is the category's name. Labels are never thinned, so give a long list room or a short name.
+ */
+export declare class BandScale extends Scale<BandScaleAttributes> {
+    private get n();
+    /** Width of the drawn part of one band as a fraction of the range, for a renderer that draws bars. */
+    get bandwidth(): number;
+    normalize(buf: Float64Array, count: number, stride: number, offset: number, range: Extent): void;
+    denormalize(f: number, r: Extent): number;
+    /** Half a band either side of the first and last category, whatever the data or attributes asked. */
+    constrain(): Extent;
+    nice(r: Extent): Extent;
+    ticks(r: Extent): readonly number[];
+    label(value: number): string | undefined;
+}

package/dist/scales.js

@@ -0,0 +1,134 @@
+import { Scale, clean, niceStep } from './scale.js';
+/** Evenly spaced values: the default, and the only scale implemented so far. */
+export class LinearScale extends Scale {
+    get isLinear() { return true; }
+    normalize(buf, count, stride, offset, range) {
+        const span = range.max - range.min;
+        // A zero span maps everything to 0 rather than dividing by zero.
+        const inv = span > 0 ? 1 / span : 0;
+        const min = range.min;
+        // 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 k = 0, i = offset; k < count; k++, i += stride)
+            buf[i] = (buf[i] - min) * inv;
+    }
+    denormalize(f, r) { return r.min + f * (r.max - r.min); }
+    constrain(r) { return r; }
+    nice(r) {
+        // Aim for about five divisions; the 1e-9 keeps an already tidy end from stepping out a whole tick on rounding error.
+        const step = niceStep((r.max - r.min) / 5);
+        return { min: clean(Math.floor(r.min / step + 1e-9) * step), max: clean(Math.ceil(r.max / step - 1e-9) * step) };
+    }
+    ticks(r, count) {
+        const step = niceStep((r.max - r.min) / Math.max(1, count));
+        const first = Math.ceil(r.min / step - 1e-9), last = Math.floor(r.max / step + 1e-9);
+        const out = [];
+        // The cap is a guard against a huge range with a tiny tick step, not a real limit.
+        for (let k = first; k <= last && out.length < 1000; k++)
+            out.push(clean(k * step));
+        return out;
+    }
+}
+export class LogScale extends Scale {
+    get base() { return this.attrs.base ?? 10; }
+    normalize(buf, count, stride, offset, range) {
+        const lo = Math.log(range.min), span = Math.log(range.max) - lo;
+        const inv = span > 0 ? 1 / span : 0;
+        for (let k = 0, i = offset; k < count; k++, i += stride) {
+            // 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 v = buf[i];
+            buf[i] = v > 0 ? (Math.log(v) - lo) * inv : NaN;
+        }
+    }
+    denormalize(f, r) {
+        const lo = Math.log(r.min);
+        return Math.exp(lo + f * (Math.log(r.max) - lo));
+    }
+    /**
+     * A range reaching zero or below cannot be drawn. Pull the low end up to three orders of magnitude under the high end
+     * (or the high end up from it, if both are bad): a choice, since there is no right answer, but a readable one.
+     */
+    constrain(r) {
+        const b = this.base;
+        if (r.max <= 0)
+            return { min: 1, max: b };
+        if (r.min <= 0)
+            return { min: r.max / b ** 3, max: r.max };
+        return r;
+    }
+    nice(r) {
+        const b = this.base, lg = (v) => Math.log(v) / Math.log(b);
+        // The epsilons stop an exact power from stepping out a whole decade on rounding error.
+        return { min: clean(b ** Math.floor(lg(r.min) + 1e-9)), max: clean(b ** Math.ceil(lg(r.max) - 1e-9)) };
+    }
+    /** The powers of the base in range, thinned to about `count`; with only a few decades, 2 and 5 times each as well. */
+    ticks(r, count) {
+        const b = this.base, lg = (v) => Math.log(v) / Math.log(b);
+        const first = Math.ceil(lg(r.min) - 1e-9), last = Math.floor(lg(r.max) + 1e-9);
+        const out = [];
+        const decades = last - first + 1;
+        if (decades < count && b === 10) {
+            for (let e = first - 1; e <= last; e++)
+                for (const m of [1, 2, 5]) {
+                    const v = clean(m * 10 ** e);
+                    if (v >= r.min && v <= r.max)
+                        out.push(v);
+                }
+            return out;
+        }
+        const stride = Math.max(1, Math.ceil(decades / Math.max(1, count)));
+        for (let e = first; e <= last && out.length < 1000; e += stride)
+            out.push(clean(b ** e));
+        return out;
+    }
+}
+/**
+ * Square root: gives zero a place (unlike a log) while giving small values more room than a linear scale does, as for
+ * counts or areas. Negative values come out NaN.
+ */
+export class SqrtScale extends Scale {
+    #linear = new LinearScale(); // tidy ends and ticks are chosen in data space, where people read them
+    normalize(buf, count, stride, offset, range) {
+        const lo = Math.sqrt(range.min), span = Math.sqrt(range.max) - lo;
+        const inv = span > 0 ? 1 / span : 0;
+        for (let k = 0, i = offset; k < count; k++, i += stride) {
+            // 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 v = buf[i];
+            buf[i] = v >= 0 ? (Math.sqrt(v) - lo) * inv : NaN;
+        }
+    }
+    denormalize(f, r) {
+        const lo = Math.sqrt(r.min), u = lo + f * (Math.sqrt(r.max) - lo);
+        return u * u;
+    }
+    /** The low end cannot go below zero. */
+    constrain(r) { return r.min < 0 ? { min: 0, max: Math.max(r.max, 0) } : r; }
+    nice(r) { return this.constrain(this.#linear.nice(r)); }
+    ticks(r, count) { return this.#linear.ticks(r, count); }
+}
+/**
+ * Categories: the domain values 0, 1, 2… are positions of equal bands, one per category, and a value is drawn at the
+ * middle of its band. The range is fixed by the categories (data cannot change it), the ticks are the categories, and
+ * every label is the category's name. Labels are never thinned, so give a long list room or a short name.
+ */
+export class BandScale extends Scale {
+    get n() { return Math.max(1, this.attrs.categories.length); }
+    /** Width of the drawn part of one band as a fraction of the range, for a renderer that draws bars. */
+    get bandwidth() { return (1 - (this.attrs.gap ?? 0.2)) / this.n; }
+    normalize(buf, count, stride, offset, range) {
+        const span = range.max - range.min, inv = span > 0 ? 1 / span : 0;
+        // 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 k = 0, i = offset; k < count; k++, i += stride)
+            buf[i] = (buf[i] - range.min) * inv;
+    }
+    denormalize(f, r) { return r.min + f * (r.max - r.min); }
+    /** Half a band either side of the first and last category, whatever the data or attributes asked. */
+    constrain() { return { min: -0.5, max: this.n - 0.5 }; }
+    nice(r) { return r; }
+    ticks(r) {
+        const out = [];
+        for (let k = Math.max(0, Math.ceil(r.min)); k <= Math.min(this.n - 1, Math.floor(r.max)); k++)
+            out.push(k);
+        return out;
+    }
+    label(value) { return this.attrs.categories[Math.round(value)]; }
+}

package/dist/serialize.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { type AnyArgs, type AnyElement } from './element.ts';
+/** The JSON form of one element: its registered class name, attributes, and children in order. */
+export interface ElementJSON {
+    type: string;
+    attrs?: Record<string, unknown>;
+    children?: ElementJSON[];
+}
+export type ElementRegistry = Readonly<Record<string, new (...args: AnyArgs) => AnyElement>>;
+/** Names for objects and functions that JSON cannot hold, so that writing can point at them and reading can find them again. */
+export declare class Refs {
+    #private;
+    /** Name whatever is asked about and not yet named, after the attribute it was found in. */
+    auto: boolean;
+    constructor(values?: Readonly<Record<string, unknown>>, options?: {
+        auto?: boolean;
+    });
+    /** 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: string, value: unknown): this;
+    has(name: string): boolean;
+    get(name: string): unknown;
+    /** The name a value goes by, if it has one. */
+    nameOf(value: unknown): string | undefined;
+    /** Give a value a name of its own, built on `hint` and made unique. Returns the one it has already, if so. */
+    adopt(value: unknown, hint?: string): string;
+    get names(): readonly string[];
+}
+export interface SerializeOptions {
+    /** Where functions and other things JSON cannot hold are found, and named. */
+    refs?: Refs;
+    /** Arrays longer than this are data and go by reference, not inline. Default 1000. */
+    inlineLimit?: number;
+}
+/** An element and everything below it as JSON. See the top of this file for what an attribute may hold. */
+export declare function toJSON(element: AnyElement, registry: ElementRegistry, options?: SerializeOptions): ElementJSON;
+/** A new, unattached element tree from JSON. `refs` is where the `$ref`s are found. */
+export declare function fromJSON<T extends AnyElement = AnyElement>(json: ElementJSON, registry: ElementRegistry, options?: SerializeOptions): T;
+/**
+ * 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 declare function applyJSON(element: AnyElement, json: ElementJSON, registry: ElementRegistry, options?: SerializeOptions): void;