@peter.prib/renderengine 0.13.0 → 0.15.0

package/src/charting/charts/SparklineTableChart.js

@@ -0,0 +1,166 @@
+import { Axis } from '../Axis.js';
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * SparklineTableChart — executive multi-metric table embedding inline
+ * sparklines, trend change badges, and bullet KPI performance bars per row.
+ *
+ * Data shape:
+ *   Array<{
+ *     label: string,
+ *     value: number,
+ *     target?: number,
+ *     sparkline?: number[],
+ *     delta?: number,
+ *     status?: 'good'|'warn'|'bad'
+ *   }>
+ */
+export class SparklineTableChart extends Chart {
+    static chartType = 'sparklineTable';
+
+    _render() {
+        const data = this.data;
+        if (!Array.isArray(data) || !data.length) return;
+
+        const options = this.options;
+        const box = ChartBox.fromRenderer(this.renderer);
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            title, rowHeight = 44, colors,
+        } = options;
+        const plotBox = { x, y, width, height };
+
+        new ChartLabels({ title }).draw(this.renderer, plotBox);
+
+        const palette = new ColorPalette(colors);
+        const totalRows = data.length;
+        const headerH = 26;
+        const startY = y + headerH;
+
+        // Column widths
+        const colLabelW = Math.max(90, width * 0.22);
+        const colValueW = Math.max(65, width * 0.16);
+        const colTrendW = Math.max(65, width * 0.15);
+        const colSparkW = Math.max(100, width * 0.24);
+        const colBulletW = Math.max(80, width - colLabelW - colValueW - colTrendW - colSparkW);
+
+        const colLabelX = x;
+        const colValueX = colLabelX + colLabelW;
+        const colTrendX = colValueX + colValueW;
+        const colSparkX = colTrendX + colTrendW;
+        const colBulletX = colSparkX + colSparkW;
+
+        // Table Header
+        this.renderer.rect(x, y, width, headerH, 'rgba(0,0,0,0.03)', { color: '#e0e0e0', width: 1 });
+        const textH = y + headerH / 2;
+        this.renderer.text('Metric / Entity', colLabelX + 8, textH, { textAnchor: 'start', verticalAlign: 'middle', fontSize: '10px', fontWeight: 'bold', fill: '#666' });
+        this.renderer.text('Current', colValueX + colValueW - 8, textH, { textAnchor: 'end', verticalAlign: 'middle', fontSize: '10px', fontWeight: 'bold', fill: '#666' });
+        this.renderer.text('Change', colTrendX + colTrendW / 2, textH, { textAnchor: this.renderer.centerTextAnchor, verticalAlign: 'middle', fontSize: '10px', fontWeight: 'bold', fill: '#666' });
+        this.renderer.text('History', colSparkX + colSparkW / 2, textH, { textAnchor: this.renderer.centerTextAnchor, verticalAlign: 'middle', fontSize: '10px', fontWeight: 'bold', fill: '#666' });
+        this.renderer.text('Target Performance', colBulletX + 8, textH, { textAnchor: 'start', verticalAlign: 'middle', fontSize: '10px', fontWeight: 'bold', fill: '#666' });
+
+        // Global max for bullet bars
+        const allTargetsAndValues = data.flatMap(d => {
+            const v = Number(d.value ?? d.current);
+            const t = Number(d.target ?? v);
+            return [Number.isFinite(v) ? v : 0, Number.isFinite(t) ? t : 0];
+        });
+        const maxBulletVal = Math.max(...allTargetsAndValues, 1);
+
+        data.forEach((row, i) => {
+            const rowY = startY + i * rowHeight;
+            if (rowY + rowHeight > y + height) return;
+
+            // Zebra striping
+            const bg = i % 2 === 0 ? '#ffffff' : 'rgba(0,0,0,0.015)';
+            this.renderer.rect(x, rowY, width, rowHeight, bg, { color: '#f0f0f0', width: 1 });
+            const midY = rowY + rowHeight / 2;
+
+            // 1. Label
+            const label = String(row.label ?? row.metric ?? row.kpi ?? row.name ?? `Metric ${i + 1}`);
+            this.renderer.text(label, colLabelX + 8, midY, {
+                textAnchor: 'start', verticalAlign: 'middle', fontSize: '12px', fontWeight: '600', fill: '#222',
+            });
+
+            // 2. Current Value
+            const rawVal = row.value ?? row.current;
+            const valStr = rawVal != null ? (typeof rawVal === 'string' ? rawVal : Axis.formatValue(rawVal)) : '';
+            this.renderer.text(valStr, colValueX + colValueW - 8, midY, {
+                textAnchor: 'end', verticalAlign: 'middle', fontSize: '12px', fontWeight: 'bold', fill: '#111',
+            });
+
+            // 3. Trend Delta Badge
+            const history = Array.isArray(row.sparkline) ? row.sparkline : (Array.isArray(row.trend) ? row.trend : (Array.isArray(row.history) ? row.history : null));
+            const delta = row.delta ?? (typeof row.change === 'number' ? row.change : null) ?? (history?.length > 1 ? history[history.length - 1] - history[0] : null);
+            const deltaStr = typeof row.change === 'string' ? row.change : (delta != null ? `${delta >= 0 ? '+' : ''}${Axis.formatValue(delta)}` : null);
+            if (deltaStr != null) {
+                const isUp = delta != null ? delta >= 0 : !deltaStr.startsWith('-');
+                const badgeColor = isUp ? '#27ae60' : '#e74c3c';
+                const badgeBg = isUp ? 'rgba(39, 174, 96, 0.12)' : 'rgba(231, 76, 60, 0.12)';
+                const badgeW = 54, badgeH = 18;
+                const badgeX = colTrendX + (colTrendW - badgeW) / 2;
+                const badgeY = midY - badgeH / 2;
+
+                this.renderer.rect(badgeX, badgeY, badgeW, badgeH, badgeBg, { color: badgeColor, width: 1 }, { rx: 3, ry: 3 });
+                this.renderer.text(deltaStr, colTrendX + colTrendW / 2, midY, {
+                    textAnchor: this.renderer.centerTextAnchor, verticalAlign: 'middle', fontSize: '10px', fontWeight: 'bold', fill: badgeColor,
+                });
+            }
+
+            // 4. Inline Sparkline
+            if (history && history.length > 1) {
+                const sPadX = 10, sPadY = 8;
+                const sw = colSparkW - sPadX * 2;
+                const sh = rowHeight - sPadY * 2;
+                const sx = colSparkX + sPadX;
+                const sy = rowY + sPadY;
+
+                const sMin = Math.min(...history);
+                const sMax = Math.max(...history);
+                const sRange = (sMax - sMin) || 1;
+                const sStep = sw / (history.length - 1);
+
+                const pts = history.map((v, idx) => ({
+                    px: sx + idx * sStep,
+                    py: sy + sh - ((v - sMin) / sRange) * sh,
+                }));
+                const sparkD = 'M' + pts.map(p => `${p.px.toFixed(1)},${p.py.toFixed(1)}`).join(' L');
+                const sparkColor = palette.colorAt(i);
+                this.renderer.path(sparkD, 'none', { color: sparkColor, width: 1.6, 'stroke-linecap': 'round' });
+
+                // Endpoint accent dot
+                const last = pts[pts.length - 1];
+                this.renderer.circle(last.px, last.py, 2.5, sparkColor, { color: '#ffffff', width: 1 });
+            }
+
+            // 5. Bullet Performance Bar
+            const bPadX = 8;
+            const bw = Math.max(10, colBulletW - bPadX * 2);
+            const bh = 14;
+            const bx = colBulletX + bPadX;
+            const by = midY - bh / 2;
+
+            // Range background track
+            this.renderer.rect(bx, by, bw, bh, '#e8ecef', null, { rx: 2, ry: 2 });
+            // Qualitative 70% threshold band
+            this.renderer.rect(bx, by, bw * 0.7, bh, '#d5dbdb', null);
+
+            // Performance value bar
+            const numVal = Number(row.value ?? row.current);
+            const valRatio = Number.isFinite(numVal) ? Math.min(1, Math.max(0, numVal / maxBulletVal)) : 0.5;
+            const barW = Math.max(2, valRatio * bw);
+            const barColor = row.status === 'bad' || row.status === 'Attention' ? '#e74c3c' : (row.status === 'warn' ? '#f39c12' : '#2c3e50');
+            this.renderer.rect(bx, by + 3, barW, bh - 6, barColor, null);
+
+            // Target marker line
+            const numTarget = Number(row.target);
+            if (Number.isFinite(numTarget)) {
+                const targetRatio = Math.min(1, Math.max(0, numTarget / maxBulletVal));
+                const targetX = bx + targetRatio * bw;
+                this.renderer.path(`M${targetX},${by - 2} L${targetX},${by + bh + 2}`, 'none', { color: '#e74c3c', width: 2.2 });
+            }
+        });
+    }
+}

