@peter.prib/renderengine 0.0.0-stage → 0.1.0

package/src/charting/charts/BarChart3D.js

@@ -0,0 +1,56 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * BarChart3D — fixed-isometric 3D bars. Each bar is drawn as a front rect
+ * plus top and right parallelogram faces for a simple 3D effect.
+ */
+export class BarChart3D extends Chart {
+    static chartType = 'bar3d';
+
+    _render() {
+        const data = this.data;
+        const options = this.options;
+        const box = ChartBox.fromRenderer(this.renderer);
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            title, xAxisLabel, yAxisLabel,
+            colors, depthScale = 0.5,
+        } = options;
+        const plotBox = { x, y, width, height };
+        const maxValue = Math.max(...data.map(d => d.value)) || 1;
+        const barWidth = width / data.length * 0.7;
+        const barMargin = width / data.length * 0.3 / 2;
+        const depth = 30 * depthScale;
+        const palette = new ColorPalette(colors);
+
+        new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, plotBox);
+        this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
+
+        data.forEach((d, i) => {
+            const barX = x + i * (width / data.length) + barMargin;
+            const barHeight = (d.value / maxValue) * height;
+            const barBaseY = y + height;
+            const color = palette.colorAt(i);
+
+            this.renderer.rect(
+                barX, barBaseY - barHeight, barWidth, barHeight,
+                color,
+                { color: '#333', width: 1 },
+                { tooltip: `${d.label}: ${d.value}` },
+            );
+
+            // Top face
+            const topPath = `M${barX},${barBaseY - barHeight} L${barX + barWidth},${barBaseY - barHeight} L${barX + barWidth + depth},${barBaseY - barHeight - depth} L${barX + depth},${barBaseY - barHeight - depth} Z`;
+            this.renderer.path(topPath, palette.lighten(color, 0.2), { color: '#333', width: 1 });
+
+            // Right face
+            const rightPath = `M${barX + barWidth},${barBaseY - barHeight} L${barX + barWidth},${barBaseY} L${barX + barWidth + depth},${barBaseY + depth} L${barX + barWidth + depth},${barBaseY - barHeight - depth} Z`;
+            this.renderer.path(rightPath, palette.lighten(color, -0.15), { color: '#333', width: 1 });
+
+            const textAnchor = this.renderer.centerTextAnchor;
+            this.renderer.text(d.label, barX + barWidth / 2, barBaseY + 20, { textAnchor });
+        });
+    }
+}

package/src/charting/charts/BarChart3DOrbit.js

