@peter.prib/renderengine 0.1.0 → 0.2.0

package/src/charting/charts/KpiTile.js

@@ -0,0 +1,72 @@
+import { GaugeChart } from './GaugeChart.js';
+import { Sparkline } from '../gauges/Sparkline.js';
+
+/**
+ * KpiTile — a key figure on a card: its title, its value large, the change
+ * since the previous value (▲ / ▼, coloured good or bad), and a sparkline of
+ * its history.
+ *
+ * Data: a number, or `{ value, previous?, history?, target? }` (`history` ends
+ * with the current value; without `previous` the one before it is used).
+ * Options: x, y, width, height (10, 10, 220, 120), format and units (a
+ * number with thousands grouped by default), change ('percent', or 'value'
+ * for the difference), upIsGood (true: up is green; false for costs, errors,
+ * ...), bands (the value takes its band's colour), sparkColor, background,
+ * and title.
+ */
+export class KpiTile extends GaugeChart {
+    static chartType = 'kpiTile';
+    static LAYOUT = { x: 10, y: 10, width: 220, height: 120 };
+    static GOOD = '#2e9e5b';
+    static BAD = '#d64545';
+
+    /** A figure reads as it is, its thousands grouped ("12,345"). */
+    defaultFormat() { return { grouping: true }; }
+
+    /** The value as it is: a tile has no range to hold it to. */
+    get value() { return this.gaugeValue.value; }
+
+    /** The value's colour: its band's when there are bands, else the text colour. */
+    valueColor(value = this.value) {
+        if (this.options.color != null || this.bands.length) return super.valueColor(value);
+        return '#2f3542';
+    }
+
+    /** The change line: "▲ 10.0%" or "▼ 3", and whether it is good; null without a previous value. */
+    get changeText() {
+        const { change, changeRatio } = this.gaugeValue;
+        if (change == null) return null;
+        const { change: as = 'percent', upIsGood = true } = this.options;
+        const arrow = change > 0 ? '▲' : change < 0 ? '▼' : '■';
+        const amount = as === 'value' || changeRatio == null
+            ? this.scale.label(Math.abs(change))
+            : `${(Math.abs(changeRatio) * 100).toFixed(1)}%`;
+        const good = change === 0 ? null : (change > 0) === upIsGood;
+        return { text: `${arrow} ${amount}`, good };
+    }
+
+    _render() {
+        const { x, y, width, height } = this.layout;
+        const { title, background = '#ffffff', sparkColor = '#5352ed' } = this.options;
+        const pad = 12;
+        this.renderer.rect(x, y, width, height, background, { color: '#e1e4e8', width: 1 }, { rx: 8, ry: 8 });
+        if (title) {
+            this.renderer.text(title, x + pad, y + pad + 6, { textAnchor: 'start', verticalAlign: 'middle', fontSize: '12px', fill: '#747d8c' });
+        }
+        const valueSize = Math.max(14, Math.round(height * 0.26));
+        const valueY = y + pad + 18 + valueSize / 2;
+        this.renderer.text(this.scale.label(this.value), x + pad, valueY, {
+            textAnchor: 'start', verticalAlign: 'middle', fontSize: `${valueSize}px`, fontWeight: 'bold', fill: this.valueColor(),
+        });
+        const change = this.changeText;
+        if (change) {
+            const color = change.good == null ? '#747d8c' : change.good ? KpiTile.GOOD : KpiTile.BAD;
+            this.renderer.text(change.text, x + width - pad, valueY, { textAnchor: 'end', verticalAlign: 'middle', fontSize: '12px', fontWeight: 'bold', fill: color });
+        }
+        const sparkTop = valueY + valueSize / 2 + 8;
+        const sparkHeight = y + height - pad - sparkTop;
+        if (sparkHeight > 4) {
+            new Sparkline(this.gaugeValue.history, { x: x + pad, y: sparkTop, width: width - 2 * pad, height: sparkHeight }).draw(this.renderer, { color: sparkColor });
+        }
+    }
+}

