@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/charts/CalendarHeatmapChart.js

@@ -0,0 +1,204 @@
+import { Chart } from '../Chart.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * CalendarHeatmapChart — a year-at-a-glance day grid (GitHub-contribution-graph
+ * style). Each cell is one day, shaded by its value along a continuous color
+ * scale. Days with no data use the empty color.
+ *
+ * Data: Array<{date: string|Date, value: number}>
+ * Options:
+ *   - year: number (defaults to current year; ignored if startDate/endDate set)
+ *   - startDate, endDate: string|Date (inclusive bounds)
+ *   - colorScale: string[] low→high stops (default GitHub-like greens)
+ *   - emptyColor: string for days with no data
+ *   - cellSize: number (auto-sized to fit box if omitted)
+ *   - cellGap: number (default 2)
+ *   - showValues: boolean (default false)
+ *   - title: string
+ *   - monthLabels: boolean (default true)
+ *   - weekdayLabels: boolean (default true)
+ *   - weekStart: 0 = Sunday, 1 = Monday (default 0)
+ */
+export class CalendarHeatmapChart extends Chart {
+    static chartType = 'calendarHeatmap';
+
+    /** Parse an ISO date string or Date into a UTC midnight Date. */
+    static parseDate(d) {
+        if (d instanceof Date) return new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+        if (typeof d === 'string') {
+            // Accept 'YYYY-MM-DD' or full ISO; normalise to UTC midnight.
+            const [y, m, day] = d.split('T')[0].split('-').map(Number);
+            return new Date(Date.UTC(y, m - 1, day));
+        }
+        return new Date(NaN);
+    }
+
+    static addDays(date, days) {
+        const r = new Date(date);
+        r.setUTCDate(r.getUTCDate() + days);
+        return r;
+    }
+
+    static diffDays(a, b) {
+        return Math.round((a.getTime() - b.getTime()) / 86400000);
+    }
+
+    static startOfWeek(date, weekStart = 0) {
+        const day = date.getUTCDay();
+        const offset = (day - weekStart + 7) % 7;
+        return CalendarHeatmapChart.addDays(date, -offset);
+    }
+
+    static isoString(date) {
+        return date.toISOString().slice(0, 10);
+    }
+
+    _render() {
+        const data = this.data || [];
+        const options = this.options || {};
+        const w = this.renderer?.width ?? 800;
+        const h = this.renderer?.height ?? 400;
+
+        const now = new Date();
+        const defaultYear = now.getFullYear();
+        const {
+            x = 60, y = 40,
+            year = defaultYear,
+            startDate: startDateOpt,
+            endDate: endDateOpt,
+            colorScale = ['#ebedf0', '#9be9a8', '#40c463', '#30a14e', '#216e39'],
+            emptyColor = '#ebedf0',
+            cellSize,
+            cellGap = 2,
+            showValues = false,
+            title,
+            monthLabels = true,
+            weekdayLabels = true,
+            weekStart = 0,
+        } = options;
+
+        const valueByDay = new Map();
+        const allValues = [];
+        for (const d of data) {
+            const date = CalendarHeatmapChart.parseDate(d.date);
+            if (Number.isNaN(date.getTime())) continue;
+            const key = CalendarHeatmapChart.isoString(date);
+            const value = typeof d.value === 'number' ? d.value : Number(d.value);
+            valueByDay.set(key, value);
+            allValues.push(value);
+        }
+
+        let start, end;
+        if (startDateOpt != null && endDateOpt != null) {
+            start = CalendarHeatmapChart.parseDate(startDateOpt);
+            end = CalendarHeatmapChart.parseDate(endDateOpt);
+        } else if (startDateOpt != null) {
+            start = CalendarHeatmapChart.parseDate(startDateOpt);
+            end = CalendarHeatmapChart.addDays(start, 364);
+        } else if (endDateOpt != null) {
+            end = CalendarHeatmapChart.parseDate(endDateOpt);
+            start = CalendarHeatmapChart.addDays(end, -364);
+        } else {
+            start = new Date(Date.UTC(year, 0, 1));
+            end = new Date(Date.UTC(year, 11, 31));
+        }
+
+        // Always start on the configured week-start day so rows line up.
+        start = CalendarHeatmapChart.startOfWeek(start, weekStart);
+        end = CalendarHeatmapChart.startOfWeek(CalendarHeatmapChart.addDays(end, 6), weekStart);
+        end = CalendarHeatmapChart.addDays(end, 6); // inclusive end of that week
+
+        const days = CalendarHeatmapChart.diffDays(end, start) + 1;
+        const weeks = Math.ceil(days / 7);
+
+        const textAnchor = this.renderer.centerTextAnchor;
+        const labelWidth = weekdayLabels ? 32 : 0;
+        const headerHeight = monthLabels ? 24 : 0;
+        const titleHeight = title ? 30 : 0;
+
+        const availW = w - x - 20;
+        const availH = h - y - 20 - headerHeight - titleHeight;
+        const computedCellSize = cellSize ?? Math.min(
+            Math.floor((availW - labelWidth - cellGap * (weeks - 1)) / weeks),
+            Math.floor((availH - cellGap * 6) / 7),
+        );
+        const size = Math.max(4, computedCellSize);
+        const step = size + cellGap;
+
+        const gridX = x + labelWidth;
+        const gridY = y + headerHeight + titleHeight;
+        const gridW = weeks * step - cellGap;
+        const gridH = 7 * step - cellGap;
+
+        if (title) {
+            this.renderer.text(title, x, y + 16, { textAnchor: 'start', fontSize: '16px', fill: '#333' });
+        }
+
+        const vMin = allValues.length ? Math.min(...allValues) : 0;
+        const vMax = allValues.length ? Math.max(...allValues) : 1;
+
+        const dayNames = weekStart === 1
+            ? ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+            : ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+
+        if (weekdayLabels) {
+            dayNames.forEach((name, i) => {
+                if (i % 2 === 0) {
+                    this.renderer.text(name, x + labelWidth - 6, gridY + i * step + size / 2 + 4, {
+                        textAnchor: 'end', fontSize: '10px', fill: '#666',
+                    });
+                }
+            });
+        }
+
+        // Month labels centered under the first week that contains that month.
+        if (monthLabels) {
+            const monthFormat = new Intl.DateTimeFormat('en-US', { month: 'short', timeZone: 'UTC' });
+            let lastMonth = -1;
+            for (let i = 0; i < days; i++) {
+                const date = CalendarHeatmapChart.addDays(start, i);
+                const month = date.getUTCMonth();
+                if (month !== lastMonth) {
+                    lastMonth = month;
+                    const week = Math.floor(i / 7);
+                    this.renderer.text(monthFormat.format(date), gridX + week * step + size / 2, gridY - 8, {
+                        textAnchor, fontSize: '10px', fill: '#666',
+                    });
+                }
+            }
+        }
+
+        for (let i = 0; i < days; i++) {
+            const date = CalendarHeatmapChart.addDays(start, i);
+            const key = CalendarHeatmapChart.isoString(date);
+            const value = valueByDay.get(key);
+            const hasValue = valueByDay.has(key);
+            const week = Math.floor(i / 7);
+            const day = i % 7;
+            const cx = gridX + week * step;
+            const cy = gridY + day * step;
+            const color = hasValue
+                ? ColorPalette.scaleColor(colorScale, vMin, vMax, value)
+                : emptyColor;
+
+            this.renderer.rect(cx, cy, size, size, color, null, {
+                tooltip: hasValue ? `${key}: ${value}` : `${key}: no data`,
+            });
+
+            if (showValues && hasValue && size >= 14) {
+                this.renderer.text(String(value), cx + size / 2, cy + size / 2 + 4, {
+                    textAnchor, verticalAlign: 'middle', fontSize: '9px', fill: ColorPalette.isDark(color) ? '#fff' : '#333',
+                });
+            }
+        }
+
+        // Legend.
+        const legendY = gridY + gridH + 24;
+        this.renderer.text('Less', x, legendY + 8, { textAnchor: 'start', fontSize: '10px', fill: '#666' });
+        colorScale.forEach((c, i) => {
+            this.renderer.rect(x + 30 + i * (size + 4), legendY, size, size, c);
+        });
+        this.renderer.text('More', x + 30 + colorScale.length * (size + 4) + 4, legendY + 8, { textAnchor: 'start', fontSize: '10px', fill: '#666' });
+    }
+}

