@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/charts/ParallelCoordinatesChart.js

@@ -0,0 +1,130 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { Legend } from '../Legend.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * ParallelCoordinatesChart — each dimension gets its own vertical axis, and
+ * every data row becomes a polyline connecting its values across the axes.
+ *
+ * Data: Array<{label?, category?, [dim: number]}>
+ * Options:
+ *   - dimensions: string[] — which numeric fields to plot, in order. If
+ *     omitted, all numeric fields except 'label' and 'category' are used.
+ *   - colors: string[] — palette for categories (or all lines if no category).
+ *   - lineWidth, lineOpacity
+ *   - title, xAxisLabel, yAxisLabel
+ *   - showAxes (default true), showLegend (default true when categories exist)
+ */
+export class ParallelCoordinatesChart extends Chart {
+    static chartType = 'parallelCoordinates';
+
+    _render() {
+        const data = this.data || [];
+        const options = this.options || {};
+        const box = ChartBox.fromRenderer(this.renderer, { left: 60, top: 50, right: 100, bottom: 60 });
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            title, xAxisLabel, yAxisLabel,
+            dimensions: explicitDimensions,
+            colors, lineWidth = 1.5, lineOpacity = 0.6,
+            showAxes = true, showLegend,
+        } = options;
+        const plotBox = { x, y, width, height };
+
+        const dimensions = explicitDimensions && explicitDimensions.length
+            ? explicitDimensions
+            : this._inferDimensions(data);
+        if (dimensions.length < 2) return;
+
+        const scales = this._computeScales(data, dimensions);
+        const hasCategories = data.some(d => d.category != null);
+        const legendVisible = showLegend != null ? showLegend : hasCategories;
+        const palette = new ColorPalette(colors);
+        const categories = hasCategories
+            ? [...new Set(data.map(d => d.category).filter(c => c != null))]
+            : [];
+        const categoryColor = (category) => palette.colorAt(categories.indexOf(category));
+
+        new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, plotBox);
+
+        const axisXs = dimensions.map((_, i) =>
+            dimensions.length === 1 ? x + width / 2 : x + (i * width) / (dimensions.length - 1)
+        );
+
+        if (showAxes) {
+            dimensions.forEach((dim, i) => {
+                const ax = axisXs[i];
+                this.renderer.path(`M${ax},${y} L${ax},${y + height}`, 'none', { color: '#ccc', width: 1 });
+                const { min, max } = scales[dim];
+                this.renderer.text(dim, ax, y + height + 25, { textAnchor: 'middle', fontSize: '12px', fill: '#333' });
+                this.renderer.text(this._fmt(min), ax, y + height + 10, { textAnchor: 'middle', fontSize: '10px', fill: '#666' });
+                this.renderer.text(this._fmt(max), ax, y - 6, { textAnchor: 'middle', fontSize: '10px', fill: '#666' });
+            });
+        }
+
+        data.forEach((row, rowIndex) => {
+            const pts = [];
+            let valid = true;
+            dimensions.forEach((dim, i) => {
+                const v = row[dim];
+                if (v == null || Number.isNaN(v)) {
+                    valid = false;
+                    return;
+                }
+                const { min, max } = scales[dim];
+                const t = max === min ? 0.5 : (v - min) / (max - min);
+                const py = y + height - t * height;
+                pts.push({ x: axisXs[i], y: py });
+            });
+            if (!valid || pts.length < 2) return;
+
+            const color = hasCategories ? categoryColor(row.category) : palette.colorAt(rowIndex);
+            let pathData = '';
+            pts.forEach((p, i) => {
+                pathData += `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`;
+            });
+            const label = row.label || (hasCategories ? row.category : null);
+            this.renderer.path(pathData, 'none', {
+                color, width: lineWidth,
+                opacity: lineOpacity,
+                tooltip: label ? `${label}: ${dimensions.map(d => `${d}=${this._fmt(row[d])}`).join(', ')}` : undefined,
+            });
+        });
+
+        if (legendVisible && hasCategories) {
+            const legendItems = categories.map((c, i) => ({ name: c, color: palette.colorAt(i) }));
+            new Legend({
+                items: legendItems, x: x + width + 20, y,
+                itemHeight: 20, markerSize: 12,
+            }).draw(this.renderer);
+        }
+    }
+
+    _inferDimensions(data) {
+        const dims = new Set();
+        data.forEach(row => {
+            Object.keys(row).forEach(key => {
+                if (key === 'label' || key === 'category') return;
+                if (typeof row[key] === 'number') dims.add(key);
+            });
+        });
+        return [...dims];
+    }
+
+    _computeScales(data, dimensions) {
+        const scales = {};
+        dimensions.forEach(dim => {
+            const values = data.map(d => d[dim]).filter(v => v != null && !Number.isNaN(v));
+            const min = values.length ? Math.min(...values) : 0;
+            const max = values.length ? Math.max(...values) : 1;
+            scales[dim] = { min, max };
+        });
+        return scales;
+    }
+
+    _fmt(v) {
+        if (Math.abs(v) >= 1000) return `${(v / 1000).toFixed(1)}k`;
+        return Number.isInteger(v) ? String(v) : v.toFixed(2);
+    }
+}

package/src/charting/charts/PieChart.js