package/src/charting/charts/MultiRingGauge.js

@@ -0,0 +1,54 @@
+import { GaugeChart } from './GaugeChart.js';
+import { ArcTrack } from '../gauges/ArcTrack.js';
+import { GaugeScale } from '../gauges/GaugeScale.js';
+
+/**
+ * MultiRingGauge — several values as rings one inside the other ("activity
+ * rings"), each filled to its value on its own scale, with a legend.
+ *
+ * Data: `[{ value, label?, color?, min?, max? }]` (or plain numbers), outer
+ * ring first; each ring's min and max default to the options'.
+ * Options: cx, cy, r (the outer ring: 100, 100, 70), thickness (12), gap (4),
+ * startAngle (-90) and sweep (360), colors (a colour per ring without its
+ * own), legend (true: each ring's label and value to the right), and the
+ * GaugeChart options min, max, format, units.
+ */
+export class MultiRingGauge extends GaugeChart {
+    static chartType = 'multiRingGauge';
+    static LAYOUT = { cx: 100, cy: 100, r: 70, thickness: 12, gap: 4, startAngle: -90, sweep: 360 };
+    static COLORS = ['#5352ed', '#2ed573', '#ffa502', '#ff4757', '#1e90ff'];
+
+    /** One per value: its track, scale and colour. */
+    get rings() {
+        const { cx, cy, r, thickness, gap, startAngle, sweep } = this.layout;
+        const { min, max, format, units, colors = MultiRingGauge.COLORS } = this.options;
+        return this.gaugeValue.values.map((v, i) => ({
+            ...v,
+            track: new ArcTrack({ cx, cy, r: r - i * (thickness + gap), thickness, startAngle, sweep }),
+            scale: new GaugeScale({ min: v.min ?? min, max: v.max ?? max, format: format ?? null, units }),
+            color: v.color ?? colors[i % colors.length],
+        })).filter(ring => ring.track.r > ring.track.thickness / 2);
+    }
+
+    _render() {
+        const { title, legend = true } = this.options;
+        const { cx, cy, r, thickness } = this.layout;
+        const rings = this.rings;
+        for (const ring of rings) {
+            this.drawBackground(ring.track);
+            this.drawValue(ring.track, { value: ring.scale.clamp(ring.value), scale: ring.scale, color: ring.color, cap: 'round' });
+        }
+        if (legend) {
+            const x = cx + r + thickness / 2 + 16;
+            const top = cy - ((rings.length - 1) * 18) / 2;
+            rings.forEach((ring, i) => {
+                const y = top + i * 18;
+                this.renderer.circle(x + 4, y, 4, ring.color);
+                this.renderer.text(`${ring.label ?? `#${i + 1}`}  ${ring.scale.label(ring.scale.clamp(ring.value))}`, x + 14, y, {
+                    textAnchor: 'start', verticalAlign: 'middle', fontSize: '12px', fill: '#2f3542',
+                });
+            });
+        }
+        this._renderTitle(title, cx, cy + r + thickness / 2 + 18, { textAnchor: 'middle', fontSize: '12px', fill: '#747d8c' });
+    }
+}

package/src/charting/charts/RingGauge.js

@@ -0,0 +1,23 @@
+import { ArcGauge } from './ArcGauge.js';
+
+/**
+ * RingGauge — a progress ring: a whole circle filled clockwise from the top
+ * to the value, its number in the middle.
+ *
+ * Options as ArcGauge's, drawn as a ring: cx, cy, r (100, 100, 60),
+ * thickness (14), startAngle (-90, the top) and sweep (360).
+ */
+export class RingGauge extends ArcGauge {
+    static chartType = 'ringGauge';
+    static LAYOUT = { cx: 100, cy: 100, r: 60, thickness: 14, startAngle: -90, sweep: 360 };
+
+    /** The number in the very middle. */
+    drawLabels(track) {
+        this._renderValueLabel(track.cx, track.cy, { fontSize: `${Math.max(12, Math.round(track.r * 0.36))}px`, fill: '#2f3542', fontWeight: 'bold' });
+    }
+
+    /** A ring's two ends are one point: no end labels. */
+    drawEnds() {}
+
+    titleY(track) { return track.cy + track.r + track.thickness / 2 + 18; }
+}