@@ -0,0 +1,53 @@
+import { ColorPalette } from '../ColorPalette.js';
+import { Chart3D } from '../Chart3D.js';
+
+/**
+ * BarChart3DOrbit — grouped 3D bar chart across two categorical axes (x and z)
+ * with a real orbit camera.
+ */
+export class BarChart3DOrbit extends Chart3D {
+    static chartType = 'bar3dOrbit';
+
+    _render() {
+        const data = this.data;
+        const options = this.options;
+        const { colors, title } = options;
+        const { cx, cy, toScreen, box } = this._viewport();
+        const { x: bx, y: by, width, height } = box;
+
+        const { xLabels, zLabels, xIndex, zIndex } = this.bucketGrid(data);
+        const valueMax = Math.max(...data.map(d => d.value)) || 1;
+        const palette = new ColorPalette(colors);
+
+        const cellW = 2 / Math.max(1, xLabels.length);
+        const cellD = 2 / Math.max(1, zLabels.length);
+        const barFrac = 0.7;
+
+        if (title) {
+            this.renderer.text(title, cx, by - 20, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
+        }
+
+        const bars = data.map(d => {
+            const xi = xIndex.get(d.x), zi = zIndex.get(d.z);
+            const xCenter = -1 + cellW * (xi + 0.5);
+            const zCenter = -1 + cellD * (zi + 0.5);
+            const hw = cellW * barFrac / 2, hd = cellD * barFrac / 2;
+            const y1 = d.value / valueMax;
+            const color = palette.colorAt(zi);
+            const { depth } = this.project(xCenter, y1 / 2, zCenter);
+            return { d, x0: xCenter - hw, x1: xCenter + hw, z0: zCenter - hd, z1: zCenter + hd, y1, color, depth };
+        }).sort((a, b) => b.depth - a.depth);
+
+        for (const bar of bars) {
+            this.drawBox(this.renderer, bar.x0, bar.x1, 0, bar.y1, bar.z0, bar.z1, bar.color, toScreen);
+        }
+
+        let legY = by + 10;
+        const legX = bx + width - 100;
+        zLabels.forEach((label, i) => {
+            this.renderer.circle(legX + 5, legY, 5, palette.colorAt(i), null, {});
+            this.renderer.text(String(label), legX + 16, legY + 4, { textAnchor: 'start', fontSize: '11px', fill: '#374151' });
+            legY += 18;
+        });
+    }
+}

package/src/charting/charts/BarChartBase.js

@@ -0,0 +1,70 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { Axis } from '../Axis.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * BarChartBase — shared foundation for cartesian bar charts.
+ *
+ * Subclasses implement `_computeMaxValue()` and `_renderBars(maxValue)`. They
+ * can also override `_beforeBars(maxValue)` (e.g., to draw a Y axis) and
+ * `_afterBars()` (e.g., to draw a legend).
+ */
+export class BarChartBase extends Chart {
+    _setup() {
+        const box = ChartBox.fromRenderer(this.renderer);
+        const options = this.options;
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            colors, title, xAxisLabel, yAxisLabel,
+        } = options;
+        this._plotBox = { x, y, width, height };
+        this._palette = new ColorPalette(colors);
+        new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, this._plotBox);
+    }
+
+    /** @returns {{bandWidth: number, step: number, margin: number}} */
+    _bandScale(count) {
+        const { width } = this._plotBox;
+        const step = width / count;
+        const bandWidth = step * 0.8;
+        const margin = step - bandWidth;
+        return { bandWidth, step, margin };
+    }
+
+    /** Draw the L-shaped base axis. */
+    _drawBaseAxis() {
+        const { x, y, width, height } = this._plotBox;
+        this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
+    }
+
+    /** Draw a Y axis and return the nice-rounded max value. */
+    _drawYAxis(rawMax) {
+        return new Axis().drawYAxis(this.renderer, this._plotBox, rawMax);
+    }
+
+    _render() {
+        this._setup();
+        const maxValue = this._computeMaxValue();
+        this._beforeBars(maxValue);
+        this._renderBars(maxValue);
+        this._drawBaseAxis();
+        this._afterBars();
+    }
+
+    /** @abstract */
+    _computeMaxValue() {
+        throw new Error(`${this.constructor.name} must implement _computeMaxValue()`);
+    }
+
+    /** @abstract */
+    _renderBars(maxValue) {
+        throw new Error(`${this.constructor.name} must implement _renderBars()`);
+    }
+
+    /** Optional hook before bars are drawn (e.g., Y axis). */
+    _beforeBars(maxValue) {}
+
+    /** Optional hook after base axis is drawn (e.g., legend). */
+    _afterBars() {}
+}

package/src/charting/charts/BarGauge.js

@@ -0,0 +1,21 @@
+import { GaugeChart } from './GaugeChart.js';
+
+/**
+ * BarGauge — a simple horizontal percentage bar.
+ */
+export class BarGauge extends GaugeChart {
+    static chartType = 'barGauge';
+
+    _render() {
+        const options = this.options;
+        const { x = 10, y = 10, width = 200, height = 30, color = '#5352ed', title } = options;
+        const p = this._normalizePercent();
+        const barWidth = (p / 100) * width;
+        const resolvedColor = this._resolveColor(color, p);
+
+        this._renderTitle(title, x, y - 5);
+        this.renderer.rect(x, y, width, height, '#f1f2f6', null, { rx: 4, ry: 4 });
+        this.renderer.rect(x, y, barWidth, height, resolvedColor, null, { rx: 4, ry: 4 });
+        this._renderPercentageLabel(p, x + width / 2, y + height / 2, { fontWeight: 'bold' });
+    }
+}

package/src/charting/charts/BoxPlotChart.js

