inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/trend.js

@@ -0,0 +1,500 @@
+/**
+ * Trendlines: a curve fitted to the data, which can be read anywhere along the domain.
+ *
+ *   <DomainSeries>
+ *     <LinearTrend><ObjectDataSource source={rows} domain="t" value="v" /></LinearTrend>
+ *     <LinePath><LinearCurve /></LinePath>
+ *   </DomainSeries>
+ *
+ *   Trendline
+ *   ├─ LinearTrend        the least-squares line
+ *   ├─ PolynomialTrend    a polynomial of a given `degree`
+ *   ├─ SinusoidalTrend    a constant plus a sine wave: of a given `period`, or the one that fits best
+ *   └─ LoessTrend         local linear regression, as smooth as `smoothness` says: 0 joins the points, 1 is the line
+ *
+ * A trendline is a `DataTransform` that behaves like a `SyntheticDataSource`: the fit is made once for each change of
+ * its source, and the points it gives are samples of the fitted curve, made when drawn: one for each pixel of width across
+ * the part of the domain in view (or `count`, always, across the whole of it). So zooming in stays smooth, and the line
+ * reaches `extend` further than the data at each end (a fraction of the data's span; one number, or `[before, after]`),
+ * which is how a trendline is extrapolated. Default 0.
+ *
+ * It fits the source's value against its domain. `x` names a channel of the source to fit against instead, which is how a
+ * scatter (an `XYSeries`) gets a trendline: `<LinearTrend x="x">`. Its own points have the sampled positions as the domain
+ * and as the channel `domain`, which is what an `XYSeries` reads x from. A point with a gap in either column is left out of the fit.
+ *
+ * Read it from code too, outside any chart: `trend.evaluate(x)` is the fitted value at a number, or at every number of an
+ * array (a `Float64Array` back), and `trend.fit` says how good the fit is: the number of points, `r2`, `rmse`, and what the
+ * kind of fit knows (coefficients, period, bandwidth). `readTable(trend)` is the sampled curve as a table.
+ *
+ * To write another, extend `Trendline` and make a `TrendModel` from the points in `fitModel`.
+ */
+/* 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 { AUTO, NUMBER, STRING } from './attrs.js';
+import { DataSource, DataTransform } from './data.js';
+import { fail } from './element.js';
+const DEFAULT_SAMPLES = 512;
+const NONE = { min: Infinity, max: -Infinity };
+/** The base of trendlines: reads the points, fits them once for each change, and samples the curve. */
+export class Trendline extends DataTransform {
+    static attrTypes = { ...DataTransform.attrTypes, x: STRING, extend: AUTO, count: NUMBER };
+    #version = 0;
+    #cache = null;
+    #fit = null;
+    get source() { return this.child(0, DataSource, DataTransform); }
+    invalidate() {
+        this.#version++;
+        super.invalidate();
+    }
+    get version() { return this.#version; }
+    get channelNames() { return ['domain']; }
+    get pointCount() { return this.attrs.count ?? DEFAULT_SAMPLES; }
+    /** The points the fit is made from and the curve, made again only after a change. */
+    #state() {
+        if (this.#cache && this.#cache.version === this.#version)
+            return this.#cache;
+        const name = this.attrs.x, src = this.source;
+        const plan = src.plan({ width: 0, height: 0, domainRange: { min: -Infinity, max: Infinity }, channels: name ? [name] : [] });
+        const stride = name ? 3 : 2, buf = new Float64Array(plan.capacity * stride), { count } = plan.fill(buf);
+        const xc = name ? 2 : 0;
+        let xs = new Float64Array(count), ys = new Float64Array(count), n = 0;
+        for (let i = 0; i < count; i++) {
+            const x = buf[stride * i + xc], y = buf[stride * i + 1];
+            if (!Number.isFinite(x) || !Number.isFinite(y))
+                continue;
+            xs[n] = x;
+            ys[n] = y;
+            n++;
+        }
+        xs = xs.slice(0, n);
+        ys = ys.slice(0, n);
+        let sorted = true;
+        for (let i = 1; i < n; i++)
+            if (xs[i] < xs[i - 1]) {
+                sorted = false;
+                break;
+            }
+        if (!sorted) {
+            const order = Uint32Array.from({ length: n }, (_, i) => i).sort((p, q) => xs[p] - xs[q]);
+            xs = Float64Array.from(order, (i) => xs[i]);
+            ys = Float64Array.from(order, (i) => ys[i]);
+        }
+        const model = n > 0 ? this.fitModel(xs, ys) : null;
+        return (this.#cache = { version: this.#version, xs, ys, model });
+    }
+    /** How well the curve fits, or null when there are too few points to fit one. */
+    get fit() {
+        if (this.#fit && this.#fit.version === this.#version)
+            return this.#fit.value;
+        const { xs, ys, model } = this.#state();
+        let value = null;
+        if (model) {
+            const n = xs.length;
+            let mean = 0;
+            for (let i = 0; i < n; i++)
+                mean += ys[i];
+            mean /= n;
+            let sse = 0, sst = 0;
+            for (let i = 0; i < n; i++) {
+                const r = ys[i] - model.at(xs[i]);
+                sse += r * r;
+                sst += (ys[i] - mean) ** 2;
+            }
+            value = { n, r2: sst > 0 ? 1 - sse / sst : sse === 0 ? 1 : 0, rmse: Math.sqrt(sse / n), ...model.details };
+        }
+        this.#fit = { version: this.#version, value };
+        return value;
+    }
+    evaluate(x) {
+        const model = this.#state().model;
+        if (typeof x === 'number')
+            return model ? model.at(x) : NaN;
+        const out = new Float64Array(x.length);
+        for (let i = 0; i < out.length; i++)
+            out[i] = model ? model.at(x[i]) : NaN;
+        return out;
+    }
+    /** The span the line covers: the data's, and the extension at each end. */
+    #span() {
+        const { xs } = this.#state();
+        if (!xs.length)
+            return null;
+        const lo = xs[0], hi = xs[xs.length - 1], e = this.attrs.extend ?? 0;
+        const [before, after] = typeof e === 'number' ? [e, e] : e;
+        if (!(before >= 0 && after >= 0))
+            fail(`${this.constructor.name}: extend must be 0 or more (got ${String(e)})`);
+        return { min: lo - (hi - lo) * before, max: hi + (hi - lo) * after };
+    }
+    /** The samples for a plot: where they are and how many. */
+    #samples(context) {
+        const span = this.#span();
+        if (!span)
+            return new Float64Array(0);
+        const count = this.attrs.count;
+        const lo = count === undefined ? Math.max(span.min, context.domainRange.min) : span.min;
+        const hi = count === undefined ? Math.min(span.max, context.domainRange.max) : span.max;
+        if (!(lo <= hi))
+            return new Float64Array(0);
+        const n = count ?? (context.width > 0 ? Math.max(2, Math.ceil(context.width)) : DEFAULT_SAMPLES);
+        return Float64Array.from({ length: n }, (_, i) => (n === 1 ? lo : i === n - 1 ? hi : lo + ((hi - lo) * i) / (n - 1)));
+    }
+    domain() { return this.#span(); }
+    valueExtent() {
+        const ys = this.evaluate(this.#samples({ width: 0, height: 0, domainRange: { min: -Infinity, max: Infinity }, channels: [] }));
+        let min = Infinity, max = -Infinity;
+        for (const y of ys)
+            if (Number.isFinite(y)) {
+                if (y < min)
+                    min = y;
+                if (y > max)
+                    max = y;
+            }
+        return min <= max ? { min, max } : null;
+    }
+    channelExtent(name) {
+        if (name !== 'domain')
+            fail(`${this.constructor.name} has no channel "${name}" (it has domain)`);
+        return this.domain();
+    }
+    plan(context) {
+        for (const c of context.channels)
+            if (c !== 'domain')
+                fail(`${this.constructor.name} has no channel "${c}" (it has domain)`);
+        const xs = this.#samples(context), n = xs.length, stride = 2 + context.channels.length;
+        return {
+            capacity: n,
+            fill: (out) => {
+                const ys = this.evaluate(xs);
+                let min = Infinity, max = -Infinity;
+                for (let i = 0; i < n; i++) {
+                    out[stride * i] = xs[i];
+                    out[stride * i + 1] = ys[i];
+                    for (let j = 0; j < context.channels.length; j++)
+                        out[stride * i + 2 + j] = xs[i];
+                    if (ys[i] < min)
+                        min = ys[i];
+                    if (ys[i] > max)
+                        max = ys[i];
+                }
+                const x = n ? { min: xs[0], max: xs[n - 1] } : NONE;
+                return { count: n, extents: [x, min <= max ? { min, max } : NONE, ...context.channels.map(() => x)] };
+            },
+        };
+    }
+}
+/** The least-squares line. `fit.coefficients` is `[intercept, slope]`. */
+export class LinearTrend extends Trendline {
+    fitModel(xs, ys) { return leastSquares(xs, ys); }
+}
+/** The least-squares line through the points; null when they share one position. */
+function leastSquares(xs, ys) {
+    const n = xs.length;
+    let mx = 0, my = 0;
+    for (let i = 0; i < n; i++) {
+        mx += xs[i];
+        my += ys[i];
+    }
+    mx /= n;
+    my /= n;
+    let sxx = 0, sxy = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = xs[i] - mx;
+        sxx += dx * dx;
+        sxy += dx * (ys[i] - my);
+    }
+    if (!(sxx > 0))
+        return null;
+    const slope = sxy / sxx, intercept = my - slope * mx;
+    return { at: (x) => intercept + slope * x, details: { coefficients: [intercept, slope] } };
+}
+const MAX_DEGREE = 12;
+/** Solve `a x = b` for a square `a` (rows of `m` numbers) by elimination with pivoting; null when it is singular. Both are overwritten. */
+function solve(a, b, m) {
+    let scale = 0;
+    for (let i = 0; i < m; i++)
+        scale = Math.max(scale, Math.abs(a[i * m + i]));
+    for (let c = 0; c < m; c++) {
+        let p = c;
+        for (let r = c + 1; r < m; r++)
+            if (Math.abs(a[r * m + c]) > Math.abs(a[p * m + c]))
+                p = r;
+        if (!(Math.abs(a[p * m + c]) > 1e-13 * scale))
+            return null;
+        if (p !== c) {
+            for (let k = 0; k < m; k++) {
+                const t = a[c * m + k];
+                a[c * m + k] = a[p * m + k];
+                a[p * m + k] = t;
+            }
+            const t = b[c];
+            b[c] = b[p];
+            b[p] = t;
+        }
+        for (let r = c + 1; r < m; r++) {
+            const f = a[r * m + c] / a[c * m + c];
+            for (let k = c; k < m; k++)
+                a[r * m + k] -= f * a[c * m + k];
+            b[r] -= f * b[c];
+        }
+    }
+    const x = new Float64Array(m);
+    for (let r = m - 1; r >= 0; r--) {
+        let s = b[r];
+        for (let k = r + 1; k < m; k++)
+            s -= a[r * m + k] * x[k];
+        x[r] = s / a[r * m + r];
+    }
+    return x;
+}
+/**
+ * A polynomial of `degree` (2 by default: a parabola). It is fitted on the positions centred and scaled to -1..1, which
+ * keeps high degrees well-behaved; `fit.coefficients` are in that scaled position `u = (x - center) / scale`. It needs
+ * more distinct positions than its degree.
+ */
+export class PolynomialTrend extends Trendline {
+    static attrTypes = { ...Trendline.attrTypes, degree: NUMBER };
+    fitModel(xs, ys) {
+        const d = this.attrs.degree ?? 2;
+        if (!Number.isInteger(d) || d < 1 || d > MAX_DEGREE)
+            fail(`PolynomialTrend: degree is a whole number from 1 to ${MAX_DEGREE} (got ${d})`);
+        const n = xs.length, m = d + 1;
+        const lo = xs[0], hi = xs[n - 1], center = (lo + hi) / 2, scale = (hi - lo) / 2;
+        if (!(scale > 0) || n < m)
+            return null;
+        const pow = new Float64Array(2 * d + 1), rhs = new Float64Array(m);
+        for (let i = 0; i < n; i++) {
+            const u = (xs[i] - center) / scale;
+            let p = 1;
+            for (let k = 0; k <= 2 * d; k++) {
+                pow[k] += p;
+                if (k < m)
+                    rhs[k] += p * ys[i];
+                p *= u;
+            }
+        }
+        const a = new Float64Array(m * m);
+        for (let r = 0; r < m; r++)
+            for (let c = 0; c < m; c++)
+                a[r * m + c] = pow[r + c];
+        const coefficients = solve(a, rhs, m);
+        if (!coefficients)
+            return null;
+        return {
+            at: (x) => { const u = (x - center) / scale; let v = 0; for (let k = d; k >= 0; k--)
+                v = v * u + coefficients[k]; return v; },
+            details: { coefficients: Array.from(coefficients), center, scale },
+        };
+    }
+}
+/** Frequencies tried when the period is not given, and points used to try them (the best is then refined on all). */
+const SCAN_FREQUENCIES = 3000;
+const SCAN_POINTS = 2000;
+/** Sums for the least-squares fit of `c + a cos(wx) + b sin(wx)` at one frequency: the coefficients and the squared error left. */
+function sinFit(xs, ys, idx, n, w, center) {
+    let s1 = 0, sc = 0, ss = 0, scc = 0, sss = 0, scs = 0, sy = 0, syc = 0, sys = 0, syy = 0;
+    for (let k = 0; k < n; k++) {
+        const i = idx ? idx(k) : k, t = w * (xs[i] - center), c = Math.cos(t), s = Math.sin(t), y = ys[i];
+        s1++;
+        sc += c;
+        ss += s;
+        scc += c * c;
+        sss += s * s;
+        scs += c * s;
+        sy += y;
+        syc += y * c;
+        sys += y * s;
+        syy += y * y;
+    }
+    const a = Float64Array.of(s1, sc, ss, sc, scc, scs, ss, scs, sss), b = Float64Array.of(sy, syc, sys);
+    const beta = solve(a, Float64Array.from(b), 3);
+    if (!beta)
+        return null;
+    const sse = syy - (beta[0] * sy + beta[1] * syc + beta[2] * sys);
+    return { c: beta[0], a: beta[1], b: beta[2], sse: Math.max(0, sse) };
+}
+/**
+ * A constant plus one sine wave. Give the `period` and only the offset, amplitude and phase are fitted (a linear fit). Without
+ * it the period is found too: a periodogram over the periods the data can show (from the whole span down to about two of its
+ * typical gaps, which works for unevenly spaced points), then a refinement of the best on every point. `fit.period` and
+ * `fit.amplitude` say what was found. A wave with fewer than three points, or with every point at one position, has no fit.
+ */
+export class SinusoidalTrend extends Trendline {
+    static attrTypes = { ...Trendline.attrTypes, period: NUMBER };
+    fitModel(xs, ys) {
+        const n = xs.length, given = this.attrs.period;
+        if (given !== undefined && !(given > 0))
+            fail(`SinusoidalTrend: period must be above 0 (got ${given})`);
+        const lo = xs[0], hi = xs[n - 1], span = hi - lo, center = (lo + hi) / 2;
+        if (n < 3 || !(span > 0))
+            return null;
+        let period = given;
+        if (period === undefined) {
+            // Typical gap: the median of the positive ones.
+            const gaps = [];
+            for (let i = 1; i < n; i++)
+                if (xs[i] > xs[i - 1])
+                    gaps.push(xs[i] - xs[i - 1]);
+            gaps.sort((p, q) => p - q);
+            const gap = gaps[gaps.length >> 1];
+            const fMin = 1 / span, fMax = Math.max(fMin * 2, 1 / (2 * gap));
+            const df = (fMax - fMin) / Math.min(SCAN_FREQUENCIES, Math.max(8, Math.ceil(4 * span * (fMax - fMin))));
+            const use = Math.min(n, SCAN_POINTS), idx = use < n ? (k) => Math.floor((k * (n - 1)) / (use - 1)) : null;
+            let best = fMin, bestSse = Infinity;
+            for (let f = fMin; f <= fMax + 1e-12; f += df) {
+                const r = sinFit(xs, ys, idx, use, 2 * Math.PI * f, center);
+                if (r && r.sse < bestSse) {
+                    bestSse = r.sse;
+                    best = f;
+                }
+            }
+            // Refine on all the points by golden-section search within a step of the best.
+            let a = Math.max(fMin * 0.5, best - df), b = best + df;
+            const phi = (Math.sqrt(5) - 1) / 2, cost = (f) => sinFit(xs, ys, null, n, 2 * Math.PI * f, center)?.sse ?? Infinity;
+            let c = b - phi * (b - a), d = a + phi * (b - a), fc = cost(c), fd = cost(d);
+            for (let it = 0; it < 40; it++) {
+                if (fc < fd) {
+                    b = d;
+                    d = c;
+                    fd = fc;
+                    c = b - phi * (b - a);
+                    fc = cost(c);
+                }
+                else {
+                    a = c;
+                    c = d;
+                    fc = fd;
+                    d = a + phi * (b - a);
+                    fd = cost(d);
+                }
+            }
+            period = 1 / ((a + b) / 2);
+        }
+        const w = (2 * Math.PI) / period, r = sinFit(xs, ys, null, n, w, center);
+        if (!r)
+            return null;
+        const { c, a, b } = r;
+        return {
+            at: (x) => c + a * Math.cos(w * (x - center)) + b * Math.sin(w * (x - center)),
+            details: { coefficients: [c, a, b], center, period, amplitude: Math.hypot(a, b) },
+        };
+    }
+}
+/** A window holds at least this many points, so a small bandwidth between sparse points still has a line to fit. */
+const MIN_WINDOW = 3;
+/** The reach at smoothness 0.5, as a fraction of the span; `smoothness / (1 - smoothness)` times this is the reach in general. */
+const REACH_AT_HALF = 0.3;
+/**
+ * Local linear regression (the method behind LOESS and LOWESS), centred on each position and reaching both ways: at each place
+ * it fits a straight line to the points near it, weighting nearer ones more, and takes that line's value. `smoothness` sets
+ * how far it reaches, as `smoothness / (1 - smoothness)` times 0.3 of the data's span: 0 reaches nowhere and the curve joins the
+ * points (straight between neighbours; points sharing a position are averaged), larger values are smoother, and 1 reaches everywhere
+ * equally, which is the least-squares line (it is that exactly). Where the points are sparse the reach widens to hold at least
+ * three of them. Past the ends of the data it continues the local line at the end, with a slope over a wide reach. Each place costs the points in its reach, so a very smooth curve over very many points is slow to sample: pick `count`.
+ * It needs sorted points, which it makes itself. `fit.bandwidth` is the reach.
+ */
+export class LoessTrend extends Trendline {
+    static attrTypes = { ...Trendline.attrTypes, smoothness: NUMBER, kernel: STRING };
+    fitModel(xs, ys) {
+        const s = this.attrs.smoothness ?? 0.5, kernel = this.attrs.kernel ?? 'tricube';
+        if (!(s >= 0 && s <= 1))
+            fail(`LoessTrend: smoothness is from 0 to 1 (got ${s})`);
+        if (kernel !== 'tricube' && kernel !== 'gaussian')
+            fail(`LoessTrend: kernel is 'tricube' or 'gaussian' (got "${kernel}")`);
+        const n = xs.length, span = xs[n - 1] - xs[0];
+        if (!(span > 0))
+            return null;
+        if (s === 1)
+            return leastSquares(xs, ys);
+        if (s === 0)
+            return interpolation(xs, ys);
+        const h0 = (REACH_AT_HALF * span * s) / (1 - s);
+        const weight = kernel === 'tricube'
+            ? (q) => { const t = 1 - q * q * q; return t * t * t; }
+            : (q) => Math.exp(-4.5 * q * q); // sigma = h / 3: the weight is negligible at the window's edge
+        // The local line at x0 (its value there and its slope) from the points within `reach`, widened to hold three.
+        const local = (x0, reach) => {
+            let h = reach;
+            let lo = lowerBound(xs, x0 - h), hi = lowerBound(xs, x0 + h, true);
+            if (hi - lo < MIN_WINDOW) {
+                // Widen to the distance of the third nearest point.
+                let l = lowerBound(xs, x0) - 1, r = l + 1, d = 0;
+                for (let k = 0; k < Math.min(MIN_WINDOW, n); k++) {
+                    const dl = l >= 0 ? x0 - xs[l] : Infinity, dr = r < n ? xs[r] - x0 : Infinity;
+                    if (dl <= dr) {
+                        d = dl;
+                        l--;
+                    }
+                    else {
+                        d = dr;
+                        r++;
+                    }
+                }
+                h = Math.max(h, d * (1 + 1e-9));
+                lo = lowerBound(xs, x0 - h);
+                hi = lowerBound(xs, x0 + h, true);
+            }
+            let s0 = 0, s1 = 0, s2 = 0, t0 = 0, t1 = 0;
+            for (let j = lo; j < hi; j++) {
+                const dx = xs[j] - x0, w = weight(Math.abs(dx) / h);
+                s0 += w;
+                s1 += w * dx;
+                s2 += w * dx * dx;
+                t0 += w * ys[j];
+                t1 += w * dx * ys[j];
+            }
+            if (!(s0 > 0))
+                return null;
+            const det = s0 * s2 - s1 * s1;
+            return det > 1e-12 * s0 * s2 ? { a: (t0 * s2 - t1 * s1) / det, b: (s0 * t1 - s1 * t0) / det } : { a: t0 / s0, b: 0 };
+        };
+        const first = xs[0], last = xs[n - 1];
+        const at = (x) => {
+            if (!Number.isFinite(x))
+                return NaN;
+            if (x >= first && x <= last)
+                return local(x, h0)?.a ?? NaN;
+            // Past the data: the local line at the end, continued with a slope taken over a wide reach, since the few points nearest
+            // the end give a slope that is mostly noise.
+            const end = x < first ? first : last, edge = local(end, h0), slope = local(end, Math.max(h0, REACH_AT_HALF * span));
+            return edge && slope ? edge.a + slope.b * (x - end) : NaN;
+        };
+        return { at, details: { bandwidth: h0 } };
+    }
+}
+/** The index of the first x not below `x` (or, with `after`, the first above it). */
+function lowerBound(xs, x, after = false) {
+    let lo = 0, hi = xs.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (after ? xs[mid] <= x : xs[mid] < x)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/** The curve straight through the points (averaging the ones that share a position), continuing the end segments past them. */
+function interpolation(xs, ys) {
+    const px = [], py = [];
+    for (let i = 0; i < xs.length;) {
+        let j = i, sum = 0;
+        while (j < xs.length && xs[j] === xs[i])
+            sum += ys[j++];
+        px.push(xs[i]);
+        py.push(sum / (j - i));
+        i = j;
+    }
+    const m = px.length;
+    if (m < 2)
+        return null;
+    const x = Float64Array.from(px);
+    return {
+        at: (v) => {
+            if (!Number.isFinite(v))
+                return NaN;
+            const k = Math.min(m - 1, Math.max(1, lowerBound(x, v)));
+            const x0 = px[k - 1], x1 = px[k];
+            return py[k - 1] + ((py[k] - py[k - 1]) * (v - x0)) / (x1 - x0);
+        },
+        details: { bandwidth: 0 },
+    };
+}

package/dist/web-components.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The Web Components adapter: chart elements as custom HTML elements, so that a chart can be written, or pre-rendered, as markup.
+ *
+ *     import * as inkplot from 'inkplot';
+ *     import { defineElements } from 'inkplot/web-components';
+ *     defineElements({ Chart: inkplot.Chart, CartesianPlane: inkplot.CartesianPlane, Axis: inkplot.Axis, … }, { prefix: 'ch' });
+ *
+ *     <ch-chart style="display:block; height:300px" meta-title="Sales">
+ *       <ch-cartesian-plane>
+ *         <ch-axis orientation="bottom" meta-title="Month"><ch-linear-scale></ch-linear-scale></ch-axis>
+ *         <ch-domain-series name="2024"><ch-flat-data-source data="[1,3,2]" regulardomain-step="1"></ch-flat-data-source> …
+ *
+ * Only the classes you give are defined, so nothing else is bundled. The tag is the prefix and the key, kebab-cased
+ * (`ch-cartesian-plane`).
+ *
+ * How it follows the DOM:
+ * - The element tree is the DOM tree: a wrapper finds its parent wrapper among its ancestors and joins it in document order
+ *   when connected, and leaves when disconnected. Moving a node moves the chart element. The outermost wrapper (one with
+ *   `attach`, a Chart) draws into a shadow root, so the wrapper elements inside it are never rendered, and the page's CSS does not reach the chart.
+ *   Give that element a size; it is `display: block`.
+ * - Attributes are the element's attributes. HTML lowercases names, so `regulardomain-step` finds `regularDomain.step` (the
+ *   class' `attrTypes` and `STYLE_NAMES` say how the names are spelled). Hyphens nest, as in attrs.ts: `meta-title`, `style-ticklabel-size`.
+ *   Text becomes a value by the class' `attrTypes`: `STRING` stays text; otherwise `true`/`false`, numbers, and `[…]`/`{…}` (JSON)
+ *   convert, and a present attribute with no value is true. Changing an attribute later updates the element (on the next microtask).
+ * - Values HTML cannot carry are set as JavaScript: `element.props = { format: fn, data: new Float64Array(…) }` on the wrapper,
+ *   and they win over attributes. `wrapper.element` is the chart element itself, for calling its methods.
+ * - Callbacks (`onClick`, `onHover`, `onDrag`, `onFlush`: attributes that are functions) are events: once the page listens, with
+ *   `addEventListener('click', …)` or `onclick=""`, the wrapper dispatches a bubbling `CustomEvent` named like the DOM's (`click`,
+ *   `hover`, `drag`, `flush`) with the callback's argument as `detail`. (Until then no callback is set, so the chart stays serializable.)
+ *   `on…` attributes are the DOM's own and are not read as chart attributes.
+ * - `style`, `class` and the other attributes every HTML element has are the page's, not the chart's: set the chart's `style` blocks with `style-…` names.
+ */
+import { type AttrTypes } from './attrs.ts';
+import { type DOMPlatformOptions } from './dom-platform.ts';
+import type { AnyArgs, AnyElement } from './element.ts';
+type Plain = Record<string, unknown>;
+type ElementConstructor = (new (...args: AnyArgs) => AnyElement) & {
+    attrTypes?: AttrTypes;
+};
+/** A defined wrapper element, as the page sees it. */
+export interface InkplotElement extends HTMLElement {
+    /** The chart element behind this tag; null until the tag is connected. */
+    readonly element: AnyElement | null;
+    /** Attributes set from JavaScript: functions, data and objects. They win over the tag's attributes. */
+    props: Plain;
+    /** How the chart is drawn, for the outermost element; read when it connects. */
+    platformOptions?: DOMPlatformOptions;
+}
+export interface DefineOptions {
+    /** The start of every tag name, which has to be a valid custom element name with the rest: `ch` gives `ch-axis`. */
+    prefix: string;
+    /** Where to define them. Default: the page's `customElements`. */
+    registry?: CustomElementRegistry;
+    /** More camelCase names that a `style-…` attribute may contain, for selectors added by augmenting `Selectors`. */
+    names?: readonly string[];
+}
+/**
+ * Define a custom element for each class. `classes` maps a name to a class, and the name gives the tag. Returns the tags by name.
+ * Does nothing at import, so a module that imports this can be loaded where there is no DOM.
+ */
+export declare function defineElements(classes: Readonly<Record<string, ElementConstructor>>, options: DefineOptions): Record<string, string>;
+export {};