@peter.prib/renderengine 0.0.0-stage → 0.1.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,47 @@
+import { Chart } from '../Chart.js';
+import { Gauge } from '../Gauge.js';
+
+/**
+ * GaugeChart — abstract base for 0-100 percentage gauges.
+ *
+ * Subclasses implement `_renderGauge()` and use the shared normalization,
+ * color resolution, title, and percentage-label helpers.
+ */
+export class GaugeChart extends Chart {
+    /** Normalize data to a 0-100 percentage. */
+    _normalizePercent() {
+        const value = Number(this.data);
+        return Math.min(Math.max(value, 0), 100);
+    }
+
+    /** Resolve the gauge color for the current percentage. */
+    _resolveColor(color, percent) {
+        return Gauge.resolveColor(color, percent);
+    }
+
+    /** 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 a centered percentage label. */
+    _renderPercentageLabel(percent, x, y, options = {}) {
+        this.renderer.text(`${percent.toFixed(1)}%`, 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()`);
+    }
+}

package/src/charting/charts/HeatmapChart.js

@@ -0,0 +1,80 @@
+import { Chart } from '../Chart.js';
+import { ChartBox } from '../ChartBox.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { Axis } from '../Axis.js';
+
+/**
+ * HeatmapChart — a grid of cells, one per (x, y) category pair, shaded by
+ * `value` along a low→high color scale.
+ */
+export class HeatmapChart extends Chart {
+    static chartType = 'heatmap';
+
+    _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,
+            xLabels, yLabels, colorScale = ['#f7fbff', '#4292c6', '#08306b'],
+            showValues = false, title,
+        } = options;
+
+        // Grid cost is xCats.length * yCats.length, NOT data.length — a row
+        // count that's perfectly reasonable elsewhere (say, 100) can still
+        // blow this up if x/y happen to be high-cardinality columns (an ID,
+        // a timestamp): up to 100*100 = 10,000 rect()+text() calls in one
+        // uninterrupted double loop, a genuine multi-second synchronous
+        // freeze confirmed in practice. Capped independently of any
+        // caller-side row limit, since THIS is what actually scales.
+        const MAX_HEATMAP_CATS = 50;
+        const xCatsAll = xLabels || [...new Set(data.map(d => d.x))];
+        const yCatsAll = yLabels || [...new Set(data.map(d => d.y))];
+        const xCats = xCatsAll.slice(0, MAX_HEATMAP_CATS);
+        const yCats = yCatsAll.slice(0, MAX_HEATMAP_CATS);
+        const catsTruncated = xCats.length < xCatsAll.length || yCats.length < yCatsAll.length;
+        const xCatSet = catsTruncated ? new Set(xCats) : null;
+        const yCatSet = catsTruncated ? new Set(yCats) : null;
+        const values = (catsTruncated ? data.filter(d => xCatSet.has(d.x) && yCatSet.has(d.y)) : data)
+            .map(d => d.value);
+        const vMin = Math.min(...values);
+        const vMax = Math.max(...values);
+        const cellW = width / xCats.length;
+        const cellH = height / yCats.length;
+        const textAnchor = this.renderer.centerTextAnchor;
+
+        if (title) this.renderer.text(title, x + width / 2, y - 30, { textAnchor: 'middle', fontSize: '18px', fill: '#333' });
+
+        const cellByKey = new Map(data.map(d => [`${d.x}|${d.y}`, d.value]));
+        yCats.forEach((yc, yi) => {
+            xCats.forEach((xc, xi) => {
+                const v = cellByKey.get(`${xc}|${yc}`);
+                const cellX = x + xi * cellW;
+                const cellY = y + yi * cellH;
+                const color = v == null ? '#eee' : ColorPalette.scaleColor(colorScale, vMin, vMax, v);
+                this.renderer.rect(cellX, cellY, Math.max(1, cellW - 1), Math.max(1, cellH - 1), color, null, {
+                    tooltip: `${xc} / ${yc}: ${v ?? 'n/a'}`,
+                });
+                if (showValues && v != null) {
+                    this.renderer.text(Axis.formatValue(v), cellX + cellW / 2, cellY + cellH / 2, {
+                        textAnchor, verticalAlign: 'middle', fontSize: '10px', fill: ColorPalette.isDark(color) ? '#fff' : '#333',
+                    });
+                }
+            });
+        });
+
+        xCats.forEach((xc, xi) => {
+            this.renderer.text(xc, x + xi * cellW + cellW / 2, y + height + 16, { textAnchor, fontSize: '10px' });
+        });
+        yCats.forEach((yc, yi) => {
+            this.renderer.text(yc, x - 8, y + yi * cellH + cellH / 2, { textAnchor: 'end', verticalAlign: 'middle', fontSize: '10px' });
+        });
+
+        if (catsTruncated) {
+            this.renderer.text(
+                `Showing ${xCats.length}×${yCats.length} of ${xCatsAll.length}×${yCatsAll.length} categories — pick lower-cardinality X/Y fields to see the rest`,
+                x + width / 2, y + height + 32, { textAnchor: 'middle', fontSize: '10px', fill: '#c0392b' },
+            );
+        }
+    }
+}

package/src/charting/charts/HierarchyChart.js

@@ -0,0 +1,39 @@
+import { Chart } from '../Chart.js';
+import { ColorPalette } from '../ColorPalette.js';
+import { Axis } from '../Axis.js';
+import { Hierarchy } from '../Hierarchy.js';
+
+/**
+ * HierarchyChart — abstract base for charts that render a hierarchy of nodes.
+ *
+ * Owns top-level palette assignment, per-depth color lightening, text-color
+ * contrast, and value formatting so subclasses stay focused on layout/rendering.
+ */
+export class HierarchyChart extends Chart {
+    _palette() {
+        if (!this._paletteInstance) {
+            this._paletteInstance = new ColorPalette(this.options.colors);
+        }
+        return this._paletteInstance;
+    }
+
+    _topLevelColor() {
+        if (!this._topLevelColorMap) {
+            this._topLevelColorMap = new Map(this.data.map((n, i) => [n, this._palette().colorAt(i)]));
+        }
+        return this._topLevelColorMap;
+    }
+
+    _colorForNode(topAncestor, depth) {
+        const baseColor = this._topLevelColor().get(topAncestor) ?? this._palette().colorAt(0);
+        return this._palette().lighten(baseColor, depth * 0.12);
+    }
+
+    _textColorForNode(topAncestor, depth) {
+        return this._palette().isDark(this._colorForNode(topAncestor, depth)) ? '#fff' : '#222';
+    }
+
+    _formatNodeValue(node) {
+        return Axis.formatValue(Hierarchy.value(node));
+    }
+}