@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/charts/GanttChart.js

@@ -0,0 +1,201 @@
+import { Chart } from '../Chart.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * GanttChart — horizontal bars on a time axis, one row per task.
+ *
+ * Data: Array<{
+ *   label: string,
+ *   start: string|Date|number,
+ *   end:   string|Date|number,
+ *   progress?: number,      // 0-100 percentage of bar to fill
+ *   category?: string,      // optional grouping / color key
+ *   color?: string,         // explicit bar color
+ * }>
+ *
+ * Options:
+ *   - title
+ *   - barHeight, barGap
+ *   - colors: string[] palette (used per category)
+ *   - axisLabel: label for the time axis
+ *   - dateFormat: 'auto' | 'date' | 'datetime' | 'iso'
+ *   - showProgress: boolean (default true when any task has progress)
+ *   - showToday: boolean (default true) — draw a vertical marker at the current time
+ */
+export class GanttChart extends Chart {
+    static chartType = 'gantt';
+
+    static parseTime(v) {
+        if (v instanceof Date) return v.getTime();
+        if (typeof v === 'number') return v;
+        if (typeof v === 'string') {
+            // Try ISO / date string first.
+            const d = new Date(v);
+            if (!Number.isNaN(d.getTime())) return d.getTime();
+        }
+        return NaN;
+    }
+
+    static formatDate(ts, mode) {
+        const d = new Date(ts);
+        if (mode === 'iso') return d.toISOString().slice(0, 10);
+        if (mode === 'datetime') return d.toISOString().replace('T', ' ').slice(0, 16);
+        if (mode === 'date') return d.toLocaleDateString('en-US', { timeZone: 'UTC' });
+        // Auto: full date if span > 1 day, otherwise include hour.
+        return d.toLocaleDateString('en-US', { timeZone: 'UTC' });
+    }
+
+    _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,
+            barHeight = 24,
+            barGap = 12,
+            colors,
+            axisLabel,
+            dateFormat = 'auto',
+            showProgress,
+            showToday = true,
+        } = options;
+
+        const palette = new ColorPalette(colors);
+        const categories = [...new Set(data.map(d => d.category).filter(Boolean))];
+        const categoryIndex = new Map(categories.map((c, i) => [c, i]));
+
+        const items = data.map(d => {
+            const start = GanttChart.parseTime(d.start);
+            const end = GanttChart.parseTime(d.end);
+            return {
+                label: d.label ?? '',
+                start,
+                end,
+                progress: typeof d.progress === 'number' ? Math.max(0, Math.min(100, d.progress)) : undefined,
+                category: d.category,
+                color: d.color,
+                duration: end - start,
+            };
+        }).filter(d => !Number.isNaN(d.start) && !Number.isNaN(d.end) && d.end >= d.start);
+
+        const allTimes = items.flatMap(d => [d.start, d.end]);
+        if (showToday) allTimes.push(Date.now());
+        const tMin = allTimes.length ? Math.min(...allTimes) : Date.now();
+        const tMax = allTimes.length ? Math.max(...allTimes) : tMin + 86400000;
+        const tRange = Math.max(1, tMax - tMin);
+
+        const textAnchor = this.renderer.centerTextAnchor;
+        const labelColW = Math.min(180, width * 0.22);
+        const plotX = x + labelColW;
+        const plotW = width - labelColW;
+        const plotY = y + (title ? 30 : 0);
+        const plotH = height - (title ? 30 : 0);
+
+        if (title) {
+            this.renderer.text(title, x, y + 12, { textAnchor: 'start', fontSize: '16px', fill: '#333' });
+        }
+
+        const showProg = showProgress ?? items.some(d => d.progress != null);
+
+        const toX = (t) => plotX + ((t - tMin) / tRange) * plotW;
+
+        // Grid lines & time-axis ticks.
+        const ticks = this._ticks(tMin, tMax, 5);
+        ticks.forEach(t => {
+            const tx = toX(t);
+            this.renderer.path(`M${tx},${plotY} L${tx},${plotY + plotH}`, 'none', { color: '#e0e0e0', width: 1 });
+            this.renderer.text(GanttChart.formatDate(t, dateFormat), tx, plotY + plotH + 18, {
+                textAnchor, fontSize: '10px', fill: '#666',
+            });
+        });
+
+        if (axisLabel) {
+            this.renderer.text(axisLabel, plotX + plotW / 2, plotY + plotH + 38, {
+                textAnchor: 'middle', fontSize: '11px', fill: '#666',
+            });
+        }
+
+        // Today marker.
+        if (showToday) {
+            const now = Date.now();
+            if (now >= tMin && now <= tMax) {
+                const tx = toX(now);
+                this.renderer.path(`M${tx},${plotY} L${tx},${plotY + plotH}`, 'none', { color: '#e74c3c', width: 1.5, dasharray: '4 3' });
+                this.renderer.text('Today', tx, plotY - 6, { textAnchor, fontSize: '10px', fill: '#e74c3c' });
+            }
+        }
+
+        // Bars.
+        const contentH = items.length * barHeight + Math.max(0, items.length - 1) * barGap;
+        const startY = plotY + (plotH - contentH) / 2;
+
+        items.forEach((d, i) => {
+            const yRow = startY + i * (barHeight + barGap);
+            const x1 = toX(d.start);
+            const x2 = toX(d.end);
+            const barW = Math.max(2, x2 - x1);
+            const baseColor = d.color ?? (d.category ? palette.colorAt(categoryIndex.get(d.category)) : '#4f8ef7');
+
+            // Background track.
+            this.renderer.rect(x1, yRow, barW, barHeight, '#eef2f7', null, {
+                tooltip: `${d.label}: ${GanttChart.formatDate(d.start, dateFormat)} → ${GanttChart.formatDate(d.end, dateFormat)}`,
+            });
+
+            // Progress fill.
+            if (showProg && d.progress != null) {
+                const progW = barW * (d.progress / 100);
+                this.renderer.rect(x1, yRow, progW, barHeight, baseColor, null, {
+                    tooltip: `${d.label}: ${d.progress}%`,
+                });
+            } else {
+                this.renderer.rect(x1, yRow, barW, barHeight, baseColor, null, {
+                    tooltip: `${d.label}: ${GanttChart.formatDate(d.start, dateFormat)} → ${GanttChart.formatDate(d.end, dateFormat)}`,
+                });
+            }
+
+            // Label in the label column.
+            this.renderer.text(d.label, x + labelColW - 8, yRow + barHeight / 2 + 4, {
+                textAnchor: 'end', fontSize: '11px', fill: '#333',
+            });
+
+            // Duration label inside/near the bar if space permits.
+            if (barW > 40) {
+                const durationDays = Math.round(d.duration / 86400000);
+                const label = durationDays >= 1 ? `${durationDays}d` : `${Math.round(d.duration / 3600000)}h`;
+                this.renderer.text(label, x1 + barW - 6, yRow + barHeight / 2 + 4, {
+                    textAnchor: 'end', fontSize: '9px', fill: ColorPalette.isDark(baseColor) ? '#fff' : '#333',
+                });
+            }
+        });
+
+        // Baseline axis.
+        this.renderer.path(`M${plotX},${plotY + plotH} L${plotX + plotW},${plotY + plotH}`, 'none', { color: '#999', width: 1 });
+    }
+
+    _ticks(tMin, tMax, count) {
+        const span = tMax - tMin;
+        if (span <= 0) return [tMin];
+        // Round to a nice interval.
+        const rough = span / count;
+        const exp = Math.floor(Math.log10(rough));
+        const frac = rough / Math.pow(10, exp);
+        let step;
+        if (frac <= 1) step = Math.pow(10, exp);
+        else if (frac <= 2) step = 2 * Math.pow(10, exp);
+        else if (frac <= 5) step = 5 * Math.pow(10, exp);
+        else step = 10 * Math.pow(10, exp);
+
+        const start = Math.ceil(tMin / step) * step;
+        const ticks = [];
+        for (let t = start; t <= tMax; t += step) {
+            ticks.push(t);
+        }
+        if (ticks.length === 0) ticks.push(tMin);
+        return ticks;
+    }
+}

