@peter.prib/renderengine 0.14.0 → 0.15.0

package/src/charting/charts/LineChart.js

@@ -4,6 +4,7 @@ import { ChartBox, ChartLabels } from '../ChartBox.js';
 import { Legend } from '../Legend.js';
 import { ColorPalette } from '../ColorPalette.js';
 import { ErrorBars } from '../ErrorBars.js';
+import { Annotations } from '../Annotations.js';
 
 /**
  * LineChart — single or multi-series line chart with optional 3D ribbon
@@ -25,27 +26,59 @@ export class LineChart extends Chart {
         // Check if data is multiline (array of series) or single line
         const isMultiline = Array.isArray(data[0]?.values);
         const series = isMultiline ? data : [{ name: 'default', values: data }];
-        const legendOptions = { items: series.map(s => ({ name: s.name })), itemHeight: 20, markerSize: 12 };
+        const lineColors = colors || ColorPalette.DEFAULT;
+        const palette = new ColorPalette(lineColors);
+
+        const legendOptions = {
+            items: series.map((s, idx) => ({
+                label: s.name,
+                color: palette.colorAt(idx),
+                hidden: this._dataFilter.has(idx),
+                dataIndex: idx,
+            })),
+            itemHeight: 20,
+            markerSize: 12,
+        };
         // With a legend, the plot leaves room for it beside, so it does not cover the last points.
         const width = options.width ?? (isMultiline && showLegend
             ? Legend.plotWidthBeside({ x, width: box.width }, this.renderer.width, legendOptions) : box.width);
         const plotBox = { x, y, width, height };
 
-        // Determine max value across all series
-        const maxValue = Math.max(...series.flatMap(s =>
-            isMultiline ? s.values.map(d => d.value) : s.values.map(d => d.value)
-        )) || 1;
+        // Determine max values per axis (supports secondary right Y-axis and active series)
+        const activeSeries = series.filter((_, idx) => !this._dataFilter.has(idx));
+        const workingSeries = activeSeries.length ? activeSeries : series;
+        const leftSeries = workingSeries.filter(s => s.yAxis !== 'right');
+        const rightSeries = workingSeries.filter(s => s.yAxis === 'right');
+        const hasSecondaryY = rightSeries.length > 0;
+
+        const maxLeftValue = Math.max(...leftSeries.flatMap(s => s.values.map(d => d.value)), 1);
+        const maxRightValue = hasSecondaryY ? Math.max(...rightSeries.flatMap(s => s.values.map(d => d.value)), 1) : 1;
 
         const pointMargin = (isMultiline ? series[0].values.length : data.length) > 1
             ? width / ((isMultiline ? series[0].values.length : data.length) - 1)
             : width;
 
         const depth = zAxis ? zDepth : 0;
-        const lineColors = colors || ColorPalette.DEFAULT;
-        const palette = new ColorPalette(lineColors);
 
         new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, plotBox);
 
+        // Draw Left Y Axis and optional Secondary Right Y Axis
+        let leftAxisRes;
+        if (!zAxis) {
+            leftAxisRes = new Axis().drawYRange(this.renderer, plotBox, 0, maxLeftValue, { scale: options.scale });
+            if (hasSecondaryY) {
+                new Axis().drawSecondaryYRange(this.renderer, plotBox, 0, maxRightValue);
+            }
+        }
+
+        const toY = leftAxisRes?.yOf ?? ((v) => y + height - (v / maxLeftValue) * height);
+        const toX = (idx) => x + idx * pointMargin;
+
+        // Draw threshold bands and reference lines
+        Annotations.drawThresholdBands(this.renderer, plotBox, options.thresholdBands, { toY });
+        const refLines = options.referenceLines ?? options.referenceLine;
+        Annotations.drawReferenceLines(this.renderer, plotBox, refLines, { toY, toX });
+
         // 3D Axes
         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}`
@@ -55,35 +88,55 @@ export class LineChart extends Chart {
 
         // Draw each series
         series.forEach((seriesData, seriesIndex) => {
+            if (this._dataFilter.has(seriesIndex)) return;
             const seriesValues = isMultiline ? seriesData.values : seriesData.values;
             const seriesColor = palette.colorAt(seriesIndex);
             const seriesDepth = zAxis ? (depth / series.length) * (series.length - 1 - seriesIndex) : 0;
+            const seriesMax = seriesData.yAxis === 'right' ? maxRightValue : maxLeftValue;
+            const stepMode = seriesData.step ?? options.step;
 
             // Draw line
             if (zAxis) {
                 // 3D effect: draw a "ribbon"
                 const ribbonPath = seriesValues.map((d, i) => {
-                    const pY = y + height - (d.value / maxValue) * height;
+                    const pY = toY(d.value);
                     return `L${x + i * pointMargin + seriesDepth},${pY - seriesDepth}`;
                 }).join(' ').replace('L', 'M');
                 this.renderer.path(ribbonPath, palette.lighten(seriesColor, -0.2), null);
             }
             let pathData = '';
+            let prevX = 0, prevY = 0;
             seriesValues.forEach((d, i) => {
                 const pointX = x + i * pointMargin + seriesDepth;
-                const pointY = y + height - (d.value / maxValue) * height - seriesDepth;
+                const pointY = toY(d.value) - seriesDepth;
                 if (i === 0) {
-                    pathData += `M${pointX},${pointY}`;
+                    pathData = `M${pointX},${pointY}`;
+                } else if (stepMode === 'before') {
+                    pathData += ` V${pointY} H${pointX}`;
+                } else if (stepMode === 'center') {
+                    const midX = (prevX + pointX) / 2;
+                    pathData += ` H${midX} V${pointY} H${pointX}`;
+                } else if (stepMode) {
+                    // 'after' or true
+                    pathData += ` H${pointX} V${pointY}`;
                 } else {
                     pathData += ` L${pointX},${pointY}`;
                 }
+                prevX = pointX;
+                prevY = pointY;
             });
             this.renderer.path(pathData, 'none', { color: seriesColor, width: 2 });
 
+            // Optional trendline per series or for primary
+            if (options.trendline && (seriesIndex === 0 || options.trendline?.series === seriesData.name)) {
+                const trendPts = seriesValues.map((d, i) => ({ x: i, y: d.value }));
+                Annotations.drawTrendline(this.renderer, plotBox, trendPts, options.trendline, { toX, toY });
+            }
+
             // Draw points + optional error bars
             seriesValues.forEach((d, i) => {
                 const pointX = x + i * pointMargin + seriesDepth;
-                const pointY = y + height - (d.value / maxValue) * height - seriesDepth;
+                const pointY = toY(d.value) - seriesDepth;
                 const textAnchor = this.renderer.centerTextAnchor;
 
                 this._datum(this.renderer.circle(
@@ -94,20 +147,24 @@ export class LineChart extends Chart {
                     { tooltip: `${isMultiline ? seriesData.name + ': ' : ''}${d.label}: ${d.value}` }
                 ), { label: d.label, series: isMultiline ? seriesData.name : null });
 
+                if (options.showValues) {
+                    this.renderer.text(Axis.formatValue(d.value), pointX, pointY - 8, {
+                        textAnchor, fontSize: '10px', fill: '#333',
+                    });
+                }
+
                 const errMinus = d.errorMinus != null ? d.errorMinus : d.error != null ? d.error : null;
                 const errPlus = d.errorPlus != null ? d.errorPlus : d.error != null ? d.error : null;
                 if (errMinus != null || errPlus != null) {
                     const yHighVal = d.value + (errPlus ?? 0);
                     const yLowVal = d.value - (errMinus ?? 0);
-                    const yHigh = y + height - (yHighVal / maxValue) * height - seriesDepth;
-                    const yLow = y + height - (yLowVal / maxValue) * height - seriesDepth;
+                    const yHigh = toY(yHighVal) - seriesDepth;
+                    const yLow = toY(yLowVal) - seriesDepth;
                     ErrorBars.draw(this.renderer, pointX, pointY, null, null, yLow, yHigh, seriesColor);
                 }
             });
 
-            // Draw labels only for first series to avoid clutter. Use this
-            // series' own seriesDepth (not the raw max `depth`) for the x-shift
-            // so labels line up under series 0's actual (depth-shifted) points.
+            // Draw labels only for first series to avoid clutter.
             if (seriesIndex === 0) {
                 const step = Axis.categoryLabelStep(seriesValues.map(d => d.label), width);
                 seriesValues.forEach((d, i) => {
@@ -121,8 +178,7 @@ export class LineChart extends Chart {
 
         // Draw legend for multiline
         if (isMultiline && showLegend) {
-            const legendItems = series.map((s, i) => ({ name: s.name, color: palette.colorAt(i) }));
-            Legend.beside({ x, y, width }, this.renderer.width, { ...legendOptions, items: legendItems }).draw(this.renderer);
+            Legend.beside({ x, y, width }, this.renderer.width, legendOptions).draw(this.renderer);
         }
     }
 }

package/src/charting/charts/OhlcChart.js

@@ -0,0 +1,79 @@
+import { Axis } from '../Axis.js';
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+
+/**
+ * OhlcChart — Open-High-Low-Close financial price bar chart.
+ *
+ * Visualizes asset price action with a vertical high-to-low spine, a left tick
+ * at open, and a right tick at close, shaded green (up) or red (down).
+ */
+export class OhlcChart extends Chart {
+    static chartType = 'ohlc';
+
+    _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, xAxisLabel, yAxisLabel,
+            upColor = '#26a69a', downColor = '#ef5350',
+            tickWidth = 5,
+        } = options;
+        const plotBox = { x, y, width, height };
+
+        new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, plotBox);
+
+        const allHighs = data.map(d => Number(d.high) || 0);
+        const allLows = data.map(d => Number(d.low) || 0);
+        const minVal = Math.min(...allLows);
+        const maxVal = Math.max(...allHighs);
+
+        // Draw axes
+        new Axis().drawYRange(this.renderer, plotBox, minVal, maxVal);
+        this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
+
+        const toY = v => y + height - ((v - minVal) / ((maxVal - minVal) || 1)) * height;
+        const N = data.length;
+        const slotW = width / N;
+
+        data.forEach((bar, i) => {
+            const cx = x + i * slotW + slotW / 2;
+            const yHigh = toY(bar.high);
+            const yLow = toY(bar.low);
+            const yOpen = toY(bar.open);
+            const yClose = toY(bar.close);
+            const isUp = bar.close >= bar.open;
+            const color = isUp ? upColor : downColor;
+            const tooltip = `${bar.label}: Open ${bar.open}, High ${bar.high}, Low ${bar.low}, Close ${bar.close}`;
+
+            // Vertical spine (high to low)
+            const spine = this._datum(this.renderer.path(`M${cx},${yHigh} L${cx},${yLow}`, 'none', {
+                color, width: 2,
+            }, { tooltip }), { label: bar.label, ...bar });
+
+            // Left open tick
+            const openTick = this.renderer.path(`M${cx - tickWidth},${yOpen} L${cx},${yOpen}`, 'none', {
+                color, width: 2,
+            });
+
+            // Right close tick
+            const closeTick = this.renderer.path(`M${cx},${yClose} L${cx + tickWidth},${yClose}`, 'none', {
+                color, width: 2,
+            });
+
+            this._wireHoverTransform([spine, openTick, closeTick], { dx: 0, dy: -2 });
+
+            // Category label along X
+            const step = Axis.categoryLabelStep(data.map(d => d.label), width);
+            if (i % step === 0) {
+                this.renderer.text(bar.label, cx, y + height + 20, {
+                    textAnchor: this.renderer.centerTextAnchor, fontSize: '10px', fill: '#333',
+                });
+            }
+        });
+    }
+}