@@ -0,0 +1,41 @@
+import { Axis } from '../Axis.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { Statistics } from '../Statistics.js';
+import { GroupedDistributionChart } from './GroupedDistributionChart.js';
+
+/**
+ * BoxPlotChart — Tukey-style box-and-whisker plot for one or more numeric
+ * samples. Each sample is summarized to quartiles + whiskers (clamped to the
+ * standard 1.5×IQR fences) so outliers don't compress the scale.
+ */
+export class BoxPlotChart extends GroupedDistributionChart {
+    static chartType = 'boxPlot';
+
+    _computeDomain() {
+        const data = this.data;
+        const stats = data.map(d => Statistics.boxPlotStats(d.values));
+        const allVals = stats.flatMap(s => [s.min, s.max, ...s.outliers]);
+        const vMax = Math.max(...allVals);
+        const vMin = Math.min(...allVals);
+        const range = (vMax - vMin) || 1;
+        return { vMin, vMax, range };
+    }
+
+    _renderGlyph(cx, slotWidth, i, d) {
+        const s = Statistics.boxPlotStats(d.values);
+        const boxWidth = slotWidth * 0.5;
+        const boxColor = this.options.boxColor ?? this._palette.colorAt(0);
+
+        this.renderer.path(`M${cx},${this._toY(s.min)} L${cx},${this._toY(s.max)}`, 'none', { color: '#555', width: 1 });
+        this.renderer.path(`M${cx - boxWidth / 4},${this._toY(s.min)} L${cx + boxWidth / 4},${this._toY(s.min)}`, 'none', { color: '#555', width: 1 });
+        this.renderer.path(`M${cx - boxWidth / 4},${this._toY(s.max)} L${cx + boxWidth / 4},${this._toY(s.max)}`, 'none', { color: '#555', width: 1 });
+        const boxTop = this._toY(s.q3), boxBottom = this._toY(s.q1);
+        this.renderer.rect(cx - boxWidth / 2, boxTop, boxWidth, Math.max(1, boxBottom - boxTop), boxColor, { color: '#333', width: 1 }, {
+            tooltip: `${d.label}: median ${Axis.formatValue(s.median)}, Q1 ${Axis.formatValue(s.q1)}, Q3 ${Axis.formatValue(s.q3)}`,
+        });
+        this.renderer.path(`M${cx - boxWidth / 2},${this._toY(s.median)} L${cx + boxWidth / 2},${this._toY(s.median)}`, 'none', { color: '#fff', width: 2 });
+        s.outliers.forEach(v => {
+            this.renderer.circle(cx, this._toY(v), 3, 'none', { color: boxColor, width: 1.5 }, { tooltip: `${d.label} outlier: ${Axis.formatValue(v)}` });
+        });
+    }
+}

package/src/charting/charts/BubbleChart.js

@@ -0,0 +1,99 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { ChartData } from '../ChartData.js';
+
+/**
+ * BubbleChart — 2D bubble chart where z encodes bubble size.
+ */
+export class BubbleChart extends Chart {
+    static chartType = 'bubble';
+
+    constructor(renderer, data, options = {}) {
+        super(renderer, data, options);
+    }
+
+    _render() {
+        const data = this.data;
+        const options = this.options;
+
+        const box = ChartBox.fromRenderer(this.renderer);
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            bubbleColor = 'rgba(100, 150, 240, 0.5)',
+            colorCol, colors, title, xAxisLabel, yAxisLabel,
+            zAxis = false, depth: zDepth = 20,
+        } = options;
+        const plotBox = { x, y, width, height };
+
+        const xValues = data.map(d => d.x);
+        const yValues = data.map(d => d.y);
+        const zValues = data.map(d => d.z);
+        const xMax = Math.max(...xValues);
+        const yMax = Math.max(...yValues);
+        const zMax = Math.max(...zValues);
+
+        const depth = zAxis ? zDepth : 0;
+
+        // Optional per-point categorical coloring — colorCol names a field on
+        // each data point (e.g. 'category'), falling back to a `category` or
+        // `group` field by convention if present. Each distinct value gets
+        // its own color from `colors`, cycling if there are more categories
+        // than colors. Without this, every bubble shares one flat color and
+        // the z-dimension (radius) is the only way to tell points apart.
+        // `colorCol` may be a plain field name or a `{formula, params}`
+        // compiled expression — see `_readColorCol`.
+        const catField = colorCol
+            ?? (data.some(d => d.category != null) ? 'category'
+              : data.some(d => d.group    != null) ? 'group' : null);
+        const palette = new ColorPalette(colors);
+        const catColors = new Map();
+        if (catField) {
+            for (const d of data) {
+                const cat = ChartData.readColorCol(d, catField);
+                if (cat != null && !catColors.has(cat)) catColors.set(cat, palette.colorAt(catColors.size));
+            }
+        }
+        const colorFor = d => {
+            if (!catField) return bubbleColor;
+            const cat = ChartData.readColorCol(d, catField);
+            return cat != null ? catColors.get(cat) : bubbleColor;
+        };
+
+        new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, plotBox);
+
+        const axisPath = zAxis
+            ? `M${x + depth},${y - depth} L${x},${y} L${x},${y + height} L${x + width},${y + height} L${x + width + depth},${y + height - depth} M${x},${y + height} L${x + depth},${y + height - depth}`
+            : `M${x},${y} L${x},${y + height} L${x + width},${y + height}`;
+        this.renderer.path(axisPath, 'none', { color: 'black', width: 1 });
+
+        data.forEach(d => {
+            const bubbleDepth = zAxis ? (d.z / zMax) * depth : 0;
+            const bubbleX = x + (d.x / xMax) * width + bubbleDepth;
+            const bubbleY = y + height - (d.y / yMax) * height;
+            const radius = (d.z / zMax) * 30; // Max radius of 30
+            const color = colorFor(d);
+
+            if (zAxis) {
+                // 3D effect: draw a shadow/base
+                const floorX = bubbleX - bubbleDepth;
+                const floorY = bubbleY + bubbleDepth;
+                this.renderer.circle(floorX, floorY, radius, 'rgba(0,0,0,0.15)', null);
+                // 3D effect: draw a line to the "floor"
+                this.renderer.path(`M${floorX},${floorY} L${bubbleX},${bubbleY}`, 'none', { color: '#e0e0e0', width: 1 });
+            }
+            this.renderer.circle(bubbleX, bubbleY, radius, color, { color: 'rgba(0,0,0,0.2)', width: 1 }, { tooltip: `${d.label}: (${d.x}, ${d.y}, ${d.z})` });
+        });
+
+        // Category color legend
+        if (catField && catColors.size > 0) {
+            let legY = y + 10;
+            const legX = x + width + 20;
+            for (const [cat, color] of catColors) {
+                this.renderer.circle(legX + 5, legY, 5, color, null, {});
+                this.renderer.text(String(cat), legX + 16, legY + 4, { textAnchor: 'start', fontSize: '11px', fill: '#374151' });
+                legY += 18;
+            }
+        }
+    }
+}

