@peter.prib/renderengine 0.1.0 → 0.2.1

package/dist/renderengine.umd.js

@@ -1449,18 +1449,18 @@
         key: 'gauge-dial', label: 'Gauge (Dial)', method: 'dialGauge', category: 'gauge',
         coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
         axes: [
-          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] },
+          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
         ],
-        dataShape: 'number (0-100) — no category axis; the only role IS the value',
+        dataShape: 'number, {value, target?}, or [{value, label?, color?}] (a needle each) — no category axis; the only role IS the value (0-100 unless min/max are given)',
         streamShape: 'none', // no array/window at all — update by calling dialGauge(newValue) again directly
       },
       {
         key: 'gauge-bar', label: 'Gauge (Bar)', method: 'barGauge', category: 'gauge',
         coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
         axes: [
-          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] },
+          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
         ],
-        dataShape: 'number (0-100)',
+        dataShape: 'number, or {value, target?} (0-100 unless min/max are given)',
         streamShape: 'none', // no array/window at all — update by calling barGauge(newValue) again directly
       },
       {
@@ -1473,6 +1473,51 @@
         dataShape: 'number or {value, target?, ranges?:Array<{max, label?, color?}>}',
         streamShape: 'none',
       },
+      {
+        key: 'gauge-arc', label: 'Gauge (Arc)', method: 'arcGauge', category: 'gauge',
+        coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+        axes: [
+          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+        ],
+        dataShape: 'number, or {value, target?} (0-100 unless min/max are given) — a half circle by default, any startAngle/sweep',
+        streamShape: 'none',
+      },
+      {
+        key: 'gauge-ring', label: 'Gauge (Ring)', method: 'ringGauge', category: 'gauge',
+        coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+        axes: [
+          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+        ],
+        dataShape: 'number, or {value, target?} (0-100 unless min/max are given)',
+        streamShape: 'none',
+      },
+      {
+        key: 'gauge-rings', label: 'Gauge (Rings)', method: 'multiRingGauge', category: 'gauge',
+        coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+        axes: [
+          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+        ],
+        dataShape: 'Array<number|{value, label?, color?, min?, max?}> — one ring per value, outer first, each on its own scale',
+        streamShape: 'none',
+      },
+      {
+        key: 'gauge-thermometer', label: 'Gauge (Thermometer)', method: 'thermometerGauge', category: 'gauge',
+        coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+        axes: [
+          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+        ],
+        dataShape: 'number, or {value, target?} (0-100 unless min/max are given)',
+        streamShape: 'none',
+      },
+      {
+        key: 'kpi-tile', label: 'KPI Tile', method: 'kpiTile', category: 'gauge',
+        coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+        axes: [
+          { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+        ],
+        dataShape: 'number, or {value?, previous?, history?:number[]} — the figure, its change since the previous value, a sparkline of the history',
+        streamShape: 'none',
+      },
       {
         key: 'bar3D', label: 'Bar (3D)', method: 'barChart3D', category: '3d',
         coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.ISOMETRIC,
@@ -11987,6 +12032,12 @@
          * Angles are in radians.
          */
         static arcPath(cx, cy, r, startAngle, endAngle) {
+            // A whole circle starts and ends on one point, which an SVG arc draws as nothing: two halves.
+            if (endAngle - startAngle >= 2 * Math.PI - 1e-9) {
+                const mid = startAngle + Math.PI;
+                const at = (a) => `${cx + r * Math.cos(a)} ${cy + r * Math.sin(a)}`;
+                return `M ${at(startAngle)} A ${r} ${r} 0 0 1 ${at(mid)} A ${r} ${r} 0 0 1 ${at(startAngle)}`;
+            }
             const largeArcFlag = endAngle - startAngle <= Math.PI ? '0' : '1';
             const start = {
                 x: cx + r * Math.cos(startAngle),
@@ -12001,21 +12052,343 @@
     }
 
     /**
-     * GaugeChart — abstract base for 0-100 percentage gauges.
+     * GaugeScale — the range a gauge measures and how its numbers read.
      *
-     * Subclasses implement `_renderGauge()` and use the shared normalization,
-     * color resolution, title, and percentage-label helpers.
+     * 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.
+     */
+    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}`;
+        }
+    }
+
+    /**
+     * 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.
+     */
+    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;
+        }
+    }
+
+    /**
+     * 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`.
+     */
+    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,
+            });
+        }
+    }
+
+    /**
+     * GaugeChart — abstract base for gauges: one value shown along a track.
+     *
+     * It reads what every gauge has in common from its data and options (a
+     * `GaugeScale`, `GaugeBands`, a `GaugeValue`) and draws the parts every gauge
+     * has on the subclass's `track()`: the background or the bands, the value, a
+     * target marker, ticks and the labels. A subclass picks the track and its
+     * layout, and adds its own parts (the dial's needle).
+     *
+     * Options every gauge takes:
+     *   min, max (0, 100), format, units  — the scale (see GaugeScale)
+     *   bands: [{to, color?, label?}]     — ranges drawn behind the value; the value takes its band's colour
+     *   bandColors: string[]              — colours for bands without their own
+     *   color                             — the value's colour: one, a gradient array, or (percent) => colour
+     *   target                            — a marker at a value (or data.target)
+     *   targetColor ('#333')
+     *   ticks: number                     — that many equal steps, marked and labelled
+     *   segments: number, segmentGap (2)  — the track as that many blocks (LED style), lit up to the value;
+     *                                       with bands, each lit block takes its own band's colour
+     *   title
      */
     class GaugeChart extends Chart {
-        /** Normalize data to a 0-100 percentage. */
-        _normalizePercent() {
-            const value = Number(this.data);
-            return Math.min(Math.max(value, 0), 100);
+        /** The value's colour when neither `color` nor a band gives one. */
+        static defaultColor = '#5352ed';
+
+        /** The track behind the value when there are no bands. */
+        static trackColor = '#f1f2f6';
+
+        /** Where and how big this type draws when the options don't say (cx, cy, r, ...). */
+        static LAYOUT = {};
+
+        /** The layout: the options' values for this type's LAYOUT keys, over its own. */
+        get layout() {
+            const layout = { ...this.constructor.LAYOUT };
+            for (const key of Object.keys(layout)) if (this.options[key] != null) layout[key] = this.options[key];
+            return layout;
         }
 
-        /** Resolve the gauge color for the current percentage. */
-        _resolveColor(color, percent) {
-            return Gauge.resolveColor(color, percent);
+        get scale() {
+            const { min, max, format, units } = this.options;
+            return (this._scale ??= new GaugeScale({ min, max, format: format ?? this.defaultFormat(), units }));
+        }
+
+        get bands() {
+            // `ranges` and `rangeColors`: the bullet graph's older names for them.
+            const { bands, ranges, bandColors = this.options.rangeColors } = this.options;
+            return (this._bands ??= new GaugeBands(bands ?? ranges ?? this.defaultBands(), this.scale, bandColors ? { colors: bandColors } : {}));
+        }
+
+        get gaugeValue() { return (this._value ??= GaugeValue.from(this.data, this.options)); }
+
+        /** The value, held to the scale. */
+        get value() { return this.scale.clamp(this.gaugeValue.value); }
+
+        /** A format this gauge type reads its numbers with when none is given (null: the scale's). */
+        defaultFormat() { return null; }
+
+        /** Bands this gauge type draws when none are given. */
+        defaultBands() { return []; }
+
+        /** The track the value moves along. Subclasses implement. @returns {import('../gauges/GaugeTrack.js').GaugeTrack} */
+        track() { throw new Error(`${this.constructor.name} must implement track()`); }
+
+        /** The value's colour: the `color` option, else its band's, else the type's own. */
+        valueColor(value = this.value) {
+            const { color } = this.options;
+            if (color != null) return Gauge.resolveColor(color, this.scale.fraction(value) * 100);
+            return this.bands.at(value)?.color ?? this.constructor.defaultColor;
+        }
+
+        /**
+         * With `segments`, the track as that many blocks a `segmentGap` (pixels)
+         * apart: [{from, to, mid}] as fractions; null without (fewer than 2).
+         */
+        segmentsOf(track) {
+            const n = Math.round(this.options.segments ?? 0);
+            if (n < 2) return null;
+            const gap = Math.min((this.options.segmentGap ?? 2) / (track.length || 1), 0.5 / n);
+            return Array.from({ length: n }, (_, i) => ({ from: i / n + gap / 2, to: (i + 1) / n - gap / 2, mid: (i + 0.5) / n }));
+        }
+
+        /** The bands, lighter, along the whole track; or the plain track without any. */
+        drawBackground(track, options = {}) {
+            const blocks = this.segmentsOf(track);
+            if (blocks) {
+                for (const block of blocks) {
+                    const band = this.bands.at(this.scale.valueAt(block.mid));
+                    track.draw(this.renderer, block.from, block.to, band ? GaugeBands.tint(band.color) : this.constructor.trackColor, { ...options, cap: undefined });
+                }
+                return;
+            }
+            if (!this.bands.length) {
+                track.draw(this.renderer, 0, 1, this.constructor.trackColor, options);
+                return;
+            }
+            for (const band of this.bands.list) {
+                track.draw(this.renderer, this.scale.fraction(band.from), this.scale.fraction(band.to), GaugeBands.tint(band.color), { ...options, cap: undefined });
+            }
+        }
+
+        /**
+         * A value: the track from the scale's start to it. This gauge's value and
+         * scale unless given (a gauge of several values draws each on its own).
+         */
+        drawValue(track, { value = this.value, scale = this.scale, color, ...options } = {}) {
+            const blocks = this.segmentsOf(track);
+            if (!blocks) {
+                track.draw(this.renderer, 0, scale.fraction(value), color ?? this.valueColor(value), options);
+                return;
+            }
+            // The blocks up to the value are lit: each in its band's colour (a level meter), unless a colour is given.
+            const lit = Math.round(scale.fraction(value) * blocks.length);
+            const own = color ?? (this.options.color != null || !this.bands.length ? this.valueColor(value) : null);
+            for (const block of blocks.slice(0, lit)) {
+                const blockColor = own ?? this.bands.at(scale.valueAt(block.mid))?.color ?? this.constructor.defaultColor;
+                track.draw(this.renderer, block.from, block.to, blockColor, { ...options, cap: undefined });
+            }
+        }
+
+        /** A line across the track at the target, a little past both edges. */
+        drawTarget(track, { overhang = 3, width = 2 } = {}) {
+            const { target } = this.gaugeValue;
+            if (target == null) return;
+            const half = track.thickness / 2 + overhang;
+            track.line(this.renderer, this.scale.fraction(target), -half, half, { color: this.options.targetColor ?? '#333', width });
+        }
+
+        /** `ticks` marks outside the track, each labelled with its value. */
+        drawTicks(track) {
+            const { ticks } = this.options;
+            if (!ticks) return;
+            const count = Math.max(1, Math.round(ticks));
+            const edge = track.thickness / 2;
+            for (const value of this.scale.ticks(count)) {
+                const f = this.scale.fraction(value);
+                track.line(this.renderer, f, edge + 2, edge + 6, { color: '#999', width: 1 });
+                const at = track.point(f, edge + 14);
+                this.renderer.text(this.scale.tickLabel(value, count), at.x, at.y, {
+                    textAnchor: track.anchorAt(f), verticalAlign: 'middle', fontSize: '10px', fill: '#747d8c',
+                });
+            }
         }
 
         /** Draw a gauge title. */
@@ -12029,9 +12402,9 @@
             });
         }
 
