@peter.prib/renderengine 0.14.0 → 0.15.0

package/README.md

@@ -322,30 +322,48 @@ The engine underneath draws **over 50 chart and diagram types** to interchangeab
 all driven by a single declarative catalog (`CHART_CATALOG`):
 
 - **Categorical & comparison**: `barChart`, `groupedBarChart`, `stackedBarChart` (standard and **100% normalized**
-  `normalize: true`), `lollipopChart` (single and multi-series dot-and-stem), `marimekkoChart` (variable-width
-  2D mosaic), `paretoChart` (descending bars + cumulative 0–100% curve + 80% threshold line), `waterfallChart`,
-  `funnelChart`, `populationPyramid`, `radialBarChart`, `wordCloud`.
-- **Time-series & trend**: `lineChart` (with error bars and multi-series), `areaChart` (standard, stacked, and
-  **100% normalized** `normalize: true`), `stackedAreaChart`, `streamGraph`, `pipeChart` (variable-width flow),
-  `candlestick` (OHLC with event markers), `ganttChart`, `calendarHeatmap`.
-- **Hierarchical & part-of-whole**: `pieChart`, `donutChart`, `treemapChart`, `sunburstChart`, `icicleChart`
-  (top-down rectangular partition), `outlineChart` (collapsible indented tree with inline proportion bars).
-- **Statistical & distribution**: `histogram`, `boxPlot`, `densityChart` (kernel density estimation), `violinChart`,
-  `qqPlot` (normal quantile-quantile), `lagPlot` (lag-1 autocorrelation), `scatterChart` (with 2D error bars and
-  reference lines), `bubbleChart`.
-- **Multivariate, matrix & network flow**: `heatmap` (correlation and matrix grids), `radarChart` (spider),
-  `parallelCoordinates`, `sankeyDiagram`, `chordDiagram`, `geoMap` (choropleth polygons + city bubbles).
-- **3D & orbit camera**: `barChart3D`, `bubbleChart3D`, `lineChart3D`, and true 4×4 matrix perspective orbit charts
-  (`scatter3DOrbit`, `barChart3DOrbit`, `stackedBarChart3DOrbit`, `graphDiagram3D`).
-- **Gauges & KPIs**: `dialGauge` (bands, ticks, multi-needle, targets), `arcGauge`, `ringGauge`, `ringsGauge`,
-  `barGauge`, `bulletChart`, `thermometerGauge`, `ledGauge`, `kpiTile` (with sparklines and delta badges).
+  `normalize: true`; vertical and horizontal `orientation: 'horizontal'`), `comboChart` (multi-type bar + line/area with dual/secondary Y-axes),
+  `dumbbellChart` (before/after gap change with directional delta indicators), `slopegraph` (multi-stage
+  trajectory lines with direct collision-resolved labels), `lollipopChart` (single and multi-series dot-and-stem),
+  `marimekkoChart` (variable-width 2D mosaic), `paretoChart` (descending bars + cumulative 0–100% curve + 80% threshold line),
+  `waterfallChart`, `funnelChart`, `populationPyramid`, `radialBarChart`, `polarAreaChart` (2D & 3D Nightingale Rose / Coxcomb
+  with exploded wedges and hover pull-out), `wordCloud`.
+- **Time-series & trend**: `lineChart` (with step modes `'before'|'after'|'center'`, dual Y-axes, direct data labels `showValues`, error bars and multi-series),
+  `areaChart` (standard, step, stacked, and **100% normalized** `normalize: true`), `stackedAreaChart`, `streamGraph`, `horizonChart`
+  (multi-band folded density for vertical strip comparison), `pipeChart` (variable-width flow), `candlestick` (OHLC with event markers),
+  `ohlcChart` (equity price bars with bullish/bearish color encoding), `ganttChart`, `calendarHeatmap`.
+- **Hierarchical & part-of-whole**: `pieChart` and `donutChart` (with exploded slices, smooth hover slice pull-out,
+  callout leader lines, `"Other"` roll-up, and center KPI totals), `pieChart3D` and `donutChart3D` (extruded 3D
+  tilted wedges and rings with cylinder skirts, radial cut walls, exploded slices, and interactive hover pull-out),
+  `circlePackChart` (nested tangent circles with translucent branch containment and hover elevation),
+  `treemapChart`, `sunburstChart` (with radial hover arc pull-out), `icicleChart` (top-down rectangular partition),
+  `outlineChart` (collapsible indented tree with inline proportion bars).
+- **Statistical & distribution**: `hexbinChart` (2D hexagonal binning density plot for dense observation clouds),
+  `ecdfChart` (empirical cumulative step distribution with Kolmogorov–Smirnov distance test),
+  `scatterMatrix` (SPLOM pairwise scatter matrix with diagonal distribution histograms),
+  `ridgelineChart` (vertically staggered, partially overlapping Joy plot KDE curves),
+  `beeswarmChart` (deterministic force-packed observation points; optional Raincloud mode pairing half-KDE cloud,
+  mini-box, and packed dots), `histogram`, `boxPlot` (vertical and horizontal), `densityChart` (kernel density estimation),
+  `violinChart` (vertical and horizontal), `qqPlot` (normal quantile-quantile), `lagPlot` (lag-1 autocorrelation),
+  `scatterChart` (with 2D error bars and reference lines), `bubbleChart`.
+- **Multivariate, matrix & network flow**: `alluvialDiagram` (multi-stage categorical flow ribbons across arbitrary stages),
+  `heatmap` (correlation and matrix grids), `radarChart` (spider), `parallelCoordinates`, `sankeyDiagram`
+  (with interactive connected-flow hover highlighting), `chordDiagram` (with radial arc pull-out and connected-chord illumination),
+  `geoMap` (choropleth polygons + city bubbles).
+- **3D & orbit camera**: `pieChart3D`, `donutChart3D`, `polarAreaChart` (`extrude3D: true`), `barChart3D`,
+  `bubbleChart3D`, `lineChart3D`, and true 4×4 matrix perspective orbit charts (`scatter3DOrbit`, `barChart3DOrbit`,
+  `stackedBarChart3DOrbit` with 100% normalized mode, `surfaceChart3D` continuous 3D surface mesh, `graphDiagram3D`).
+- **Gauges & KPIs**: `sparklineTable` (executive KPI table with inline trend sparklines), `dialGauge` (bands, ticks, multi-needle, targets),
+  `arcGauge`, `ringGauge`, `ringsGauge`, `barGauge`, `bulletChart`, `thermometerGauge`, `ledGauge`, `kpiTile` (with sparklines and delta badges).
 - **Interactive tables & diagrams**: `tableChart`, `resultView` (sortable, filterable, pageable table that switches
   into any fitting chart via `ChartChooser`), `pivotView`, `pivotChart`, `graphDiagram` (force-directed, hierarchical
   Dewey keys, table nodes, orthogonal/polyline obstacle-avoiding routing, manual bendpoints), `archimateDiagram`,
   `dataModelDiagram`, `railroadDiagram`, `ebnfDiagram`.
 