package/src/charting/charts/GaugeChart.js

@@ -0,0 +1,175 @@
+import { Chart } from '../Chart.js';
+import { Gauge } from '../Gauge.js';
+import { GaugeScale } from '../gauges/GaugeScale.js';
+import { GaugeBands } from '../gauges/GaugeBands.js';
+import { GaugeValue } from '../gauges/GaugeValue.js';
+
+/**
+ * GaugeChart — abstract base for gauges: one value shown along a track.
+ *
+ * It reads what every gauge has in common from its data and options (a
+ * `GaugeScale`, `GaugeBands`, a `GaugeValue`) and draws the parts every gauge
+ * has on the subclass's `track()`: the background or the bands, the value, a
+ * target marker, ticks and the labels. A subclass picks the track and its
+ * layout, and adds its own parts (the dial's needle).
+ *
+ * Options every gauge takes:
+ *   min, max (0, 100), format, units  — the scale (see GaugeScale)
+ *   bands: [{to, color?, label?}]     — ranges drawn behind the value; the value takes its band's colour
+ *   bandColors: string[]              — colours for bands without their own
+ *   color                             — the value's colour: one, a gradient array, or (percent) => colour
+ *   target                            — a marker at a value (or data.target)
+ *   targetColor ('#333')
+ *   ticks: number                     — that many equal steps, marked and labelled
+ *   segments: number, segmentGap (2)  — the track as that many blocks (LED style), lit up to the value;
+ *                                       with bands, each lit block takes its own band's colour
+ *   title
+ */
+export class GaugeChart extends Chart {
+    /** The value's colour when neither `color` nor a band gives one. */
+    static defaultColor = '#5352ed';
+
+    /** The track behind the value when there are no bands. */
+    static trackColor = '#f1f2f6';
+
+    /** Where and how big this type draws when the options don't say (cx, cy, r, ...). */
+    static LAYOUT = {};
+
+    /** The layout: the options' values for this type's LAYOUT keys, over its own. */
+    get layout() {
+        const layout = { ...this.constructor.LAYOUT };
+        for (const key of Object.keys(layout)) if (this.options[key] != null) layout[key] = this.options[key];
+        return layout;
+    }
+
+    get scale() {
+        const { min, max, format, units } = this.options;
+        return (this._scale ??= new GaugeScale({ min, max, format: format ?? this.defaultFormat(), units }));
+    }
+
+    get bands() {
+        // `ranges` and `rangeColors`: the bullet graph's older names for them.
+        const { bands, ranges, bandColors = this.options.rangeColors } = this.options;
+        return (this._bands ??= new GaugeBands(bands ?? ranges ?? this.defaultBands(), this.scale, bandColors ? { colors: bandColors } : {}));
+    }
+
+    get gaugeValue() { return (this._value ??= GaugeValue.from(this.data, this.options)); }
+
+    /** The value, held to the scale. */
+    get value() { return this.scale.clamp(this.gaugeValue.value); }
+
+    /** A format this gauge type reads its numbers with when none is given (null: the scale's). */
+    defaultFormat() { return null; }
+
+    /** Bands this gauge type draws when none are given. */
+    defaultBands() { return []; }
+
+    /** The track the value moves along. Subclasses implement. @returns {import('../gauges/GaugeTrack.js').GaugeTrack} */
+    track() { throw new Error(`${this.constructor.name} must implement track()`); }
+
+    /** The value's colour: the `color` option, else its band's, else the type's own. */
+    valueColor(value = this.value) {
+        const { color } = this.options;
+        if (color != null) return Gauge.resolveColor(color, this.scale.fraction(value) * 100);
+        return this.bands.at(value)?.color ?? this.constructor.defaultColor;
+    }
+
+    /**
+     * With `segments`, the track as that many blocks a `segmentGap` (pixels)
+     * apart: [{from, to, mid}] as fractions; null without (fewer than 2).
+     */
+    segmentsOf(track) {
+        const n = Math.round(this.options.segments ?? 0);
+        if (n < 2) return null;
+        const gap = Math.min((this.options.segmentGap ?? 2) / (track.length || 1), 0.5 / n);
+        return Array.from({ length: n }, (_, i) => ({ from: i / n + gap / 2, to: (i + 1) / n - gap / 2, mid: (i + 0.5) / n }));
+    }
+
+    /** The bands, lighter, along the whole track; or the plain track without any. */
+    drawBackground(track, options = {}) {
+        const blocks = this.segmentsOf(track);
+        if (blocks) {
+            for (const block of blocks) {
+                const band = this.bands.at(this.scale.valueAt(block.mid));
+                track.draw(this.renderer, block.from, block.to, band ? GaugeBands.tint(band.color) : this.constructor.trackColor, { ...options, cap: undefined });
+            }
+            return;
+        }
+        if (!this.bands.length) {
+            track.draw(this.renderer, 0, 1, this.constructor.trackColor, options);
+            return;
+        }
+        for (const band of this.bands.list) {
+            track.draw(this.renderer, this.scale.fraction(band.from), this.scale.fraction(band.to), GaugeBands.tint(band.color), { ...options, cap: undefined });
+        }
+    }
+
+    /**
+     * A value: the track from the scale's start to it. This gauge's value and
+     * scale unless given (a gauge of several values draws each on its own).
+     */
+    drawValue(track, { value = this.value, scale = this.scale, color, ...options } = {}) {
+        const blocks = this.segmentsOf(track);
+        if (!blocks) {
+            track.draw(this.renderer, 0, scale.fraction(value), color ?? this.valueColor(value), options);
+            return;
+        }
+        // The blocks up to the value are lit: each in its band's colour (a level meter), unless a colour is given.
+        const lit = Math.round(scale.fraction(value) * blocks.length);
+        const own = color ?? (this.options.color != null || !this.bands.length ? this.valueColor(value) : null);
+        for (const block of blocks.slice(0, lit)) {
+            const blockColor = own ?? this.bands.at(scale.valueAt(block.mid))?.color ?? this.constructor.defaultColor;
+            track.draw(this.renderer, block.from, block.to, blockColor, { ...options, cap: undefined });
+        }
+    }
+
+    /** A line across the track at the target, a little past both edges. */
+    drawTarget(track, { overhang = 3, width = 2 } = {}) {
+        const { target } = this.gaugeValue;
+        if (target == null) return;
+        const half = track.thickness / 2 + overhang;
+        track.line(this.renderer, this.scale.fraction(target), -half, half, { color: this.options.targetColor ?? '#333', width });
+    }
+
+    /** `ticks` marks outside the track, each labelled with its value. */
+    drawTicks(track) {
+        const { ticks } = this.options;
+        if (!ticks) return;
+        const count = Math.max(1, Math.round(ticks));
+        const edge = track.thickness / 2;
+        for (const value of this.scale.ticks(count)) {
+            const f = this.scale.fraction(value);
+            track.line(this.renderer, f, edge + 2, edge + 6, { color: '#999', width: 1 });
+            const at = track.point(f, edge + 14);
+            this.renderer.text(this.scale.tickLabel(value, count), at.x, at.y, {
+                textAnchor: track.anchorAt(f), verticalAlign: 'middle', fontSize: '10px', fill: '#747d8c',
+            });
+        }
+    }
+
+    /** Draw a gauge title. */
+    _renderTitle(title, x, y, options = {}) {
+        if (!title) return;
+        this.renderer.text(title, x, y, {
+            textAnchor: options.textAnchor || 'start',
+            fontSize: options.fontSize || '10px',
+            fill: options.fill || '#333',
+            ...options,
+        });
+    }
+
+    /** Draw the value's label, centred at a point. */
+    _renderValueLabel(x, y, options = {}) {
+        this.renderer.text(this.scale.label(this.value), x, y, {
+            textAnchor: options.textAnchor || 'middle',
+            verticalAlign: options.verticalAlign || 'middle',
+            fontSize: options.fontSize || '12px',
+            fill: options.fill || '#fff',
+            ...options,
+        });
+    }
+
+    _render() {
+        throw new Error(`${this.constructor.name} must implement _render()`);
+    }
+}

