@peter.prib/renderengine 0.1.0 → 0.2.0

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) {