@peter.prib/renderengine 0.1.0 → 0.2.0

package/README.md

@@ -124,7 +124,7 @@ Each model can hold several diagrams, with line styles inherited from the diagra
 ## The chart library
 
 The engine underneath draws 24 chart types: bar, line, area, pie, scatter, bubble, heatmap, candlestick,
-waterfall, histogram, box plot, violin, radar, funnel, treemap, sunburst, gauges, 3D bars and others. It also
+waterfall, histogram, box plot, violin, radar, funnel, treemap, sunburst, gauges (dial, arc, ring, rings, bar, bullet, thermometer, KPI tiles; with bands, targets, LED segments and animation), 3D bars and others. It also
 draws graph and railroad diagrams, all to SVG or Canvas. `test/charts.html` is the full gallery, and
 `examples/csv-chart-builder.html` builds a chart from a CSV file without code.
 

package/REFERENCE.md

@@ -81,9 +81,14 @@ catalog `key` for you.
 | `treemap` | `treemapChart(data, opts)` | `Array<{label, value?, children?}>` (hierarchical) | squarified layout, palette by top-level branch |
 | `sunburst` | `sunburstChart(data, opts)` | same hierarchical shape as `treemap` | nested rings by depth |
 | `outline` | `outlineChart(data, opts)` | same hierarchical shape as `treemap`/`sunburst` | `onNodeClick`; collapsible indented list |
-| `gauge-dial` | `dialGauge(value, opts)` | `number` (0–100) | `color`, `title` |
-| `gauge-bar` | `barGauge(value, opts)` | `number` (0–100) | `color`, `title` |
-| `bullet` | `bulletGauge(data, opts)` | `number` or `{value, target?, ranges?:Array<{max,label?,color?}>}` | `target`, `ranges`, `barColor`, `targetColor`, `min`, `max`, `title` |
+| `gauge-dial` | `dialGauge(value, opts)` | `number`, `{value, target?}`, or `[{value, label?, color?}]` for a needle each (0–100 unless `min`/`max`) | the gauge options below; `cx`, `cy`, `r`, `thickness`, `startAngle`, `sweep`, `needleColors`; several needles get a legend, the first fills the arc |
+| `gauge-bar` | `barGauge(value, opts)` | `number` or `{value, target?}` (0–100 unless `min`/`max`) | the gauge options below; `x`, `y`, `width`, `height`, `orientation: 'vertical'` |
+| `gauge-arc` | `arcGauge(value, opts)` | `number` or `{value, target?}` | the gauge options below; `cx`, `cy`, `r`, `thickness`, `startAngle`, `sweep` (a half circle by default), `cap` |
+| `gauge-thermometer` | `thermometerGauge(value, opts)` | `number` or `{value, target?}` | the gauge options below; `x`, `y`, `width`, `height` (the tube), `bulb` (its radius) |
+| `gauge-ring` | `ringGauge(value, opts)` | `number` or `{value, target?}` | the gauge options below; a whole circle from the top, the value in the middle |
+| `gauge-rings` | `multiRingGauge(values, opts)` | numbers or `{value, label?, color?, min?, max?}`, outer first | one ring per value on its own scale; `gap`, `colors`, `legend` |
+| `kpi-tile` | `kpiTile(data, opts)` | `number` or `{value?, previous?, history?:number[]}` | the figure (grouped), its change (`change`: `'percent'` or `'value'`; `upIsGood`), a sparkline of the history; `x`, `y`, `width`, `height`, `bands`, `sparkColor`, `background` |
+| `bullet` | `bulletGauge(data, opts)` | `number` or `{value, target?, ranges?:Array<{max,label?,color?}>}` | the gauge options below; `ranges` (its name for `bands`), `barColor`, `rangeColors`, `showLabels` |
 | `bar3D` | `barChart3D(data, opts)` | `Array<{label, value, depth?}>` | `depthScale`; fixed-angle isometric, not a real camera |
 | `bubble3D` | `bubbleChart3D(data, opts)` | `Array<{label, x, y, z, size?, category?}>` | real orbit camera — drag to rotate, wheel to zoom |
 | `bar3DOrbit` | `barChart3DOrbit(data, opts)` | `Array<{x, z, value}>` (grid) | real orbit camera |