package/src/charting/charts/GeoMapChart.js

@@ -0,0 +1,146 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * GeoMapChart — simple equirectangular-projection map for choropleth fills
+ * and bubble markers. No external dependencies; the caller supplies the
+ * GeoJSON-like feature collection.
+ *
+ * Data:
+ *   {
+ *     features: Array<{
+ *       id, name, value?, color?,
+ *       geometry: { type: 'Polygon'|'MultiPolygon', coordinates: number[][][][] }
+ *     }>,
+ *     bubbles?: Array<{ lat, lon, value, label?, color?, radius? }>
+ *   }
+ *
+ * Options:
+ *   - center: [lon, lat] — default [0, 20]
+ *   - scale: number — pixels per degree; auto-fitted if omitted
+ *   - colorScale: string[] — gradient stops for choropleth values
+ *   - bubbleMaxRadius: number — max bubble radius (default 20)
+ *   - bubbleColor: string — default bubble fill
+ *   - title
+ */
+export class GeoMapChart extends Chart {
+    static chartType = 'geoMap';
+
+    static DEFAULT_COLOR_SCALE = ['#e0f3f8', '#abd9e9', '#74add1', '#4575b4', '#313695'];
+
+    _render() {
+        const data = this.data || {};
+        const options = this.options || {};
+        const box = ChartBox.fromRenderer(this.renderer, { left: 40, top: 50, right: 40, bottom: 50 });
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            title,
+            center: [centerLon = 0, centerLat = 20] = [],
+            scale: explicitScale,
+            colorScale = GeoMapChart.DEFAULT_COLOR_SCALE,
+            bubbleMaxRadius = 20,
+            bubbleColor = '#e74c3c',
+        } = options;
+        const features = data.features || [];
+        const bubbles = data.bubbles || [];
+
+        new ChartLabels({ title }).draw(this.renderer, { x, y, width, height });
+
+        const scale = explicitScale || this._fitScale(features, width, height, centerLon, centerLat);
+        const cx = x + width / 2;
+        const cy = y + height / 2;
+        const project = (lon, lat) => ({
+            x: cx + (lon - centerLon) * scale,
+            y: cy - (lat - centerLat) * scale,
+        });
+
+        const valueRange = this._valueRange(features);
+        const palette = new ColorPalette(colorScale);
+
+        features.forEach(f => {
+            const pathData = this._featurePath(f.geometry, project);
+            if (!pathData) return;
+            const fill = f.color || this._choroplethColor(f.value, valueRange, palette);
+            this.renderer.path(pathData, fill, { color: '#fff', width: 1 }, {
+                tooltip: f.name || f.id || '',
+            });
+        });
+
+        if (bubbles.length) {
+            const bubbleValues = bubbles.map(b => b.value).filter(v => v != null && !Number.isNaN(v));
+            const maxBubbleValue = bubbleValues.length ? Math.max(...bubbleValues) : 1;
+            bubbles.forEach(b => {
+                const p = project(b.lon, b.lat);
+                const r = b.radius || (b.value != null ? Math.max(3, (b.value / maxBubbleValue) * bubbleMaxRadius) : 5);
+                this.renderer.circle(p.x, p.y, r, b.color || bubbleColor, { color: '#fff', width: 1 }, {
+                    tooltip: b.label ? `${b.label}: ${b.value ?? ''}` : String(b.value ?? ''),
+                });
+            });
+        }
+    }
+
+    _featurePath(geometry, project) {
+        if (!geometry) return '';
+        const rings = geometry.type === 'Polygon'
+            ? [geometry.coordinates]
+            : geometry.type === 'MultiPolygon'
+                ? geometry.coordinates
+                : [];
+        if (!rings.length) return '';
+
+        let d = '';
+        rings.forEach(polygon => {
+            polygon.forEach(ring => {
+                ring.forEach(([lon, lat], i) => {
+                    const p = project(lon, lat);
+                    d += `${i === 0 ? 'M' : 'L'}${p.x},${p.y} `;
+                });
+                d += 'Z ';
+            });
+        });
+        return d.trim();
+    }
+
+    _fitScale(features, width, height, centerLon, centerLat) {
+        const lons = [];
+        const lats = [];
+        features.forEach(f => this._walkCoordinates(f.geometry, (lon, lat) => {
+            lons.push(lon);
+            lats.push(lat);
+        }));
+        if (!lons.length) return 4;
+        const lonRange = Math.max(1, Math.max(...lons) - Math.min(...lons));
+        const latRange = Math.max(1, Math.max(...lats) - Math.min(...lats));
+        return Math.min(width / lonRange, height / latRange) * 0.9;
+    }
+
+    _walkCoordinates(geometry, cb) {
+        if (!geometry) return;
+        const rings = geometry.type === 'Polygon'
+            ? [geometry.coordinates]
+            : geometry.type === 'MultiPolygon'
+                ? geometry.coordinates
+                : [];
+        rings.forEach(polygon => {
+            polygon.forEach(ring => {
+                ring.forEach(([lon, lat]) => cb(lon, lat));
+            });
+        });
+    }
+
+    _valueRange(features) {
+        const values = features.map(f => f.value).filter(v => v != null && !Number.isNaN(v));
+        return {
+            min: values.length ? Math.min(...values) : 0,
+            max: values.length ? Math.max(...values) : 1,
+        };
+    }
+
+    _choroplethColor(value, range, palette) {
+        if (value == null || range.max === range.min) return palette.colorAt(0);
+        const t = (value - range.min) / (range.max - range.min);
+        const index = Math.min(palette.colors.length - 1, Math.floor(t * palette.colors.length));
+        return palette.colorAt(index);
+    }
+}

