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

package/dist/series.js

@@ -0,0 +1,513 @@
+/**
+ * Series: a data pipeline, the axes it reads through, and the renderers that draw it.
+ *
+ * A series is two things. The base class is everything about getting points from a source and into plot pixels; a
+ * subclass says which axes the first and second coordinate ride on, and which columns of the data they come from.
+ *
+ *  - `DomainSeries`: the domain goes along one axis and the value along another, as in a line chart, or round and out
+ *    on a polar plane. Points are windowed to the visible domain.
+ *  - `XYSeries`: two values, one on each axis, in the order the source holds them. The source's domain is only the
+ *    order (by default the row's index), so a path can cross itself and a scatter needs none.
+ *
+ * Whichever it is, renderers are handed the same thing: `points`, laid out `[first, second, ...bound channels]` in plot
+ * pixels, so they never need to know.
+ *
+ * The life of a point, and who owns each step (so a change lands in the right place)
+ * ─────────────────────────────────────────────────────────────────────────────────
+ *   data stage ──fill──▶ raw buffer ──gather columns──▶ points ──axis.normalize──▶ 0..1 ──plane.place──▶ pixels
+ *   (source, Decimator)  (this class;   (this class;    (this     (Axis: scale,      (Plane: Cartesian
+ *                         cached by key)  `project`)      class)    inversion)         rectangle, polar, radar)
+ * The raw buffer is filled once per change of data, window or width (`fill`) and is *not* touched by projection, so
+ * resizing the plot or panning a value axis only re-runs the cheap normalise-and-place tail (`project`). Subclasses
+ * choose which raw columns are the two coordinates; nothing after the gather step knows how they were chosen.
+ */
+/* oxlint-disable typescript/no-non-null-assertion -- stride-addressed rows of the managed buffers: every index is bounded by the row count */
+import { STRING } from './attrs.js';
+import { Axis } from './axis.js';
+import { DataSource, DataTransform } from './data.js';
+import { ChartElement, fail, resolveRef } from './element.js';
+import { writeAria } from './aria.js';
+import { EVENT_ATTACH, EVENT_PAINT } from './events.js';
+import { SeriesRenderer } from './renderer.js';
+/** 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 function groupOf(child) {
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- `members` was probed on the line above
+    return typeof child === 'object' && child !== null && 'members' in child ? child : null;
+}
+/** The series a plane child stands for: itself, the members of a group, or none. */
+export function seriesOf(child) {
+    if (child instanceof Series)
+        return [child];
+    return groupOf(child)?.members ?? [];
+}
+/** What `points` is before the first projection, so renderers never need a null check. */
+const NO_DRAWN_POINTS = { data: new Float64Array(0), stride: 2, count: 0 };
+/** The contribution of a column the fill did not report (never happens for a valid source); NaN is ignored by axes. */
+const NO_EXTENT = { min: NaN, max: NaN };
+/** The shared pipeline: raw fill (cached), column gather, normalise, place. Subclasses say which columns and axes. */
+export class Series extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, name: STRING };
+    // The projected points handed to renderers; grown as needed and reused so a redraw allocates nothing.
+    #points = null;
+    // The unprojected fill, with the key it was made for: data version, window, width and requested columns.
+    #raw = new Float64Array(0);
+    #rawCount = 0;
+    #extents = [];
+    #rowOf = null;
+    #key = '';
+    #stride = 2;
+    // For `baseline`: the plane of the last projection, a counter that says whether it moved, and the cached result.
+    #plane = null;
+    #projections = 0;
+    #base = { data: new Float64Array(0), stride: 2, count: 0 };
+    #baseKey = '';
+    // A stack's say over this series: the shift of its rows, and a table of rows lined up with the others' (else its own).
+    #layer = null;
+    #aligned = null;
+    /** Whether a missing value is drawn as 0 (not in a stack, which has its own say). */
+    get #zero() { return this.attrs.gaps === 'zero' && this.#layer === null; }
+    /** The plane this series is drawn on, which is its parent unless a stack sits between them. */
+    get plane() {
+        const p = this.requireParent();
+        // oxlint-disable-next-line typescript/consistent-type-assertions -- `members` was probed in the condition: this is the series group's plane
+        return 'members' in p ? p.requireParent() : p;
+    }
+    /** The rows drawn from: a stack's lined-up table when it made one, else the series' own fill. */
+    rows() {
+        return this.#aligned ?? { raw: this.#raw, count: this.#rawCount, stride: this.#stride, rowOf: this.#rowOf };
+    }
+    /** Engine protocol for a `Stack`: the series' own fill as it stands (call after `prepare`). */
+    ownRows() { return { raw: this.#raw, count: this.#rawCount, stride: this.#stride, rowOf: this.#rowOf }; }
+    /** 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, rows) { this.#layer = layer; this.#aligned = rows; }
+    /** What a stack has made of this series, if it is in one. */
+    get layer() { return this.#layer; }
+    get data() { return this.child(0, DataSource, DataTransform); }
+    /**
+     * 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() {
+        const names = new Set();
+        for (const r of this)
+            if (r instanceof SeriesRenderer) {
+                for (const b of r.bindings)
+                    names.add(b.channel);
+                for (const c of r.channelNames)
+                    names.add(c);
+            }
+        return [...names];
+    }
+    /**
+     * 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() {
+        const palette = (this.chart ?? fail('series is not in a chart')).attrs.theme.palette;
+        const index = Math.max(0, this.plane.allSeries.indexOf(this));
+        return palette[index % palette.length] ?? '#888';
+    }
+    /** 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() { return this.attrs.visible !== false; }
+    /**
+     * 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, parent, key, width, height) {
+        let n = 0;
+        for (const r of this)
+            if (r instanceof SeriesRenderer)
+                r.sample(surface, parent, `${key}/${n++}`, width, height);
+    }
+    /**
+     * 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() {
+        for (const r of this)
+            if (r instanceof SeriesRenderer) {
+                const c = r.swatch;
+                if (c && c !== 'none')
+                    return c;
+            }
+        return this.accentColor;
+    }
+    /** What the first renderer that has an opinion says a hit on this series should measure: bars say the shapes they draw. */
+    get hitHint() {
+        for (const r of this)
+            if (r instanceof SeriesRenderer && r.hitMode)
+                return r.hitMode;
+        return undefined;
+    }
+    /** The shapes the series draws, as polygons in plot pixels, if a renderer draws any (bars): what a 'shape' hit is inside. */
+    shapes() {
+        for (const r of this)
+            if (r instanceof SeriesRenderer) {
+                const g = r.shapes?.();
+                if (g)
+                    return g;
+            }
+        return 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() {
+        for (const r of this)
+            if (r instanceof SeriesRenderer) {
+                const t = r.trace?.();
+                if (t)
+                    return t;
+            }
+        return 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() { return this.#projections; }
+    /** The last projected points, in plot pixels: `[first, second, ...channels]` in each row of `points.stride` numbers. */
+    get points() { return this.#points ?? NO_DRAWN_POINTS; }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_ATTACH:
+                this.surface.wrapper(); // carries the clip
+                break;
+            case EVENT_PAINT: {
+                const clip = this.plane.clipUrl;
+                if (clip)
+                    this.surface.set(this.surface.wrapper(), 'clip-path', clip);
+                writeAria(this.surface, this.surface.wrapper(), this.attrs.meta, { role: 'group' });
+                break;
+            }
+        }
+    }
+    /**
+     * 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() {
+        const plane = this.#plane, points = this.#points;
+        if (!plane || !points)
+            return null;
+        const rows = this.rows(), layer = this.#layer;
+        return {
+            plane, points, raw: rows.raw, stride: rows.stride, firstColumn: this.firstColumn, secondColumn: this.secondColumn,
+            channels: this.channels, rowOf: rows.rowOf, alongDomain: this.alongDomain,
+            base: layer?.base ?? null, top: layer?.top ?? null, slot: layer?.slot ?? { index: 0, count: 1 }, additive: layer?.additive ?? true,
+        };
+    }
+    /** Whether the first coordinate is a position along the line, so that a value can be read between two points. */
+    get alongDomain() { return false; }
+    // ─── Engine protocol: the plane calls these, in this order, each pass. ───
+    /**
+     * 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.
+     */
+    fill(ctx) {
+        const data = this.data, counters = this.counters;
+        const stride = 2 + ctx.channels.length;
+        const key = `${data.version}|${ctx.domainRange.min}|${ctx.domainRange.max}|${ctx.width}|${ctx.channels.join()}`;
+        if (key === this.#key) {
+            counters.cached++;
+        }
+        else {
+            const t0 = performance.now(), d0 = counters.stages.decimate;
+            const plan = data.plan(ctx);
+            if (this.#raw.length < plan.capacity * stride)
+                this.#raw = new Float64Array(plan.capacity * stride);
+            const result = plan.fill(this.#raw);
+            this.#rawCount = result.count;
+            this.#rowOf = result.rowOf ?? null;
+            this.#extents = result.extents;
+            this.#key = key;
+            this.#stride = stride;
+            counters.filled++;
+            counters.pointsIn += data.pointCount;
+            counters.stages.generate += performance.now() - t0 - (counters.stages.decimate - d0);
+        }
+        return this.#extents;
+    }
+    /**
+     * 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.
+     */
+    contributeReach() {
+        let px = 0;
+        for (const r of this)
+            if (r instanceof SeriesRenderer && r.reach > px)
+                px = r.reach;
+        if (px > 0) {
+            this.firstAxis.reach(px);
+            this.secondAxis.reach(px);
+        }
+    }
+    /** The largest `spans` of the renderers: how far they draw beyond a point along the domain, as a fraction of the gap between points. */
+    get spans() {
+        let m = 0;
+        for (const r of this)
+            if (r instanceof SeriesRenderer && r.spans > m)
+                m = r.spans;
+        return m;
+    }
+    /**
+     * 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.
+     */
+    contributeChannels() {
+        if (this.#zero) {
+            const { raw, count: n, stride: rs } = this.rows(), c = this.secondColumn;
+            for (let i = 0; i < n; i++)
+                if (!Number.isFinite(raw[i * rs + c])) {
+                    this.secondAxis.contribute(0, 0);
+                    break;
+                }
+        }
+        // Values a renderer needs on the value axis whatever the data says: the baseline bars grow from.
+        for (const r of this)
+            if (r instanceof SeriesRenderer)
+                for (const v of r.includes)
+                    this.secondAxis.contribute(v, v);
+        // What renderers draw beyond the values (error bars) is part of what the axes must show.
+        const view = this.spreadView();
+        for (const r of this) {
+            if (!(r instanceof SeriesRenderer) || !r.spread)
+                continue;
+            const s = r.spread(view);
+            if (s?.first)
+                this.firstAxis.contribute(s.first.min, s.first.max);
+            if (s?.second)
+                this.secondAxis.contribute(s.second.min, s.second.max);
+        }
+        for (const r of this) {
+            if (!(r instanceof SeriesRenderer))
+                continue;
+            for (const b of r.bindings) {
+                const e = this.data.channelExtent(b.channel);
+                if (e)
+                    b.axis.contribute(e.min, e.max);
+            }
+        }
+    }
+    /** The rows as a renderer's `spread` sees them. */
+    spreadView() {
+        const { raw, count, stride } = this.rows(), channels = this.channels, layer = this.#layer;
+        const first = channels.length === 0 ? stride : stride - channels.length;
+        return {
+            raw, count, stride, firstColumn: this.firstColumn, secondColumn: this.secondColumn, top: layer?.top ?? null,
+            channelColumn: (name) => { const k = channels.indexOf(name); return k < 0 ? -1 : first + k; },
+        };
+    }
+    /** An axis' natural extent: the data's, widened by what the renderers draw beyond it. Zooming is held to this. */
+    widened(axis, base) {
+        let e = base;
+        if (this.#layer)
+            return e;
+        for (const r of this) {
+            if (!(r instanceof SeriesRenderer) || !r.limit)
+                continue;
+            const s = r.limit(this), w = axis === this.firstAxis ? s?.first : axis === this.secondAxis ? s?.second : undefined;
+            if (w)
+                e = e ? { min: Math.min(e.min, w.min), max: Math.max(e.max, w.max) } : w;
+        }
+        return e;
+    }
+    /**
+     * 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) {
+        const counters = this.counters, first = this.firstAxis, second = this.secondAxis;
+        const { raw, count: n, stride: rs } = this.rows(), layer = this.#layer;
+        const c0 = this.firstColumn, c1 = this.secondColumn, bound = this.channels.length, stride = 2 + bound;
+        if (!this.#points || this.#points.data.length < n * stride)
+            this.#points = { data: new Float64Array(n * stride), stride, count: 0 };
+        const p = this.#points;
+        p.stride = stride;
+        p.count = n;
+        if (c0 === 0 && c1 === 1 && rs === stride) {
+            p.data.set(raw.subarray(0, n * stride));
+        }
+        else {
+            // The coordinates are not the first two columns: gather them, then the bound channels, which come last.
+            const channels = rs - bound;
+            for (let i = 0; i < n; i++) {
+                p.data[i * stride] = raw[i * rs + c0];
+                p.data[i * stride + 1] = raw[i * rs + c1];
+                for (let k = 0; k < bound; k++)
+                    p.data[i * stride + 2 + k] = raw[i * rs + channels + k];
+            }
+        }
+        if (this.#zero)
+            for (let i = 0; i < n; i++) {
+                const v = p.data[i * stride + 1];
+                if (!Number.isFinite(v) && Number.isFinite(p.data[i * stride]))
+                    p.data[i * stride + 1] = 0;
+            }
+        // In a stack a point is drawn where the stack puts it: the row's own value has already served its purpose.
+        if (layer)
+            for (let i = 0; i < n; i++) {
+                const v = p.data[i * stride + 1];
+                p.data[i * stride + 1] = Number.isFinite(v) ? layer.top[i] : NaN;
+            }
+        let t = performance.now();
+        first.normalize(p.data, n, stride, 0);
+        second.normalize(p.data, n, stride, 1);
+        counters.stages.normalize += performance.now() - t;
+        t = performance.now();
+        plane.place(p, first, second);
+        counters.stages.place += performance.now() - t;
+        counters.projected++;
+        counters.pointsDrawn += n;
+        this.#plane = plane;
+        this.#projections++;
+    }
+    /**
+     * 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) {
+        const plane = this.#plane ?? fail('series has not been projected'), { raw, count: n, stride: rs } = this.rows(), layer = this.#layer;
+        const key = `${this.#projections}|${value}`;
+        if (key === this.#baseKey)
+            return this.#base;
+        this.#baseKey = key;
+        if (this.#base.data.length < n * 2)
+            this.#base.data = new Float64Array(n * 2);
+        const b = this.#base, c0 = this.firstColumn, c1 = this.secondColumn;
+        b.count = n;
+        for (let i = 0; i < n; i++) {
+            b.data[2 * i] = raw[i * rs + c0];
+            // A gap in the data stays a gap in the baseline.
+            // In a stack the baseline is the layer below, row by row, and `value` is not asked.
+            b.data[2 * i + 1] = Number.isFinite(raw[i * rs + c1]) || (this.#zero && Number.isFinite(raw[i * rs + c0])) ? (layer ? layer.base[i] : value) : NaN;
+        }
+        this.firstAxis.normalize(b.data, n, 2, 0);
+        this.secondAxis.normalize(b.data, n, 2, 1);
+        // Keep the baseline inside its axis, so a fill to a value outside the range closes along the edge.
+        for (let i = 1; i < 2 * n; i += 2) {
+            const v = b.data[i];
+            if (v < 0)
+                b.data[i] = 0;
+            else if (v > 1)
+                b.data[i] = 1;
+        }
+        plane.place(b, this.firstAxis, this.secondAxis);
+        return b;
+    }
+}
+/**
+ * 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 class DomainSeries extends Series {
+    static attrTypes = { ...Series.attrTypes, domainAxis: STRING, valueAxis: STRING };
+    #domainAxis = null;
+    #valueAxis = null;
+    get domainAxis() { return this.#domainAxis ?? fail('series has not been laid out'); }
+    get valueAxis() { return this.#valueAxis ?? fail('series has not been laid out'); }
+    get firstAxis() { return this.domainAxis; }
+    get secondAxis() { return this.valueAxis; }
+    get firstColumn() { return 0; }
+    get secondColumn() { return 1; }
+    get alongDomain() { return true; }
+    resolveAxes(plane) {
+        const a = this.attrs;
+        this.#domainAxis = resolveRef(a.domainAxis, this, Axis) ?? plane.defaultAxis('first') ?? fail('plane has no axis for the domain');
+        this.#valueAxis = resolveRef(a.valueAxis, this, Axis) ?? plane.defaultAxis('second') ?? fail('plane has no axis for the value');
+    }
+    contributeDomain() {
+        const d = this.data.domain(), n = this.data.pointCount, spans = this.spans;
+        if (d) {
+            // Bars centred on the first and last points reach half a bar past them: the mean gap is what is known before reading.
+            const room = spans > 0 && n > 1 && !('bandwidth' in this.domainAxis.scale) ? (spans * (d.max - d.min)) / (n - 1) : 0;
+            this.domainAxis.contribute(d.min - room, d.max + room);
+        }
+        this.contributeReach();
+    }
+    resolveDomain() { this.domainAxis.resolve(); }
+    load(estimate) {
+        const ext = this.fill({ ...estimate, domainRange: this.domainAxis.range, channels: this.channels })[1] ?? NO_EXTENT;
+        this.valueAxis.contribute(ext.min, ext.max);
+        this.contributeChannels();
+    }
+    /** 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) {
+        this.fill({ ...estimate, domainRange: this.domainAxis.range, channels: this.channels });
+        return this.ownRows();
+    }
+    /** Engine protocol for a `Stack`: the rest of `load`, with the value extent the stack worked out for its stacked values. */
+    settle(extent) {
+        if (extent)
+            this.valueAxis.contribute(extent.min, extent.max);
+        this.contributeChannels();
+    }
+    ownExtent(role) { return role === 'first' ? this.data.domain() : this.data.valueExtent(); }
+    extentFor(axis) {
+        if (axis === this.valueAxis && this.layer)
+            return this.layer.extent;
+        return axis === this.domainAxis ? this.widened(axis, this.data.domain()) : axis === this.valueAxis ? this.widened(axis, this.data.valueExtent()) : null;
+    }
+}
+/**
+ * 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 class XYSeries extends Series {
+    static attrTypes = { ...Series.attrTypes, xAxis: STRING, yAxis: STRING };
+    #xAxis = null;
+    #yAxis = null;
+    get xAxis() { return this.#xAxis ?? fail('series has not been laid out'); }
+    get yAxis() { return this.#yAxis ?? fail('series has not been laid out'); }
+    get firstAxis() { return this.xAxis; }
+    get secondAxis() { return this.yAxis; }
+    // The data is [order, y, x, ...bound channels]: x is asked for ahead of the channels the renderers bind.
+    get firstColumn() { return 2; }
+    get secondColumn() { return 1; }
+    resolveAxes(plane) {
+        const a = this.attrs;
+        this.#xAxis = resolveRef(a.xAxis, this, Axis) ?? plane.defaultAxis('first') ?? fail('plane has no axis for x');
+        this.#yAxis = resolveRef(a.yAxis, this, Axis) ?? plane.defaultAxis('second') ?? fail('plane has no axis for y');
+    }
+    // An order has no extent to agree on before reading, so there is nothing to do ahead of `load`.
+    contributeDomain() { this.contributeReach(); }
+    resolveDomain() { }
+    load(estimate) {
+        const ext = this.fill({
+            ...estimate, domainRange: { min: -Infinity, max: Infinity }, sequence: true, channels: [this.attrs.x, ...this.channels],
+        });
+        const x = ext[2] ?? NO_EXTENT, y = ext[1] ?? NO_EXTENT;
+        this.xAxis.contribute(x.min, x.max);
+        this.yAxis.contribute(y.min, y.max);
+        this.contributeChannels();
+    }
+    ownExtent(role) { return role === 'first' ? this.data.channelExtent(this.attrs.x) : this.data.valueExtent(); }
+    extentFor(axis) {
+        return axis === this.xAxis ? this.widened(axis, this.data.channelExtent(this.attrs.x)) : axis === this.yAxis ? this.widened(axis, this.data.valueExtent()) : null;
+    }
+}
+/**
+ * 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 function paintSample(surface, key, series, x, y, width, height, cache) {
+    let renderers = 0;
+    for (const r of series)
+        if (r instanceof SeriesRenderer)
+            renderers++;
+    const last = cache.get(key);
+    if (!last || last.series !== series || last.renderers !== renderers) {
+        surface.removePrefix(key);
+        cache.set(key, { series, renderers });
+    }
+    const group = surface.node(key, 'g');
+    surface.set(group, 'transform', `translate(${Math.round(x * 100) / 100} ${Math.round(y * 100) / 100})`);
+    series.sample(surface, group, key, width, height);
+    return group;
+}

package/dist/simple.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shortcuts for the common cases. These only compose the public classes (a series, a renderer, optionally a decimator and a
+ * marker), so everything they do can be done, and tuned, with the elements themselves.
+ */
+import { type Curve } from './curve.ts';
+import type { Axis } from './axis.ts';
+import type { DataNode } from './data.ts';
+import { type DecimationKernel } from './decimation.ts';
+import type { ElementRef } from './element.ts';
+import { type SeriesRenderer } from './renderer.ts';
+import { DomainSeries } from './series.ts';
+/**
+ * The handful of choices a quick line chart needs. A marker and a kernel are given as the classes themselves
+ * (`marker: CircleMarker`, `decimate: M4Kernel`), not as names, so that this module only refers to what you pass it: a
+ * bundle that never decimates carries no kernel, and one that draws no markers carries no marker. For anything the
+ * options do not cover, such as a marker's size or a kernel's settings, build the elements directly.
+ */
+export interface LineSeriesOptions {
+    stroke?: string;
+    strokeWidth?: number;
+    domainAxis?: ElementRef<Axis>;
+    valueAxis?: ElementRef<Axis>;
+    /** Draw a marker of this class at every point: `CircleMarker`. */
+    marker?: new (attrs: {
+        stroke?: string;
+    }) => SeriesRenderer;
+    /** The markers' stroke. Default the line's `stroke`, else the series' palette colour. */
+    markerStroke?: string;
+    /** Wrap the source in a decimator with a kernel of this class: `MinMaxKernel`, `M4Kernel`. */
+    decimate?: new () => DecimationKernel;
+    /** How the points are joined: a curve of any kind (`new MonotoneCurve()`, `new StepCurve({ mode: 'after' })`). Default straight lines. */
+    curve?: Curve;
+}
+/** A series with a line renderer: the common case in one call. */
+export declare function lineSeries(source: DataNode, options?: LineSeriesOptions): DomainSeries;

package/dist/simple.js

@@ -0,0 +1,20 @@
+/**
+ * Shortcuts for the common cases. These only compose the public classes (a series, a renderer, optionally a decimator and a
+ * marker), so everything they do can be done, and tuned, with the elements themselves.
+ */
+import { LinearCurve } from './curve.js';
+import { Decimator } from './decimation.js';
+import { LinePath } from './renderer.js';
+import { DomainSeries } from './series.js';
+/** A series with a line renderer: the common case in one call. */
+export function lineSeries(source, options = {}) {
+    const { stroke, strokeWidth, domainAxis, valueAxis, marker, markerStroke, decimate, curve } = options;
+    const line = new LinePath({ ...(stroke !== undefined && { stroke }), ...(strokeWidth !== undefined && { strokeWidth }) }, curve ?? new LinearCurve());
+    const attrs = {
+        ...(domainAxis !== undefined && { domainAxis }),
+        ...(valueAxis !== undefined && { valueAxis }),
+    };
+    const data = decimate ? new Decimator({}, new decimate(), source) : source;
+    const mark = markerStroke ?? stroke;
+    return marker ? new DomainSeries(attrs, data, line, new marker(mark === undefined ? {} : { stroke: mark })) : new DomainSeries(attrs, data, line);
+}