package/src/charting/charts/ThermometerGauge.js

@@ -0,0 +1,43 @@
+import { GaugeChart } from './GaugeChart.js';
+import { VerticalTrack } from '../gauges/VerticalTrack.js';
+
+/**
+ * ThermometerGauge — a tube filled from a bulb at its foot up to the value.
+ *
+ * Options: x, y, width, height (the tube: 40, 20, 18, 200), bulb (its radius:
+ * 16), and every GaugeChart option (min, max, units, bands, target, ticks,
+ * segments, ...). The value's label sits under the bulb.
+ */
+export class ThermometerGauge extends GaugeChart {
+    static chartType = 'thermometerGauge';
+    static LAYOUT = { x: 40, y: 20, width: 18, height: 200, bulb: 16 };
+    static defaultColor = '#ff4757';
+
+    track() {
+        const { x, y, width, height } = this.layout;
+        return new VerticalTrack({ x, y, length: height, thickness: width, radius: width / 2 });
+    }
+
+    /** The bulb's centre: under the tube, overlapping its foot so the two join. */
+    bulbCenter(track) {
+        const { bulb } = this.layout;
+        const foot = track.point(0);
+        return { x: foot.x, y: foot.y + bulb * 0.75 };
+    }
+
+    _render() {
+        const { title } = this.options;
+        const { bulb } = this.layout;
+        const track = this.track();
+        const centre = this.bulbCenter(track);
+        this._renderTitle(title, centre.x, track.y - 10, { textAnchor: 'middle', fontSize: '12px', fill: '#747d8c' });
+        this.drawBackground(track);
+        this.drawValue(track);
+        // The bulb is always full: the value's colour, round a lighter ring.
+        this.renderer.circle(centre.x, centre.y, bulb, this.constructor.trackColor);
+        this.renderer.circle(centre.x, centre.y, bulb - 3, this.valueColor());
+        this.drawTarget(track);
+        this.drawTicks(track);
+        this._renderValueLabel(centre.x, centre.y + bulb + 14, { fontWeight: 'bold', fill: '#2f3542' });
+    }
+}

package/src/charting/gauges/ArcTrack.js

@@ -0,0 +1,51 @@
+import { Gauge } from '../Gauge.js';
+import { GaugeTrack } from './GaugeTrack.js';
+
+/**
+ * ArcTrack — a gauge track along a circle's arc: the dial's 270°, a half
+ * circle, a full ring. Angles are degrees clockwise from 3 o'clock (the
+ * screen's own direction), so 135° with a 270° sweep is the dial's
+ * bottom-left to bottom-right, and 180° with 180° is a half circle over the top.
+ */
+export class ArcTrack extends GaugeTrack {
+    /**
+     * @param {Object} options
+     * @param {number} options.cx
+     * @param {number} options.cy
+     * @param {number} options.r - The radius of the track's centre line
+     * @param {number} options.thickness
+     * @param {number} [options.startAngle=135]
+     * @param {number} [options.sweep=270]
+     */
+    constructor({ cx, cy, r, thickness, startAngle = 135, sweep = 270 }) {
+        super(thickness);
+        Object.assign(this, { cx, cy, r, startAngle, sweep });
+    }
+
+    /** The arc's length along its centre line, in pixels. */
+    get length() { return this.r * Math.abs(this.sweep) * Math.PI / 180; }
+
+    /** The angle in degrees at a fraction along. */
+    angleAt(fraction) { return this.startAngle + fraction * this.sweep; }
+
+    point(fraction, offset = 0) {
+        const a = this.angleAt(fraction) * Math.PI / 180;
+        const r = this.r + offset;
+        return { x: this.cx + r * Math.cos(a), y: this.cy + r * Math.sin(a) };
+    }
+
+    draw(renderer, from, to, color, { thickness = this.thickness, cap } = {}) {
+        const rad = Math.PI / 180;
+        const a0 = this.angleAt(Math.min(from, to)) * rad;
+        const a1 = this.angleAt(Math.max(from, to)) * rad;
+        renderer.path(Gauge.arcPath(this.cx, this.cy, this.r, a0, a1), 'none', { color, width: thickness, ...(cap ? { cap } : {}) });
+    }
+
+    get center() { return { x: this.cx, y: this.cy }; }
+
+    /** A label outside the arc leans away from the centre: 'start' on the right, 'end' on the left. */
+    anchorAt(fraction) {
+        const dx = Math.cos(this.angleAt(fraction) * Math.PI / 180);
+        return dx > 0.3 ? 'start' : dx < -0.3 ? 'end' : 'middle';
+    }
+}