package/src/charting/charts/GroupedBarChart.js

@@ -0,0 +1,88 @@
+import { Legend } from '../Legend.js';
+import { BarChartBase } from './BarChartBase.js';
+
+/**
+ * GroupedBarChart — vertical grouped (multi-set) bar chart.
+ *
+ * Data shape:
+ *   Array<{name: string, values: Array<{label: string, value: number}>}>
+ *
+ * Each category (`label`) gets a cluster of bars side-by-side, one per series.
+ */
+export class GroupedBarChart extends BarChartBase {
+    static chartType = 'groupedBar';
+
+    _computeMaxValue() {
+        const series = this.data;
+        const rawMax = Math.max(
+            ...series.flatMap(s => s.values.map(v => v.value)),
+            1,
+        );
+        return this._drawYAxis(rawMax);
+    }
+
+    _renderBars(maxValue) {
+        const series = this.data;
+        const options = this.options;
+        const { x, y, width, height } = this._plotBox;
+        const {
+            groupPadding = 0.2, barPadding = 0.05,
+        } = options;
+        const seriesCount = series.length;
+        const labels = [...new Set(series.flatMap(s => s.values.map(v => v.label)))];
+        const categoryCount = labels.length;
+
+        // Build a value lookup so missing labels per series render as 0.
+        const valueBySeriesLabel = series.map(s => {
+            const map = new Map();
+            for (const v of s.values) map.set(v.label, v.value);
+            return map;
+        });
+
+        const clusterWidth = width / categoryCount;
+        const groupGap = clusterWidth * groupPadding;
+        const availableWidth = clusterWidth - groupGap;
+        const barWidth = availableWidth / seriesCount;
+        const barGap = barWidth * barPadding;
+        const finalBarWidth = barWidth - barGap;
+
+        const textAnchor = this.renderer.centerTextAnchor;
+
+        labels.forEach((label, categoryIndex) => {
+            const clusterX = x + categoryIndex * clusterWidth + groupGap / 2;
+
+            series.forEach((seriesData, seriesIndex) => {
+                const value = valueBySeriesLabel[seriesIndex].get(label) ?? 0;
+                const barHeight = (value / maxValue) * height;
+                const barX = clusterX + seriesIndex * barWidth + barGap / 2;
+                const barY = y + height - barHeight;
+                const color = this._palette.colorAt(seriesIndex);
+
+                this.renderer.rect(barX, barY, finalBarWidth, barHeight, color, null, {
+                    tooltip: `${seriesData.name} — ${label}: ${value}`,
+                });
+            });
+
+            this.renderer.text(label, clusterX + availableWidth / 2, y + height + 20, { textAnchor });
+        });
+    }
+
+    _afterBars() {
+        const series = this.data;
+        const options = this.options;
+        const { x, y, width } = this._plotBox;
+        const { legend: showLegend = false } = options;
+
+        if (showLegend) {
+            const legendItems = series.map((s, i) => ({
+                label: s.name,
+                color: this._palette.colorAt(i),
+                dataIndex: i,
+            }));
+            new Legend({
+                items: legendItems, x: x + width + 20, y,
+                itemHeight: 20, markerSize: 10,
+            }).draw(this.renderer);
+        }
+    }
+}

