@peter.prib/renderengine 0.1.0 → 0.2.1

package/src/charting/gauges/GaugeValue.js

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

package/src/charting/gauges/HorizontalTrack.js

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

package/src/charting/gauges/LinearTrack.js

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

package/src/charting/gauges/Sparkline.js

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

package/src/charting/gauges/VerticalTrack.js

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

package/src/charting/templates/Template.js

@@ -170,20 +170,14 @@ export class Template {
         };
         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() {

package/src/index.js

@@ -39,6 +39,13 @@ import { WaterfallChart } from './charting/charts/WaterfallChart.js';
 import { BarGauge } from './charting/charts/BarGauge.js';
 import { BulletGauge } from './charting/charts/BulletGauge.js';
 import { DialGauge } from './charting/charts/DialGauge.js';
+import { ArcGauge } from './charting/charts/ArcGauge.js';
+import { RingGauge } from './charting/charts/RingGauge.js';
+import { MultiRingGauge } from './charting/charts/MultiRingGauge.js';
+import { KpiTile } from './charting/charts/KpiTile.js';
+import { ThermometerGauge } from './charting/charts/ThermometerGauge.js';
+import { GaugeAnimation } from './charting/gauges/GaugeAnimation.js';
+import { GaugeValue } from './charting/gauges/GaugeValue.js';
 import { BarChart3D } from './charting/charts/BarChart3D.js';
 import { BubbleChart3D } from './charting/charts/BubbleChart3D.js';
 import { BarChart3DOrbit } from './charting/charts/BarChart3DOrbit.js';
@@ -1657,14 +1664,11 @@ export class RenderEngine {
 
     /**
      * 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);
     }
 
     /**
@@ -1674,22 +1678,90 @@ export class RenderEngine {
      * @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) {