package/src/charting/charts/StackedBarChart.js

@@ -1,35 +1,149 @@
 import { Axis } from '../Axis.js';
+import { Legend } from '../Legend.js';
 import { BarChartBase } from './BarChartBase.js';
+import { TableChart } from './TableChart.js';
 
 /**
  * StackedBarChart — vertical stacked bar chart.
+ *
+ * Accepts either:
+ *   - Multi-series `Array<{name: string, values: Array<{label: string, value: number}>}>` (the same
+ *     shape as `GroupedBarChart`, `LineChart` and `StackedAreaChart`), or
+ *   - Flat per-category stacks `Array<{label: string, values: number[]}>` with optional
+ *     `options.seriesLabels`.
+ *
+ * Draws a numeric Y axis (`_drawYAxis`), optional series legend (`legend: true`), and records each
+ * segment with `this._datum()` so `onDatumClick` / `PivotChart` drilling works on every segment.
  */
 export class StackedBarChart extends BarChartBase {
     static chartType = 'stackedBar';
 
+    static _normalize(data, seriesLabels = null) {
+        if (!Array.isArray(data) || data.length === 0) return { categories: [], seriesNames: [] };
+        if (Array.isArray(data[0]?.values) && typeof data[0].values[0] === 'object' && data[0].values[0] !== null) {
+            const labels = [...new Set(data.flatMap(s => s.values.map(v => v.label)))];
+            const maps = data.map(s => new Map(s.values.map(v => [v.label, v.value])));
+            return {
+                seriesNames: data.map((s, i) => s.name ?? seriesLabels?.[i] ?? `Series ${i + 1}`),
+                categories: labels.map(label => ({ label, values: maps.map(m => m.get(label) ?? 0) })),
+            };
+        }
+        const maxLen = Math.max(0, ...data.map(d => d.values?.length ?? 0));
+        return {
+            seriesNames: Array.from({ length: maxLen }, (_, i) => seriesLabels?.[i] ?? `Series ${i + 1}`),
+            categories: data.map(d => ({ label: d.label, values: (d.values ?? []).map(v => v ?? 0) })),
+        };
+    }
+
+    _setup() {
+        this._normalized = StackedBarChart._normalize(this.data, this.options.seriesLabels);
+        super._setup();
+        if (this.options.legend && this.options.width === undefined && this._normalized.seriesNames.length > 0) {
+            this._plotBox.width = Legend.plotWidthBeside(this._plotBox, this.renderer.width, this._legendOptions());
+        }
+    }
+
+    _legendOptions() {
+        return {
+            items: this._normalized.seriesNames.map((name, i) => ({
+                label: name,
+                color: this._palette.colorAt(i),
+                hidden: this._dataFilter.has(i),
+                dataIndex: i,
+            })),
+            itemHeight: 20, markerSize: 10,
+        };
+    }
+
+    _isNormalized() {
+        return Boolean(this.options.normalize || this.options.stackMode === 'percent');
+    }
+
     _computeMaxValue() {
-        const data = this.data;
-        return Math.max(...data.map(d => d.values.reduce((sum, val) => sum + val, 0)));
+        if (this._isNormalized()) {
+            return this._isHorizontal() ? this._drawXAxis(100) : this._drawYAxis(100);
+        }
+        const { categories } = this._normalized;
+        const rawMax = Math.max(0, ...categories.map(d => d.values.reduce((sum, val, idx) => sum + (this._dataFilter.has(idx) ? 0 : Math.max(0, val)), 0))) || 1;
+        return this._isHorizontal() ? this._drawXAxis(rawMax) : this._drawYAxis(rawMax);
     }
 
     _renderBars(maxStackValue) {
-        const data = this.data;
+        const { categories, seriesNames } = this._normalized;
+        if (categories.length === 0) return;
         const { x, y, width, height } = this._plotBox;
-        const labelStep = Axis.categoryLabelStep(data.map(d => d.label), width);
-        const { bandWidth, margin } = this._bandScale(data.length);
+        const normalize = this._isNormalized();
+        const labels = categories.map(d => d.label);
+        const { bandWidth, margin } = this._bandScale(categories.length);
         const textAnchor = this.renderer.centerTextAnchor;
 
-        data.forEach((d, i) => {
+        if (this._isHorizontal()) {
+            categories.forEach((d, i) => {
+                let currentX = x;
+                const barY = y + i * (bandWidth + margin);
+                const colTotal = d.values.reduce((sum, val, idx) => sum + (this._dataFilter.has(idx) ? 0 : Math.max(0, val ?? 0)), 0);
+                d.values.forEach((value, j) => {
+                    if (this._dataFilter.has(j)) return;
+                    if (value == null || value <= 0) return;
+                    const plotted = normalize ? (colTotal > 0 ? (value / colTotal) * 100 : 0) : value;
+                    const barWidth = (plotted / maxStackValue) * width;
+                    const series = seriesNames[j] ?? `Series ${j + 1}`;
+                    const tipVal = normalize ? `${plotted.toFixed(1)}% (${value})` : `${value}`;
+                    this._datum(this.renderer.rect(currentX, barY, barWidth, bandWidth, this._palette.colorAt(j), null, {
+                        tooltip: `${d.label} - ${series}: ${tipVal}`,
+                    }), { label: d.label, series });
+                    if (this.options.showValues && barWidth > 20 && bandWidth > 12) {
+                        const valText = typeof this.options.format === 'function' ? this.options.format(value) : (normalize ? `${plotted.toFixed(0)}%` : String(value));
+                        this.renderer.text(valText, currentX + barWidth / 2, barY + bandWidth / 2, {
+                            textAnchor: 'middle', verticalAlign: 'middle', fontSize: '9px', fill: '#ffffff', 'pointer-events': 'none',
+                        });
+                    }
+                    currentX += barWidth;
+                });
+                this.renderer.text(d.label, x - 8, barY + bandWidth / 2, {
+                    textAnchor: 'end', verticalAlign: 'middle', fontSize: '11px', fill: '#333',
+                });
+            });
+            return;
+        }
+
+        const measure = (s) => this.renderer.measureText?.(s, { fontSize: '12px' }) ?? s.length * 12 * 0.55;
+        const room = (bandWidth + margin) - 4;
+        const cut = room >= measure('x'.repeat(6));
+        const labelStep = cut ? 1 : Axis.categoryLabelStep(labels, width);
+
+        categories.forEach((d, i) => {
             let currentY = y + height;
             const barX = x + i * (bandWidth + margin);
+            const colTotal = d.values.reduce((sum, val, idx) => sum + (this._dataFilter.has(idx) ? 0 : Math.max(0, val ?? 0)), 0);
             d.values.forEach((value, j) => {
-                const barHeight = (value / maxStackValue) * height;
+                if (this._dataFilter.has(j)) return;
+                if (value == null || value <= 0) return;
+                const plotted = normalize ? (colTotal > 0 ? (value / colTotal) * 100 : 0) : value;
+                const barHeight = (plotted / maxStackValue) * height;
                 currentY -= barHeight;
-                this.renderer.rect(barX, currentY, bandWidth, barHeight, this._palette.colorAt(j), null, {
-                    tooltip: `${d.label} - Series ${j + 1}: ${value}`,
-                });
+                const series = seriesNames[j] ?? `Series ${j + 1}`;
+                const tipVal = normalize ? `${plotted.toFixed(1)}% (${value})` : `${value}`;
+                this._datum(this.renderer.rect(barX, currentY, bandWidth, barHeight, this._palette.colorAt(j), null, {
+                    tooltip: `${d.label} - ${series}: ${tipVal}`,
+                }), { label: d.label, series });
+                if (this.options.showValues && barHeight > 14 && bandWidth > 18) {
+                    const valText = typeof this.options.format === 'function' ? this.options.format(value) : (normalize ? `${plotted.toFixed(0)}%` : String(value));
+                    this.renderer.text(valText, barX + bandWidth / 2, currentY + barHeight / 2, {
+                        textAnchor: 'middle', verticalAlign: 'middle', fontSize: '9px', fill: '#ffffff', 'pointer-events': 'none',
+                    });
+                }
             });
-            if (i % labelStep === 0) this.renderer.text(d.label, barX + bandWidth / 2, y + height + 20, { textAnchor });
+            if (i % labelStep === 0) {
+                this.renderer.text(cut ? TableChart.fit(String(d.label), room, measure) : d.label, barX + bandWidth / 2, y + height + 20, { textAnchor });
+            }
         });
     }
+
+    _afterBars() {
+        const { x, y, width } = this._plotBox;
+        if (this.options.legend && this._normalized.seriesNames.length > 0) {
+            Legend.beside({ x, y, width }, this.renderer.width, this._legendOptions()).draw(this.renderer);
+        }
+    }
 }

package/src/charting/charts/StackedBarChart3DOrbit.js

@@ -16,7 +16,8 @@ export class StackedBarChart3DOrbit extends Chart3D {
         const { x: bx, y: by, width, height } = box;
 
         const { xLabels, zLabels, xIndex, zIndex } = this.bucketGrid(data);
-        const stackMax = Math.max(...data.map(d => d.values.reduce((s, v) => s + v, 0))) || 1;
+        const normalize = Boolean(options.normalize || options.stackMode === 'percent');
+        const stackMax = normalize ? 100 : (Math.max(...data.map(d => d.values.reduce((s, v) => s + v, 0))) || 1);
         const palette = new ColorPalette(colors);
 
         const cellW = 2 / Math.max(1, xLabels.length);
@@ -32,24 +33,31 @@ export class StackedBarChart3DOrbit extends Chart3D {
             const xCenter = -1 + cellW * (xi + 0.5);
             const zCenter = -1 + cellD * (zi + 0.5);
             const hw = cellW * barFrac / 2, hd = cellD * barFrac / 2;
-            const stackTotal = d.values.reduce((s, v) => s + v, 0) / stackMax;
+            const colTotal = d.values.reduce((s, v) => s + Math.max(0, v), 0) || 1;
+            const stackTotal = normalize ? 1 : colTotal / stackMax;
             const { depth } = this.project(xCenter, stackTotal / 2, zCenter);
-            return { d, x0: xCenter - hw, x1: xCenter + hw, z0: zCenter - hd, z1: zCenter + hd, depth };
+            return { d, colTotal, x0: xCenter - hw, x1: xCenter + hw, z0: zCenter - hd, z1: zCenter + hd, depth };
         }).sort((a, b) => b.depth - a.depth);
 
         for (const bar of bars) {
             let yCursor = 0;
             for (let j = 0; j < bar.d.values.length; j++) {
-                const segHeight = bar.d.values[j] / stackMax;
+                const rawVal = bar.d.values[j] ?? 0;
+                const plotted = normalize ? (rawVal / bar.colTotal) * 100 : rawVal;
+                const segHeight = plotted / stackMax;
                 const y0 = yCursor, y1 = yCursor + segHeight;
                 yCursor = y1;
-                this.drawBox(this.renderer, bar.x0, bar.x1, y0, y1, bar.z0, bar.z1, palette.colorAt(j), toScreen);
+                const series = options.seriesLabels?.[j] ?? `Series ${j + 1}`;
+                const tipVal = normalize ? `${((rawVal / bar.colTotal) * 100).toFixed(1)}% (${rawVal})` : `${rawVal}`;
+                this.drawBox(this.renderer, bar.x0, bar.x1, y0, y1, bar.z0, bar.z1, palette.colorAt(j), toScreen, {
+                    label: bar.d.x, series, x: bar.d.x, z: bar.d.z, tooltip: `${bar.d.x} / ${bar.d.z} — ${series}: ${tipVal}`,
+                });
             }
         }
 
         const maxSegments = Math.max(...data.map(d => d.values.length));
         new Legend({
-            items: Array.from({ length: maxSegments }, (_, j) => ({ label: `Series ${j + 1}`, color: palette.colorAt(j) })),
+            items: Array.from({ length: maxSegments }, (_, j) => ({ label: options.seriesLabels?.[j] ?? `Series ${j + 1}`, color: palette.colorAt(j) })),
             x: bx + width - 100, y: by + 5, itemHeight: 18, fontSize: '11px', marker: 'circle',
         }).draw(this.renderer);
     }

package/src/charting/charts/StreamGraphChart.js

@@ -69,7 +69,8 @@ export class StreamGraphChart extends Chart {
 
         // Compute totals per point and max extent for scaling.
         const totals = new Array(pointCount).fill(0);
-        series.forEach(s => {
+        series.forEach((s, si) => {
+            if (this._dataFilter.has(si)) return;
             s.values.forEach((d, i) => { totals[i] += d.value; });
         });
         const maxExtent = Math.max(...totals.map(v => Math.abs(v))) || 1;
@@ -81,7 +82,7 @@ export class StreamGraphChart extends Chart {
             const total = totals[i];
             let y0 = -total / 2;
             series.forEach((s, si) => {
-                const v = s.values[i].value;
+                const v = this._dataFilter.has(si) ? 0 : s.values[i].value;
                 bands[si][i] = { y0, y1: y0 + v };
                 y0 += v;
             });
@@ -102,12 +103,21 @@ export class StreamGraphChart extends Chart {
 
         // Draw layers bottom-up so overlaps look correct.
         series.forEach((s, si) => {
+            if (this._dataFilter.has(si)) return;
             const color = palette.colorAt(si);
             const topPts = bands[si].map((b, i) => ({ x: x + i * pointMargin, y: toY(b.y1) }));
             const bottomPts = bands[si].map((b, i) => ({ x: x + i * pointMargin, y: toY(b.y0) }));
             const path = StreamGraphChart.areaPath(topPts, bottomPts, smooth, tension);
             const { r, g, b: bl } = palette.hexToRgb(color);
             this.renderer.path(path, `rgba(${r},${g},${bl},0.75)`, { color: color, width: 1 }, { tooltip: s.name });
+            if (typeof this.renderer.circle === 'function') {
+                topPts.forEach((p, i) => {
+                    const d = s.values[i];
+                    this._datum(this.renderer.circle(p.x, p.y, 3, color, { color: '#fff', width: 1 }, {
+                        tooltip: `${isMultiline ? s.name + ': ' : ''}${d.label}: ${d.value}`,
+                    }), { label: d.label, series: isMultiline ? s.name : null });
+                });
+            }
         });
 
         // X-axis labels.
@@ -124,7 +134,12 @@ export class StreamGraphChart extends Chart {
         this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: '#999', width: 1 });
 
         if (isMultiline && showLegend) {
-            const legendItems = series.map((s, i) => ({ label: s.name, color: palette.colorAt(i) }));
+            const legendItems = series.map((s, i) => ({
+                label: s.name,
+                color: palette.colorAt(i),
+                hidden: this._dataFilter.has(i),
+                dataIndex: i,
+            }));
             Legend.beside({ x, y, width }, this.renderer.width, {
                 items: legendItems,
                 itemHeight: 20, markerSize: 12,

package/src/charting/charts/SunburstChart.js

@@ -6,16 +6,17 @@ import { HierarchyChart } from './HierarchyChart.js';
  * SunburstChart — the same hierarchical composition a treemap shows as nested
  * rectangles, drawn instead as nested rings (one ring per depth), each ring's
  * arcs sized by value like a pie chart.
+ * Supports breadcrumb drill-down.
  */
 export class SunburstChart extends HierarchyChart {
     static chartType = 'sunburst';
 
     _render() {
-        const data = this.data;
-        const options = this.options;
+        const data = this._activeData();
+        const options = this.options || {};
         const w = this.renderer?.width ?? 640;
         const h = this.renderer?.height ?? 400;
-        const {
+        let {
             cx = w / 2, cy = h / 2 + 10,
             radius = Math.min(w, h) / 2 - 60,
             innerRadiusRatio = 0,
@@ -26,6 +27,12 @@ export class SunburstChart extends HierarchyChart {
             this.renderer.text(title, cx, cy - radius - 20, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
         }
 
+        const crumbH = this._drawBreadcrumbs(this.renderer, { x: 20, y: 10, width: w - 40 });
+        if (crumbH > 0) {
+            cy += crumbH / 2;
+            radius -= crumbH / 3;
+        }
+
         const maxDepth = Math.max(1, ...data.map(n => Hierarchy.depth(n)));
         const innerHole = radius * innerRadiusRatio;
         const ringWidth = (radius - innerHole) / maxDepth;
@@ -35,23 +42,36 @@ export class SunburstChart extends HierarchyChart {
             const { node, cx: ecx, cy: ecy, rInner, rOuter, startAngle, endAngle, depth, topAncestor } = entry;
             const color = this._colorForNode(topAncestor, depth);
             const textColor = this._textColorForNode(topAncestor, depth);
+            const hasChildren = Boolean(node.children?.length);
 
             const path = ShapePaths.donutSlicePath(ecx, ecy, rOuter, rInner, startAngle, endAngle);
-            this.renderer.path(path, color, { color: '#fff', width: 1 }, {
-                tooltip: `${node.label}: ${this._formatNodeValue(node)}`,
-            });
+            const arcEl = this._datum(this.renderer.path(path, color, { color: '#fff', width: 1 }, {
+                cursor: (hasChildren && options.drilldown !== false) ? 'pointer' : 'default',
+                tooltip: `${node.label}: ${this._formatNodeValue(node)}${hasChildren ? ' (Click to drill down)' : ''}`,
+            }), { label: node.label });
+
+            if (hasChildren && options.drilldown !== false && typeof arcEl?.addEventListener === 'function') {
+                arcEl.addEventListener('click', (e) => {
+                    e.stopPropagation();
+                    this.drillTo(node);
+                });
+            }
+
+            const midAngle = (startAngle + endAngle) / 2;
+            const hoverEls = [arcEl];
 
             if (endAngle - startAngle > 0.35) {
-                const midAngle = (startAngle + endAngle) / 2;
                 const midR = (rInner + rOuter) / 2;
                 const labelX = ecx + midR * Math.cos(midAngle);
                 const labelY = ecy + midR * Math.sin(midAngle);
                 const upright = Math.cos(midAngle) >= 0;
                 const rotation = upright ? midAngle : midAngle + Math.PI;
-                this.renderer.text(node.label, labelX, labelY, {
+                const txtEl = this.renderer.text(node.label, labelX, labelY, {
                     textAnchor: 'middle', verticalAlign: 'middle', fontSize: '9px', fill: textColor, rotation, 'pointer-events': 'none',
                 });
+                hoverEls.push(txtEl);
             }
+            this._wireRadialHover(hoverEls, midAngle, { offset: options.hoverOffset ?? 8 });
         });
     }
 }

package/src/charting/charts/SurfaceChart3D.js

@@ -0,0 +1,157 @@
+import { Chart3D } from '../Chart3D.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * SurfaceChart3D — 3D `(x, z) -> value` surface mesh rendered through the real 4×4
+ * `OrbitCamera` (drag to rotate, wheel to zoom).
+ *
+ * Accepts either:
+ * - `Array<{x: string, z: string, value: number}>` (same flat grid contract as `barChart3DOrbit` and `heatmap`)
+ * - `{ xLabels: string[], zLabels: string[], values: number[][] }`
+ */
+export class SurfaceChart3D extends Chart3D {
+    static chartType = 'surface3D';
+
+    _render() {
+        const data = this.data;
+        const options = this.options || {};
+        const {
+            title,
+            colorScale = ['#313695', '#4575b4', '#74add1', '#fee090', '#f46d43', '#d73027'],
+            wireframe = true,
+            wireframeColor = 'rgba(255,255,255,0.45)',
+            initialTheta = -0.6,
+            initialPhi = 0.45,
+            initialDistance = 2.35,
+        } = options;
+
+        this.seedCamera({ theta: initialTheta, phi: initialPhi, distance: initialDistance });
+        const { cx, toScreen, box } = this._viewport();
+        const { y: by } = box;
+
+        if (title) {
+            this.renderer.text(title, cx, by - 20, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
+        }
+
+        const { xLabels, zLabels, grid } = this._normalizeGrid(data);
+        const nx = xLabels.length;
+        const nz = zLabels.length;
+        if (nx < 2 || nz < 2) return;
+
+        let minVal = Infinity;
+        let maxVal = -Infinity;
+        for (let ix = 0; ix < nx; ix++) {
+            for (let iz = 0; iz < nz; iz++) {
+                const v = grid[ix][iz];
+                if (v < minVal) minVal = v;
+                if (v > maxVal) maxVal = v;
+            }
+        }
+        const span = (maxVal - minVal) || 1;
+
+        const normX = (ix) => nx === 1 ? 0 : (ix / (nx - 1)) * 1.6 - 0.8;
+        const normZ = (iz) => nz === 1 ? 0 : (iz / (nz - 1)) * 1.6 - 0.8;
+        const normY = (v) => -0.55 + ((v - minVal) / span) * 1.15;
+
+        // Draw floor base frame
+        const floor = [
+            toScreen(-0.8, -0.55, -0.8),
+            toScreen(0.8, -0.55, -0.8),
+            toScreen(0.8, -0.55, 0.8),
+            toScreen(-0.8, -0.55, 0.8),
+        ];
+        this.renderer.path(
+            `M${floor[0].x},${floor[0].y} L${floor[1].x},${floor[1].y} L${floor[2].x},${floor[2].y} L${floor[3].x},${floor[3].y} Z`,
+            'rgba(241, 245, 249, 0.55)',
+            { color: '#cbd5e1', width: 1 }
+        );
+
+        // Build surface quads for each (ix, iz) -> (ix+1, iz+1) cell
+        const quads = [];
+        for (let ix = 0; ix < nx - 1; ix++) {
+            for (let iz = 0; iz < nz - 1; iz++) {
+                const v00 = grid[ix][iz];
+                const v10 = grid[ix + 1][iz];
+                const v11 = grid[ix + 1][iz + 1];
+                const v01 = grid[ix][iz + 1];
+                const avgVal = (v00 + v10 + v11 + v01) / 4;
+                const t = Math.max(0, Math.min(1, (avgVal - minVal) / span));
+
+                const p00 = toScreen(normX(ix),     normY(v00), normZ(iz));
+                const p10 = toScreen(normX(ix + 1), normY(v10), normZ(iz));
+                const p11 = toScreen(normX(ix + 1), normY(v11), normZ(iz + 1));
+                const p01 = toScreen(normX(ix),     normY(v01), normZ(iz + 1));
+
+                // Directional slope shading based on finite differences along x and z
+                const dxSlope = (v10 + v11 - v00 - v01) / (2 * span);
+                const dzSlope = (v01 + v11 - v00 - v10) / (2 * span);
+                const lightShade = Math.max(-0.22, Math.min(0.22, dxSlope * 0.25 - dzSlope * 0.18));
+                const baseColor = this._sampleGradient(colorScale, t);
+                const shadedColor = ColorPalette.lighten(baseColor, lightShade);
+
+                const depth = (p00.depth + p10.depth + p11.depth + p01.depth) / 4;
+                quads.push({
+                    pts: [p00, p10, p11, p01],
+                    color: shadedColor,
+                    depth,
+                    label: `${xLabels[ix]}–${xLabels[ix + 1]}`,
+                    series: `${zLabels[iz]}–${zLabels[iz + 1]}`,
+                    avgVal,
+                });
+            }
+        }
+
+        // Painter's sort: furthest (most negative depth) first
+        quads.sort((a, b) => a.depth - b.depth);
+
+        const stroke = wireframe ? { color: wireframeColor, width: 0.8 } : null;
+        for (const q of quads) {
+            const [p0, p1, p2, p3] = q.pts;
+            const d = `M${p0.x},${p0.y} L${p1.x},${p1.y} L${p2.x},${p2.y} L${p3.x},${p3.y} Z`;
+            const el = this._datum(this.renderer.path(d, q.color, stroke, {
+                tooltip: `${q.label} / ${q.series}: ${q.avgVal.toFixed(2)}`,
+            }), { label: q.label, series: q.series });
+            this._wireHoverTransform([el], { dx: 0, dy: -4 });
+        }
+
+        // Draw X and Z floor tick labels
+        const xStep = Math.max(1, Math.ceil(nx / 6));
+        for (let ix = 0; ix < nx; ix += xStep) {
+            const lp = toScreen(normX(ix), -0.58, 0.92);
+            this.renderer.text(String(xLabels[ix]), lp.x, lp.y, { textAnchor: 'middle', fontSize: '10px', fill: '#475569' });
+        }
+        const zStep = Math.max(1, Math.ceil(nz / 6));
+        for (let iz = 0; iz < nz; iz += zStep) {
+            const lp = toScreen(0.92, -0.58, normZ(iz));
+            this.renderer.text(String(zLabels[iz]), lp.x, lp.y, { textAnchor: 'middle', fontSize: '10px', fill: '#475569' });
+        }
+    }
+
+    _normalizeGrid(data) {
+        if (data && !Array.isArray(data) && Array.isArray(data.values)) {
+            const xLabels = data.xLabels || data.values.map((_, i) => String(i));
+            const zLabels = data.zLabels || (data.values[0] || []).map((_, j) => String(j));
+            return { xLabels, zLabels, grid: data.values };
+        }
+        const rows = Array.isArray(data) ? data : [];
+        const { xLabels, zLabels, xIndex, zIndex } = this.bucketGrid(rows);
+        const grid = Array.from({ length: xLabels.length }, () => new Array(zLabels.length).fill(0));
+        for (const r of rows) {
+            const ix = xIndex.get(r.x);
+            const iz = zIndex.get(r.z);
+            if (ix != null && iz != null) {
+                grid[ix][iz] = Number(r.value) || 0;
+            }
+        }
+        return { xLabels, zLabels, grid };
+    }
+
+    _sampleGradient(stops, t) {
+        if (!Array.isArray(stops) || stops.length === 0) return '#4f8ef7';
+        if (stops.length === 1) return stops[0];
+        const scaled = Math.max(0, Math.min(1, t)) * (stops.length - 1);
+        const idx = Math.min(stops.length - 2, Math.floor(scaled));
+        const localT = scaled - idx;
+        return ColorPalette.interpolate(stops[idx], stops[idx + 1], localT);
+    }
+}