package/src/charting/charts/GroupedDistributionChart.js

@@ -0,0 +1,70 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+
+/**
+ * GroupedDistributionChart — abstract base for charts that draw one glyph per
+ * grouped numeric sample (`{label, values: number[]}`).
+ *
+ * Owns the cartesian setup, shared value-domain computation, slot layout, and
+ * x-axis label drawing. Subclasses implement `_renderGlyph(cx, slotWidth, i, d)`.
+ */
+export class GroupedDistributionChart extends Chart {
+    _setup() {
+        const box = ChartBox.fromRenderer(this.renderer);
+        const options = this.options;
+        const {
+            x = box.x, y = box.y, width = box.width, height = box.height,
+            colors, title, xAxisLabel, yAxisLabel,
+        } = options;
+        this._plotBox = { x, y, width, height };
+        this._palette = new ColorPalette(colors);
+        new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, this._plotBox);
+    }
+
+    _computeDomain() {
+        const data = this.data;
+        const allVals = data.flatMap(d => d.values);
+        const vMax = Math.max(...allVals);
+        const vMin = Math.min(...allVals);
+        const range = (vMax - vMin) || 1;
+        return { vMin, vMax, range };
+    }
+
+    _toY(v) {
+        const { y, height } = this._plotBox;
+        return y + height - ((v - this._domain.vMin) / this._domain.range) * height;
+    }
+
+    _slotWidth() {
+        return this._plotBox.width / this.data.length;
+    }
+
+    _drawBaseAxis() {
+        const { x, y, width, height } = this._plotBox;
+        this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
+    }
+
+    _drawXAxisLabel(cx, label) {
+        const { y, height } = this._plotBox;
+        this.renderer.text(label, cx, y + height + 20, { textAnchor: this.renderer.centerTextAnchor, fontSize: '10px' });
+    }
+
+    _render() {
+        this._setup();
+        this._domain = this._computeDomain();
+        this._drawBaseAxis();
+        const slotWidth = this._slotWidth();
+        const data = this.data;
+        data.forEach((d, i) => {
+            const cx = this._plotBox.x + i * slotWidth + slotWidth / 2;
+            this._renderGlyph(cx, slotWidth, i, d);
+            this._drawXAxisLabel(cx, d.label);
+        });
+    }
+
+    /** @abstract */
+    _renderGlyph(cx, slotWidth, i, d) {
+        throw new Error(`${this.constructor.name} must implement _renderGlyph()`);
+    }
+}