@@ -0,0 +1,56 @@
+import { Chart } from '../Chart.js';
+import { Legend } from '../Legend.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { ShapePaths } from '../ShapePaths.js';
+
+/**
+ * PieChart — pie or doughnut chart with optional legend.
+ */
+export class PieChart extends Chart {
+    static chartType = 'pie';
+
+    _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 - 60,
+            innerRadiusRatio = 0,
+            colors, legend: showLegend = true, title,
+        } = options;
+        const palette = new ColorPalette(colors);
+        const total = data.reduce((s, d) => s + d.value, 0) || 1;
+        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.renderer.path(path, color, { color: '#fff', width: 1 }, {
+                tooltip: `${d.label}: ${d.value} (${(d.value / total * 100).toFixed(1)}%)`,
+            });
+            angle += slice;
+        });
+
+        if (showLegend) {
+            const legendItems = data.map((d, i) => ({
+                label: `${d.label} (${(d.value / total * 100).toFixed(0)}%)`,
+                color: palette.colorAt(i),
+            }));
+            new Legend({
+                items: legendItems,
+                x: cx + radius + 30,
+                y: cy - radius,
+                itemHeight: 20,
+                markerSize: 12,
+            }).draw(this.renderer);
+        }
+    }
+}

package/src/charting/charts/PipeChart.js

@@ -0,0 +1,88 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * PipeChart — tapering ribbon / pipe chart with optional multi-series legend.
+ */
+export class PipeChart extends Chart {
+    static chartType = 'pipe';
+
+    _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,
+            metricCol = 'metric', minWidth = 4, maxWidth = 28,
+            colors, title, xAxisLabel, yAxisLabel, legend: showLegend = false,
+        } = options;
+
+        const plotBox = { x, y, width, height };
+        const isMultiline = Array.isArray(data[0]?.values);
+        const series = isMultiline ? data : [{ name: 'default', values: data }];
+        const allPoints = series.flatMap(s => s.values);
+        const maxValue = Math.max(...allPoints.map(d => d.value));
+        const maxMetric = Math.max(...allPoints.map(d => d[metricCol] ?? 0)) || 1;
+        const pointCount = series[0].values.length;
+        const pointMargin = pointCount > 1 ? width / (pointCount - 1) : width;
+
+        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 });
+
+        const palette = new ColorPalette(colors);
+
+        series.forEach((s, seriesIndex) => {
+            const color = palette.colorAt(seriesIndex);
+            const pts = s.values.map((d, i) => ({
+                x: x + i * pointMargin,
+                y: y + height - (d.value / maxValue) * height,
+                w: minWidth + ((d[metricCol] ?? 0) / maxMetric) * (maxWidth - minWidth),
+                d,
+            }));
+
+            // Local direction at each point = average of incoming/outgoing
+            // segment vectors (endpoints just use their one available
+            // segment) — simple smoothing so the ribbon doesn't kink where
+            // width changes between neighboring points.
+            const dirs = pts.map((p, i) => {
+                const prev = pts[i - 1], next = pts[i + 1];
+                const dx = (next ? next.x : p.x) - (prev ? prev.x : p.x);
+                const dy = (next ? next.y : p.y) - (prev ? prev.y : p.y);
+                const len = Math.sqrt(dx * dx + dy * dy) || 1;
+                return { nx: -dy / len, ny: dx / len };
+            });
+
+            const upper = pts.map((p, i) => ({ x: p.x + dirs[i].nx * p.w / 2, y: p.y + dirs[i].ny * p.w / 2 }));
+            const lower = pts.map((p, i) => ({ x: p.x - dirs[i].nx * p.w / 2, y: p.y - dirs[i].ny * p.w / 2 }));
+
+            const ribbonPath = 'M' + upper.map(p => `${p.x},${p.y}`).join(' L')
+                + ' L' + [...lower].reverse().map(p => `${p.x},${p.y}`).join(' L') + ' Z';
+            // Partial opacity so overlapping pipes in a multi-series chart stay legible.
+            const { r, g, b } = palette.hexToRgb(color);
+            this.renderer.path(ribbonPath, `rgba(${r},${g},${b},0.55)`, null);
+            // Thin centerline for readability, especially useful with a single pipe.
+            const centerline = 'M' + pts.map(p => `${p.x},${p.y}`).join(' L');
+            this.renderer.path(centerline, 'none', { color: palette.lighten(color, -0.25), width: 1 });
+
+            pts.forEach(p => {
+                this.renderer.circle(p.x, p.y, 2, '#fff', { color, width: 1.5 },
+                    { tooltip: `${isMultiline ? s.name + ': ' : ''}${p.d.label}: ${p.d.value} (${metricCol}: ${p.d[metricCol] ?? 0})` });
+            });
+
+            if (seriesIndex === 0) {
+                const textAnchor = this.renderer.centerTextAnchor;
+                pts.forEach(p => this.renderer.text(p.d.label, p.x, y + height + 20, { textAnchor }));
+            }
+        });
+
+        if (isMultiline && showLegend) {
+            series.forEach((s, 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(s.name, legendX + 20, legendY + 6, { fontSize: '12px', fill: '#333' });
+            });
+        }
+    }
+}

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/RingGauge.js

@@ -0,0 +1,23 @@
+import { ArcGauge } from './ArcGauge.js';
+
+/**
+ * RingGauge — a progress ring: a whole circle filled clockwise from the top
+ * to the value, its number in the middle.
+ *
+ * Options as ArcGauge's, drawn as a ring: cx, cy, r (100, 100, 60),
+ * thickness (14), startAngle (-90, the top) and sweep (360).
+ */
+export class RingGauge extends ArcGauge {
+    static chartType = 'ringGauge';
+    static LAYOUT = { cx: 100, cy: 100, r: 60, thickness: 14, startAngle: -90, sweep: 360 };
+
+    /** The number in the very middle. */
+    drawLabels(track) {
+        this._renderValueLabel(track.cx, track.cy, { fontSize: `${Math.max(12, Math.round(track.r * 0.36))}px`, fill: '#2f3542', fontWeight: 'bold' });
+    }
+
+    /** A ring's two ends are one point: no end labels. */
+    drawEnds() {}
+
+    titleY(track) { return track.cy + track.r + track.thickness / 2 + 18; }
+}