package/src/charting/gauges/GaugeAnimation.js

@@ -0,0 +1,51 @@
+import { GaugeValue } from './GaugeValue.js';
+
+/**
+ * GaugeAnimation — eases a gauge from the value it shows to a new one, so a
+ * needle or fill moves instead of jumping.
+ *
+ * Each frame draws the gauge from `GaugeValue.between(from, to, t)`: the
+ * value, the target and each of several values move together; the history
+ * and the previous value are the new ones throughout. The clock is
+ * injectable (`schedule`, `now`) so it runs without a browser in tests.
+ */
+export class GaugeAnimation {
+    /** Ease out (cubic): quick at first, settling on the value. */
+    static ease(t) { return 1 - (1 - t) ** 3; }
+
+    /**
+     * @param {Object} options
+     * @param {GaugeValue} options.from
+     * @param {GaugeValue} options.to
+     * @param {number} [options.duration=400] - Milliseconds
+     * @param {(data: Object) => void} options.draw - Draws one frame from its gauge data
+     * @param {(callback: Function) => *} [options.schedule] - requestAnimationFrame, else a 16ms timer
+     * @param {() => number} [options.now]
+     */
+    constructor({ from, to, duration = 400, draw, schedule = GaugeAnimation.defaultSchedule(), now = () => Date.now() }) {
+        Object.assign(this, { from, to, duration, draw, schedule, now });
+        this.stopped = false;
+    }
+
+    static defaultSchedule() {
+        return typeof globalThis.requestAnimationFrame === 'function'
+            ? (callback) => globalThis.requestAnimationFrame(callback)
+            : (callback) => setTimeout(callback, 16);
+    }
+
+    /** Draw the first frame now and the rest on the clock, ending exactly on `to`. */
+    start() {
+        const started = this.now();
+        const frame = () => {
+            if (this.stopped) return;
+            const t = this.duration > 0 ? Math.min(1, (this.now() - started) / this.duration) : 1;
+            this.draw(GaugeValue.between(this.from, this.to, GaugeAnimation.ease(t)));
+            if (t < 1) this.schedule(frame);
+        };
+        frame();
+        return this;
+    }
+
+    /** No more frames (a newer value has started its own). */
+    stop() { this.stopped = true; }
+}

package/src/charting/gauges/GaugeBands.js