package/src/charting/charts/CandlestickChart.js

@@ -0,0 +1,54 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+
+/**
+ * CandlestickChart — OHLC financial chart. Each entry draws a vertical wick
+ * from low to high and a rectangular body from open to close.
+ */
+export class CandlestickChart extends Chart {
+    static chartType = 'candlestick';
+
+    _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,
+            upColor = '#26a69a', downColor = '#ef5350', title, xAxisLabel, yAxisLabel,
+            markers = [],
+        } = options;
+
+        const vMax = Math.max(...data.map(d => d.high));
+        const vMin = Math.min(...data.map(d => d.low));
+        const range = (vMax - vMin) || 1;
+        const slotWidth = width / data.length;
+        const bodyWidth = slotWidth * 0.6;
+        const toY = (v) => y + height - ((v - vMin) / range) * height;
+        const textAnchor = this.renderer.centerTextAnchor;
+
+        new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, { x, y, width, height });
+        this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
+
+        data.forEach((d, i) => {
+            const cx = x + i * slotWidth + slotWidth / 2;
+            const isUp = d.close >= d.open;
+            const color = isUp ? upColor : downColor;
+            this.renderer.path(`M${cx},${toY(d.high)} L${cx},${toY(d.low)}`, 'none', { color, width: 1 });
+            const bodyTop = toY(Math.max(d.open, d.close));
+            const bodyBottom = toY(Math.min(d.open, d.close));
+            this.renderer.rect(cx - bodyWidth / 2, bodyTop, bodyWidth, Math.max(1, bodyBottom - bodyTop), color, null, {
+                tooltip: `${d.label}: O ${d.open} H ${d.high} L ${d.low} C ${d.close}`,
+            });
+            if (i % Math.ceil(data.length / 10 || 1) === 0) {
+                this.renderer.text(d.label, cx, y + height + 20, { textAnchor, fontSize: '10px' });
+            }
+        });
+
+        markers.forEach((m) => {
+            const idx = data.findIndex(d => d.label === m.label);
+            if (idx < 0) return;
+            const cx = x + idx * slotWidth + slotWidth / 2;
+            this.renderer.circle(cx, y - 8, 4, '#f39c12', { color: '#fff', width: 1 }, { tooltip: m.tooltip ?? m.label });
+        });
+    }
+}