package/src/charting/charts/ParallelCoordinatesChart.js

@@ -64,6 +64,9 @@ export class ParallelCoordinatesChart extends Chart {
         }
 
         data.forEach((row, rowIndex) => {
+            const catIdx = hasCategories ? categories.indexOf(row.category) : -1;
+            if (catIdx >= 0 && this._dataFilter.has(catIdx)) return;
+
             const pts = [];
             let valid = true;
             dimensions.forEach((dim, i) => {
@@ -93,7 +96,12 @@ export class ParallelCoordinatesChart extends Chart {
         });
 
         if (legendVisible && hasCategories) {
-            const legendItems = categories.map((c, i) => ({ name: c, color: palette.colorAt(i) }));
+            const legendItems = categories.map((c, i) => ({
+                name: c,
+                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/PieChart.js

@@ -4,11 +4,174 @@ import { ColorPalette } from '../ColorPalette.js';
 import { ShapePaths } from '../ShapePaths.js';
 
 /**
- * PieChart — pie or doughnut chart with optional legend.
+ * PieChart — pie or doughnut chart with optional legend, exploded slices,
+ * interactive hover slice pull-out (`hoverExplode`), callout leader lines
+ * (`showLabels`), `"Other"` slice roll-up (`maxSlices`), and center KPI label
+ * (`centerLabel` / `showTotal` when `innerRadiusRatio > 0`).
+ *
+ * Also serves as the shared base class for `DonutChart`, `PieChart3D`, and `DonutChart3D`.
  */
 export class PieChart extends Chart {
     static chartType = 'pie';
 
+    /**
+     * Resolve whether/how far slice `(d, i)` is pre-exploded in pixels.
+     * Supports:
+     * - per-slice `d.exploded` (`true` -> `explodeOffset`, or a numeric pixel offset)
+     * - `options.exploded`:
+     *   - `true`: all slices exploded by `explodeOffset`
+     *   - `'max'`: explodes the largest slice
+     *   - `number`: slice index
+     *   - `string`: slice label
+     *   - `Array<number|string>`: matching indices or labels
+     *   - `Function`: `(d, i) => boolean | number`
+     */
+    static resolveExplodeDistance(d, i, data, options = {}) {
+        const explodeOffset = options.explodeOffset ?? 14;
+        if (typeof d?.exploded === 'number') return d.exploded;
+        if (d?.exploded === true) return explodeOffset;
+
+        const { exploded } = options;
+        if (exploded == null || exploded === false) return 0;
+        if (exploded === true) return explodeOffset;
+        if (exploded === 'max') {
+            let maxIdx = 0;
+            let maxVal = -Infinity;
+            data.forEach((item, idx) => {
+                if ((item?.value ?? 0) > maxVal) {
+                    maxVal = item.value;
+                    maxIdx = idx;
+                }
+            });
+            return i === maxIdx ? explodeOffset : 0;
+        }
+        if (typeof exploded === 'number') return i === exploded ? explodeOffset : 0;
+        if (typeof exploded === 'string') return d?.label === exploded ? explodeOffset : 0;
+        if (Array.isArray(exploded)) {
+            return (exploded.includes(i) || exploded.includes(d?.label)) ? explodeOffset : 0;
+        }
+        if (typeof exploded === 'function') {
+            const res = exploded(d, i);
+            if (typeof res === 'number') return res;
+            return res ? explodeOffset : 0;
+        }
+        return 0;
+    }
+
+    /**
+     * Prepare normalized slice geometry (angles, percentages, colors, explosion offsets,
+     * and optional `maxSlices` roll-up into an `"Other"` slice).
+     */
+    static prepareSlices(data = [], options = {}) {
+        const {
+            colors,
+            maxSlices = 0,
+            otherLabel = 'Other',
+            startAngle: initialAngle = -Math.PI / 2,
+        } = options;
+        const palette = new ColorPalette(colors);
+        let items = Array.isArray(data) ? data.filter(d => (d?.value ?? 0) > 0) : [];
+        if (maxSlices > 1 && items.length > maxSlices) {
+            const head = items.slice(0, maxSlices - 1);
+            const tail = items.slice(maxSlices - 1);
+            const otherVal = tail.reduce((s, d) => s + (d.value || 0), 0);
+            items = [...head, { label: otherLabel, value: otherVal }];
+        }
+        const total = items.reduce((s, d) => s + d.value, 0) || 1;
+        let angle = initialAngle;
+        const slices = items.map((d, i) => {
+            const span = (d.value / total) * Math.PI * 2;
+            const startAngle = angle;
+            const endAngle = angle + span;
+            const midAngle = startAngle + span / 2;
+            angle = endAngle;
+            const explodeDistance = PieChart.resolveExplodeDistance(d, i, items, options);
+            return {
+                index: i,
+                datum: d,
+                label: d.label,
+                value: d.value,
+                percent: (d.value / total) * 100,
+                color: d.color || palette.colorAt(i),
+                startAngle,
+                endAngle,
+                midAngle,
+                explodeDistance,
+            };
+        });
+        return { slices, total, palette };
+    }
+
+    /**
+     * Wire smooth hover pull-out on a slice's SVG elements (`elements` moves as a unit).
+     */
+    _wireSliceHover(elements, midAngle, ryRatio = 1) {
+        const { hoverExplode = true, hoverOffset = 14 } = this.options;
+        if (!hoverExplode || hoverOffset <= 0) return;
+        this._wireRadialHover(elements, midAngle, { offset: hoverOffset, ryRatio });
+    }
+
+    /**
+     * Draw optional callout leader lines and external labels for slices.
+     */
+    _drawCalloutLabel(slice, cx, cy, rxOuter, ryOuter, ryRatio = 1, sliceEls = null) {
+        const { showLabels = false, minLabelPercent = 2 } = this.options;
+        if (!showLabels || slice.percent < minLabelPercent) return;
+
+        const cos = Math.cos(slice.midAngle);
+        const sin = Math.sin(slice.midAngle);
+        const sx = cx + Math.cos(slice.midAngle) * slice.explodeDistance;
+        const sy = cy + Math.sin(slice.midAngle) * slice.explodeDistance * ryRatio;
+
+        const x0 = sx + rxOuter * cos;
+        const y0 = sy + ryOuter * sin;
+        const x1 = sx + (rxOuter + 14) * cos;
+        const y1 = sy + (ryOuter + 14 * ryRatio) * sin;
+        const rightSide = cos >= 0;
+        const x2 = x1 + (rightSide ? 12 : -12);
+        const y2 = y1;
+
+        const lineEl = this.renderer.path(`M${x0},${y0} L${x1},${y1} L${x2},${y2}`, 'none', { color: '#64748b', width: 1 });
+        const labelText = showLabels === 'percent'
+            ? `${slice.percent.toFixed(1)}%`
+            : showLabels === 'label'
+                ? slice.label
+                : `${slice.label} (${slice.percent.toFixed(0)}%)`;
+        const textEl = this.renderer.text(labelText, x2 + (rightSide ? 4 : -4), y2 + 4, {
+            textAnchor: rightSide ? 'start' : 'end',
+            fontSize: '11px',
+            fill: '#334155',
+        });
+        if (sliceEls) {
+            if (lineEl) sliceEls.push(lineEl);
+            if (textEl) sliceEls.push(textEl);
+        }
+    }
+
+    /**
+     * Draw an optional center KPI / total label inside a doughnut hole.
+     */
+    _drawCenterLabel(cx, cy, total, rInner) {
+        if (rInner <= 0) return;
+        const { centerLabel, centerSubLabel, showTotal = false } = this.options;
+        if (centerLabel == null && !showTotal) return;
+        const mainText = centerLabel != null ? String(centerLabel) : total.toLocaleString();
+        this.renderer.text(mainText, cx, cy + (centerSubLabel ? -2 : 5), {
+            textAnchor: 'middle',
+            fontSize: '18px',
+            fontWeight: 'bold',
+            fill: '#1e293b',
+        });
+        const sub = centerSubLabel ?? (showTotal && centerLabel == null ? 'Total' : null);
+        if (sub) {
+            this.renderer.text(String(sub), cx, cy + 16, {
+                textAnchor: 'middle',
+                fontSize: '11px',
+                fill: '#64748b',
+            });
+        }
+    }
+
     _render() {
         const data = this.data;
         const options = this.options;
@@ -18,31 +181,46 @@ export class PieChart extends Chart {
             cx = w / 2, cy = h / 2 + 10,
             radius = Math.min(w, h) / 2 - 60,
             innerRadiusRatio = 0,
-            colors, legend: showLegend = true, title,
+            legend: showLegend = true, title,
         } = options;
-        const palette = new ColorPalette(colors);
-        const total = data.reduce((s, d) => s + d.value, 0) || 1;
+        const { slices, total } = PieChart.prepareSlices(data, options);
         const rInner = radius * innerRadiusRatio;
 
         if (title) {
             this.renderer.text(title, cx, cy - radius - 20, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
         }
 
-        let angle = -Math.PI / 2; // start at 12 o'clock
-        data.forEach((d, i) => {
-            const slice = (d.value / total) * Math.PI * 2;
-            const color = palette.colorAt(i);
-            const path = ShapePaths.donutSlicePath(cx, cy, radius, rInner, angle, angle + slice);
-            this._datum(this.renderer.path(path, color, { color: '#fff', width: 1 }, {
-                tooltip: `${d.label}: ${d.value} (${(d.value / total * 100).toFixed(1)}%)`,
-            }), { label: d.label });
-            angle += slice;
-        });
+        for (const s of slices) {
+            const dx = Math.cos(s.midAngle) * s.explodeDistance;
+            const dy = Math.sin(s.midAngle) * s.explodeDistance;
+            const path = ShapePaths.donutSlicePath(cx + dx, cy + dy, radius, rInner, s.startAngle, s.endAngle);
+            const el = this._datum(this.renderer.path(path, s.color, { color: '#fff', width: 1 }, {
+                tooltip: `${s.label}: ${s.value} (${s.percent.toFixed(1)}%)`,
+            }), { label: s.label });
+            const sliceEls = [el];
+            if (options.showValues && s.percent >= 4) {
+                const rMid = (radius + rInner) / 2;
+                const vx = cx + dx + Math.cos(s.midAngle) * rMid;
+                const vy = cy + dy + Math.sin(s.midAngle) * rMid;
+                const valText = typeof options.format === 'function' ? options.format(s.value) : s.value.toLocaleString();
+                const textEl = this.renderer.text(valText, vx, vy + 4, {
+                    textAnchor: 'middle',
+                    fontSize: '11px',
+                    fontWeight: 'bold',
+                    fill: '#ffffff',
+                });
+                if (textEl) sliceEls.push(textEl);
+            }
+            this._drawCalloutLabel(s, cx, cy, radius, radius, 1, sliceEls);
+            this._wireSliceHover(sliceEls, s.midAngle, 1);
+        }
+
+        this._drawCenterLabel(cx, cy, total, rInner);
 
         if (showLegend) {
-            const legendItems = data.map((d, i) => ({
-                label: `${d.label} (${(d.value / total * 100).toFixed(0)}%)`,
-                color: palette.colorAt(i),
+            const legendItems = slices.map(s => ({
+                label: `${s.label} (${s.percent.toFixed(0)}%)`,
+                color: s.color,
             }));
             new Legend({
                 items: legendItems,

package/src/charting/charts/PieChart3D.js

@@ -0,0 +1,137 @@
+import { PieChart } from './PieChart.js';
+import { Legend } from '../Legend.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { ShapePaths } from '../ShapePaths.js';
+
+/**
+ * PieChart3D — extruded 3D tilted pie/doughnut chart with shaded outer/inner
+ * cylinder skirts, radial cut walls, pre-exploded slices (`exploded`), and
+ * interactive hover pull-out (`hoverExplode`: hovering over any slice smoothly
+ * slides the entire 3D wedge out along its radial angle).
+ */
+export class PieChart3D extends PieChart {
+    static chartType = 'pie3D';
+
+    _render() {
+        const data = this.data;
+        const options = this.options;
+        const w = this.renderer?.width ?? 640;
+        const h = this.renderer?.height ?? 400;
+        const {
+            tilt = 0.58,
+            depth = 26,
+            innerRadiusRatio = 0,
+            legend: showLegend = true,
+            title,
+        } = options;
+        const rx = options.radius ?? (Math.min(w, h) / 2 - 55);
+        const ry = rx * tilt;
+        const rxInner = rx * innerRadiusRatio;
+        const ryInner = ry * innerRadiusRatio;
+        const cx = options.cx ?? (showLegend ? Math.max(rx + 45, w / 2 - 45) : w / 2);
+        const cy = options.cy ?? (h / 2 - depth / 2 + 8);
+
+        const { slices, total } = PieChart.prepareSlices(data, {
+            explodeOffset: 16,
+            ...options,
+        });
+
+        if (title) {
+            this.renderer.text(title, w / 2, Math.max(24, cy - ry - 26), {
+                textAnchor: 'middle',
+                fontSize: '18px',
+                fill: '#333',
+            });
+        }
+
+        // Sort slices from back (12 o'clock, sin(θ) = -1) to front (6 o'clock, sin(θ) = +1)
+        // so painter's algorithm naturally occludes back wedges with front wedges while keeping
+        // all faces of each slice grouped for smooth hover pull-out.
+        const ordered = [...slices].sort((a, b) => Math.sin(a.midAngle) - Math.sin(b.midAngle));
+
+        for (const s of ordered) {
+            const dx = Math.cos(s.midAngle) * s.explodeDistance;
+            const dy = Math.sin(s.midAngle) * s.explodeDistance * tilt;
+            const scx = cx + dx;
+            const scy = cy + dy;
+            const tooltip = `${s.label}: ${s.value} (${s.percent.toFixed(1)}%)`;
+            const datum = { label: s.label };
+            const sliceEls = [];
+
+            const topColor = ColorPalette.lighten(s.color, 0.06);
+            const outerSkirtColor = ColorPalette.lighten(s.color, -0.22);
+            const innerSkirtColor = ColorPalette.lighten(s.color, -0.28);
+            const wallColorA = ColorPalette.lighten(s.color, -0.15);
+            const wallColorB = ColorPalette.lighten(s.color, -0.25);
+            const stroke = { color: ColorPalette.lighten(s.color, -0.32), width: 0.8 };
+
+            // Order the two radial cut walls from further back (smaller average sin) to further front
+            const walls = [
+                { angle: s.startAngle, depthOrder: Math.sin(s.startAngle), color: wallColorA },
+                { angle: s.endAngle,   depthOrder: Math.sin(s.endAngle),   color: wallColorB },
+            ].sort((a, b) => a.depthOrder - b.depthOrder);
+
+            const drawWall = (wSpec) => {
+                if (depth <= 0 || slices.length <= 1) return;
+                const dPath = ShapePaths.radialWallPath(scx, scy, rxInner, ryInner, rx, ry, depth, wSpec.angle);
+                const el = this._datum(this.renderer.path(dPath, wSpec.color, stroke, { tooltip }), datum);
+                if (el) sliceEls.push(el);
+            };
+
+            // 1. Back-most radial cut wall
+            drawWall(walls[0]);
+
+            // 2. Inner donut hole cylinder wall (visible along the back half where sin(θ) <= 0)
+            if (rxInner > 0 && depth > 0) {
+                for (const [a0, a1] of ShapePaths.visibleArcIntervals(s.startAngle, s.endAngle, 'back')) {
+                    const innerPath = ShapePaths.cylinderSkirtPath(scx, scy, rxInner, ryInner, depth, a0, a1);
+                    if (innerPath) {
+                        const el = this._datum(this.renderer.path(innerPath, innerSkirtColor, stroke, { tooltip }), datum);
+                        if (el) sliceEls.push(el);
+                    }
+                }
+            }
+
+            // 3. Front-most radial cut wall
+            drawWall(walls[1]);
+
+            // 4. Outer cylinder rim skirt (visible along the front half where sin(θ) >= 0)
+            if (depth > 0) {
+                for (const [a0, a1] of ShapePaths.visibleArcIntervals(s.startAngle, s.endAngle, 'front')) {
+                    const skirtPath = ShapePaths.cylinderSkirtPath(scx, scy, rx, ry, depth, a0, a1);
+                    if (skirtPath) {
+                        const el = this._datum(this.renderer.path(skirtPath, outerSkirtColor, stroke, { tooltip }), datum);
+                        if (el) sliceEls.push(el);
+                    }
+                }
+            }
+
+            // 5. Top elliptical slice face
+            const topPath = ShapePaths.ellipticalSlicePath(scx, scy, rx, ry, rxInner, ryInner, s.startAngle, s.endAngle);
+            const topEl = this._datum(this.renderer.path(topPath, topColor, { color: '#fff', width: 1 }, { tooltip }), datum);
+            if (topEl) sliceEls.push(topEl);
+
+            // 6. Optional callout leader line + label (moves with slice on hover)
+            this._drawCalloutLabel(s, cx, cy, rx, ry, tilt, sliceEls);
+
+            // 7. Wire smooth radial hover pull-out across all 3D faces of this slice
+            this._wireSliceHover(sliceEls, s.midAngle, tilt);
+        }
+
+        this._drawCenterLabel(cx, cy, total, rxInner);
+
+        if (showLegend) {
+            const legendItems = slices.map(s => ({
+                label: `${s.label} (${s.percent.toFixed(0)}%)`,
+                color: s.color,
+            }));
+            new Legend({
+                items: legendItems,
+                x: cx + rx + 28,
+                y: cy - ry,
+                itemHeight: 20,
+                markerSize: 12,
+            }).draw(this.renderer);
+        }
+    }
+}