@@ -0,0 +1,48 @@
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * GaugeBands — ranges along a gauge's scale ("poor", "ok", "good"), each with
+ * its colour and label.
+ *
+ * Given as `[{ to, color?, label? }]` in order: each band runs from where the
+ * one before it ended (the scale's min for the first) to its `to` (`max` is
+ * read the same, as the bullet graph has always taken it). Every gauge draws
+ * its bands from here, and a value takes the colour of the band it falls in.
+ */
+export class GaugeBands {
+    /** Band colours used when a band has none of its own: bad, warning, good. */
+    static COLORS = ['#ff6b6b', '#ffd93d', '#6bcb77'];
+
+    /** How far a band's colour is mixed toward white when drawn behind a value. */
+    static TINT = 0.65;
+
+    /**
+     * @param {Array<{to?:number, max?:number, color?:string, label?:string}>} bands
+     * @param {import('./GaugeScale.js').GaugeScale} scale
+     * @param {Object} [options]
+     * @param {string[]} [options.colors] - Colours for bands without their own
+     */
+    constructor(bands = [], scale, { colors = GaugeBands.COLORS } = {}) {
+        this.scale = scale;
+        let from = scale.min;
+        this.list = (bands ?? []).map((band, index) => {
+            const to = scale.clamp(band.to ?? band.max ?? scale.max);
+            const entry = { from, to, color: band.color ?? colors[index % colors.length], label: band.label ?? null, index };
+            from = to;
+            return entry;
+        });
+    }
+
+    get length() { return this.list.length; }
+
+    /** The band a value falls in (the last one at a shared edge), or null. */
+    at(value) {
+        const v = this.scale.clamp(value);
+        return this.list.find(b => v >= b.from && v < b.to) ?? this.list.findLast(b => v >= b.from && v <= b.to) ?? null;
+    }
+
+    /** A band's colour as drawn behind the value: lighter, so the value shows on it. */
+    static tint(color) {
+        return /^#[0-9a-f]{6}$/i.test(color) ? ColorPalette.interpolate(color, '#ffffff', GaugeBands.TINT) : color;
+    }
+}

package/src/charting/gauges/GaugeScale.js

@@ -0,0 +1,87 @@
+/**
+ * GaugeScale — the range a gauge measures and how its numbers read.
+ *
+ * One scale per gauge: it turns a value into a 0-1 fraction of the way along
+ * the track, gives the tick values, and formats the value and tick labels.
+ * Every gauge draws from it, so `min`, `max` and `format` mean the same on
+ * all of them.
+ */
+export class GaugeScale {
+    /**
+     * @param {Object} [options]
+     * @param {number} [options.min=0]
+     * @param {number} [options.max=100]
+     * @param {Function|Object} [options.format] - `(value) => string`, or
+     *   `{ decimals, prefix, suffix, grouping, compact }`. Without one, a
+     *   0-100 scale reads as a percentage ("75.0%"), any other as its number.
+     * @param {string} [options.units] - The suffix when no format is given ("ms", "°C")
+     */
+    constructor({ min = 0, max = 100, format = null, units = null } = {}) {
+        this.min = Number(min);
+        this.max = Number(max);
+        this.format = format ?? { decimals: 1, suffix: units != null ? ` ${units}` : (this.isPercent ? '%' : '') };
+    }
+
+    /** True for the plain 0-100 scale a percentage gauge has. */
+    get isPercent() { return this.min === 0 && this.max === 100; }
+
+    get span() { return (this.max - this.min) || 1; }
+
+    /** The value held to the scale's range. */
+    clamp(value) {
+        const v = Number(value);
+        if (!Number.isFinite(v)) return this.min;
+        return Math.min(Math.max(v, Math.min(this.min, this.max)), Math.max(this.min, this.max));
+    }
+
+    /** How far along the scale a value is, 0-1 (held to the range). */
+    fraction(value) { return (this.clamp(value) - this.min) / this.span; }
+
+    /** The value at a fraction of the way along. */
+    valueAt(fraction) { return this.min + fraction * this.span; }
+
+    /** `count` equal steps: count + 1 values from min to max. */
+    ticks(count = 5) {
+        const n = Math.max(1, Math.round(count));
+        return Array.from({ length: n + 1 }, (_, i) => this.valueAt(i / n));
+    }
+
+    /** A value as the gauge shows it. */
+    label(value) { return GaugeScale.formatNumber(value, this.format); }
+
+    /**
+     * A tick's label: the value's prefix and suffix, with only the decimals a
+     * step of `span / count` needs ("0", "25", ... not "0.0%", "25.0%").
+     */
+    tickLabel(value, count = 5) {
+        if (typeof this.format === 'function') return this.format(value);
+        const step = this.span / Math.max(1, Math.round(count));
+        // The fewest decimals that show the step exactly (0.25 needs 2), at most 6.
+        let decimals = 0;
+        while (decimals < 6 && Math.abs(step * 10 ** decimals - Math.round(step * 10 ** decimals)) > 1e-9) decimals++;
+        return GaugeScale.formatNumber(value, { ...this.format, decimals });
+    }
+
+    /**
+     * Format a number: a function format is called; an object one gives
+     * decimals (null: as it is), prefix, suffix, grouping (1,234) and compact (1.2K).
+     */
+    static formatNumber(value, format = {}) {
+        if (typeof format === 'function') return format(value);
+        const { decimals = null, prefix = '', suffix = '', grouping = false, compact = false } = format ?? {};
+        const v = Number(value);
+        if (!Number.isFinite(v)) return `${prefix}${value}${suffix}`;
+        let text;
+        if (compact || grouping) {
+            const digits = decimals ?? (compact ? 1 : undefined);
+            text = new Intl.NumberFormat('en', {
+                notation: compact ? 'compact' : 'standard',
+                useGrouping: true,
+                ...(digits != null ? { minimumFractionDigits: compact ? 0 : digits, maximumFractionDigits: digits } : {}),
+            }).format(v);
+        } else {
+            text = decimals == null ? String(v) : v.toFixed(decimals);
+        }
+        return `${prefix}${text}${suffix}`;
+    }
+}