package/src/charting/charts/ChordDiagram.js

@@ -0,0 +1,130 @@
+import { Chart } from '../Chart.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * ChordDiagram — entities arranged around a circle, with curved links
+ * (chords) showing directed or undirected relationships. Link thickness is
+ * proportional to value.
+ *
+ * Data:
+ *   {
+ *     nodes?: Array<{id: string, label?: string, color?: string}>,
+ *     links: Array<{source: string, target: string, value: number}>
+ *   }
+ *
+ * Options:
+ *   - cx, cy, radius, innerRadius
+ *   - padAngle: gap between node arcs in radians (default 0.04)
+ *   - colors
+ *   - title
+ */
+export class ChordDiagram extends Chart {
+    static chartType = 'chord';
+
+    _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.92,
+            padAngle = 0.04,
+            colors,
+            title,
+        } = options;
+
+        const links = (data.links || []).filter(l => l.value > 0);
+        if (links.length === 0) return;
+
+        const nodeMap = new Map();
+        const ensureNode = (id) => {
+            if (!nodeMap.has(id)) nodeMap.set(id, { id, label: id, value: 0, color: null });
+            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 => {
+            nodeMap.get(l.source).value += l.value;
+            nodeMap.get(l.target).value += l.value;
+        });
+
+        const nodes = [...nodeMap.values()];
+        const total = nodes.reduce((s, n) => s + n.value, 0) || 1;
+        const palette = new ColorPalette(colors);
+        nodes.forEach((n, i) => { n.color = n.color || palette.colorAt(i); });
+
+        // Assign angles.
+        let currentAngle = -Math.PI / 2;
+        nodes.forEach(n => {
+            const sweep = (n.value / total) * (Math.PI * 2 - nodes.length * padAngle);
+            n.start = currentAngle + padAngle / 2;
+            n.end = n.start + sweep;
+            n.mid = (n.start + n.end) / 2;
+            currentAngle = n.end + padAngle / 2;
+        });
+
+        if (title) {
+            this.renderer.text(title, cx, cy - radius - 30, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
+        }
+
+        // Draw chords first so they sit under the node rim.
+        const maxLink = Math.max(...links.map(l => l.value));
+        const maxStroke = radius * 0.08;
+        links.forEach(l => {
+            const s = nodeMap.get(l.source);
+            const t = nodeMap.get(l.target);
+            const sx = cx + innerRadius * Math.cos(s.mid);
+            const sy = cy + innerRadius * Math.sin(s.mid);
+            const tx = cx + innerRadius * Math.cos(t.mid);
+            const ty = cy + innerRadius * Math.sin(t.mid);
+            const c1x = cx + (innerRadius * 0.2) * Math.cos(s.mid);
+            const c1y = cy + (innerRadius * 0.2) * Math.sin(s.mid);
+            const c2x = cx + (innerRadius * 0.2) * Math.cos(t.mid);
+            const c2y = cy + (innerRadius * 0.2) * Math.sin(t.mid);
+            const width = Math.max(1, (l.value / maxLink) * maxStroke);
+            this.renderer.path(`M${sx},${sy} C${c1x},${c1y} ${c2x},${c2y} ${tx},${ty}`, 'none', {
+                color: s.color, width,
+            }, {
+                tooltip: `${s.label} ↔ ${t.label}: ${l.value}`,
+            });
+        });
+
+        // Draw node arcs.
+        nodes.forEach(n => {
+            const path = this._arcPath(cx, cy, radius, innerRadius, n.start, n.end);
+            this.renderer.path(path, n.color, { color: '#fff', width: 1 }, {
+                tooltip: `${n.label}: ${n.value}`,
+            });
+
+            // Label outside the circle.
+            const lx = cx + (radius + 16) * Math.cos(n.mid);
+            const ly = cy + (radius + 16) * Math.sin(n.mid);
+            const deg = ((n.mid * 180 / Math.PI) + 90) % 360;
+            const rotate = deg > 90 && deg < 270 ? deg + 180 : deg;
+            this.renderer.text(n.label, lx, ly, {
+                textAnchor: 'middle', fontSize: '10px', fill: '#333',
+                transform: `rotate(${rotate - 90},${lx},${ly})`,
+            });
+        });
+    }
+
+    _arcPath(cx, cy, rOuter, rInner, a0, a1) {
+        const largeArc = (a1 - a0) > Math.PI ? 1 : 0;
+        const o0 = { x: cx + rOuter * Math.cos(a0), y: cy + rOuter * Math.sin(a0) };
+        const o1 = { x: cx + rOuter * Math.cos(a1), y: cy + rOuter * Math.sin(a1) };
+        const i0 = { x: cx + rInner * Math.cos(a1), y: cy + rInner * Math.sin(a1) };
+        const i1 = { x: cx + rInner * Math.cos(a0), y: cy + rInner * Math.sin(a0) };
+        return `M${o0.x},${o0.y} A${rOuter},${rOuter} 0 ${largeArc} 1 ${o1.x},${o1.y} `
+             + `L${i0.x},${i0.y} A${rInner},${rInner} 0 ${largeArc} 0 ${i1.x},${i1.y} Z`;
+    }
+}