-`test/charts.html` is the full interactive workspace gallery (including the dedicated **Cubing** perspective), and
-`examples/csv-chart-builder.html` builds charts from a CSV file without code.
+`test/charts.html` is the full interactive workspace gallery (including the dedicated **Cubing** perspective,
+nested perspective sub-menus with instant search filtering & smooth card jumping, and a **`</> JS`** button on
+every card to view and 1-click copy the generating JavaScript), and `examples/csv-chart-builder.html` builds charts
+from a CSV file without code.
 
 ```javascript
 const engine = new RenderEngine('#chart', { rendererType: 'svg' });
@@ -368,6 +386,14 @@ engine.stackedBarChart([
 engine.marimekkoChart(seriesData, { title: 'Market Share by Region & Segment' });
 engine.lollipopChart(seriesData, { title: 'Regional Revenue Comparison', legend: true });
 engine.icicleChart(hierarchyTree, { title: 'Disk Usage by Category' });
+
+// 3D Pie & 3D Donut with pre-exploded slice and smooth hover pull-out
+engine.pieChart3D(sectorData, {
+    title: '3D Sector Exposure',
+    exploded: 'max',        // pre-explode largest slice (or pass index, label, array, or predicate)
+    hoverExplode: true,     // smoothly slides any slice out along its radial angle on hover
+    showLabels: 'percent',
+});
 ```
 
 ![Gauges: a dial with bands, ticks and a target; arc, ring and nested rings; a two-needle dial; LED segments; a thermometer; KPI tiles with sparklines](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/gauges.png)