package/src/charting/gauges/GaugeTrack.js

@@ -0,0 +1,44 @@
+/**
+ * GaugeTrack — the path a gauge's value moves along, as fractions 0-1.
+ *
+ * A subclass is one geometry (a straight bar, an arc). The gauge asks it for
+ * points and draws segments on it, so bands, the value, ticks and a target
+ * marker are drawn the same way on every gauge whatever its shape.
+ *
+ * A track has a `length` (pixels along it) as well as its `thickness`.
+ * Offsets are across the track from its centre line: positive is outward
+ * (below a horizontal bar, right of a vertical one, away from an arc's centre).
+ */
+export class GaugeTrack {
+    /** @param {number} thickness - The track's width across */
+    constructor(thickness) {
+        if (new.target === GaugeTrack) throw new TypeError('GaugeTrack is abstract — subclass it');
+        this.thickness = thickness;
+    }
+
+    /** The point at a fraction along, `offset` across. @returns {{x:number, y:number}} */
+    point(fraction, offset = 0) { throw new Error(`${this.constructor.name} must implement point()`); }
+
+    /**
+     * Draw the track from one fraction to another, in a colour.
+     * @param {Object} renderer
+     * @param {number} from - 0-1
+     * @param {number} to - 0-1
+     * @param {string} color
+     * @param {Object} [options] - `thickness` (this track's by default), `cap` ('round' ends)
+     */
+    draw(renderer, from, to, color, options = {}) { throw new Error(`${this.constructor.name} must implement draw()`); }
+
+    /** Where a label sits in the middle of the gauge. @returns {{x:number, y:number}} */
+    get center() { throw new Error(`${this.constructor.name} must implement center`); }
+
+    /** A straight line across the track at a fraction, between two offsets (a tick, a target). */
+    line(renderer, fraction, fromOffset, toOffset, stroke) {
+        const a = this.point(fraction, fromOffset);
+        const b = this.point(fraction, toOffset);
+        renderer.path(`M${a.x},${a.y} L${b.x},${b.y}`, 'none', stroke);
+    }
+
+    /** How a label at a point outside the track is anchored ('start', 'middle' or 'end'). */
+    anchorAt(fraction) { return 'middle'; }
+}