package/src/charting/charts/BubbleChart3D.js

@@ -0,0 +1,78 @@
+import { ColorPalette } from '../ColorPalette.js';
+import { Chart3D } from '../Chart3D.js';
+import { ChartData } from '../ChartData.js';
+
+/**
+ * BubbleChart3D — true 3D scatter/bubble chart with an orbit camera.
+ */
+export class BubbleChart3D extends Chart3D {
+    static chartType = 'bubble3d';
+
+    _render() {
+        const data = this.data;
+        const options = this.options;
+        const { colorCol, colors, title } = options;
+        const { cx, cy, toScreen, box } = this._viewport();
+        const { x: bx, y: by, width, height } = box;
+        const pixelRadius = Math.min(width, height) / 2 - 20;
+
+        const xs = data.map(d => d.x), ys = data.map(d => d.y), zs = data.map(d => d.z);
+        const xMax = Math.max(...xs.map(Math.abs)) || 1;
+        const yMax = Math.max(...ys.map(Math.abs)) || 1;
+        const zMax = Math.max(...zs.map(Math.abs)) || 1;
+        const sizes = data.map(d => d.size ?? 0);
+        const sizeMax = Math.max(...sizes) || 1;
+
+        const catField = colorCol
+            ?? (data.some(d => d.category != null) ? 'category'
+              : data.some(d => d.group != null) ? 'group' : null);
+        const palette = new ColorPalette(colors);
+        const catColors = new Map();
+        if (catField) {
+            for (const d of data) {
+                const cat = ChartData.readColorCol(d, catField);
+                if (cat != null && !catColors.has(cat)) catColors.set(cat, palette.colorAt(catColors.size));
+            }
+        }
+
+        if (title) {
+            this.renderer.text(title, cx, by - 20, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
+        }
+
+        const axisEnd = { x: toScreen(1, 0, 0), y: toScreen(0, 1, 0), z: toScreen(0, 0, 1) };
+        const origin = toScreen(0, 0, 0);
+        const axisSpecs = [
+            { end: axisEnd.x, color: '#e74c3c', label: 'X' },
+            { end: axisEnd.y, color: '#2ecc71', label: 'Y' },
+            { end: axisEnd.z, color: '#3498db', label: 'Z' },
+        ];
+        for (const { end, color, label } of axisSpecs) {
+            this.renderer.path(`M${origin.x},${origin.y} L${end.x},${end.y}`, 'none', { color, width: 1.5 });
+            this.renderer.text(label, end.x, end.y, { textAnchor: 'middle', fontSize: '11px', fill: color, fontWeight: 'bold' });
+        }
+
+        const projected = data.map(d => {
+            const screen = toScreen(d.x / xMax, d.y / yMax, d.z / zMax);
+            const radius = d.size != null ? 4 + (d.size / sizeMax) * 16 : 7;
+            const cat = catField ? ChartData.readColorCol(d, catField) : null;
+            const color = cat != null ? catColors.get(cat) : '#4f8ef7';
+            return { d, screen, radius, color };
+        }).sort((a, b) => b.screen.depth - a.screen.depth);
+
+        for (const { d, screen, radius, color } of projected) {
+            this.renderer.circle(screen.x, screen.y, Math.max(2, radius * screen.scale), color,
+                { color: 'rgba(0,0,0,0.25)', width: 1 },
+                { tooltip: `${d.label}: (${d.x}, ${d.y}, ${d.z})` });
+        }
+
+        if (catField && catColors.size > 0) {
+            let legY = by + 10;
+            const legX = bx + width - 90;
+            for (const [cat, color] of catColors) {
+                this.renderer.circle(legX + 5, legY, 5, color, null, {});
+                this.renderer.text(String(cat), legX + 16, legY + 4, { textAnchor: 'start', fontSize: '11px', fill: '#374151' });
+                legY += 18;
+            }
+        }
+    }
+}

package/src/charting/charts/BulletGauge.js

@@ -0,0 +1,91 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+
+/**
+ * BulletGauge — a bullet graph: a primary measure bar compared against one
+ * or more qualitative performance ranges and a target marker.
+ *
+ * Data may be a plain number (the actual value) or an object
+ * `{ value: number, target?: number, ranges?: Array<{max:number, label?, color?}> }`.
+ *
+ * Options:
+ *   target?: number            — target value (overrides data.target)
+ *   ranges?: Range[]            — qualitative ranges (overrides data.ranges)
+ *   min?: number = 0            — scale minimum
+ *   max?: number = 100          — scale maximum
+ *   barColor?: string           — color of the actual-value bar
+ *   targetColor?: string = #333 — color of the target marker
+ *   rangeColors?: string[]      — fallback palette for ranges without their own color
+ *   title?: string
+ *   showLabels?: boolean = true — value/target/range labels
+ */
+export class BulletGauge extends Chart {
+    static chartType = 'bullet';
+
+    _render() {
+        const data = this.data;
+        const options = this.options;
+        const box = ChartBox.fromRenderer(this.renderer);
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height * 0.4,
+            min = 0, max = 100,
+            target: optTarget, targetColor = '#333',
+            barColor = '#5470c6',
+            ranges: optRanges, rangeColors = ['#ff6b6b', '#ffd93d', '#6bcb77'],
+            title, showLabels = true,
+        } = options;
+
+        const actual = typeof data === 'number' ? data : (data?.value ?? 0);
+        const target = optTarget != null ? optTarget : data?.target ?? null;
+        const ranges = optRanges ?? data?.ranges ?? [
+            { max: max * 0.6, label: 'Poor' },
+            { max: max * 0.8, label: 'Satisfactory' },
+            { max: max, label: 'Good' },
+        ];
+
+        const span = (max - min) || 1;
+        const toX = (v) => x + Math.min(Math.max((v - min) / span, 0), 1) * width;
+
+        new ChartLabels({ title }).draw(this.renderer, { x, y, width, height });
+
+        // Draw qualitative range bands
+        let rangeStart = min;
+        ranges.forEach((range, i) => {
+            const rangeEnd = Math.min(Math.max(range.max, min), max);
+            const rx = toX(rangeStart);
+            const rw = toX(rangeEnd) - rx;
+            const color = range.color ?? rangeColors[i % rangeColors.length];
+            this.renderer.rect(rx, y, rw, height, color, null, { opacity: 0.35 });
+            if (showLabels && range.label) {
+                this.renderer.text(range.label, rx + rw / 2, y + height + 14, {
+                    textAnchor: 'middle', fontSize: '10px', fill: '#666',
+                });
+            }
+            rangeStart = rangeEnd;
+        });
+
+        // Draw actual-value bar (thinner, centered vertically)
+        const barHeight = height * 0.5;
+        const barY = y + (height - barHeight) / 2;
+        const actualX = toX(min);
+        const actualW = toX(actual) - actualX;
+        this.renderer.rect(actualX, barY, actualW, barHeight, barColor, null, {});
+
+        // Draw target marker (vertical line)
+        if (target != null) {
+            const tx = toX(target);
+            this.renderer.path(`M${tx},${y - 2} L${tx},${y + height + 2}`, 'none', { color: targetColor, width: 2 });
+        }
+
+        if (showLabels) {
+            this.renderer.text(String(actual), x + width / 2, barY + barHeight / 2, {
+                textAnchor: 'middle', verticalAlign: 'middle', fontSize: '11px', fill: '#fff', fontWeight: 'bold',
+            });
+            if (target != null) {
+                this.renderer.text(String(target), toX(target) + 5, y - 8, {
+                    textAnchor: 'start', fontSize: '10px', fill: targetColor,
+                });
+            }
+        }
+    }
+}