package/bin/renderengine.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadModel, checkModel, reportModel, saveModel, formatFindings } from '../src/cli.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function getPackageVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf8'));
+        return pkg.version || '0.0.0';
+    } catch {
+        return '0.0.0';
+    }
+}
+
+function printUsage() {
+    console.log(`RenderEngine CLI v${getPackageVersion()}
+
+Usage:
+  renderengine <command> [options]
+
+Commands:
+  check <modelPath>       Validate a model and display issues
+    --json                Output findings as JSON
+    --severity <level>    Filter by severity: error, warning, info
+
+  report <modelPath>      Generate a standalone HTML report
+    --output, -o <file>   Output HTML path (default: <modelName>-report.html)
+    --title <title>       Report title
+
+  save <modelPath>        Convert or save a model
+    --output, -o <file>   Output file path (required)
+    --format <format>     Output format: archi (default), exchange, json
+
+General Options:
+  --help, -h              Show this help message
+  --version, -v           Show version number
+`);
+}
+
+function parseArgs(args) {
+    const parsed = { _: [], flags: {} };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help' || arg === '-h') {
+            parsed.flags.help = true;
+        } else if (arg === '--version' || arg === '-v') {
+            parsed.flags.version = true;
+        } else if (arg === '--json') {
+            parsed.flags.json = true;
+        } else if (arg === '--output' || arg === '-o') {
+            parsed.flags.output = args[++i];
+        } else if (arg === '--format') {
+            parsed.flags.format = args[++i];
+        } else if (arg === '--title') {
+            parsed.flags.title = args[++i];
+        } else if (arg === '--severity') {
+            parsed.flags.severity = args[++i];
+        } else if (arg.startsWith('--')) {
+            const [k, v] = arg.slice(2).split('=');
+            parsed.flags[k] = v ?? true;
+        } else {
+            parsed._.push(arg);
+        }
+    }
+    return parsed;
+}
+
+export async function run(argv = process.argv.slice(2)) {
+    const { _, flags } = parseArgs(argv);
+
+    if (flags.version) {
+        console.log(`v${getPackageVersion()}`);
+        return 0;
+    }
+
+    if (flags.help || !_.length) {
+        printUsage();
+        return 0;
+    }
+
+    const command = _[0];
+    const modelPath = _[1];
+
+    if (!modelPath && command !== 'help') {
+        console.error(`Error: Model path required for '${command}'`);
+        printUsage();
+        return 1;
+    }
+
+    try {
+        const readInput = (file) => {
+            if (!fs.existsSync(file)) throw new Error(`File not found: ${file}`);
+            return fs.readFileSync(file);
+        };
+
+        if (command === 'check') {
+            const model = loadModel(readInput(modelPath));
+            const { findings, summary } = checkModel(model, { severity: flags.severity });
+
+            if (flags.json) {
+                console.log(JSON.stringify({ findings, summary }, null, 2));
+            } else {
+                console.log(formatFindings(findings, summary));
+            }
+            return summary.errors > 0 ? 1 : 0;
+        }
+
+        if (command === 'report') {
+            const model = loadModel(readInput(modelPath));
+            const title = flags.title || model.name || 'Model Report';
+            const html = reportModel(model, { title });
+            const defaultOut = `${path.basename(modelPath, path.extname(modelPath))}-report.html`;
+            const outPath = flags.output || defaultOut;
+
+            fs.writeFileSync(outPath, html, 'utf8');
+            console.log(`Report generated: ${outPath} (${html.length} bytes)`);
+            return 0;
+        }
+
+        if (command === 'save') {
+            if (!flags.output) {
+                console.error('Error: --output (-o) is required for the save command');
+                return 1;
+            }
+            const model = loadModel(readInput(modelPath));
+            const format = flags.format || 'archi';
+            const { data } = saveModel(model, { format });
+
+            if (data instanceof Uint8Array || Buffer.isBuffer(data)) {
+                fs.writeFileSync(flags.output, Buffer.from(data));
+            } else {
+                fs.writeFileSync(flags.output, String(data), 'utf8');
+            }
+            console.log(`Saved model to: ${flags.output} (${format})`);
+            return 0;
+        }
+
+        console.error(`Unknown command: ${command}`);
+        printUsage();
+        return 1;
+    } catch (err) {
+        console.error(`Error: ${err.message}`);
+        return 1;
+    }
+}
+
+// Only execute when run directly from the command line
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(__filename)) {
+    run().then(code => {
+        if (code !== 0) process.exit(code);
+    });
+}