package/src/charting/gauges/GaugeValue.js

@@ -0,0 +1,61 @@
+/**
+ * GaugeValue — what a gauge's data says: the value, and what it is compared
+ * with.
+ *
+ * Data is a plain number, or `{ value, target?, previous?, history?, values? }`;
+ * options of the same names win over the data's. `values` is for gauges that
+ * show several (one ring each): numbers, or `{ value, label?, color?, min?, max? }`;
+ * an array as the data is read as `values`.
+ */
+export class GaugeValue {
+    constructor({ value = 0, target = null, previous = null, history = [], values = [] } = {}) {
+        this.value = Number(value) || 0;
+        this.target = target == null ? null : Number(target);
+        this.history = (history ?? []).map(Number).filter(Number.isFinite);
+        // The value before this one: given, or the one before the last in the history.
+        this.previous = previous != null ? Number(previous) : (this.history.length > 1 ? this.history.at(-2) : null);
+        this.values = (values ?? []).map(v => (typeof v === 'object' && v !== null ? { ...v, value: Number(v.value) || 0 } : { value: Number(v) || 0 }));
+    }
+
+    /** The change from the previous value, or null without one. */
+    get change() { return this.previous == null ? null : this.value - this.previous; }
+
+    /** The change as a fraction of the previous value (0.1 is up 10%), or null. */
+    get changeRatio() { return this.previous ? this.change / Math.abs(this.previous) : null; }
+
+    /** As gauge data again (`{ value, target, previous, history, values }`). */
+    toData() {
+        const { value, target, previous, history, values } = this;
+        return { value, target, previous, history: [...history], values: values.map(v => ({ ...v })) };
+    }
+
+    /**
+     * The data part of the way (t, 0-1) from one value to another: the value,
+     * the target and each of several values in between (one that is new
+     * starts from the first value); the rest as `to` has them.
+     */
+    static between(from, to, t) {
+        const mix = (a, b) => (a == null || b == null ? b : a + (b - a) * t);
+        const data = to.toData();
+        data.value = mix(from.value, to.value);
+        data.target = mix(from.target, to.target);
+        data.values = to.values.map((v, i) => ({ ...v, value: mix(from.values[i]?.value ?? from.value, v.value) }));
+        return data;
+    }
+
+    static from(data, options = {}) {
+        const given = Array.isArray(data) ? { values: data } : (typeof data === 'object' && data !== null ? data : { value: data });
+        const pick = (key) => options[key] ?? given[key];
+        const values = pick('values') ?? [];
+        const history = pick('history') ?? [];
+        // Without a value: the first of several, else the last of the history.
+        const first = values.length ? (typeof values[0] === 'object' ? values[0].value : values[0]) : history.at(-1);
+        return new GaugeValue({
+            value: given.value ?? first ?? 0,
+            target: pick('target'),
+            previous: pick('previous'),
+            history,
+            values,
+        });
+    }
+}

package/src/charting/gauges/HorizontalTrack.js

@@ -0,0 +1,14 @@
+import { LinearTrack } from './LinearTrack.js';
+
+/** A track left to right. */
+export class HorizontalTrack extends LinearTrack {
+    point(fraction, offset = 0) {
+        return { x: this.x + fraction * this.length, y: this.y + this.thickness / 2 + offset };
+    }
+
+    rectangle(from, to, thickness) {
+        return { x: this.x + from * this.length, y: this.y + (this.thickness - thickness) / 2, width: (to - from) * this.length, height: thickness };
+    }
+
+    get center() { return this.point(0.5); }
+}

package/src/charting/gauges/LinearTrack.js

