@peter.prib/renderengine 0.1.0 → 0.2.1

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',

package/src/charting/charts/KpiTile.js

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

package/src/charting/charts/MultiRingGauge.js

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

package/src/charting/charts/RingGauge.js

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

package/src/charting/charts/ThermometerGauge.js

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

package/src/charting/gauges/ArcTrack.js

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

package/src/charting/gauges/GaugeAnimation.js

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

package/src/charting/gauges/GaugeBands.js

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

package/src/charting/gauges/GaugeScale.js

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

package/src/charting/gauges/GaugeTrack.js

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