@peter.prib/renderengine 0.0.0-stage → 0.1.0

package/src/charting/charts/PopulationPyramidChart.js

@@ -0,0 +1,106 @@
+import { Chart } from '../Chart.js';
+
+/**
+ * PopulationPyramidChart — back-to-back horizontal bars, typically used to
+ * compare age-group distributions for two populations (e.g. male / female).
+ *
+ * Data: Array<{label: string, left: number, right: number}>
+ * Options:
+ *   - title
+ *   - leftLabel, rightLabel: axis labels
+ *   - leftColor, rightColor: bar colors
+ *   - showValues: boolean
+ *   - barHeight, barGap
+ *   - xAxisLabel, yAxisLabel
+ */
+export class PopulationPyramidChart extends Chart {
+    static chartType = 'populationPyramid';
+
+    _render() {
+        const data = this.data || [];
+        const options = this.options || {};
+        const w = this.renderer?.width ?? 800;
+        const h = this.renderer?.height ?? 400;
+
+        const {
+            x = 60, y = 40,
+            width = w - x - 40,
+            height = h - y - 60,
+            title,
+            leftLabel = 'Left',
+            rightLabel = 'Right',
+            leftColor = '#4f8ef7',
+            rightColor = '#e91e63',
+            showValues = false,
+            barHeight,
+            barGap = 4,
+            xAxisLabel,
+            yAxisLabel,
+        } = options;
+
+        const textAnchor = this.renderer.centerTextAnchor;
+        const maxValue = Math.max(...data.map(d => Math.max(d.left || 0, d.right || 0)), 1);
+        const halfW = width / 2;
+        const centerX = x + halfW;
+        const count = data.length || 1;
+        const bh = barHeight ?? Math.min(28, Math.max(10, (height - (count - 1) * barGap) / count));
+        const totalRowH = bh + barGap;
+        const contentH = count * totalRowH - barGap;
+        const startY = y + (height - contentH) / 2;
+
+        if (title) {
+            this.renderer.text(title, x + width / 2, y - 16, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
+        }
+        if (xAxisLabel) {
+            this.renderer.text(xAxisLabel, x + width / 2, y + height + 36, { textAnchor: 'middle', fontSize: '12px', fill: '#666' });
+        }
+        if (yAxisLabel) {
+            this.renderer.text(yAxisLabel, y + height / 2, x - 45, { textAnchor: 'middle', fontSize: '12px', fill: '#666', transform: `rotate(-90,${x - 45},${y + height / 2})` });
+        }
+
+        // Axis labels at top of each half.
+        this.renderer.text(leftLabel, x + halfW / 2, startY - 10, { textAnchor, fontSize: '12px', fill: leftColor, fontWeight: 'bold' });
+        this.renderer.text(rightLabel, centerX + halfW / 2, startY - 10, { textAnchor, fontSize: '12px', fill: rightColor, fontWeight: 'bold' });
+
+        data.forEach((d, i) => {
+            const rowY = startY + i * totalRowH;
+            const leftW = ((d.left || 0) / maxValue) * halfW;
+            const rightW = ((d.right || 0) / maxValue) * halfW;
+
+            // Left bar grows from center to the left.
+            if (leftW > 0) {
+                this.renderer.rect(centerX - leftW, rowY, leftW, bh, leftColor, null, {
+                    tooltip: `${d.label} — ${leftLabel}: ${d.left}`,
+                });
+            }
+            // Right bar grows from center to the right.
+            if (rightW > 0) {
+                this.renderer.rect(centerX, rowY, rightW, bh, rightColor, null, {
+                    tooltip: `${d.label} — ${rightLabel}: ${d.right}`,
+                });
+            }
+
+            // Row label centered on the axis.
+            this.renderer.text(d.label, centerX, rowY + bh / 2 + 4, {
+                textAnchor: 'middle', fontSize: '10px', fill: '#333',
+            });
+
+            if (showValues) {
+                if (leftW > 14) {
+                    this.renderer.text(String(d.left ?? 0), centerX - leftW + 6, rowY + bh / 2 + 4, {
+                        textAnchor: 'start', fontSize: '9px', fill: '#fff',
+                    });
+                }
+                if (rightW > 14) {
+                    this.renderer.text(String(d.right ?? 0), centerX + rightW - 6, rowY + bh / 2 + 4, {
+                        textAnchor: 'end', fontSize: '9px', fill: '#fff',
+                    });
+                }
+            }
+        });
+
+        // Center and baseline axes.
+        this.renderer.path(`M${x},${y + height} L${x + width},${y + height}`, 'none', { color: '#999', width: 1 });
+        this.renderer.path(`M${centerX},${startY - 6} L${centerX},${y + height}`, 'none', { color: '#999', width: 1, dasharray: '4 3' });
+    }
+}

package/src/charting/charts/QQPlotChart.js

@@ -0,0 +1,64 @@
+import { ScatterChart } from './ScatterChart.js';
+import { Statistics } from '../Statistics.js';
+
+/**
+ * QQPlotChart — Q-Q plot against the theoretical normal distribution.
+ *
+ * Transforms a raw numeric sample into (theoretical quantile, sample value)
+ * scatter points, fits a Q1/Q3 reference line, and delegates the actual
+ * rendering to ScatterChart.
+ */
+export class QQPlotChart extends ScatterChart {
+    static chartType = 'qqPlot';
+
+    constructor(renderer, data, options = {}) {
+        super(renderer, data, options);
+    }
+
+    _render() {
+        const values = this.data;
+        const options = this.options;
+        const points = Statistics.qqPoints(values);
+        if (!points.length) return;
+
+        const theo = points.map(p => p.theoretical);
+        const sample = points.map(p => p.sample);
+        const theoQ1 = Statistics.quantile(theo, 0.25);
+        const theoQ3 = Statistics.quantile(theo, 0.75);
+        const sampleQ1 = Statistics.quantile(sample, 0.25);
+        const sampleQ3 = Statistics.quantile(sample, 0.75);
+        const slope = (theoQ3 - theoQ1) ? (sampleQ3 - sampleQ1) / (theoQ3 - theoQ1) : 0;
+        const intercept = sampleQ1 - slope * theoQ1;
+        const theoMin = theo[0];
+        const theoMax = theo[theo.length - 1];
+
+        const originalData = this.data;
+        const originalTitle = options.title;
+        const originalXAxisLabel = options.xAxisLabel;
+        const originalYAxisLabel = options.yAxisLabel;
+        const originalReferenceLine = options.referenceLine;
+
+        try {
+            this.data = points.map((p, i) => ({
+                label: `p${i + 1}`,
+                x: p.theoretical,
+                y: p.sample,
+            }));
+            options.title = originalTitle ?? 'Q-Q Plot';
+            options.xAxisLabel = originalXAxisLabel ?? 'Theoretical Quantile';
+            options.yAxisLabel = originalYAxisLabel ?? 'Sample Quantile';
+            options.referenceLine = {
+                from: { x: theoMin, y: slope * theoMin + intercept },
+                to: { x: theoMax, y: slope * theoMax + intercept },
+            };
+
+            super._render();
+        } finally {
+            this.data = originalData;
+            options.title = originalTitle;
+            options.xAxisLabel = originalXAxisLabel;
+            options.yAxisLabel = originalYAxisLabel;
+            options.referenceLine = originalReferenceLine;
+        }
+    }
+}

package/src/charting/charts/RadarChart.js

@@ -0,0 +1,76 @@
+import { Chart } from '../Chart.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * RadarChart — one polygon per series across N shared axes, each axis scaled
+ * independently by its own max value across all series.
+ */
+export class RadarChart extends Chart {
+    static chartType = 'radar';
+
+    _render() {
+        const data = this.data;
+        const options = this.options;
+        const w = this.renderer?.width ?? 640;
+        const h = this.renderer?.height ?? 400;
+        const {
+            cx = w / 2, cy = h / 2 + 10,
+            radius = Math.min(w, h) / 2 - 70,
+            colors, legend: showLegend = true, title,
+        } = options;
+        const isMulti = Array.isArray(data[0]?.values);
+        const series = isMulti ? data : [{ name: 'default', values: data }];
+        const axes = series[0].values.map(v => v.axis);
+        const n = axes.length;
+        const palette = new ColorPalette(colors);
+        const axisMax = axes.map((_, ai) => Math.max(...series.map(s => s.values[ai]?.value ?? 0)) || 1);
+        const angleFor = (i) => -Math.PI / 2 + (i / n) * Math.PI * 2;
+        const pointFor = (i, value) => {
+            const r = (value / axisMax[i]) * radius;
+            const a = angleFor(i);
+            return { px: cx + r * Math.cos(a), py: cy + r * Math.sin(a) };
+        };
+
+        if (title) {
+            this.renderer.text(title, cx, cy - radius - 20, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
+        }
+
+        [0.25, 0.5, 0.75, 1].forEach(frac => {
+            const ringPath = 'M' + axes.map((_, i) => {
+                const a = angleFor(i);
+                return `${cx + radius * frac * Math.cos(a)},${cy + radius * frac * Math.sin(a)}`;
+            }).join(' L') + ' Z';
+            this.renderer.path(ringPath, 'none', { color: '#e0e0e0', width: 1 });
+        });
+        axes.forEach((axisName, i) => {
+            const a = angleFor(i);
+            this.renderer.path(`M${cx},${cy} L${cx + radius * Math.cos(a)},${cy + radius * Math.sin(a)}`, 'none', { color: '#e0e0e0', width: 1 });
+            const labelR = radius + 16;
+            this.renderer.text(axisName, cx + labelR * Math.cos(a), cy + labelR * Math.sin(a), {
+                textAnchor: 'middle', verticalAlign: 'middle', fontSize: '11px', fill: '#555',
+            });
+        });
+
+        series.forEach((s, seriesIndex) => {
+            const color = palette.colorAt(seriesIndex);
+            const pts = s.values.map((v, i) => pointFor(i, v.value));
+            const path = 'M' + pts.map(p => `${p.px},${p.py}`).join(' L') + ' Z';
+            const { r, g, b } = ColorPalette.hexToRgb(color);
+            this.renderer.path(path, `rgba(${r},${g},${b},0.25)`, { color, width: 2 }, { tooltip: s.name });
+            pts.forEach((p, i) => {
+                this.renderer.circle(p.px, p.py, 3, color, { color: '#fff', width: 1 }, {
+                    tooltip: `${s.name} — ${s.values[i].axis}: ${s.values[i].value}`,
+                });
+            });
+        });
+
+        if (isMulti && showLegend) {
+            series.forEach((s, i) => {
+                const legendX = cx + radius + 40;
+                const legendY = cy - radius + i * 20;
+                this.renderer.rect(legendX, legendY, 12, 12, palette.colorAt(i), null);
+                this.renderer.text(s.name, legendX + 18, legendY + 6, { fontSize: '12px', fill: '#333', verticalAlign: 'middle' });
+            });
+        }
+    }
+}

package/src/charting/charts/RadialBarChart.js

@@ -0,0 +1,96 @@
+import { Chart } from '../Chart.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { ShapePaths } from '../ShapePaths.js';
+import { Legend } from '../Legend.js';
+
+/**
+ * RadialBarChart — bars radiating from a central point (also called a circular
+ * barplot or radial column chart). Each category gets an angular slice whose
+ * radial length encodes its value.
+ *
+ * Data: Array<{label: string, value: number}>
+ * Options:
+ *   - cx, cy, radius, innerRadius
+ *   - padAngle: gap between bars in radians (default 0.02)
+ *   - startAngle, endAngle: overall angular span (default 0 → 2π)
+ *   - colors: string[] palette
+ *   - title
+ *   - showValues: boolean
+ *   - legend: boolean (default true)
+ */
+export class RadialBarChart extends Chart {
+    static chartType = 'radialBar';
+
+    _render() {
+        const data = this.data || [];
+        const options = this.options || {};
+        const w = this.renderer?.width ?? 800;
+        const h = this.renderer?.height ?? 400;
+
+        const {
+            cx = w / 2, cy = h / 2 + 10,
+            radius = Math.min(w, h) / 2 - 60,
+            innerRadius = radius * 0.15,
+            padAngle = 0.02,
+            startAngle = 0,
+            endAngle = Math.PI * 2,
+            colors, title, showValues = false, legend: showLegend = true,
+        } = options;
+
+        const palette = new ColorPalette(colors);
+        const textAnchor = this.renderer.centerTextAnchor;
+        const totalAngle = endAngle - startAngle;
+        const count = data.length || 1;
+        const anglePerBar = totalAngle / count;
+        const maxValue = Math.max(...data.map(d => d.value), 1);
+        const trackRadius = radius + 10;
+
+        if (title) {
+            this.renderer.text(title, cx, cy - radius - 30, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
+        }
+
+        data.forEach((d, i) => {
+            const a0 = startAngle + i * anglePerBar + padAngle / 2;
+            const a1 = startAngle + (i + 1) * anglePerBar - padAngle / 2;
+            const barLen = ((d.value / maxValue) * (radius - innerRadius));
+            const rOuter = innerRadius + barLen;
+            const color = d.color ?? palette.colorAt(i);
+            const path = ShapePaths.donutSlicePath(cx, cy, rOuter, innerRadius, a0, a1);
+            this.renderer.path(path, color, { color: '#fff', width: 1 }, {
+                tooltip: `${d.label}: ${d.value}`,
+            });
+
+            // Category label around the outer track.
+            const midAngle = (a0 + a1) / 2;
+            const lx = cx + trackRadius * Math.cos(midAngle);
+            const ly = cy + trackRadius * Math.sin(midAngle);
+            const deg = (midAngle * 180 / Math.PI + 90) % 360;
+            const rotate = deg > 90 && deg < 270 ? deg + 180 : deg;
+            this.renderer.text(d.label, lx, ly, {
+                textAnchor: 'middle', fontSize: '10px', fill: '#333',
+                transform: `rotate(${rotate - 90},${lx},${ly})`,
+            });
+
+            if (showValues && barLen > 16) {
+                const vmid = (innerRadius + rOuter) / 2;
+                const vx = cx + vmid * Math.cos(midAngle);
+                const vy = cy + vmid * Math.sin(midAngle);
+                this.renderer.text(String(d.value), vx, vy, {
+                    textAnchor: 'middle', verticalAlign: 'middle', fontSize: '9px',
+                    fill: ColorPalette.isDark(color) ? '#fff' : '#333',
+                });
+            }
+        });
+
+        if (showLegend) {
+            const legendItems = data.map((d, i) => ({ label: d.label, color: palette.colorAt(i) }));
+            new Legend({
+                items: legendItems,
+                x: cx + radius + 40,
+                y: cy - radius,
+                itemHeight: 18,
+                markerSize: 10,
+            }).draw(this.renderer);
+        }
+    }
+}

package/src/charting/charts/SankeyDiagram.js

@@ -0,0 +1,174 @@
+import { Chart } from '../Chart.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * SankeyDiagram — flow diagram where the width of each link is proportional
+ * to the value it carries.
+ *
+ * Data:
+ *   {
+ *     nodes?: Array<{id: string, label?: string, color?: string}>,
+ *     links: Array<{source: string, target: string, value: number}>
+ *   }
+ * If nodes are omitted, they are inferred from link source/target IDs.
+ *
+ * Options:
+ *   - title
+ *   - nodeWidth
+ *   - nodePadding
+ *   - linkOpacity
+ *   - colors
+ */
+export class SankeyDiagram extends Chart {
+    static chartType = 'sankey';
+
+    _render() {
+        const data = this.data || {};
+        const options = this.options || {};
+        const w = this.renderer?.width ?? 800;
+        const h = this.renderer?.height ?? 400;
+
+        const {
+            x = 40, y = 40,
+            width = w - x - 40,
+            height = h - y - 60,
+            title,
+            nodeWidth = 16,
+            nodePadding = 16,
+            linkOpacity = 0.45,
+            colors,
+        } = options;
+
+        const links = (data.links || []).filter(l => l.value > 0);
+        if (links.length === 0) return;
+
+        // Infer nodes if not provided.
+        const nodeMap = new Map();
+        const ensureNode = (id) => {
+            if (!nodeMap.has(id)) nodeMap.set(id, { id, label: id, in: [], out: [], value: 0 });
+            return nodeMap.get(id);
+        };
+        (data.nodes || []).forEach(n => {
+            const node = ensureNode(n.id);
+            if (n.label != null) node.label = n.label;
+            if (n.color != null) node.color = n.color;
+        });
+        links.forEach(l => {
+            ensureNode(l.source);
+            ensureNode(l.target);
+        });
+        links.forEach(l => {
+            const s = nodeMap.get(l.source);
+            const t = nodeMap.get(l.target);
+            s.out.push({ target: t, value: l.value });
+            t.in.push({ source: s, value: l.value });
+            s.value += l.value;
+            t.value += l.value;
+        });
+
+        const nodes = [...nodeMap.values()];
+        this._assignLevels(nodes);
+        const levels = this._levels(nodes);
+        const maxLevel = Math.max(...nodes.map(n => n.level));
+        const levelWidth = (width - nodeWidth) / Math.max(1, maxLevel);
+
+        // Scale node heights so the tallest column fits.
+        const levelMaxValues = levels.map(levelNodes => Math.max(...levelNodes.map(n => n.value), 1));
+        const globalMax = Math.max(...levelMaxValues);
+        const scale = (height - (Math.max(...levels.map(l => l.length)) - 1) * nodePadding) / globalMax;
+
+        // Position nodes within each level.
+        levels.forEach(levelNodes => {
+            const totalH = levelNodes.reduce((sum, n) => sum + n.value * scale + nodePadding, 0) - nodePadding;
+            let cy = y + (height - totalH) / 2;
+            levelNodes.forEach(n => {
+                n.x = x + n.level * levelWidth;
+                n.y = cy;
+                n.h = n.value * scale;
+                cy += n.h + nodePadding;
+            });
+        });
+
+        const palette = new ColorPalette(colors);
+        levels.forEach((levelNodes, li) => {
+            levelNodes.forEach((n, i) => {
+                n.color = n.color || palette.colorAt(li * 3 + i);
+            });
+        });
+
+        if (title) {
+            this.renderer.text(title, x + width / 2, y - 16, {
+                textAnchor: 'middle', fontSize: '18px', fill: '#333',
+            });
+        }
+
+        // Draw links first so nodes sit on top.
+        nodes.forEach(n => {
+            let outY = n.y;
+            n.out.forEach(l => {
+                const t = l.target;
+                const inIndex = t.in.findIndex(inL => inL.source === n);
+                let inY = t.y;
+                for (let k = 0; k < inIndex; k++) inY += t.in[k].value * scale;
+                const linkH = l.value * scale;
+                const path = this._linkPath(n.x + nodeWidth, outY + linkH / 2, t.x, inY + linkH / 2, linkH);
+                const { r, g, b: bl } = palette.hexToRgb(n.color);
+                this.renderer.path(path, `rgba(${r},${g},${bl},${linkOpacity})`, null, {
+                    tooltip: `${n.label} → ${t.label}: ${l.value}`,
+                });
+                outY += linkH;
+            });
+        });
+
+        // Draw nodes.
+        nodes.forEach(n => {
+            this.renderer.rect(n.x, n.y, nodeWidth, Math.max(1, n.h), n.color, null, {
+                tooltip: `${n.label}: ${n.value}`,
+            });
+            this.renderer.text(n.label, n.x + nodeWidth / 2, n.y - 6, {
+                textAnchor: 'middle', fontSize: '10px', fill: '#333',
+            });
+        });
+    }
+
+    _assignLevels(nodes) {
+        // Sources (no incoming) are level 0; do a BFS forward.
+        nodes.forEach(n => { n.level = -1; });
+        let changed = true;
+        while (changed) {
+            changed = false;
+            nodes.forEach(n => {
+                if (n.level === -1 && n.in.length === 0) {
+                    n.level = 0;
+                    changed = true;
+                }
+                n.in.forEach(l => {
+                    if (l.source.level >= 0 && (n.level === -1 || l.source.level + 1 > n.level)) {
+                        n.level = l.source.level + 1;
+                        changed = true;
+                    }
+                });
+            });
+        }
+        // Any remaining unresolved nodes (cycles) get level 0.
+        nodes.forEach(n => { if (n.level < 0) n.level = 0; });
+    }
+
+    _levels(nodes) {
+        const maxLevel = Math.max(...nodes.map(n => n.level), 0);
+        const levels = [];
+        for (let i = 0; i <= maxLevel; i++) levels.push([]);
+        nodes.forEach(n => levels[n.level].push(n));
+        // Sort by value descending for a cleaner layout.
+        levels.forEach(level => level.sort((a, b) => b.value - a.value));
+        return levels;
+    }
+
+    _linkPath(x0, y0, x1, y1, h) {
+        const c0x = x0 + (x1 - x0) / 2;
+        const c1x = x1 - (x1 - x0) / 2;
+        const half = h / 2;
+        return `M${x0},${y0 - half} C${c0x},${y0 - half} ${c1x},${y1 - half} ${x1},${y1 - half} `
+             + `L${x1},${y1 + half} C${c1x},${y1 + half} ${c0x},${y0 + half} ${x0},${y0 + half} Z`;
+    }
+}

package/src/charting/charts/ScatterChart.js

@@ -0,0 +1,104 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { ChartData } from '../ChartData.js';
+import { ErrorBars } from '../ErrorBars.js';
+
+/**
+ * ScatterChart — x/y point scatter plot with optional categorical coloring.
+ */
+export class ScatterChart extends Chart {
+    static chartType = 'scatter';
+
+    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,
+            pointColor = 'rgba(100, 150, 240, 0.7)', pointRadius = 5,
+            colorCol, colors, title, xAxisLabel, yAxisLabel, referenceLine,
+        } = options;
+        const plotBox = { x, y, width, height };
+        const xValues = data.map(d => d.x);
+        const yValues = data.map(d => d.y);
+        const xMin = Math.min(...xValues), xMax = Math.max(...xValues);
+        const yMin = Math.min(...yValues), yMax = Math.max(...yValues);
+        const xRange = (xMax - xMin) || 1;
+        const yRange = (yMax - yMin) || 1;
+        const toX = (v) => x + ((v - xMin) / xRange) * width;
+        const toY = (v) => y + height - ((v - yMin) / yRange) * height;
+
+        // Same optional per-point categorical coloring as bubbleChart — see
+        // its own comment for why colorCol/category/group fall back this way.
+        // `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 pointColor;
+            const cat = ChartData.readColorCol(d, catField);
+            return cat != null ? catColors.get(cat) : pointColor;
+        };
+
+        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 });
+
+        if (referenceLine) {
+            let from, to;
+            if (referenceLine === true) {
+                const lo = Math.max(xMin, yMin), hi = Math.min(xMax, yMax);
+                if (hi > lo) { from = { x: lo, y: lo }; to = { x: hi, y: hi }; }
+            } else {
+                ({ from, to } = referenceLine);
+            }
+            if (from && to) {
+                const line = this.renderer.path(`M${toX(from.x)},${toY(from.y)} L${toX(to.x)},${toY(to.y)}`, 'none', { color: '#999', width: 1 });
+                line.setAttribute('stroke-dasharray', '4 3');
+            }
+        }
+
+        data.forEach(d => {
+            const cx = toX(d.x);
+            const cy = toY(d.y);
+            const tooltip = d.label ? `${d.label}: (${d.x}, ${d.y})` : `(${d.x}, ${d.y})`;
+            this.renderer.circle(cx, cy, pointRadius, colorFor(d), { color: 'rgba(0,0,0,0.2)', width: 1 }, { tooltip });
+
+            const xLow = d.errorXMinus != null ? toX(d.x - d.errorXMinus)
+                : d.errorX != null ? toX(d.x - d.errorX) : null;
+            const xHigh = d.errorXPlus != null ? toX(d.x + d.errorXPlus)
+                : d.errorX != null ? toX(d.x + d.errorX) : null;
+            const yLow = d.errorYMinus != null ? toY(d.y - d.errorYMinus)
+                : d.errorY != null ? toY(d.y - d.errorY) : null;
+            const yHigh = d.errorYPlus != null ? toY(d.y + d.errorYPlus)
+                : d.errorY != null ? toY(d.y + d.errorY) : null;
+            ErrorBars.draw(this.renderer, cx, cy, xLow, xHigh, yLow, yHigh);
+        });
+
+        // Category color legend — same inline pattern as bubbleChart (not the
+        // generic showLegend mechanism other 2D charts use).
+        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/StackedAreaChart.js