@@ -0,0 +1,29 @@
+import { GaugeTrack } from './GaugeTrack.js';
+
+/**
+ * LinearTrack — a straight gauge track: a box `length` long and `thickness`
+ * across, its segments drawn as rectangles. A subclass gives the direction.
+ */
+export class LinearTrack extends GaugeTrack {
+    /**
+     * @param {Object} options
+     * @param {number} options.x - The box's left
+     * @param {number} options.y - The box's top
+     * @param {number} options.length
+     * @param {number} options.thickness
+     * @param {number} [options.radius=0] - Corner radius of the drawn segments
+     */
+    constructor({ x, y, length, thickness, radius = 0 }) {
+        super(thickness);
+        if (new.target === LinearTrack) throw new TypeError('LinearTrack is abstract — use HorizontalTrack or VerticalTrack');
+        Object.assign(this, { x, y, length, radius });
+    }
+
+    /** The rectangle covering from one fraction to another, `thickness` across and centred. */
+    rectangle(from, to, thickness) { throw new Error(`${this.constructor.name} must implement rectangle()`); }
+
+    draw(renderer, from, to, color, { thickness = this.thickness } = {}) {
+        const r = this.rectangle(Math.min(from, to), Math.max(from, to), thickness);
+        renderer.rect(r.x, r.y, r.width, r.height, color, null, this.radius ? { rx: this.radius, ry: this.radius } : {});
+    }
+}

package/src/charting/gauges/Sparkline.js

@@ -0,0 +1,42 @@
+/**
+ * Sparkline — a small line of a series' recent values, fitted to a box:
+ * the first value at the left, the last at the right, the lowest at the
+ * bottom and the highest at the top.
+ */
+export class Sparkline {
+    /**
+     * @param {number[]} values - At least two to draw a line
+     * @param {{x:number, y:number, width:number, height:number}} box
+     */
+    constructor(values, box) {
+        this.values = values.map(Number).filter(Number.isFinite);
+        this.box = box;
+    }
+
+    /** Each value's point in the box (none for fewer than two values). */
+    get points() {
+        const { values, box } = this;
+        if (values.length < 2) return [];
+        const lo = Math.min(...values);
+        const hi = Math.max(...values);
+        const span = (hi - lo) || 1;
+        // A flat series sits across the middle.
+        const flat = hi === lo;
+        return values.map((v, i) => ({
+            x: box.x + (i / (values.length - 1)) * box.width,
+            y: flat ? box.y + box.height / 2 : box.y + box.height - ((v - lo) / span) * box.height,
+        }));
+    }
+
+    /** The line as a path `d` (empty for fewer than two values). */
+    get d() { return this.points.map((p, i) => `${i ? 'L' : 'M'}${p.x},${p.y}`).join(' '); }
+
+    /** Draw the line and a dot on its last value. */
+    draw(renderer, { color = '#5352ed', width = 1.5 } = {}) {
+        const points = this.points;
+        if (!points.length) return;
+        renderer.path(this.d, 'none', { color, width });
+        const last = points.at(-1);
+        renderer.circle(last.x, last.y, 2.5, color);
+    }
+}

package/src/charting/gauges/VerticalTrack.js

@@ -0,0 +1,17 @@
+import { LinearTrack } from './LinearTrack.js';
+
+/** A track bottom to top. */
+export class VerticalTrack extends LinearTrack {
+    point(fraction, offset = 0) {
+        return { x: this.x + this.thickness / 2 + offset, y: this.y + this.length - fraction * this.length };
+    }
+
+    rectangle(from, to, thickness) {
+        return { x: this.x + (this.thickness - thickness) / 2, y: this.y + this.length - to * this.length, width: thickness, height: (to - from) * this.length };
+    }
+
+    get center() { return this.point(0.5); }
+
+    /** Labels beside a vertical track start at their point. */
+    anchorAt() { return 'start'; }
+}