package/src/charting/charts/DensityChart.js

@@ -0,0 +1,73 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { Statistics } from '../Statistics.js';
+
+/**
+ * DensityChart — overlaid distribution curves, one Gaussian-KDE curve per
+ * group, sharing one value-axis so shapes are visually comparable. Same
+ * top-level data shape as BoxPlotChart (a caller can hand the identical
+ * dataset to either) and the same multi-series fill+topline+legend rendering
+ * pattern as AreaChart, just with the curve computed from a raw sample
+ * instead of literal category/value points. Y is relative density (curve
+ * shape only) — no meaningful absolute-number axis, so no numeric y-tick
+ * labels.
+ */
+export class DensityChart extends Chart {
+    static chartType = 'density';
+
+    _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,
+            colors, title, xAxisLabel, legend: showLegend = true,
+        } = options;
+        const plotBox = { x, y, width, height };
+        const palette = new ColorPalette(colors);
+
+        // One shared x-domain (pooled bandwidth) so every group's curve
+        // tapers consistently and aligns on the same axis — otherwise a
+        // narrow group would get a different padding amount than a broad
+        // one, purely as an artifact of computing its own domain alone.
+        const allValues = data.flatMap(d => d.values);
+        const dataMin = Math.min(...allValues), dataMax = Math.max(...allValues);
+        const pooledStdev = Statistics.stdev(allValues);
+        const sharedBandwidth = pooledStdev > 0
+            ? 1.06 * pooledStdev * Math.pow(Math.max(allValues.length, 1), -1 / 5)
+            : (dataMax - dataMin) * 0.1 || 1;
+        const domainMin = dataMin - 3 * sharedBandwidth;
+        const domainMax = dataMax + 3 * sharedBandwidth;
+
+        // Each curve still uses its OWN group's Silverman bandwidth (a
+        // group with fewer/noisier points is smoothed differently than one
+        // with many tight points) — only the x-domain/padding is shared.
+        const curves = data.map(d => Statistics.kernelDensityEstimate(d.values, { min: domainMin, max: domainMax }));
+        const maxDensity = Math.max(...curves.flat().map(p => p.density)) || 1;
+        const toX = (v) => x + ((v - domainMin) / (domainMax - domainMin || 1)) * width;
+        const toY = (d) => y + height - (d / maxDensity) * height;
+
+        new ChartLabels({ title, xAxisLabel }).draw(this.renderer, plotBox);
+        this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
+
+        data.forEach((d, i) => {
+            const color = palette.colorAt(i);
+            const topPts = curves[i].map(p => ({ px: toX(p.x), py: toY(p.density) }));
+            const topPath = 'M' + topPts.map(p => `${p.px},${p.py}`).join(' L');
+            const areaPath = topPath + ` L${x + width},${y + height} L${x},${y + height} Z`;
+            const { r, g, b } = ColorPalette.hexToRgb(color);
+            this.renderer.path(areaPath, `rgba(${r},${g},${b},0.25)`, null, { tooltip: d.label });
+            this.renderer.path(topPath, 'none', { color, width: 2 });
+        });
+
+        if (showLegend) {
+            data.forEach((d, i) => {
+                const legendX = x + width + 20;
+                const legendY = y + i * 20;
+                this.renderer.rect(legendX, legendY, 12, 12, palette.colorAt(i), null);
+                this.renderer.text(d.label, legendX + 20, legendY + 6, { fontSize: '12px', fill: '#333' });
+            });
+        }
+    }
+}

