@peter.prib/renderengine 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",

package/src/chartCatalog.js

@@ -461,18 +461,18 @@ export const CHART_CATALOG = [
     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
   },
   {
@@ -485,6 +485,51 @@ export const CHART_CATALOG = [
     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,

package/src/charting/Gauge.js

@@ -38,6 +38,12 @@ export class Gauge {
      * 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),

package/src/charting/charts/ArcGauge.js

@@ -0,0 +1,55 @@
+import { GaugeChart } from './GaugeChart.js';
+import { ArcTrack } from '../gauges/ArcTrack.js';
+
+/**
+ * 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.
+ */
+export 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',
+            });
+        }
+    }
+}

package/src/charting/charts/BarGauge.js

@@ -1,21 +1,42 @@
 import { GaugeChart } from './GaugeChart.js';
+import { HorizontalTrack } from '../gauges/HorizontalTrack.js';
+import { VerticalTrack } from '../gauges/VerticalTrack.js';
 
 /**
- * BarGauge — a simple horizontal percentage bar.
+ * 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, ...).
  */
 export 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' });
+        }
     }
 }

package/src/charting/charts/BulletGauge.js

@@ -1,4 +1,5 @@
-import { Chart } from '../Chart.js';
+import { GaugeChart } from './GaugeChart.js';
+import { HorizontalTrack } from '../gauges/HorizontalTrack.js';
 import { ChartBox, ChartLabels } from '../ChartBox.js';
 
 /**
@@ -8,82 +9,77 @@ import { ChartBox, ChartLabels } from '../ChartBox.js';
  * 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
  */
-export class BulletGauge extends Chart {
+export 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);
+    }
+
+    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 };
+    }
 
-        const span = (max - min) || 1;
-        const toX = (v) => x + Math.min(Math.max((v - min) / span, 0), 1) * width;
+    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',
                 });
             }
         }

package/src/charting/charts/DialGauge.js

@@ -1,37 +1,65 @@
-import { Gauge } from '../Gauge.js';
 import { GaugeChart } from './GaugeChart.js';
+import { ArcTrack } from '../gauges/ArcTrack.js';
 
 /**
- * DialGauge — a semicircular percentage gauge with a needle.
+ * 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, ...).
  */
 export 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'];
+
+    track() { return new ArcTrack(this.layout); }
+
+    /** 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] }));
+    }
 
     _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;
-
-        // 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' });
-
-        // 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');
-
-        // Text
+        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);
+
         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]);
+        });
     }
 }

package/src/charting/charts/GaugeChart.js

@@ -1,22 +1,150 @@
 import { Chart } from '../Chart.js';
 import { Gauge } from '../Gauge.js';
+import { GaugeScale } from '../gauges/GaugeScale.js';
+import { GaugeBands } from '../gauges/GaugeBands.js';
+import { GaugeValue } from '../gauges/GaugeValue.js';
 
 /**
- * GaugeChart — abstract base for 0-100 percentage gauges.
+ * GaugeChart — abstract base for gauges: one value shown along a track.
  *
- * Subclasses implement `_renderGauge()` and use the shared normalization,
- * color resolution, title, and percentage-label helpers.
+ * 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
  */
 export 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;
+    }
+
+    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 });
     }
 
-    /** Resolve the gauge color for the current percentage. */
-    _resolveColor(color, percent) {
-        return Gauge.resolveColor(color, percent);
+    /** `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. */
@@ -30,9 +158,9 @@ export class GaugeChart extends Chart {
         });
     }
 
-    /** 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',