@@ -0,0 +1,15 @@
+import { AreaChart } from './AreaChart.js';
+
+/**
+ * StackedAreaChart — convenience subclass that forces `stacked: true`.
+ *
+ * Data shape is the same as AreaChart/LineChart multi-series:
+ *   Array<{name: string, values: Array<{label: string, value: number}>}>
+ */
+export class StackedAreaChart extends AreaChart {
+    static chartType = 'stackedArea';
+
+    constructor(renderer, data, options = {}) {
+        super(renderer, data, { ...options, stacked: true });
+    }
+}

package/src/charting/charts/StackedBarChart.js

@@ -0,0 +1,33 @@
+import { BarChartBase } from './BarChartBase.js';
+
+/**
+ * StackedBarChart — vertical stacked bar chart.
+ */
+export class StackedBarChart extends BarChartBase {
+    static chartType = 'stackedBar';
+
+    _computeMaxValue() {
+        const data = this.data;
+        return Math.max(...data.map(d => d.values.reduce((sum, val) => sum + val, 0)));
+    }
+
+    _renderBars(maxStackValue) {
+        const data = this.data;
+        const { x, y, height } = this._plotBox;
+        const { bandWidth, margin } = this._bandScale(data.length);
+        const textAnchor = this.renderer.centerTextAnchor;
+
+        data.forEach((d, i) => {
+            let currentY = y + height;
+            const barX = x + i * (bandWidth + margin);
+            d.values.forEach((value, j) => {
+                const barHeight = (value / maxStackValue) * height;
+                currentY -= barHeight;
+                this.renderer.rect(barX, currentY, bandWidth, barHeight, this._palette.colorAt(j), null, {
+                    tooltip: `${d.label} - Series ${j + 1}: ${value}`,
+                });
+            });
+            this.renderer.text(d.label, barX + bandWidth / 2, y + height + 20, { textAnchor });
+        });
+    }
+}