package/src/charting/charts/DialGauge.js

@@ -0,0 +1,65 @@
+import { GaugeChart } from './GaugeChart.js';
+import { ArcTrack } from '../gauges/ArcTrack.js';
+
+/**
+ * DialGauge — an arc filled to the value, with a needle pointing at it.
+ *
+ * Data: a value, or several (`[{ value, label?, color? }]`, e.g. actual and
+ * budget): a needle each, the first also filling the arc and labelled in
+ * the middle, and a legend of them all under the title.
+ * Options: cx, cy, r (100, 80, 60), thickness (12), startAngle and sweep in
+ * degrees (135 and 270: bottom-left round to bottom-right), needleColors,
+ * and every GaugeChart option (min, max, bands, target, ticks, segments, ...).
+ */
+export class DialGauge extends GaugeChart {
+    static chartType = 'dialGauge';
+    static LAYOUT = { cx: 100, cy: 80, r: 60, thickness: 12, startAngle: 135, sweep: 270 };
+    static NEEDLE_COLORS = ['#2f3542', '#ff4757', '#1e90ff', '#ffa502'];
+
+    track() { return new ArcTrack(this.layout); }
+
+    /** One per value, the first the main one: {value, label, color}. */
+    get needles() {
+        const { needleColors = DialGauge.NEEDLE_COLORS } = this.options;
+        const values = this.gaugeValue.values.length ? this.gaugeValue.values : [{ value: this.gaugeValue.value }];
+        return values.map((v, i) => ({ ...v, value: this.scale.clamp(v.value), color: v.color ?? needleColors[i % needleColors.length] }));
+    }
+
+    _render() {
+        const { title } = this.options;
+        const track = this.track();
+        const { cx, cy, r } = track;
+
+        this.drawBackground(track, { cap: 'round' });
+        this.drawValue(track, { cap: 'round' });
+        this.drawTarget(track);
+        this.drawTicks(track);
+        const needles = this.needles;
+        // The main needle last, so it is on top.
+        for (const needle of [...needles].reverse()) this.drawNeedle(track, needle);
+        this.renderer.circle(cx, cy, 5, needles[0].color);
+
+        this._renderTitle(title, cx, cy + r + 25, { textAnchor: 'middle', fill: '#747d8c', textTransform: 'uppercase' });
+        this._renderValueLabel(cx, cy + r - 15, { fontSize: '18px', fill: '#2f3542', fontWeight: 'bold' });
+        if (needles.length > 1) this.drawLegend(needles, cx, cy + r + (title ? 42 : 25));
+    }
+
+    /** A needle from the centre to just inside the arc. */
+    drawNeedle(track, { value, color }) {
+        const tip = track.point(this.scale.fraction(value), -8);
+        this.renderer.path(`M${track.cx},${track.cy} L${tip.x},${tip.y}`, 'none', { color, width: 3, cap: 'round' });
+    }
+
+    /** Each needle's label and value on one line, centred. */
+    drawLegend(needles, cx, y) {
+        const text = needles.map((n, i) => `${n.label ?? `#${i + 1}`} ${this.scale.label(n.value)}`);
+        const font = { fontSize: '11px' };
+        const width = (t) => (this.renderer.measureText?.(t, font) ?? t.length * 6) + 22;
+        let x = cx - text.reduce((sum, t) => sum + width(t), 0) / 2;
+        needles.forEach((needle, i) => {
+            this.renderer.circle(x + 4, y, 4, needle.color);
+            this.renderer.text(text[i], x + 12, y, { ...font, textAnchor: 'start', verticalAlign: 'middle', fill: '#2f3542' });
+            x += width(text[i]);
+        });
+    }
+}

package/src/charting/charts/DonutChart.js

@@ -0,0 +1,15 @@
+import { PieChart } from './PieChart.js';
+
+/**
+ * DonutChart — convenience subclass that forces a default inner radius.
+ *
+ * `pieChart` already supports `innerRadiusRatio`; this class exposes the same
+ * chart as a first-class catalog type with a sensible default hole size.
+ */
+export class DonutChart extends PieChart {
+    static chartType = 'donut';
+
+    constructor(renderer, data, options = {}) {
+        super(renderer, data, { innerRadiusRatio: 0.5, ...options });
+    }
+}

package/src/charting/charts/FunnelChart.js

@@ -0,0 +1,47 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * FunnelChart — one horizontal trapezoid band per stage, width proportional to
+ * `value` relative to the largest stage. Each stage's bottom edge width comes
+ * from the next stage's value, so the taper between adjacent bands is continuous.
+ */
+export class FunnelChart extends Chart {
+    static chartType = 'funnel';
+
+    _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,
+            colors, title,
+        } = options;
+        const plotBox = { x, y, width, height };
+        const palette = new ColorPalette(colors || ['#5470c6', '#6690d6', '#79aae4', '#8cc4f0', '#a0dcf6', '#b8eefa', '#d0f5fc']);
+        const maxValue = Math.max(...data.map(d => d.value)) || 1;
+        const stageHeight = height / data.length;
+        const textAnchor = this.renderer.centerTextAnchor;
+
+        new ChartLabels({ title }).draw(this.renderer, plotBox);
+
+        data.forEach((d, i) => {
+            const topWidth = (d.value / maxValue) * width;
+            const nextValue = data[i + 1]?.value ?? d.value;
+            const bottomWidth = (nextValue / maxValue) * width;
+            const top = y + i * stageHeight;
+            const bottom = top + stageHeight;
+            const topLeft = x + (width - topWidth) / 2;
+            const topRight = topLeft + topWidth;
+            const bottomLeft = x + (width - bottomWidth) / 2;
+            const bottomRight = bottomLeft + bottomWidth;
+
+            const path = `M${topLeft},${top} L${topRight},${top} L${bottomRight},${bottom} L${bottomLeft},${bottom} Z`;
+            this.renderer.path(path, palette.colorAt(i), { color: '#fff', width: 1 }, { tooltip: `${d.label}: ${d.value}` });
+            this.renderer.text(`${d.label} (${d.value})`, x + width / 2, top + stageHeight / 2, {
+                textAnchor, verticalAlign: 'middle', fontSize: '12px', fill: '#fff', fontWeight: 'bold',
+            });
+        });
+    }
+}