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

package/dist/density.js

@@ -0,0 +1,252 @@
+/**
+ * Binning as a data transform: points in, a count (or a sum, or a mean) for each bin out. A histogram is this and `BarPath`;
+ * a heat map is this over two dimensions and `HeatMap`.
+ *
+ *   <DomainSeries>
+ *     <Density width={5}><ObjectDataSource source={people} domain="age" value="age" /></Density>
+ *     <BarPath width={1} />
+ *   </DomainSeries>
+ *
+ * `by` names the dimensions to bin, any number of them: `'domain'` and `'value'` are the source's own two columns, and any
+ * other name is one of its channels. The default is `['domain']`. Every point that has a finite number in each of those
+ * dimensions lands in one bin. Each bin is one point of the output, at the bin's centre:
+ *
+ *   one dimension    domain = the bin's centre, value = the statistic (`stat`)
+ *   two or more      domain = the first dimension's centre, value = the second's, and each further dimension is a channel of its name
+ *
+ * and these channels in any case: `domain` (the first dimension's centre again, since an `XYSeries` takes its x from a channel), `count` (the points in the bin), `sum` (the total of the `weight` channel, which
+ * is `count` when there is none), `mean` (`sum / count`), `fraction` (the bin's share of the total), `density` (the share per unit
+ * of the bin's size, so a histogram of it has area 1), and `width` and `height`: the size of the bin along the first and the
+ * second dimension, so a renderer can draw a bin as the box it is. `weight` is what each point counts for: left out, a point
+ * counts as 1; with a channel (or `'value'`) named, `sum` and `mean` are of it. `stat` is the value of a one-dimensional
+ * output: `'count'` (the default; with a `weight`, `'sum'`), `'sum'`, `'mean'`, `'fraction'` or `'density'`.
+ *
+ * Bin size is set for each dimension, as a number (every dimension) or an array with one for each:
+ *   `width`   the size of a bin, in the dimension's own units. Edges fall at `origin` plus a whole number of widths (origin 0 by default).
+ *   `bins`    how many bins, spread evenly over the dimension's extent.
+ *   `extent`  the span to bin over, `{ min, max }`, instead of the data's own; points outside it are left out.
+ * With neither `width` nor `bins` the Freedman–Diaconis rule picks a width from the spread of the points (Sturges' rule when
+ * that is zero), never more than `maxBins` (default 200) bins along a dimension. A bin is closed on the left and open on the
+ * right, except the last, which holds the top edge. With one dimension empty bins are kept as zeros (so bars are evenly
+ * spaced); with more they are left out (`empty` says otherwise). The result is worked out once for each change of the source or the attributes.
+ */
+/* 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';
+import { quantile } from './quantile.js';
+const STATS = ['count', 'sum', 'mean', 'fraction', 'density'];
+/** Channels beside the statistics: the bin's size along the first two dimensions. */
+const SIZES = ['width', 'height'];
+/** Most cells a grid may have: a dense array of them is held. */
+const MAX_CELLS = 4_000_000;
+const list = (v, k) => (Array.isArray(v) ? v[k] : v);
+export class Density extends DataTransform {
+    static attrTypes = { ...DataTransform.attrTypes, by: AUTO, weight: STRING, stat: STRING, width: AUTO, bins: AUTO, origin: AUTO, extent: AUTO, maxBins: NUMBER, empty: STRING };
+    #version = 0;
+    #cache = null;
+    get source() { return this.child(0, DataSource, DataTransform); }
+    invalidate() {
+        this.#version++;
+        super.invalidate();
+    }
+    get version() { return this.#version; }
+    get #dims() { return this.attrs.by ?? ['domain']; }
+    /** What it offers: the other dimensions, then the statistics and sizes. */
+    get channelNames() {
+        const dims = this.#dims;
+        return ['domain', ...(dims.length > 2 ? dims.slice(2) : []), ...STATS, ...SIZES];
+    }
+    #compute() {
+        if (this.#cache && this.#cache.version === this.#version)
+            return this.#cache.value;
+        const a = this.attrs, dims = this.#dims, k = dims.length;
+        if (k === 0)
+            fail('Density: `by` needs at least one dimension');
+        if (new Set(dims).size !== k)
+            fail('Density: `by` names a dimension twice');
+        const weightName = a.weight;
+        // Read what is needed from the source: its own two columns, and a channel for each other name.
+        const names = [...new Set([...dims, ...(weightName ? [weightName] : [])].filter((n) => n !== 'domain' && n !== 'value'))];
+        const plan = this.source.plan({ width: 0, height: 0, domainRange: { min: -Infinity, max: Infinity }, channels: names });
+        const stride = 2 + names.length, buf = new Float64Array(plan.capacity * stride), { count: n } = plan.fill(buf);
+        const column = (name) => (name === 'domain' ? 0 : name === 'value' ? 1 : 2 + names.indexOf(name));
+        const cols = dims.map(column), wcol = weightName ? column(weightName) : -1;
+        // The points that count: every dimension (and the weight) a number.
+        const rows = [];
+        for (let i = 0; i < n; i++) {
+            let ok = true;
+            for (const c of cols) {
+                const v = buf[stride * i + c];
+                if (!Number.isFinite(v)) {
+                    ok = false;
+                    break;
+                }
+            }
+            if (ok && wcol >= 0) {
+                const w = buf[stride * i + wcol];
+                if (!Number.isFinite(w))
+                    ok = false;
+            }
+            if (ok)
+                rows.push(i);
+        }
+        // One dimension's bins from the data and the attributes.
+        const axes = dims.map((_, d) => {
+            const v = Float64Array.from(rows, (i) => buf[stride * i + cols[d]]);
+            const given = a.extent === undefined ? undefined : Array.isArray(a.extent) ? a.extent[d] : a.extent;
+            let min = Infinity, max = -Infinity;
+            if (given) {
+                min = given.min;
+                max = given.max;
+            }
+            else
+                for (const x of v) {
+                    if (x < min)
+                        min = x;
+                    if (x > max)
+                        max = x;
+                }
+            if (!(min <= max))
+                return { lo: 0, width: 1, n: 0 };
+            const width = list(a.width, d), bins = list(a.bins, d), origin = list(a.origin, d) ?? 0, maxBins = a.maxBins ?? 200;
+            if (width !== undefined && !(width > 0))
+                fail(`Density: width must be above 0 (got ${width})`);
+            if (bins !== undefined && !(bins >= 1))
+                fail(`Density: bins must be at least 1 (got ${bins})`);
+            if (width !== undefined) {
+                const i0 = Math.floor((min - origin) / width + 1e-9), i1 = Math.floor((max - origin) / width + 1e-9);
+                if (i1 - i0 + 1 > MAX_CELLS)
+                    fail(`Density: width ${width} makes ${i1 - i0 + 1} bins along "${dims[d]}": use a wider bin`);
+                return { lo: origin + i0 * width, width, n: i1 - i0 + 1 };
+            }
+            const span = max - min;
+            if (span === 0)
+                return { lo: min - 0.5, width: 1, n: 1 }; // no spread: one bin round the value
+            if (bins !== undefined) {
+                const nb = Math.floor(bins);
+                return { lo: min, width: span > 0 ? span / nb : 1, n: nb };
+            }
+            // The rule: Freedman–Diaconis from the spread of the points, else Sturges.
+            v.sort();
+            const m = v.length;
+            const iqr = m > 1 ? quantile(v, 0.75) - quantile(v, 0.25) : 0;
+            let nb = iqr > 0 && span > 0 ? Math.ceil(span / ((2 * iqr) / Math.cbrt(m))) : Math.ceil(Math.log2(Math.max(m, 1)) + 1);
+            nb = Math.max(1, Math.min(maxBins, nb));
+            return { lo: min, width: span > 0 ? span / nb : 1, n: nb };
+        });
+        let cells = 1;
+        for (const ax of axes) {
+            cells *= Math.max(ax.n, 1);
+            if (cells > MAX_CELLS)
+                fail(`Density: ${axes.map((x) => x.n).join(' by ')} bins is too many cells: use \`width\` or \`bins\` to make them fewer`);
+        }
+        const counts = new Float64Array(cells), sums = new Float64Array(cells);
+        if (!axes.some((ax) => ax.n === 0)) {
+            for (const i of rows) {
+                let at = 0, inside = true;
+                for (let d = 0; d < k; d++) {
+                    const ax = axes[d], v = buf[stride * i + cols[d]], x = Math.floor((v - ax.lo) / ax.width + 1e-9);
+                    // The top edge belongs to the last bin; a point past the ends (an explicit extent) is left out.
+                    const idx = v === ax.lo + ax.n * ax.width ? ax.n - 1 : x;
+                    if (idx < 0 || idx >= ax.n) {
+                        inside = false;
+                        break;
+                    }
+                    at = at * ax.n + idx;
+                }
+                if (!inside)
+                    continue;
+                counts[at]++;
+                sums[at] += wcol >= 0 ? buf[stride * i + wcol] : 1;
+            }
+        }
+        // The output: each bin, ascending in the first dimension and then the second…
+        const keepEmpty = (a.empty ?? (k === 1 ? 'keep' : 'omit')) === 'keep';
+        const kept = [];
+        for (let c = 0; c < cells; c++)
+            if (keepEmpty ? counts.length > 0 && axes.every((x) => x.n > 0) : counts[c] > 0)
+                kept.push(c);
+        const m = kept.length;
+        let total = 0;
+        for (const c of kept)
+            total += sums[c];
+        const volume = axes.reduce((p, ax) => p * ax.width, 1);
+        const centres = axes.map(() => new Float64Array(m));
+        const out = Object.fromEntries([...STATS, ...SIZES].map((s) => [s, new Float64Array(m)]));
+        kept.forEach((cell, r) => {
+            let rest = cell;
+            for (let d = k - 1; d >= 0; d--) {
+                const ax = axes[d], idx = rest % ax.n;
+                rest = (rest - idx) / ax.n;
+                centres[d][r] = ax.lo + (idx + 0.5) * ax.width;
+            }
+            const cnt = counts[cell], sum = sums[cell];
+            out.count[r] = cnt;
+            out.sum[r] = sum;
+            out.mean[r] = cnt > 0 ? sum / cnt : NaN;
+            out.fraction[r] = total > 0 ? sum / total : NaN;
+            out.density[r] = total > 0 ? sum / total / volume : NaN;
+            out.width[r] = axes[0].width;
+            out.height[r] = k > 1 ? axes[1].width : NaN;
+        });
+        const value = { centres, columns: out, count: m };
+        this.#cache = { version: this.#version, value };
+        return value;
+    }
+    /** The value column: the statistic for one dimension, else the second dimension's centres. */
+    #value(c) {
+        if (this.#dims.length > 1)
+            return c.centres[1];
+        const stat = this.attrs.stat ?? (this.attrs.weight ? 'sum' : 'count');
+        if (!STATS.includes(stat))
+            fail(`Density: stat is one of ${STATS.join(', ')} (got "${stat}")`);
+        return c.columns[stat];
+    }
+    /** A named channel's column. */
+    #channel(c, name) {
+        const dims = this.#dims, extra = dims.indexOf(name);
+        if (name === 'domain')
+            return c.centres[0];
+        if (extra >= 2)
+            return c.centres[extra];
+        if (STATS.includes(name) || SIZES.includes(name))
+            return c.columns[name];
+        return fail(`Density has no channel "${name}" (it has ${this.channelNames.join(', ')})`);
+    }
+    #extent(a) {
+        let min = Infinity, max = -Infinity;
+        for (const v of a)
+            if (Number.isFinite(v)) {
+                if (v < min)
+                    min = v;
+                if (v > max)
+                    max = v;
+            }
+        return min <= max ? { min, max } : null;
+    }
+    get pointCount() { return this.#compute().count; }
+    domain() {
+        const c = this.#compute(), d = c.centres[0];
+        return d.length > 0 ? { min: d[0], max: d[d.length - 1] } : null;
+    }
+    valueExtent() { return this.#extent(this.#value(this.#compute())); }
+    channelExtent(name) { return this.#extent(this.#channel(this.#compute(), name)); }
+    plan(context) {
+        const c = this.#compute(), want = context.channels.map((n) => this.#channel(c, n)), stride = 2 + want.length;
+        const domain = c.centres[0], value = this.#value(c), count = c.count;
+        return {
+            capacity: count,
+            fill: (out) => {
+                for (let i = 0; i < count; i++) {
+                    out[stride * i] = domain[i];
+                    out[stride * i + 1] = value[i];
+                    for (let j = 0; j < want.length; j++)
+                        out[stride * i + 2 + j] = want[j][i];
+                }
+                const none = { min: Infinity, max: -Infinity };
+                return { count, extents: [this.#extent(domain) ?? none, this.#extent(value) ?? none, ...want.map((w) => this.#extent(w) ?? none)] };
+            },
+        };
+    }
+}

package/dist/dimension.d.ts

@@ -0,0 +1,103 @@
+import { type AnyElement, type BaseAttributes, ChartElement } from './element.ts';
+import type { Extent } from './geometry.ts';
+import { Scale } from './scale.ts';
+/** One mark on an axis: where (`value`), what it says, and whether it is a labelled tick or a minor one. */
+export interface Tick {
+    value: number;
+    label: string;
+    major: boolean;
+}
+export interface DimensionAttributes extends BaseAttributes {
+    /** Fix an end of the range. Beats everything else, including `nice`. */
+    min?: number;
+    /** Fix the top end of the range. Beats everything else, including `nice`. */
+    max?: number;
+    /** Values the range must cover, e.g. `[0]` to anchor a bar-like axis at zero. */
+    include?: readonly number[];
+    /** Extra room at both ends as a fraction of the data's span. */
+    padding?: number;
+    /** Round the ends outwards to tidy tick values. Recommended with a RadarPlane, whose spokes come from the ticks. */
+    nice?: boolean;
+    /** Run from max to min along the axis. */
+    inverted?: boolean;
+    /** The axis title (or, on a `ColorAxis` or `SizeAxis`, the default title of its key). Default: none. */
+    title?: string;
+    /** Ask for about this many ticks, whatever the length. */
+    tickCount?: number;
+    /** Put ticks exactly here (those inside the range are drawn), or at whatever a function of the range returns. Beats `tickStep` and `tickCount`. */
+    ticks?: readonly number[] | ((range: Readonly<Extent>) => readonly number[]);
+    /** Put ticks at every multiple of this step. Beats `tickCount`. */
+    tickStep?: number;
+    /** Turns a tick's number into its label, e.g. (v) => `${v}%`. Default: plain digits, grouped by `locale` if one is set. */
+    format?: (value: number) => string;
+    /** A BCP 47 tag for how this writes its numbers (grouping and decimal mark). Default: the chart's `locale`, else plain digits. A `format` beats it. */
+    locale?: string;
+    /** Called when the view (what pan, zoom or a reset has set) changes: the new range, or null when it is back to the natural one. */
+    onViewChange?: (view: Readonly<Extent> | null) => void;
+}
+/** Anything that turns a data range into 0..1. Its one child is the scale that does the turning. */
+export declare abstract class Dimension<Parent extends AnyElement = AnyElement, A extends DimensionAttributes = DimensionAttributes> extends ChartElement<Parent, [scale: Scale], A> {
+    #private;
+    static attrTypes: {
+        title: 1;
+        tickCount: 2;
+        tickStep: 2;
+        locale: 1;
+        onViewChange: 0;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    private lo;
+    private hi;
+    private resolved;
+    private view;
+    private reachPx;
+    private lengthPx;
+    /** Scratch for `fractionOf`, so a single-value lookup (called per tick) allocates nothing. */
+    private readonly tmp;
+    /** The resolved range after the last layout: the view if one is set, otherwise the natural range. */
+    get range(): Readonly<Extent>;
+    /** True while a view range overrides the natural one. */
+    get isZoomed(): boolean;
+    /** The range pan/zoom has set, which takes effect at the next layout (`range` still holds the last one until then). */
+    get viewRange(): Readonly<Extent> | null;
+    get scale(): Scale;
+    /**
+     * Start a layout pass: forget last pass's contributions. `lengthInPixels` is how long the dimension is expected to be
+     * drawn, which is what turns a reach in pixels into data; 0 (the default) where that is not meaningful.
+     */
+    begin(lengthInPixels?: number): void;
+    /** A series asks for room of `pixels` past the ends of its data, so that marks centred on them are not cut by the plot. Ignored once resolved. */
+    reach(pixels: number): void;
+    /** A series reports the extent it will draw. Ignored once the range is resolved. */
+    contribute(min: number, max: number): void;
+    /** Fix the range for this pass. Does nothing if it is already fixed. */
+    resolve(): void;
+    /**
+     * The range these data extents ask for once the attributes have had their say: `include`, `padding`, fixed
+     * `min` and `max`, what the scale can represent, and tidy ends. With nothing to fit it is 0 to 1.
+     */
+    fit(lo: number, hi: number): Extent;
+    /** Temporary range override (pan/zoom). `null` returns to the attribute-driven range. */
+    setViewRange(range: Extent | null): void;
+    /** In place over an interleaved buffer (the hot path), applying `inverted` after the scale. */
+    normalize(buffer: Float64Array, count: number, stride: number, offset: number): void;
+    denormalize(fraction: number): number;
+    /** Position of one value along the dimension, 0..1. */
+    fractionOf(value: number): number;
+    /**
+     * One value as text, the way this dimension would label a tick but with the precision a reading needs: its `format`,
+     * else its scale's own labelling (a band's category name), else the number to five significant figures.
+     */
+    formatValue(value: number): string;
+    /** Where the ticks are: the attributes' say if they have one, else the scale's choice of about `count`. Always inside the range. */
+    private tickValues;
+    /** Overridden by dimensions that know their length matters (an axis wants more ticks when longer). */
+    protected tickCountFor(_lengthInPixels: number): number;
+    /** The ticks for a dimension drawn `lengthInPixels` long. `tickCount` wins; else `count`; else a number that suits the length. */
+    getTicks(lengthInPixels: number, count?: number): readonly Tick[];
+}

package/dist/dimension.js

@@ -0,0 +1,205 @@
+/**
+ * A dimension: a scale plus the range it covers, the view into it, and how it fits data.
+ *
+ * How a range gets decided (the "fit protocol"), because several elements take part:
+ *   1. The plane calls `begin()` on each dimension to forget last layout's data.
+ *   2. Each series `contribute()`s the extent it will draw (for the value axis, only the part inside the view).
+ *   3. The plane calls `resolve()`, which fixes the range once: a pan/zoom `view` wins, otherwise `fit()` applies the
+ *      attributes (`min`/`max`/`include`/`padding`/`nice`) to what was contributed.
+ * After `resolve()` further contributions are ignored, which is what lets a series' domain window depend on the domain
+ * dimension's resolved range while still being allowed to contribute to the value dimension afterwards.
+ */
+import { AUTO, NUMBER, STRING } from './attrs.js';
+import { ChartElement } from './element.js';
+import { Scale } from './scale.js';
+const numberFormats = new Map();
+/** A cached `Intl.NumberFormat`: tick labels are made often, and building one is the slow part. */
+function numberFormat(locale, options) {
+    const key = locale + JSON.stringify(options);
+    let f = numberFormats.get(key);
+    if (!f) {
+        f = new Intl.NumberFormat(locale, options);
+        numberFormats.set(key, f);
+    }
+    return f;
+}
+/** Anything that turns a data range into 0..1. Its one child is the scale that does the turning. */
+export class Dimension extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, title: STRING, tickCount: NUMBER, tickStep: NUMBER, locale: STRING, onViewChange: AUTO };
+    #range = { min: 0, max: 1 };
+    lo = Infinity;
+    hi = -Infinity;
+    resolved = false;
+    view = null;
+    // The most room in pixels any series asks beyond the ends of its data (a marker's radius), and the axis' length to turn it into data.
+    reachPx = 0;
+    lengthPx = 0;
+    /** Scratch for `fractionOf`, so a single-value lookup (called per tick) allocates nothing. */
+    tmp = new Float64Array(1);
+    /** The resolved range after the last layout: the view if one is set, otherwise the natural range. */
+    get range() { return this.#range; }
+    /** True while a view range overrides the natural one. */
+    get isZoomed() { return this.view !== null; }
+    /** The range pan/zoom has set, which takes effect at the next layout (`range` still holds the last one until then). */
+    get viewRange() { return this.view; }
+    get scale() { return this.child(0, Scale); }
+    // ─── Engine protocol: a plane and its series negotiate the range through these. ───
+    /**
+     * Start a layout pass: forget last pass's contributions. `lengthInPixels` is how long the dimension is expected to be
+     * drawn, which is what turns a reach in pixels into data; 0 (the default) where that is not meaningful.
+     */
+    begin(lengthInPixels = 0) { this.lo = Infinity; this.hi = -Infinity; this.resolved = false; this.reachPx = 0; this.lengthPx = lengthInPixels; }
+    /** A series asks for room of `pixels` past the ends of its data, so that marks centred on them are not cut by the plot. Ignored once resolved. */
+    reach(pixels) { if (!this.resolved && pixels > this.reachPx)
+        this.reachPx = pixels; }
+    /** A series reports the extent it will draw. Ignored once the range is resolved. */
+    contribute(min, max) {
+        if (this.resolved)
+            return;
+        if (min < this.lo)
+            this.lo = min;
+        if (max > this.hi)
+            this.hi = max;
+    }
+    /** Fix the range for this pass. Does nothing if it is already fixed. */
+    resolve() {
+        if (this.resolved)
+            return;
+        this.resolved = true;
+        this.#range = this.view ?? this.fit(this.lo, this.hi);
+    }
+    /**
+     * The range these data extents ask for once the attributes have had their say: `include`, `padding`, fixed
+     * `min` and `max`, what the scale can represent, and tidy ends. With nothing to fit it is 0 to 1.
+     */
+    fit(lo, hi) {
+        const a = this.attrs, scale = this.scale;
+        for (const v of a.include ?? []) {
+            if (v < lo)
+                lo = v;
+            if (v > hi)
+                hi = v;
+        }
+        // Nothing contributed (no data yet): a unit range keeps every downstream division finite.
+        if (!(lo <= hi)) {
+            lo = 0;
+            hi = 1;
+        }
+        const span = hi - lo;
+        if (a.padding && span > 0) {
+            lo -= span * a.padding;
+            hi += span * a.padding;
+        }
+        let r = { min: a.min ?? lo, max: a.max ?? hi };
+        // A flat line has zero span; open it up so the scale has something to divide by.
+        if (r.min === r.max) {
+            const d = r.min === 0 ? 1 : Math.abs(r.min) * 0.1;
+            r = { min: r.min - d, max: r.max + d };
+        }
+        r = scale.constrain(r);
+        // Room for what reaches past the ends of the data: the same number of pixels at each end, in the scale's own terms.
+        // An end the attributes fixed is left where it was put.
+        const m = this.reachPx, L = this.lengthPx;
+        if (m > 0 && L > 2 * m + 1 && (a.min === undefined || a.max === undefined)) {
+            const f = m / (L - 2 * m), lo2 = scale.denormalize(-f, r), hi2 = scale.denormalize(1 + f, r);
+            r = scale.constrain({ min: a.min ?? (Number.isFinite(lo2) ? lo2 : r.min), max: a.max ?? (Number.isFinite(hi2) ? hi2 : r.max) });
+        }
+        if (a.nice) {
+            const n = scale.nice(r);
+            r = { min: a.min ?? n.min, max: a.max ?? n.max };
+        }
+        return r;
+    }
+    /** Temporary range override (pan/zoom). `null` returns to the attribute-driven range. */
+    setViewRange(range) {
+        const old = this.view;
+        if (old === range || (old && range && old.min === range.min && old.max === range.max))
+            return;
+        this.view = range;
+        this.invalidate();
+        this.attrs.onViewChange?.(range);
+    }
+    /** In place over an interleaved buffer (the hot path), applying `inverted` after the scale. */
+    normalize(buffer, count, stride, offset) {
+        this.scale.normalize(buffer, count, stride, offset, this.range);
+        if (this.attrs.inverted) {
+            // 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)
+                buffer[i] = 1 - buffer[i];
+        }
+    }
+    denormalize(fraction) {
+        return this.scale.denormalize(this.attrs.inverted ? 1 - fraction : fraction, this.range);
+    }
+    /** Position of one value along the dimension, 0..1. */
+    fractionOf(value) {
+        this.tmp[0] = value;
+        this.normalize(this.tmp, 1, 1, 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
+        return this.tmp[0];
+    }
+    /**
+     * One value as text, the way this dimension would label a tick but with the precision a reading needs: its `format`,
+     * else its scale's own labelling (a band's category name), else the number to five significant figures.
+     */
+    formatValue(value) {
+        const a = this.attrs;
+        if (a.format)
+            return a.format(value);
+        const label = this.scale.label?.(value);
+        if (label !== undefined)
+            return label;
+        const locale = a.locale ?? this.chart?.attrs.locale;
+        if (locale)
+            return numberFormat(locale, Math.abs(value) >= 1e5 ? { maximumFractionDigits: 0 } : { maximumSignificantDigits: 5 }).format(value);
+        return Math.abs(value) >= 1e5 ? value.toFixed(0) : String(+value.toPrecision(5));
+    }
+    /** A tick's number as plain text, or in the locale's way if there is one. */
+    #plain(value, decimals) {
+        const locale = this.attrs.locale ?? this.chart?.attrs.locale;
+        return locale ? numberFormat(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals }).format(value) : value.toFixed(decimals);
+    }
+    /** Where the ticks are: the attributes' say if they have one, else the scale's choice of about `count`. Always inside the range. */
+    tickValues(count) {
+        const a = this.attrs, r = this.range, lo = Math.min(r.min, r.max), hi = Math.max(r.min, r.max);
+        const eps = (hi - lo) * 1e-9;
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- the attribute type with its default filled in
+        const explicit = a.ticks;
+        if (explicit) {
+            const given = typeof explicit === 'function' ? explicit(r) : explicit;
+            return given.filter((v) => v >= lo - eps && v <= hi + eps);
+        }
+        if (a.tickStep && a.tickStep > 0) {
+            const out = [], step = a.tickStep;
+            for (let k = Math.ceil(lo / step - 1e-9); k * step <= hi + eps && out.length < 1000; k++)
+                out.push(Number((k * step).toPrecision(12)));
+            return out;
+        }
+        return this.scale.ticks(r, count);
+    }
+    /** Overridden by dimensions that know their length matters (an axis wants more ticks when longer). */
+    tickCountFor(_lengthInPixels) { return 5; }
+    /** The ticks for a dimension drawn `lengthInPixels` long. `tickCount` wins; else `count`; else a number that suits the length. */
+    getTicks(lengthInPixels, count) {
+        const a = this.attrs;
+        count = a.tickCount ?? count ?? this.tickCountFor(lengthInPixels);
+        const values = this.tickValues(count);
+        let step = values.length > 1 ? Infinity : Math.abs(this.range.max - this.range.min) || 1;
+        // 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 = 1; i < values.length; i++) {
+            const d = Math.abs(values[i] - values[i - 1]);
+            if (d > 0 && d < step)
+                step = d;
+        }
+        // Enough decimals to tell neighbouring ticks apart, and the same for all so the labels line up.
+        const decimals = Math.min(10, Math.max(0, Math.ceil(-Math.log10(step) - 1e-9)));
+        const set = !a.format ? this.scale.labels?.(values, this.range) : undefined;
+        return values.map((value, i) => {
+            // 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
+            let label = a.format ? a.format(value) : set ? set[i] : this.scale.label?.(value) ?? this.#plain(value, decimals);
+            if (label === '-0')
+                label = '0'; // toFixed keeps the sign of a tiny negative
+            return { value, label, major: true };
+        });
+    }
+}

package/dist/dom-platform.d.ts

@@ -0,0 +1,53 @@
+/** The browser platform: renders into a real SVG element and listens for resize and pointer input. */
+import type { Size } from './geometry.ts';
+import { type Platform, type PlatformNode, type RawFocus, type RawKey, type RawPointer, type SvgTag, type TextMeasurer, type Unsubscribe } from './platform.ts';
+/** The part of an element the DOM platform needs. A real `HTMLElement` fits. */
+export interface DOMContainer {
+    readonly ownerDocument: {
+        createElementNS(namespace: string, tag: string): unknown;
+    };
+    readonly clientWidth: number;
+    readonly clientHeight: number;
+    appendChild(node: unknown): unknown;
+}
+/** Choices that differ between pages: a fixed size for static layouts, canvas-free text metrics, and flush timing. */
+export interface DOMPlatformOptions {
+    /** A fixed size. Default: the container's own size, followed as it changes. */
+    size?: Size;
+    /** Measure labels with the browser rather than estimating them. Default true. */
+    preciseText?: boolean;
+    /** When to flush after an invalidation. Default 'frame'. 'manual' leaves it to `chart.flush()`. */
+    schedule?: 'frame' | 'microtask' | 'manual' | ((callback: () => void) => Unsubscribe);
+}
+/**
+ * Draws into a live `<svg>` appended to a container, and reports the container's size and pointer input on it.
+ * The container needs a height of its own; without one the platform assumes 600 wide by 300 high.
+ * Pointer events are captured while a button is down. Once something in the chart listens for the pointer (the chart then
+ * subscribes through `onPointer`) the svg sets `touch-action: none`, so a drag or a wheel turn over the chart belongs to the
+ * chart (`setTouchMode('two-finger')` lets one finger scroll the page instead); until then it sets none, and the chart is a picture.
+ */
+export declare class DOMPlatform implements Platform {
+    #private;
+    readonly name = "dom";
+    readonly root: PlatformNode;
+    schedule?: (callback: () => void) => Unsubscribe;
+    measureText?: TextMeasurer;
+    constructor(container: DOMContainer, options?: DOMPlatformOptions);
+    /** `|| 600` / `|| 300`: a container that has not been laid out yet reports 0, which would give an unusable chart. */
+    size(): Size;
+    createNode(tag: SvgTag): PlatformNode;
+    setAttribute(node: PlatformNode, name: string, value: string | number): void;
+    setText(node: PlatformNode, text: string): void;
+    insertBefore(parent: PlatformNode, node: PlatformNode, before: PlatformNode | null): void;
+    remove(node: PlatformNode): void;
+    setCursor(cursor: string): void;
+    setTouchMode(mode: 'always' | 'two-finger'): void;
+    onResize(callback: (size: Size) => void): Unsubscribe;
+    onPointer(callback: (pointer: RawPointer) => boolean | void): Unsubscribe;
+    onKey(callback: (key: RawKey, node: PlatformNode) => boolean | void): Unsubscribe;
+    onFocus(callback: (focus: RawFocus) => void): Unsubscribe;
+    /** A visually hidden live region beside the chart: SVG text is not reliably announced when it changes, an HTML status is. */
+    announce(text: string): void;
+    focus(node: PlatformNode): void;
+    dispose(): void;
+}