@@ -92,6 +97,40 @@ catalog `key` for you.
 | `parallelCoordinates` | `parallelCoordinates(data, opts)` | `Array<{label?, category?, [dim: number]}>` | one vertical axis per numeric dimension; category-driven colors; `dimensions` |
 | `geoMap` | `geoMap(data, opts)` | `{features: Array<{id, name, value?, color?, geometry}>, bubbles?: Array<{lat, lon, value}>}` | equirectangular projection; `center`, `scale`, `colorScale`; see note below |
 
+**Gauges.** Every gauge is a `GaugeChart` (`src/charting/charts/GaugeChart.js`) and takes the same options:
+
+| Option | Meaning |
+|---|---|
+| `min`, `max` | The scale (0 and 100). A 0–100 scale reads as a percentage ("75.0%"), any other as its number |
+| `format`, `units` | How numbers read: `(v) => string`, or `{decimals, prefix, suffix, grouping, compact}` ("$1,234.5", "12.3K"); `units` is a suffix ("120.0 ms") |
+| `bands` | `[{to, color?, label?}]` in order, each from where the one before ended; drawn lighter behind the value, and the value takes its band's colour. `bandColors` colours the bands without their own |
+| `color` | The value's colour (wins over its band's): one, a gradient array of colours or `{stop, color}`, or `(percent) => colour` |
+| `target`, `targetColor` | A marker across the track at a value (or the data's `target`) |
+| `ticks` | That many equal steps, marked outside the track and labelled with only the decimals a step needs |
+| `segments`, `segmentGap` | The track as that many blocks, `segmentGap` pixels apart (2), lit up to the value (LED style); with bands each lit block takes its own band's colour, a level meter |
+| `animate` | `true` (400 ms) or milliseconds: drawing the same type of gauge again on the same engine eases from the value it shows to the new one (the value, target and each of several values; ease-out). A newer value stops an older animation and starts from where it got to |
+| `title` | |
+
+```js
+engine.dialGauge(72, { min: 0, max: 120, units: 'km/h', ticks: 6, target: 100,
+    bands: [{ to: 80, color: '#6bcb77' }, { to: 100, color: '#ffd93d' }, { to: 120, color: '#ff6b6b' }] });
+engine.barGauge({ value: 40, target: 55 }, { orientation: 'vertical', ticks: 4 });
+engine.ringGauge({ value: 380 }, { max: 500, format: { decimals: 0, suffix: ' / 500' } });
+engine.multiRingGauge([{ label: 'Move', value: 420, max: 600 }, { label: 'Stand', value: 9, max: 12 }]);
+engine.kpiTile({ history: [182000, 191200, 214300] }, { title: 'Revenue', format: { prefix: '$', grouping: true } });
+engine.dialGauge([{ label: 'Actual', value: 68 }, { label: 'Budget', value: 80 }], { animate: true });
+engine.barGauge(84, { segments: 20, bands: [{ to: 70, color: '#2ed573' }, { to: 100, color: '#ff4757' }] });
+```
+
+The pieces are in `src/charting/gauges/`: `GaugeScale` (range, fractions, ticks, formatting), `GaugeBands`
+(the bands and which one a value is in), `GaugeValue` (value, target, previous, history, several values) and the
+tracks a value moves along, `HorizontalTrack`, `VerticalTrack` (both `LinearTrack`s) and `ArcTrack` (any start
+angle and sweep, a full ring included), `Sparkline` (a series fitted to a box) and `GaugeAnimation` (frames from `GaugeValue.between(from, to, t)` on an
+injectable clock). A new gauge picks a track and
+draws with `drawBackground`, `drawValue`, `drawTarget` and `drawTicks`; its `static LAYOUT` gives its default place
+and size (`cx`, `cy`, `r`, ...), which the options of the same names override. `ArcGauge` → `RingGauge` is the
+pattern: the ring only changes the layout and where the labels go.
+
 **`geoMap` note:** the `test/charts.html` demo uses deliberately rough, hand-drawn continental
 polygons so the page needs no external map file. Real use should pass proper GeoJSON-like
 `Polygon`/`MultiPolygon` features; the engine itself has no bundled world geometry and makes no