-        /** Draw a centered percentage label. */
-        _renderPercentageLabel(percent, x, y, options = {}) {
-            this.renderer.text(`${percent.toFixed(1)}%`, x, y, {
+        /** Draw the value's label, centred at a point. */
+        _renderValueLabel(x, y, options = {}) {
+            this.renderer.text(this.scale.label(this.value), x, y, {
                 textAnchor: options.textAnchor || 'middle',
                 verticalAlign: options.verticalAlign || 'middle',
                 fontSize: options.fontSize || '12px',
@@ -12046,22 +12419,143 @@
     }
 
     /**
-     * BarGauge — a simple horizontal percentage bar.
+     * 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).
+     */
+    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'; }
+    }
+
+    /**
+     * LinearTrack — a straight gauge track: a box `length` long and `thickness`
+     * across, its segments drawn as rectangles. A subclass gives the direction.
+     */
+    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 } : {});
+        }
+    }
+
+    /** A track left to right. */
+    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); }
+    }
+
+    /** A track bottom to top. */
+    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'; }
+    }
+
+    /**
+     * BarGauge — a straight bar filled to the value, left to right or (with
+     * `orientation: 'vertical'`) bottom to top.
+     *
+     * Options: x, y, width, height (the bar's box; 200 × 30 across, 30 × 200 up),
+     * orientation, and every GaugeChart option (min, max, bands, target, ticks, ...).
      */
     class BarGauge extends GaugeChart {
         static chartType = 'barGauge';
 
-        _render() {
-            const options = this.options;
-            const { x = 10, y = 10, width = 200, height = 30, color = '#5352ed', title } = options;
-            const p = this._normalizePercent();
-            const barWidth = (p / 100) * width;
-            const resolvedColor = this._resolveColor(color, p);
+        get vertical() { return this.options.orientation === 'vertical'; }
+
+        track() {
+            const { x = 10, y = 10 } = this.options;
+            const { width = this.vertical ? 30 : 200, height = this.vertical ? 200 : 30 } = this.options;
+            return this.vertical
+                ? new VerticalTrack({ x, y, length: height, thickness: width, radius: 4 })
+                : new HorizontalTrack({ x, y, length: width, thickness: height, radius: 4 });
+        }
 
-            this._renderTitle(title, x, y - 5);
-            this.renderer.rect(x, y, width, height, '#f1f2f6', null, { rx: 4, ry: 4 });
-            this.renderer.rect(x, y, barWidth, height, resolvedColor, null, { rx: 4, ry: 4 });
-            this._renderPercentageLabel(p, x + width / 2, y + height / 2, { fontWeight: 'bold' });
+        _render() {
+            const { x = 10, y = 10, title } = this.options;
+            const track = this.track();
+            this._renderTitle(title, x, y - (this.vertical ? 8 : 5));
+            this.drawBackground(track);
+            this.drawValue(track);
+            this.drawTarget(track);
+            this.drawTicks(track);
+            if (this.vertical) {
+                // A vertical bar is too narrow for its label: it goes underneath.
+                const below = track.point(0, 0);
+                this._renderValueLabel(below.x, below.y + 14, { fontWeight: 'bold', fill: '#2f3542' });
+            } else {
+                const { x: cx, y: cy } = track.center;
+                this._renderValueLabel(cx, cy, { fontWeight: 'bold' });
+            }
         }
     }
 
@@ -12072,82 +12566,77 @@
      * Data may be a plain number (the actual value) or an object
      * `{ value: number, target?: number, ranges?: Array<{max:number, label?, color?}> }`.
      *
-     * Options:
-     *   target?: number            — target value (overrides data.target)
-     *   ranges?: Range[]            — qualitative ranges (overrides data.ranges)
-     *   min?: number = 0            — scale minimum
-     *   max?: number = 100          — scale maximum
+     * Options (with every GaugeChart option: min, max, bands, target, ticks, ...):
+     *   ranges?: Range[]            — the bands, by their older name (overrides data.ranges)
      *   barColor?: string           — color of the actual-value bar
      *   targetColor?: string = #333 — color of the target marker
      *   rangeColors?: string[]      — fallback palette for ranges without their own color
-     *   title?: string
      *   showLabels?: boolean = true — value/target/range labels
      */
-    class BulletGauge extends Chart {
+    class BulletGauge extends GaugeChart {
         static chartType = 'bullet';
+        static defaultColor = '#5470c6';
 
-        _render() {
-            const data = this.data;
-            const options = this.options;
-            const box = ChartBox.fromRenderer(this.renderer);
-            const {
-                x = box.x, y = box.y, width = box.width, height = box.height * 0.4,
-                min = 0, max = 100,
-                target: optTarget, targetColor = '#333',
-                barColor = '#5470c6',
-                ranges: optRanges, rangeColors = ['#ff6b6b', '#ffd93d', '#6bcb77'],
-                title, showLabels = true,
-            } = options;
+        /** Its numbers as they are ("65", not "65.0%"). */
+        defaultFormat() { return (v) => String(v); }
 
-            const actual = typeof data === 'number' ? data : (data?.value ?? 0);
-            const target = optTarget != null ? optTarget : data?.target ?? null;
-            const ranges = optRanges ?? data?.ranges ?? [
+        /** The data's ranges, else poor / satisfactory / good at 60% and 80% of the scale. */
+        defaultBands() {
+            const max = this.options.max ?? 100;
+            return this.data?.bands ?? this.data?.ranges ?? [
                 { max: max * 0.6, label: 'Poor' },
                 { max: max * 0.8, label: 'Satisfactory' },
-                { max: max, label: 'Good' },
+                { max, label: 'Good' },
             ];
+        }
+
+        /** The bar keeps one colour (`barColor`): the bands behind it are the comparison. */
+        valueColor(value) {
+            const { barColor, color } = this.options;
+            return barColor ?? (color != null ? super.valueColor(value) : this.constructor.defaultColor);
+        }
 
-            const span = (max - min) || 1;
-            const toX = (v) => x + Math.min(Math.max((v - min) / span, 0), 1) * width;
+        get box() {
+            const box = ChartBox.fromRenderer(this.renderer);
+            const { x = box.x, y = box.y, width = box.width, height = box.height * 0.4 } = this.options;
+            return { x, y, width, height };
+        }
+
+        track() {
+            const { x, y, width, height } = this.box;
+            return new HorizontalTrack({ x, y, length: width, thickness: height });
+        }
+
+        _render() {
+            const { title, showLabels = true, ticks } = this.options;
+            const { x, y, width, height } = this.box;
+            const track = this.track();
 
             new ChartLabels({ title }).draw(this.renderer, { x, y, width, height });
 
-            // Draw qualitative range bands
-            let rangeStart = min;
-            ranges.forEach((range, i) => {
-                const rangeEnd = Math.min(Math.max(range.max, min), max);
-                const rx = toX(rangeStart);
-                const rw = toX(rangeEnd) - rx;
-                const color = range.color ?? rangeColors[i % rangeColors.length];
-                this.renderer.rect(rx, y, rw, height, color, null, { opacity: 0.35 });
-                if (showLabels && range.label) {
-                    this.renderer.text(range.label, rx + rw / 2, y + height + 14, {
-                        textAnchor: 'middle', fontSize: '10px', fill: '#666',
-                    });
+            this.drawBackground(track);
+            if (showLabels) {
+                const below = y + height + (ticks ? 28 : 14);
+                for (const band of this.bands.list) {
+                    if (!band.label) continue;
+                    const mid = track.point((this.scale.fraction(band.from) + this.scale.fraction(band.to)) / 2);
+                    this.renderer.text(band.label, mid.x, below, { textAnchor: 'middle', fontSize: '10px', fill: '#666' });
                 }
-                rangeStart = rangeEnd;
-            });
+            }
 
-            // Draw actual-value bar (thinner, centered vertically)
+            // The actual value: a bar half as thick, centred on the bands.
             const barHeight = height * 0.5;
-            const barY = y + (height - barHeight) / 2;
-            const actualX = toX(min);
-            const actualW = toX(actual) - actualX;
-            this.renderer.rect(actualX, barY, actualW, barHeight, barColor, null, {});
-
-            // Draw target marker (vertical line)
-            if (target != null) {
-                const tx = toX(target);
-                this.renderer.path(`M${tx},${y - 2} L${tx},${y + height + 2}`, 'none', { color: targetColor, width: 2 });
-            }
+            this.drawValue(track, { thickness: barHeight });
+            this.drawTarget(track, { overhang: 2 });
+            this.drawTicks(track);
 
             if (showLabels) {
-                this.renderer.text(String(actual), x + width / 2, barY + barHeight / 2, {
-                    textAnchor: 'middle', verticalAlign: 'middle', fontSize: '11px', fill: '#fff', fontWeight: 'bold',
-                });
+                const { x: cx, y: cy } = track.center;
+                this._renderValueLabel(cx, cy, { fontSize: '11px', fontWeight: 'bold' });
+                const { target } = this.gaugeValue;
                 if (target != null) {
-                    this.renderer.text(String(target), toX(target) + 5, y - 8, {
-                        textAnchor: 'start', fontSize: '10px', fill: targetColor,
+                    this.renderer.text(this.scale.label(target), track.point(this.scale.fraction(target)).x + 5, y - 8, {
+                        textAnchor: 'start', fontSize: '10px', fill: this.options.targetColor ?? '#333',
                     });
                 }
             }
@@ -12155,38 +12644,445 @@
     }
 
     /**
-     * DialGauge — a semicircular percentage gauge with a needle.
+     * 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.
+     */
+    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';
+        }
+    }
+
+    /**
+     * DialGauge — an arc filled to the value, with a needle pointing at it.
+     *
+     * Data: a value, or several (`[{ value, label?, color? }]`, e.g. actual and
+     * budget): a needle each, the first also filling the arc and labelled in
+     * the middle, and a legend of them all under the title.
+     * Options: cx, cy, r (100, 80, 60), thickness (12), startAngle and sweep in
+     * degrees (135 and 270: bottom-left round to bottom-right), needleColors,
+     * and every GaugeChart option (min, max, bands, target, ticks, segments, ...).
      */
     class DialGauge extends GaugeChart {
         static chartType = 'dialGauge';
+        static LAYOUT = { cx: 100, cy: 80, r: 60, thickness: 12, startAngle: 135, sweep: 270 };
+        static NEEDLE_COLORS = ['#2f3542', '#ff4757', '#1e90ff', '#ffa502'];
 
-        _render() {
-            const options = this.options;
-            const { cx = 100, cy = 80, r = 60, color = '#5352ed', title } = options;
-            const p = this._normalizePercent();
-            const resolvedColor = this._resolveColor(color, p);
-            const totalAngle = 270;
-            const startAngle = 135;
-            const endAngle = startAngle + totalAngle;
-            const needleAngle = startAngle + (p / 100) * totalAngle;
-            const rad = Math.PI / 180;
+        track() { return new ArcTrack(this.layout); }
 
-            // Background Arc
-            this.renderer.path(Gauge.arcPath(cx, cy, r, startAngle * rad, endAngle * rad), 'none', { color: '#f1f2f6', width: 12, cap: 'round' });
-            // Progress Arc
-            this.renderer.path(Gauge.arcPath(cx, cy, r, startAngle * rad, needleAngle * rad), 'none', { color: resolvedColor, width: 12, cap: 'round' });
+        /** One per value, the first the main one: {value, label, color}. */
+        get needles() {
+            const { needleColors = DialGauge.NEEDLE_COLORS } = this.options;
+            const values = this.gaugeValue.values.length ? this.gaugeValue.values : [{ value: this.gaugeValue.value }];
+            return values.map((v, i) => ({ ...v, value: this.scale.clamp(v.value), color: v.color ?? needleColors[i % needleColors.length] }));
+        }
 
-            // Needle
-            const needleRad = needleAngle * rad;
-            const nx = cx + (r - 8) * Math.cos(needleRad);
-            const ny = cy + (r - 8) * Math.sin(needleRad);
-            this.renderer.path(`M${cx},${cy} L${nx},${ny}`, 'none', { color: '#2f3542', width: 3, cap: 'round' });
-            this.renderer.circle(cx, cy, 5, '#2f3542');
+        _render() {
+            const { title } = this.options;
+            const track = this.track();
+            const { cx, cy, r } = track;
+
+            this.drawBackground(track, { cap: 'round' });
+            this.drawValue(track, { cap: 'round' });
+            this.drawTarget(track);
+            this.drawTicks(track);
+            const needles = this.needles;
+            // The main needle last, so it is on top.
+            for (const needle of [...needles].reverse()) this.drawNeedle(track, needle);
+            this.renderer.circle(cx, cy, 5, needles[0].color);
 
-            // Text
             this._renderTitle(title, cx, cy + r + 25, { textAnchor: 'middle', fill: '#747d8c', textTransform: 'uppercase' });
-            this._renderPercentageLabel(p, cx, cy + r - 15, { fontSize: '18px', fill: '#2f3542', fontWeight: 'bold' });
+            this._renderValueLabel(cx, cy + r - 15, { fontSize: '18px', fill: '#2f3542', fontWeight: 'bold' });
+            if (needles.length > 1) this.drawLegend(needles, cx, cy + r + (title ? 42 : 25));
+        }
+
+        /** A needle from the centre to just inside the arc. */
+        drawNeedle(track, { value, color }) {
+            const tip = track.point(this.scale.fraction(value), -8);
+            this.renderer.path(`M${track.cx},${track.cy} L${tip.x},${tip.y}`, 'none', { color, width: 3, cap: 'round' });
+        }
+
+        /** Each needle's label and value on one line, centred. */
+        drawLegend(needles, cx, y) {
+            const text = needles.map((n, i) => `${n.label ?? `#${i + 1}`} ${this.scale.label(n.value)}`);
+            const font = { fontSize: '11px' };
+            const width = (t) => (this.renderer.measureText?.(t, font) ?? t.length * 6) + 22;
+            let x = cx - text.reduce((sum, t) => sum + width(t), 0) / 2;
+            needles.forEach((needle, i) => {
+                this.renderer.circle(x + 4, y, 4, needle.color);
+                this.renderer.text(text[i], x + 12, y, { ...font, textAnchor: 'start', verticalAlign: 'middle', fill: '#2f3542' });
+                x += width(text[i]);
+            });
+        }
+    }
+
+    /**
+     * ArcGauge — an arc filled to the value, its number in the middle: a half
+     * circle by default, or any start angle and sweep.
+     *
+     * Options: cx, cy, r (100, 100, 70), thickness (16), startAngle and sweep in
+     * degrees (180 and 180: a half circle over the top), cap ('round' ends), and
+     * every GaugeChart option (min, max, bands, target, ticks, ...). Without
+     * ticks the scale's two ends are labelled.
+     */
+    class ArcGauge extends GaugeChart {
+        static chartType = 'arcGauge';
+
+        static LAYOUT = { cx: 100, cy: 100, r: 70, thickness: 16, startAngle: 180, sweep: 180 };
+
+        track() { return new ArcTrack(this.layout); }
+
+        _render() {
+            const { title, cap } = this.options;
+            const track = this.track();
+            const capOption = cap ? { cap } : {};
+            this.drawBackground(track, capOption);
+            this.drawValue(track, capOption);
+            this.drawTarget(track);
+            if (this.options.ticks) this.drawTicks(track);
+            else this.drawEnds(track);
+            this.drawLabels(track);
+            this._renderTitle(title, track.cx, this.titleY(track), { textAnchor: 'middle', fontSize: '12px', fill: '#747d8c' });
+        }
+
+        /** The value's number in the middle, a little above the centre for an open arc. */
+        drawLabels(track) {
+            const { cx, cy, r } = track;
+            this._renderValueLabel(cx, cy - r * 0.15, { fontSize: `${Math.max(12, Math.round(r * 0.32))}px`, fill: '#2f3542', fontWeight: 'bold' });
+        }
+
+        /** Below the arc's lowest point. */
+        titleY(track) {
+            const lowest = Math.max(track.point(0).y, track.point(1).y, track.cy);
+            return lowest + track.thickness / 2 + 18;
+        }
+
+        /** The scale's min and max under the arc's two ends. */
+        drawEnds(track) {
+            const below = track.thickness / 2 + 2;
+            for (const f of [0, 1]) {
+                const at = track.point(f);
+                this.renderer.text(this.scale.tickLabel(this.scale.valueAt(f), 1), at.x, at.y + below + 8, {
+                    textAnchor: 'middle', verticalAlign: 'middle', fontSize: '10px', fill: '#747d8c',
+                });
+            }
+        }
+    }
+
+    /**
+     * 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).
+     */
+    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; }
+    }
+
+    /**
+     * 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.
+     */
+    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' });
+        }
+    }
+
+    /**
+     * 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.
+     */
+    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);
+        }
+    }
+
+    /**
+     * 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.
+     */
+    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 });
+            }
+        }
+    }
+
+    /**
+     * 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.
+     */
+    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' });
+        }
+    }
+
+    /**
+     * 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.
+     */
+    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; }
     }
 
     /**
@@ -22316,20 +23212,14 @@
             };
             const style = this.textStyle;
             const font = TextStyle.svgAttributes(style, { defaultPixels: 12 });
-            const zLine = `Z:${this.zIndex || 0}`;
             if (TextStyle.placesText(style)) {
                 // Placed in the shape's box by its alignment and position (centred, middle where unset).
                 const at = TextStyle.block(style, this, 1, { pixels: font['font-size'], defaults: { textAlign: 'center', textPosition: 'middle' } });
                 const placed = { 'text-anchor': at.textAnchor, 'dominant-baseline': 'auto' };
                 if (this.name) text({ x: at.x, y: at.baseline, ...font, ...placed, fill: this.textColor }, this.name);
-                // Under the name, or over it when the name is at the bottom (so it stays in the shape).
-                const zY = style.textPosition === 'bottom' ? at.baseline - font['font-size'] - 2 : at.baseline + 12;
-                text({ x: at.x, y: zY, 'font-size': 10, fill: '#666', ...placed }, zLine);
                 return;
             }
             if (this.name) text({ x, y, ...font, fill: this.textColor }, this.name);
-            // Below the name, however large it is set.
-            text({ x, y: y + Math.max(16, font['font-size'] / 2 + 10), 'font-size': 10, fill: '#666' }, zLine);
         }
 
         serialize() {
@@ -40085,14 +40975,11 @@
 
         /**
          * Renders a bar gauge.
-         * @param {number} value The value to display (0-100).
+         * @param {number|{value:number, target?:number}} value The value to display (0-100 unless options.min/max are given).
          * @param {object} [options] Charting options.
          */
         barGauge(value, options = {}) {
-            if (!this.renderer) return;
-            this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
-            this._chartState = { type: 'barGauge', data: value, options };
-            this._renderChart(new BarGauge(this.renderer, value, options));
+            this._renderGauge(BarGauge, 'barGauge', value, options);
         }
 
         /**
@@ -40102,22 +40989,90 @@
          * @param {object} [options] Charting options.
          */
         bulletGauge(data, options = {}) {
-            if (!this.renderer) return;
-            this._chart3D = false;
-            this._chartState = { type: 'bullet', data, options };
-            this._renderChart(new BulletGauge(this.renderer, data, options));
+            this._renderGauge(BulletGauge, 'bullet', data, options);
         }
 
         /**
          * Renders a dial gauge.
-         * @param {number} value The value to display (0-100).
+         * @param {number|{value:number, target?:number}} value The value to display (0-100 unless options.min/max are given).
          * @param {object} [options] Charting options.
          */
         dialGauge(value, options = {}) {
+            this._renderGauge(DialGauge, 'dialGauge', value, options);
+        }
+
+        /**
+         * Renders an arc gauge: a half circle (or any start angle and sweep) filled to the value.
+         * @param {number|{value:number, target?:number}} value The value (0-100 unless options.min/max are given).
+         * @param {object} [options] The gauge options (see REFERENCE.md, Gauges), cx, cy, r, thickness, startAngle, sweep, cap.
+         */
+        arcGauge(value, options = {}) {
+            this._renderGauge(ArcGauge, 'arcGauge', value, options);
+        }
+
+        /**
+         * Renders a progress ring, its value in the middle.
+         * @param {number|{value:number, target?:number}} value The value (0-100 unless options.min/max are given).
+         * @param {object} [options] The gauge options, cx, cy, r, thickness.
+         */
+        ringGauge(value, options = {}) {
+            this._renderGauge(RingGauge, 'ringGauge', value, options);
+        }
+
+        /**
+         * Renders several values as rings one inside the other, with a legend.
+         * @param {Array<number|{value:number, label?:string, color?:string, min?:number, max?:number}>} values Outer ring first.
+         * @param {object} [options] cx, cy, r, thickness, gap, colors, legend, min, max, format, units, title.
+         */
+        multiRingGauge(values, options = {}) {
+            this._renderGauge(MultiRingGauge, 'multiRingGauge', values, options);
+        }
+
+        /**
+         * Renders a KPI tile: a figure, its change since the previous value, and a sparkline of its history.
+         * @param {number|{value?:number, previous?:number, history?:number[]}} data
+         * @param {object} [options] x, y, width, height, format, units, change ('percent'|'value'), upIsGood, bands, sparkColor, background, title.
+         */
+        kpiTile(data, options = {}) {
+            this._renderGauge(KpiTile, 'kpiTile', data, options);
+        }
+
+        /**
+         * Renders a thermometer: a tube filled from a bulb up to the value.
+         * @param {number|{value:number, target?:number}} value The value (0-100 unless options.min/max are given).
+         * @param {object} [options] The gauge options, x, y, width, height, bulb.
+         */
+        thermometerGauge(value, options = {}) {
+            this._renderGauge(ThermometerGauge, 'thermometerGauge', value, options);
+        }
+
+        /**
+         * Every gauge method draws through here. With `options.animate` (true:
+         * 400ms, or milliseconds) a gauge of the same type already showing eases
+         * from the value it shows to the new one; a newer call stops an older
+         * animation and starts from where it got to.
+         * @private
+         */
+        _renderGauge(GaugeType, type, data, options = {}) {
             if (!this.renderer) return;
             this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
-            this._chartState = { type: 'dialGauge', data: value, options };
-            this._renderChart(new DialGauge(this.renderer, value, options));
+            this._chartState = { type, data, options };
+            this._gaugeAnimation?.stop();
+            const shown = this._gaugeShown?.type === type ? this._gaugeShown.data : null;
+            const draw = (frame) => {
+                this._gaugeShown = { type, data: frame };
+                this._renderChart(new GaugeType(this.renderer, frame, options));
+            };
+            if (!options.animate || shown == null) {
+                draw(data);
+                return;
+            }
+            this._gaugeAnimation = new GaugeAnimation({
+                from: GaugeValue.from(shown, options),
+                to: GaugeValue.from(data, options),
+                duration: options.animate === true ? 400 : Number(options.animate),
+                draw,
+            }).start();
         }
 
         _arcPath(cx, cy, r, startAngle, endAngle) {