chart-factory 0.1.2

package/src/table/d3-table.js

@@ -0,0 +1,1570 @@
+/**
+ * D3Table - A flexible table component with intelligent column sizing
+ *
+ * Features:
+ * - Automatic column width calculation based on content
+ * - Sortable columns with visual indicators
+ * - Bar chart cells with animations
+ * - Heatmap cells with color scales
+ * - Row and column highlighting
+ * - Tooltips
+ * - Responsive design
+ *
+ * @requires d3 v7+
+ */
+
+import * as d3 from 'd3';
+import { getCSSVar, TextMeasurer, createColorScale, getLuminance, getContrastColor, formatValue } from '../core/d3-base.js';
+
+export class D3Table {
+    /**
+     * Create a D3Table instance
+     * @param {string} containerId - ID of the table element (without #)
+     * @param {Object} config - Table configuration
+     * @param {Array} config.columns - Column definitions
+     * @param {boolean} [config.sortable=false] - Enable sorting
+     * @param {boolean} [config.highlightSortedColumn=false] - Highlight sorted column
+     * @param {Array} [config.barColumns] - Bar chart column configs
+     * @param {Array} [config.heatmapColumns] - Heatmap column configs
+     * @param {Array} [config.highlightRows] - Row highlight conditions
+     */
+    constructor(containerId, config) {
+        this.containerId = containerId;
+        this.container = d3.select(`#${containerId}`);
+        this.config = config;
+        this.textMeasurer = new TextMeasurer();
+        this.sortState = {
+            column: null,
+            direction: null,
+            originalOrder: []
+        };
+        this.currentData = [];
+        this.userSorted = false;
+        this.expandedRows = new Set();
+        this.expandInitialized = false;
+        this.showAllRows = false;
+    }
+
+    /**
+     * Flatten parents + sub-rows into the display order and build a
+     * per-row metadata map. config.subRows names the row field holding
+     * an array of child rows (same column shape as parents). Children
+     * always render directly under their parent — hidden until expanded
+     * — and are sorted within the parent by the active sort column.
+     * @private
+     */
+    flattenRows(tableData) {
+        const meta = new Map();
+        const key = this.config.subRows;
+        if (!key) {
+            tableData.forEach(d => meta.set(d, {}));
+            return { flat: tableData, meta };
+        }
+
+        const sortCol = this.sortState.column ?
+            this.config.columns.find(c => c.key === this.sortState.column) : null;
+
+        const flat = [];
+        tableData.forEach(parent => {
+            let children = Array.isArray(parent[key]) ? parent[key] : [];
+            if (children.length > 1 && sortCol && sortCol.sortable) {
+                const sortFn = this.getSortFunction(sortCol);
+                children = [...children].sort((a, b) =>
+                    sortFn(a, b, this.sortState.column, this.sortState.direction));
+            }
+            flat.push(parent);
+            meta.set(parent, { hasChildren: children.length > 0 });
+            children.forEach(child => {
+                flat.push(child);
+                meta.set(child, { isChild: true, parent });
+            });
+        });
+        return { flat, meta };
+    }
+
+    /**
+     * Expand or collapse a parent row's sub-rows (no re-render — just
+     * visibility and toggle state).
+     */
+    toggleRow(row) {
+        if (this.expandedRows.has(row)) {
+            this.expandedRows.delete(row);
+        } else {
+            this.expandedRows.add(row);
+        }
+        this.updateExpandedState();
+    }
+
+    /**
+     * Sync sub-row visibility and toggle chevrons/aria with expandedRows.
+     * @private
+     */
+    updateExpandedState() {
+        const self = this;
+        this.container.select('tbody').selectAll('tr').each(function(d) {
+            const m = self.rowMeta?.get(d) || {};
+            if (m.isChild) {
+                this.style.display = self.expandedRows.has(m.parent) ? '' : 'none';
+            } else if (m.hasChildren) {
+                const expanded = self.expandedRows.has(d);
+                d3.select(this).classed('expanded', expanded)
+                    .select('.row-toggle')
+                    .attr('aria-expanded', expanded ? 'true' : 'false');
+            }
+        });
+    }
+
+    /**
+     * Normalize the target DOM and apply the layout mode.
+     * - Warns (instead of failing silently) when the id matches nothing.
+     * - If the target is not a <table>, a <table><thead><tbody> is created
+     *   inside it so divs work as containers.
+     * - Fill layout (default): the table fills its container, carries a
+     *   computed min-width floor, and is wrapped in a horizontal-scroll
+     *   container. `layout: 'fixed'` keeps the legacy content-measured
+     *   pixel-width rendering.
+     * @private
+     */
+    prepareDom() {
+        let node = this.container.node();
+        if (!node) {
+            console.warn(`D3Table: no element found for id "#${this.containerId}" — nothing rendered.`);
+            return false;
+        }
+
+        if (node.tagName !== 'TABLE') {
+            let inner = node.querySelector('table');
+            if (!inner) {
+                inner = document.createElement('table');
+                node.appendChild(inner);
+            }
+            this.container = d3.select(inner);
+            node = inner;
+        }
+        if (!node.querySelector('thead')) {
+            node.insertBefore(document.createElement('thead'), node.firstChild);
+        }
+        if (!node.querySelector('tbody')) {
+            node.appendChild(document.createElement('tbody'));
+        }
+
+        if (this.config.layout !== 'fixed') {
+            node.classList.add('d3-table--fill');
+            node.style.minWidth = `${this.computeMinTableWidth()}px`;
+            const parent = node.parentElement;
+            if (parent && !parent.classList.contains('d3-table-scroll')) {
+                const scroll = document.createElement('div');
+                scroll.className = 'd3-table-scroll';
+                parent.insertBefore(scroll, node);
+                scroll.appendChild(node);
+            }
+            const wrapper = node.closest('.d3-table-wrapper');
+            if (wrapper) wrapper.classList.add('d3-table-wrapper--fill');
+        }
+        this.applyStickyOptions(node);
+        return true;
+    }
+
+    /**
+     * Sticky header / sticky first column setup.
+     * - stickyHeader + maxHeight: the scroll wrapper becomes a vertical
+     *   scroll container and the header sticks inside it.
+     * - stickyHeader alone: sticks to the page. The horizontal scroll
+     *   wrapper would swallow page-stickiness, so render() switches it
+     *   to overflow-x: clip while the table fits its container.
+     * - stickyFirstColumn: first column pins during horizontal scroll,
+     *   with an edge shadow only while actually scrolled.
+     * @private
+     */
+    applyStickyOptions(node) {
+        const scroll = node.parentElement?.classList.contains('d3-table-scroll') ?
+            node.parentElement : null;
+
+        if (this.config.stickyHeader) {
+            node.classList.add('d3-table--sticky-header');
+            if (scroll && typeof this.config.maxHeight === 'number') {
+                scroll.classList.add('d3-table-scroll--vertical');
+                scroll.style.maxHeight = `${this.config.maxHeight}px`;
+            }
+        }
+
+        if (this.config.stickyFirstColumn) {
+            node.classList.add('d3-table--sticky-first-col');
+            if (scroll && !scroll.dataset.stickyScrollBound) {
+                scroll.dataset.stickyScrollBound = '1';
+                scroll.addEventListener('scroll', () => {
+                    scroll.classList.toggle('is-h-scrolled', scroll.scrollLeft > 0);
+                }, { passive: true });
+            }
+        }
+    }
+
+    /**
+     * Readable floor for fill layout: per-column-type minimums summed.
+     * Below this width the scroll container takes over instead of
+     * crushing columns further. Override per column via col.minWidth,
+     * or wholesale via config.minTableWidth.
+     * @private
+     */
+    computeMinTableWidth() {
+        if (typeof this.config.minTableWidth === 'number') return this.config.minTableWidth;
+
+        const defaultMin = parseInt(this.getCSSVar('--table-min-col-width', '48'));
+        const primaryMin = parseInt(this.getCSSVar('--table-min-col-width-primary', '110'));
+        const secondaryMin = parseInt(this.getCSSVar('--table-min-col-width-secondary', '28'));
+        const barMin = parseInt(this.getCSSVar('--bar-column-min-width', '130'));
+        const barColumnKeys = (this.config.barColumns || []).map(b => b.key);
+
+        const imageSize = parseInt(this.getCSSVar('--table-image-size', '22'));
+        const imageGap = parseInt(this.getCSSVar('--table-image-gap', '8'));
+
+        return (this.config.columns || []).reduce((sum, col) => {
+            let floor;
+            if (barColumnKeys.includes(col.key)) floor = barMin;
+            else if (col.className === 'primary-cell' || col.className === 'team-cell') floor = primaryMin;
+            else if (col.className === 'secondary-cell' || col.className === 'rank-cell') floor = secondaryMin;
+            else floor = defaultMin;
+            if (col.image) floor += (col.imageSize || imageSize) + imageGap;
+            return sum + Math.max(floor, col.minWidth || 0);
+        }, 0);
+    }
+
+    /**
+     * Get CSS variable value with fallback. Reads from the table's own
+     * container (computed style, so container-scoped token overrides like
+     * `#my-table-wrap { --bar-column-min-width: 80px }` work exactly like
+     * they do in CSS), falling back to :root and then the literal fallback.
+     * @private
+     */
+    getCSSVar(name, fallback = '') {
+        const node = this.container?.node?.();
+        if (node && node.isConnected) {
+            const value = getComputedStyle(node).getPropertyValue(name).trim();
+            if (value) return value;
+        }
+        return getCSSVar(name, fallback);
+    }
+
+    /**
+     * Measure text width for a given string
+     * @private
+     */
+    measureText(text, fontSize = null, fontWeight = null, options = {}) {
+        return this.textMeasurer.measure(text, fontSize, fontWeight, options);
+    }
+
+    /**
+     * Calculate optimal column widths based on content
+     * @private
+     */
+    calculateColumnWidths(tableData, columns) {
+        const columnWidths = {};
+
+        // Get bar column keys for special handling
+        const barColumnKeys = (this.config.barColumns || []).map(b => b.key);
+
+        columns.forEach(col => {
+            let maxWidth = 0;
+
+            // Measure header width (headers are uppercase with letter-spacing)
+            let headerWidth = this.measureText(
+                col.header,
+                this.getCSSVar('--table-header-font-size', '10px'),
+                this.getCSSVar('--font-weight-normal', '400'),
+                {
+                    letterSpacing: this.getCSSVar('--letter-spacing-wide', '0.8px'),
+                    textTransform: 'uppercase'
+                }
+            );
+
+            // Add space for sort indicator if column is sortable
+            if (col.sortable) {
+                const sortIndicatorSize = parseInt(this.getCSSVar('--sort-indicator-size', '10'));
+                const sortIndicatorMargin = parseInt(this.getCSSVar('--space-1', '4'));
+                headerWidth += sortIndicatorSize + sortIndicatorMargin;
+            }
+
+            maxWidth = Math.max(maxWidth, headerWidth);
+
+            // Check if this is a bar column
+            const isBarColumn = barColumnKeys.includes(col.key);
+
+            // Measure content widths
+            const isPrimary = col.className === 'primary-cell' || col.className === 'team-cell';
+            const isSecondary = col.className === 'secondary-cell' || col.className === 'rank-cell';
+
+            if (isBarColumn) {
+                // Bar columns need special calculation
+                let maxLabelWidth = 0;
+                tableData.forEach(row => {
+                    const value = row[col.key];
+                    const labelText = col.format === 'percentage' ? `${value}%` : String(value);
+                    const labelWidth = this.measureText(
+                        labelText,
+                        this.getCSSVar('--table-font-size'),
+                        this.getCSSVar('--font-weight-semibold')
+                    );
+                    maxLabelWidth = Math.max(maxLabelWidth, labelWidth);
+                });
+
+                const barMaxPercent = parseInt(this.getCSSVar('--bar-max-width-percent', '70'));
+                const barTextPadding = parseInt(this.getCSSVar('--bar-text-padding', '4'));
+                const cellPaddingX = parseInt(this.getCSSVar('--table-cell-padding-x', '20'));
+
+                // The label starts 2% after the bar (up to barMaxPercent), so
+                // it lives in the remaining (100 - barMaxPercent - 2) share of
+                // the padded interior; only the label needs scaling up by that
+                // share — the padding is a constant added on top. (Dividing
+                // the padding by the share too was a long-standing bug that
+                // inflated every bar column by ~100px.)
+                const labelPercent = (100 - barMaxPercent - 2) / 100;
+                const minWidthForLabel =
+                    (maxLabelWidth + 2 * barTextPadding) / labelPercent + 2 * cellPaddingX;
+                maxWidth = Math.max(maxWidth, minWidthForLabel);
+
+                let optimalWidth = maxWidth;
+
+                const barMinWidth = parseInt(this.getCSSVar('--bar-column-min-width', '130'));
+                const barMaxWidth = parseInt(this.getCSSVar('--bar-column-max-width', '250'));
+                optimalWidth = Math.max(optimalWidth, col.minWidth || barMinWidth);
+                // A cap (explicit or token) never shrinks below the label
+                // requirement — a clipped value label is always wrong.
+                const cap = Math.max(col.maxWidth || barMaxWidth, Math.ceil(minWidthForLabel));
+                if ((col.maxWidth || barMaxWidth) < minWidthForLabel) {
+                    console.warn(`D3Table: bar column "${col.key}" max width ` +
+                        `${col.maxWidth || barMaxWidth}px would clip its value ` +
+                        `label; using ${cap}px.`);
+                }
+                optimalWidth = Math.min(optimalWidth, cap);
+
+                columnWidths[col.key] = optimalWidth;
+            } else {
+                // Regular column width calculation
+                tableData.forEach(row => {
+                    let displayText;
+
+                    if (col.render) {
+                        // For columns with render functions, call render and
+                        // extract text. render may return a number (or throw);
+                        // measurement must degrade to the raw value, never
+                        // kill the caller's page.
+                        let rendered;
+                        try {
+                            rendered = col.render(row[col.key], row);
+                        } catch (e) {
+                            rendered = row[col.key];
+                        }
+                        // Strip HTML tags to get plain text for measurement
+                        displayText = String(rendered ?? '').replace(/<[^>]*>/g, '').trim();
+                    } else {
+                        displayText = formatValue(row[col.key], col.format);
+                    }
+
+                    const fontSize = isPrimary ?
+                        this.getCSSVar('--table-primary-font-size', this.getCSSVar('--table-team-font-size')) :
+                        this.getCSSVar('--table-font-size');
+                    const fontWeight = isPrimary ?
+                        this.getCSSVar('--font-weight-bold') :
+                        this.getCSSVar('--font-weight-normal');
+
+                    const textWidth = this.measureText(displayText.toString(), fontSize, fontWeight,
+                        isPrimary ? { fontFamily: this.getCSSVar('--table-primary-font', '') } : {});
+                    maxWidth = Math.max(maxWidth, textWidth);
+                });
+
+                // Image columns reserve room for the leading image + gap
+                if (col.image) {
+                    const imageSize = col.imageSize || parseInt(this.getCSSVar('--table-image-size', '22'));
+                    const imageGap = parseInt(this.getCSSVar('--table-image-gap', '8'));
+                    maxWidth += imageSize + imageGap;
+                }
+
+                const padding = isSecondary ?
+                    parseInt(this.getCSSVar('--col-padding-secondary', '10')) :
+                    parseInt(this.getCSSVar('--col-padding-total', '28'));
+                let optimalWidth = maxWidth + padding;
+
+                const primaryMaxWidth = parseInt(this.getCSSVar('--col-primary-max-width', '250'));
+                const secondaryMaxWidth = parseInt(this.getCSSVar('--col-secondary-max-width', '60'));
+                const defaultMaxWidth = parseInt(this.getCSSVar('--col-default-max-width', '150'));
+
+                if (isPrimary) {
+                    optimalWidth = Math.min(optimalWidth, col.maxWidth || primaryMaxWidth);
+                    if (col.minWidth) optimalWidth = Math.max(optimalWidth, col.minWidth);
+                } else if (isSecondary) {
+                    optimalWidth = Math.min(optimalWidth, col.maxWidth || secondaryMaxWidth);
+                    if (col.minWidth) optimalWidth = Math.max(optimalWidth, col.minWidth);
+                } else {
+                    optimalWidth = Math.min(optimalWidth, col.maxWidth || defaultMaxWidth);
+                    if (col.minWidth) optimalWidth = Math.max(optimalWidth, col.minWidth);
+                }
+
+                columnWidths[col.key] = optimalWidth;
+            }
+        });
+
+        return columnWidths;
+    }
+
+    /**
+     * Label-aware minimum width for a bar column (fill layout).
+     * The end-of-bar value label is absolutely positioned after the bar
+     * (up to --bar-max-width-percent), so the cell must reserve room for
+     * the widest label in the remaining share or the label bleeds into
+     * the next column. Mirrors the fixed-layout bar branch of
+     * calculateColumnWidths, applied as min-width instead of width.
+     * @private
+     */
+    computeBarColumnMinWidth(col, tableData) {
+        let maxLabelWidth = 0;
+        tableData.forEach(row => {
+            const value = row[col.key];
+            const labelText = col.format === 'percentage' ? `${value}%` : String(value);
+            maxLabelWidth = Math.max(maxLabelWidth, this.measureText(
+                labelText,
+                this.getCSSVar('--table-font-size'),
+                this.getCSSVar('--font-weight-semibold')
+            ));
+        });
+
+        const barMaxPercent = parseInt(this.getCSSVar('--bar-max-width-percent', '70'));
+        const barTextPadding = parseInt(this.getCSSVar('--bar-text-padding', '4'));
+        const cellPaddingX = parseInt(this.getCSSVar('--table-cell-padding-x', '20'));
+        const barMinWidth = parseInt(this.getCSSVar('--bar-column-min-width', '130'));
+        const barMaxWidth = parseInt(this.getCSSVar('--bar-column-max-width', '250'));
+
+        // Same formula as the fixed-layout branch: scale only the label by
+        // its share of the interior (net of the 2% bar-to-label gap);
+        // padding is a constant on top. The cap never shrinks below the
+        // label requirement (no clipped labels).
+        const labelPercent = (100 - barMaxPercent - 2) / 100;
+        const minWidthForLabel =
+            (maxLabelWidth + 2 * barTextPadding) / labelPercent + 2 * cellPaddingX;
+
+        const floor = Math.max(minWidthForLabel, barMinWidth, col.minWidth || 0);
+        const cap = Math.max(col.maxWidth || barMaxWidth, Math.ceil(minWidthForLabel));
+        return Math.round(Math.min(floor, cap));
+    }
+
+    /**
+     * Format a value based on format type (instance method wrapper)
+     * @private
+     */
+    formatValue(value, format) {
+        return formatValue(value, format);
+    }
+
+    /**
+     * Minimal HTML escaping for plain values entering .html() paths.
+     * @private
+     */
+    escapeHtml(value) {
+        return String(value).replace(/[&<>"']/g, c => (
+            { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+    }
+
+    /**
+     * Final content for a regular cell: format > render > escaped plain
+     * value, then col.emphasize wraps the result — return true for bold
+     * ("led league" style) or 'strong' for bold-italic ("led MLB").
+     * Used by body cells, image cells, and footer rows so emphasis
+     * behaves identically everywhere.
+     * @private
+     */
+    formatCellContent(col, value, row) {
+        let html;
+        if (col.format) html = this.formatValue(value, col.format);
+        // String()-coerce renderer output: a render function returning a
+        // number (a natural mistake for value columns) must not leak a
+        // non-string into the html pipeline (width measurement coerces the
+        // same way — see calculateColumnWidths).
+        else if (col.render) html = String(col.render(value, row) ?? '');
+        else html = (value === undefined || value === null) ? '' : this.escapeHtml(value);
+
+        const level = col.emphasize ? col.emphasize(value, row) : null;
+        if (level === 'strong') return `<b><i>${html}</i></b>`;
+        if (level) return `<b>${html}</b>`;
+        return html;
+    }
+
+    /**
+     * Get a D3 color scale
+     * @param {string} type - Scale type name
+     * @param {Array} domain - [min, max] domain values
+     */
+    getColorScale(type, domain) {
+        return createColorScale(type, domain);
+    }
+
+    /**
+     * Optional spanning group-header row above the column headers.
+     * Consecutive columns sharing the same col.group value are spanned
+     * by one th ("Passing" over passYds/passTd); runs of ungrouped
+     * columns get one empty spacer th. Rendered only if any column
+     * declares a group.
+     * @private
+     */
+    renderGroupHeaderRow(thead, columns) {
+        if (!columns.some(c => c.group)) return;
+        const tr = thead.append('tr').attr('class', 'd3-table-group-row');
+        let i = 0;
+        while (i < columns.length) {
+            const group = columns[i].group;
+            let span = 1;
+            while (i + span < columns.length && columns[i + span].group === group) span++;
+            const th = tr.append('th').attr('colspan', span);
+            if (group) th.attr('class', 'group-header').text(group);
+            i += span;
+        }
+    }
+
+    /**
+     * Render table headers
+     * @private
+     */
+    /**
+     * Apply a measured column width. Text columns get the fixed pixel width.
+     * In fill layout exactly one column stays flexible to absorb the
+     * container's spare width: the first `wrap: true` column when one
+     * exists (spare width un-wraps its text), else the bar column (spare
+     * width stretches the bars — the legacy behavior). A bar column that
+     * is NOT the flexible one pins at its cap so value labels sit right
+     * after the bars instead of a field of dead space before the next
+     * column.
+     * @private
+     */
+    applyColumnWidth(node, col, px) {
+        const isBarColumn = (this.config.barColumns || []).some(b => b.key === col.key);
+        const fill = this.config.layout !== 'fixed';
+        const wrapCol = fill ? (this.config.columns || []).find(c => c.wrap) : null;
+
+        if (fill && wrapCol && col.key === wrapCol.key) {
+            // Wrap column: floor only, no width — it renders at its natural
+            // (unwrapped) width and wraps only when the container runs out.
+            node.style.minWidth = `${px}px`;
+        } else if (isBarColumn && fill) {
+            // Floor only here; adjustBarColumnFlex() grows the bar column
+            // toward its cap from the container slack measured after render
+            // (and on every container resize).
+            node.style.minWidth = `${px}px`;
+        } else {
+            node.style.setProperty('width', `${px}px`, 'important');
+            // Floor, not suggestion: the remainder-taking column must not
+            // squeeze text columns below their measured width (dates
+            // wrapping to three lines inflates every row).
+            node.style.minWidth = `${px}px`;
+        }
+    }
+
+    /**
+     * Explicit per-column `minWidth` / `maxWidth` config always reaches the
+     * cells as inline styles, so it outranks the stylesheet's auto-width
+     * clamps (e.g. the static secondary-cell max-width) and applies even in
+     * fill layout, where columns otherwise carry no width at all.
+     * `minWidth` is a floor (it only ever raises a computed floor);
+     * `maxWidth` is a hard cap.
+     * @private
+     */
+    applyExplicitColumnBounds(node, col) {
+        if (typeof col.minWidth === 'number') {
+            const current = parseFloat(node.style.minWidth) || 0;
+            if (col.minWidth > current) node.style.minWidth = `${col.minWidth}px`;
+        }
+        if (typeof col.maxWidth === 'number') {
+            node.style.maxWidth = `${col.maxWidth}px`;
+        }
+    }
+
+    renderHeaders(columns, columnWidths = {}) {
+        const thead = this.container.select('thead');
+        thead.selectAll('*').remove();
+        this.renderGroupHeaderRow(thead, columns);
+        const headerRow = thead.append('tr').attr('class', 'd3-table-header-row');
+
+        const barColumnKeys = (this.config.barColumns || []).map(b => b.key);
+
+        columns.forEach(col => {
+            let classes = [];
+
+            const isBarColumn = barColumnKeys.includes(col.key);
+            if (isBarColumn) {
+                classes.push('bar-cell');
+            } else {
+                if (col.align === 'right') classes.push('align-right');
+                if (col.align === 'center') classes.push('align-center');
+            }
+
+            if (col.autoWidth !== false) classes.push('auto-width');
+            if (col.wrap) classes.push('wrap-cell');
+            if (col.className) classes.push(col.className);
+            if (col.highlight) classes.push('highlight-header');
+
+            const isSortable = !!(this.config.sortable && col.sortable);
+            if (isSortable) classes.push('sortable-header');
+
+            const th = headerRow.append('th')
+                .attr('class', classes.join(' '));
+
+            if (isSortable) {
+                this.renderSortableHeaderContent(th, col, isBarColumn);
+            } else {
+                th.text(col.header);
+            }
+
+            if (columnWidths[col.key]) {
+                this.applyColumnWidth(th.node(), col, columnWidths[col.key]);
+            } else if (this.barColumnMinWidths?.[col.key]) {
+                this.applyColumnWidth(th.node(), col, this.barColumnMinWidths[col.key]);
+            } else if (this.fillMinWidths?.[col.key]) {
+                this.applyColumnWidth(th.node(), col, this.fillMinWidths[col.key]);
+            }
+            this.applyExplicitColumnBounds(th.node(), col);
+        });
+    }
+
+    /**
+     * Build a sortable header: a real <button> (Tab / Enter / Space,
+     * aria-sort lives on the th) containing the label with the sort
+     * indicator glued to the adjacent word so it can never wrap onto a
+     * line by itself. Placement is alignment-aware: right-aligned
+     * (numeric) columns carry the indicator BEFORE the label so the
+     * aligned number edge stays clean; all other columns carry it after.
+     * @private
+     */
+    renderSortableHeaderContent(th, col, isBarColumn) {
+        const button = th.append('button')
+            .attr('type', 'button')
+            .attr('class', 'sort-button');
+
+        const words = String(col.header).split(' ');
+        const leadIndicator = col.align === 'right' && !isBarColumn;
+
+        if (leadIndicator) {
+            const first = words.shift();
+            const glue = button.append('span').attr('class', 'sort-glue-lead');
+            glue.append('span').attr('class', 'sort-indicator inactive');
+            glue.append(() => document.createTextNode(first));
+            if (words.length) {
+                button.append(() => document.createTextNode(` ${words.join(' ')}`));
+            }
+        } else {
+            const last = words.pop();
+            if (words.length) {
+                button.append(() => document.createTextNode(`${words.join(' ')} `));
+            }
+            const glue = button.append('span').attr('class', 'sort-glue');
+            glue.append(() => document.createTextNode(last));
+            glue.append('span').attr('class', 'sort-indicator inactive');
+        }
+    }
+
+    /**
+     * Render table body
+     * @private
+     */
+    renderBody(tableData, columns, columnWidths = {}) {
+        const tbody = this.container.select('tbody');
+        tbody.selectAll('*').remove();
+
+        // Parents + sub-rows in display order (sub-rows hidden until expanded)
+        const { flat, meta } = this.flattenRows(tableData);
+        this.rowMeta = meta;
+
+        // Calculate domains for special columns (sub-rows included, so
+        // expansion never changes the scales)
+        const barDomains = {};
+        if (this.config.barColumns) {
+            this.config.barColumns.forEach(barCol => {
+                const values = flat.map(d => parseFloat(d[barCol.key]) || 0);
+                barDomains[barCol.key] = [0, d3.max(values)];
+            });
+        }
+
+        const heatmapDomains = {};
+        if (this.config.heatmapColumns) {
+            this.config.heatmapColumns.forEach(heatmapCol => {
+                // Missing values stay out of the domain — a null must not
+                // drag the scale's min down to 0.
+                const values = flat.map(d => parseFloat(d[heatmapCol.key]))
+                    .filter(v => !isNaN(v));
+                heatmapDomains[heatmapCol.key] = [d3.min(values), d3.max(values)];
+            });
+        }
+
+        const rows = tbody.selectAll('tr')
+            .data(flat)
+            .join('tr');
+
+        if (this.config.subRows) {
+            rows.classed('sub-row', d => !!meta.get(d).isChild)
+                .classed('expandable-row', d => !!meta.get(d).hasChildren);
+        }
+
+        // Apply row highlighting
+        if (this.config.highlightRows) {
+            rows.classed('highlight-row', d => {
+                return this.config.highlightRows.some(highlight => {
+                    if (typeof highlight === 'string') {
+                        return Object.values(d).includes(highlight);
+                    }
+                    if (typeof highlight === 'object' && highlight.key && highlight.value !== undefined) {
+                        return d[highlight.key] === highlight.value;
+                    }
+                    return false;
+                });
+            });
+        }
+
+        const barColumnKeys = (this.config.barColumns || []).map(b => b.key);
+
+        columns.forEach((col) => {
+            const isBarColumn = barColumnKeys.includes(col.key);
+
+            const cells = rows.append('td')
+                .attr('class', () => {
+                    let classes = [];
+                    if (!isBarColumn) {
+                        if (col.align === 'right') classes.push('align-right');
+                        if (col.align === 'center') classes.push('align-center');
+                    }
+                    if (col.className) classes.push(col.className);
+                    if (col.autoWidth !== false) classes.push('auto-width');
+                    if (col.wrap) classes.push('wrap-cell');
+                    if (col.highlight) classes.push('highlight-column');
+                    return classes.join(' ');
+                });
+
+            if (columnWidths[col.key]) {
+                const applyWidth = (node) => this.applyColumnWidth(node, col, columnWidths[col.key]);
+                cells.each(function() { applyWidth(this); });
+            } else if (this.barColumnMinWidths?.[col.key]) {
+                const applyWidth = (node) => this.applyColumnWidth(node, col, this.barColumnMinWidths[col.key]);
+                cells.each(function() { applyWidth(this); });
+            } else if (this.fillMinWidths?.[col.key]) {
+                const applyWidth = (node) => this.applyColumnWidth(node, col, this.fillMinWidths[col.key]);
+                cells.each(function() { applyWidth(this); });
+            }
+            {
+                const applyBounds = (node) => this.applyExplicitColumnBounds(node, col);
+                cells.each(function() { applyBounds(this); });
+            }
+
+            const barConfig = this.config.barColumns?.find(b => b.key === col.key);
+            const heatmapConfig = this.config.heatmapColumns?.find(h => h.key === col.key);
+
+            if (barConfig) {
+                this.renderBarCell(cells, col, barConfig, barDomains[col.key]);
+            } else if (heatmapConfig) {
+                this.renderHeatmapCell(cells, col, heatmapConfig, heatmapDomains[col.key]);
+            } else if (col.image) {
+                // Image module — composes with subtitle/format/render
+                this.renderImageCell(cells, col);
+            } else if (col.subtitle) {
+                // Render cell with subtitle
+                this.renderSubtitleCell(cells, col);
+            } else if (col.format || col.render || col.emphasize) {
+                cells.html(d => this.formatCellContent(col, d[col.key], d));
+            } else {
+                cells.text(d => d[col.key]);
+            }
+        });
+
+        if (this.config.subRows) {
+            this.attachRowToggles(rows, meta);
+        }
+        this.applyCapClasses();
+    }
+
+    /**
+     * Prepend an expand/collapse chevron button to the first cell of
+     * every parent row that has sub-rows (a same-width spacer keeps
+     * childless parents aligned), then apply the current expanded state.
+     * @private
+     */
+    attachRowToggles(rows, meta) {
+        const self = this;
+        rows.each(function(d) {
+            const m = meta.get(d);
+            if (m.isChild) return;
+            const td = this.querySelector('td');
+            if (!td) return;
+
+            if (m.hasChildren) {
+                const btn = document.createElement('button');
+                btn.type = 'button';
+                btn.className = 'row-toggle';
+                btn.setAttribute('aria-label', 'Toggle sub-rows');
+                btn.addEventListener('click', (e) => {
+                    e.stopPropagation();
+                    self.toggleRow(d);
+                });
+                td.insertBefore(btn, td.firstChild);
+            } else {
+                const spacer = document.createElement('span');
+                spacer.className = 'row-toggle-spacer';
+                td.insertBefore(spacer, td.firstChild);
+            }
+        });
+        this.updateExpandedState();
+    }
+
+    /**
+     * Hide top-level rows beyond config.maxRows (sub-rows follow their
+     * parent) unless the user pressed Show all. Class-based so it
+     * composes with sub-row expand/collapse visibility.
+     * @private
+     */
+    applyCapClasses() {
+        const max = this.config.maxRows;
+        if (!max) return;
+        const self = this;
+        let parentIdx = -1;
+        this.container.select('tbody').selectAll('tr').each(function(d) {
+            const m = self.rowMeta?.get(d) || {};
+            if (!m.isChild) parentIdx++;
+            this.classList.toggle('row-capped', !self.showAllRows && parentIdx >= max);
+        });
+    }
+
+    /**
+     * "Show all N" / "Show fewer" toggle below the table when maxRows
+     * caps it. Lives outside the scroll container so it never scrolls.
+     * @private
+     */
+    renderShowAllControl() {
+        const max = this.config.maxRows;
+        const node = this.container.node();
+        // Host must be the element that CONTAINS the control after the
+        // afterend insertion below: the page wrapper when present, else the
+        // parent of the fill-layout scroll wrapper. Using the scroll wrapper
+        // itself (node.parentElement when the container is the wrapped
+        // <table>) made the dedupe lookup search a subtree the button sits
+        // AFTER — so every re-render minted another button.
+        const scroll = node.closest('.d3-table-scroll');
+        const host = node.closest('.d3-table-wrapper') ||
+            (scroll ? scroll.parentElement : node.parentElement);
+        if (!host) return;
+
+        let btn = host.querySelector(`.d3-table-showmore[data-for="${this.containerId}"]`);
+        const total = this.currentData.length;
+        if (!max || total <= max) {
+            if (btn) btn.remove();
+            return;
+        }
+
+        if (!btn) {
+            btn = document.createElement('button');
+            btn.type = 'button';
+            btn.className = 'd3-table-showmore';
+            btn.dataset.for = this.containerId;
+            const anchor = host.querySelector('.d3-table-scroll') ||
+                (node.closest('.d3-table-scroll') || node);
+            anchor.insertAdjacentElement('afterend', btn);
+            btn.addEventListener('click', () => {
+                this.showAllRows = !this.showAllRows;
+                this.applyCapClasses();
+                this.renderShowAllControl();
+            });
+        }
+        btn.textContent = this.showAllRows ?
+            (this.config.showLessLabel || 'Show fewer') :
+            (this.config.showAllLabel || `Show all ${total}`);
+    }
+
+    /**
+     * Pinned summary rows (config.footerRows: array of row objects with
+     * the same keys as data rows; footerRow is a single-row shorthand).
+     * Rendered in tfoot — exempt from sorting and the row cap. The first
+     * footer row carries the heavy total rule; later rows get the normal
+     * row border. Values go through the column's format/render/emphasize;
+     * bar, heatmap, and image treatments don't apply.
+     * @private
+     */
+    renderFooter(columns) {
+        let tfoot = this.container.select('tfoot');
+        const footerRows = this.config.footerRows ||
+            (this.config.footerRow ? [this.config.footerRow] : []);
+        if (!footerRows.length) {
+            tfoot.remove();
+            return;
+        }
+        if (tfoot.empty()) tfoot = this.container.append('tfoot');
+        tfoot.selectAll('*').remove();
+
+        footerRows.forEach(rowData => {
+            const tr = tfoot.append('tr');
+            columns.forEach(col => {
+                const classes = [];
+                if (col.align === 'right') classes.push('align-right');
+                if (col.align === 'center') classes.push('align-center');
+                if (col.className) classes.push(col.className);
+                const td = tr.append('td').attr('class', classes.join(' '));
+
+                const value = rowData[col.key];
+                if (value === undefined || value === null) return;
+                td.html(this.formatCellContent(col, value, rowData));
+            });
+        });
+    }
+
+    /**
+     * Render a cell with a leading image (flag / logo / headshot) next to
+     * the value. col.image names the row field holding the image URL.
+     * Options: imageShape 'circle' | 'rounded' (default) | 'square';
+     * imageSize px override (token --table-image-size otherwise);
+     * imageFit 'cover' | 'contain' (default: cover for circle —
+     * headshots crop well — contain otherwise, so logos letterbox).
+     * Composes with subtitle (image + two-line stack), format, and
+     * render. Rows with a falsy image field keep an invisible slot so
+     * text stays aligned; broken URLs hide themselves the same way.
+     * @private
+     */
+    renderImageCell(cells, col) {
+        cells.classed('has-image', true);
+
+        const shape = col.imageShape || 'rounded';
+        const fit = col.imageFit || (shape === 'circle' ? 'cover' : 'contain');
+        const self = this;
+
+        cells.each(function(d) {
+            const cell = d3.select(this);
+            const wrapper = cell.append('div').attr('class', 'cell-with-image');
+
+            const src = d[col.image];
+            if (src) {
+                wrapper.append('img')
+                    .attr('class', `d3-table-img img-${shape} img-fit-${fit}`)
+                    .attr('src', src)
+                    .attr('alt', '')
+                    .attr('loading', 'lazy')
+                    .on('error', function() { this.style.visibility = 'hidden'; })
+                    .call(img => {
+                        if (col.imageSize) {
+                            img.style('width', `${col.imageSize}px`).style('height', `${col.imageSize}px`);
+                        }
+                    });
+            } else {
+                const placeholder = wrapper.append('span')
+                    .attr('class', 'd3-table-img d3-table-img-placeholder');
+                if (col.imageSize) {
+                    placeholder.style('width', `${col.imageSize}px`).style('height', `${col.imageSize}px`);
+                }
+            }
+
+            if (col.subtitle) {
+                const stack = wrapper.append('div').attr('class', 'cell-with-subtitle');
+                stack.append('div').attr('class', 'cell-main-text').text(d[col.key]);
+                stack.append('div').attr('class', 'cell-subtitle-text').text(d[col.subtitle]);
+            } else {
+                wrapper.append('span').html(self.formatCellContent(col, d[col.key], d));
+            }
+        });
+
+        if (col.subtitle) {
+            cells.classed('has-subtitle', true);
+        }
+    }
+
+    /**
+     * Render a cell with main text and subtitle
+     * @private
+     */
+    renderSubtitleCell(cells, col) {
+        cells.classed('has-subtitle', true);
+
+        cells.each(function(d) {
+            const cell = d3.select(this);
+            const mainValue = d[col.key];
+            const subtitleValue = d[col.subtitle];
+
+            const wrapper = cell.append('div')
+                .attr('class', 'cell-with-subtitle');
+
+            wrapper.append('div')
+                .attr('class', 'cell-main-text')
+                .text(mainValue);
+
+            wrapper.append('div')
+                .attr('class', 'cell-subtitle-text')
+                .text(subtitleValue);
+        });
+    }
+
+    /**
+     * Render a bar chart cell
+     * @private
+     */
+    renderBarCell(cells, col, barConfig, domain) {
+        cells.classed('bar-cell', true);
+
+        const colorScale = this.getColorScale(
+            barConfig.colorScale || 'orange',
+            domain
+        );
+
+        const animationDuration = parseInt(this.getCSSVar('--animation-duration-slow', '1000'));
+        const staggerDelay = parseInt(this.getCSSVar('--animation-stagger-delay', '50'));
+        const barMaxWidthPercent = parseInt(this.getCSSVar('--bar-max-width-percent', '70'));
+        const barMaxWidthHighlighted = parseInt(this.getCSSVar('--bar-max-width-percent-highlighted', '65'));
+        const barLabelMaxPosition = parseInt(this.getCSSVar('--bar-label-max-position', '75'));
+
+        cells.each(function(d, i) {
+            const cell = d3.select(this);
+            const value = parseFloat(d[col.key]) || 0;
+            const maxValue = domain[1];
+
+            const isHighlighted = cell.classed('highlight-column');
+            const maxWidth = isHighlighted ? barMaxWidthHighlighted : barMaxWidthPercent;
+            const widthPercent = (value / maxValue) * maxWidth;
+            const barWidth = Math.min(widthPercent, maxWidth);
+
+            // Bar + label live in a track spanning the padded interior, so
+            // their percentages are interior-relative and can't overflow the
+            // cell padding in tight columns.
+            const track = cell.append('div').attr('class', 'bar-track');
+
+            const bar = track.append('div')
+                .attr('class', 'bar-background')
+                .style('width', '0%')
+                .style('background-color', colorScale(value));
+
+            const labelText = col.format === 'percentage' ? `${value}%` : value;
+            const labelLeft = Math.min(Math.max(barWidth + 2, 0), barLabelMaxPosition);
+            const label = track.append('div')
+                .attr('class', 'bar-value')
+                .style('left', '0%')
+                .text(labelText);
+
+            const delay = i * staggerDelay;
+            bar.transition()
+                .delay(delay)
+                .duration(animationDuration)
+                .ease(d3.easeCubicOut)
+                .style('width', `${barWidth}%`);
+
+            label.transition()
+                .delay(delay)
+                .duration(animationDuration)
+                .ease(d3.easeCubicOut)
+                .style('left', `${labelLeft}%`);
+        });
+    }
+
+    /**
+     * Render a heatmap cell. Display text goes through the column's
+     * format/render/emphasize (formatCellContent) so a heatmap column
+     * reads exactly like a plain column with a color behind it; a
+     * missing value (null/undefined/non-numeric) renders an em dash
+     * with no fill instead of being treated as 0.
+     * @private
+     */
+    renderHeatmapCell(cells, col, heatmapConfig, domain) {
+        cells.classed('heatmap-cell-padded', true);
+
+        const colorScale = this.getColorScale(
+            heatmapConfig.colorScale || 'orange',
+            domain
+        );
+
+        const animationDuration = parseInt(this.getCSSVar('--animation-duration-normal', '500'));
+        const staggerDelay = parseInt(this.getCSSVar('--animation-stagger-delay', '50'));
+        const self = this;
+
+        cells.each(function(d, i) {
+            const cell = d3.select(this);
+            const raw = d[col.key];
+            const value = parseFloat(raw);
+            const hasValue = raw !== null && raw !== undefined && raw !== '' && !isNaN(value);
+
+            const box = cell.append('div')
+                .attr('class', 'heatmap-box')
+                .style('opacity', 0);
+
+            if (hasValue) {
+                const bgColor = colorScale(value);
+                box.style('background-color', bgColor)
+                    .style('color', getContrastColor(bgColor))
+                    .html(self.formatCellContent(col, raw, d));
+            } else {
+                box.classed('heatmap-box-empty', true).text('—');
+            }
+
+            const delay = i * staggerDelay;
+            box.transition()
+                .delay(delay)
+                .duration(animationDuration)
+                .ease(d3.easeCubicOut)
+                .style('opacity', 1);
+        });
+    }
+
+    // ===== SORTING =====
+
+    /**
+     * Sort by numeric value
+     * @private
+     */
+    numericSort(a, b, key, direction) {
+        const valA = typeof a[key] === 'number' ? a[key] : parseFloat(a[key]) || 0;
+        const valB = typeof b[key] === 'number' ? b[key] : parseFloat(b[key]) || 0;
+        return direction === 'asc' ? valA - valB : valB - valA;
+    }
+
+    /**
+     * Sort by text value
+     * @private
+     */
+    textSort(a, b, key, direction) {
+        const valA = (a[key] || '').toString().toLowerCase();
+        const valB = (b[key] || '').toString().toLowerCase();
+        const result = valA.localeCompare(valB);
+        return direction === 'asc' ? result : -result;
+    }
+
+    /**
+     * Sort by W-L record format
+     * @private
+     */
+    recordSort(a, b, key, direction) {
+        const parseRecord = (record) => {
+            const [wins] = (record || '0-0').split('-').map(Number);
+            return wins || 0;
+        };
+
+        const winsA = parseRecord(a[key]);
+        const winsB = parseRecord(b[key]);
+        return direction === 'asc' ? winsA - winsB : winsB - winsA;
+    }
+
+    /**
+     * Get the appropriate sort function for a column
+     * @private
+     */
+    getSortFunction(column) {
+        switch(column.sortType) {
+            case 'numeric': return this.numericSort.bind(this);
+            case 'text': return this.textSort.bind(this);
+            case 'record': return this.recordSort.bind(this);
+            default: return this.numericSort.bind(this);
+        }
+    }
+
+    /**
+     * Sort data by a column
+     * @private
+     */
+    sortData(columnKey, direction) {
+        if (!this.currentData || this.currentData.length === 0) return [];
+
+        const column = this.config.columns.find(col => col.key === columnKey);
+        if (!column || !column.sortable) return this.currentData;
+
+        const sortFunction = this.getSortFunction(column);
+        return [...this.currentData].sort((a, b) =>
+            sortFunction(a, b, columnKey, direction)
+        );
+    }
+
+    /**
+     * Initialize sorting functionality
+     * @private
+     */
+    initializeSorting() {
+        if (!this.config.sortable) return;
+
+        this.config.columns.forEach(col => {
+            if (!col.sortable) return;
+
+            const colIndex = this.config.columns.indexOf(col) + 1;
+            this.container.select(`thead tr.d3-table-header-row th:nth-child(${colIndex})`)
+                .on('click', () => this.handleHeaderClick(col.key));
+        });
+    }
+
+    /**
+     * First-click direction for a column: explicit defaultSort wins;
+     * otherwise text sorts ascending, numeric/record sort descending
+     * (best-first, the data-table convention).
+     * @private
+     */
+    firstSortDirection(column) {
+        if (column.defaultSort) return column.defaultSort;
+        return column.sortType === 'text' ? 'asc' : 'desc';
+    }
+
+    /**
+     * Handle header click for sorting
+     * @private
+     */
+    handleHeaderClick(columnKey) {
+        const column = this.config.columns.find(col => col.key === columnKey);
+
+        let newDirection;
+        if (this.sortState.column === columnKey) {
+            newDirection = this.sortState.direction === 'asc' ? 'desc' : 'asc';
+        } else {
+            newDirection = this.firstSortDirection(column);
+        }
+
+        this.sortState.column = columnKey;
+        this.sortState.direction = newDirection;
+        this.userSorted = true;
+
+        const sortedData = this.sortData(columnKey, newDirection);
+        const columnWidths = this.config.layout === 'fixed' ?
+            this.calculateColumnWidths(sortedData, this.config.columns) : {};
+        this.renderBody(sortedData, this.config.columns, columnWidths);
+
+        setTimeout(() => this.updateSortIndicators(), 0);
+    }
+
+    /**
+     * Update sort indicator visuals, aria-sort, and the sorted-column
+     * highlight. The quiet column wash (header included) appears for
+     * user-initiated sorts by default; highlightSortedColumn: true
+     * forces it always on, false disables it entirely.
+     * @private
+     */
+    updateSortIndicators() {
+        this.container.selectAll('.sort-indicator')
+            .classed('active asc desc', false)
+            .classed('inactive', true);
+
+        this.container.selectAll('th, td')
+            .classed('sorted-column', false);
+
+        this.container.selectAll('thead th').each(function() {
+            this.removeAttribute('aria-sort');
+        });
+
+        if (!this.sortState.column) return;
+
+        const columnIndex = this.config.columns.findIndex(col => col.key === this.sortState.column);
+        if (columnIndex === -1) return;
+
+        const th = this.container.select(`thead tr.d3-table-header-row th:nth-child(${columnIndex + 1})`);
+        th.select('.sort-indicator')
+            .classed('inactive', false)
+            .classed('active', true)
+            .classed(this.sortState.direction, true);
+
+        const thNode = th.node();
+        if (thNode) {
+            thNode.setAttribute('aria-sort', this.sortState.direction === 'asc' ? 'ascending' : 'descending');
+        }
+
+        const highlight = this.config.highlightSortedColumn === true ||
+            (this.config.highlightSortedColumn !== false && this.userSorted);
+        if (highlight) {
+            this.container.selectAll(`tr.d3-table-header-row th:nth-child(${columnIndex + 1}), tbody td:nth-child(${columnIndex + 1})`)
+                .classed('sorted-column', true);
+        }
+    }
+
+    // ===== PUBLIC API =====
+
+    /**
+     * Render the table with data
+     * @param {Array} data - Array of row objects
+     */
+    render(data) {
+        if (!this.prepareDom()) return;
+
+        this.sortState.originalOrder = [...data];
+        this.currentData = [...data];
+
+        // A sortable table ships pre-sorted: the first column with a
+        // defaultSort is applied on load (indicator visible from first
+        // paint, no column highlight — that's reserved for user sorts).
+        // Re-renders (update()) keep whatever sort is active.
+        let rows = data;
+        if (this.config.sortable && !this.sortState.column) {
+            const defaultCol = this.config.columns.find(col => col.sortable && col.defaultSort);
+            if (defaultCol) {
+                this.sortState.column = defaultCol.key;
+                this.sortState.direction = defaultCol.defaultSort;
+            }
+        }
+        if (this.sortState.column) {
+            rows = this.sortData(this.sortState.column, this.sortState.direction);
+        }
+
+        // Expandable sub-rows: defaultExpanded opens every parent on the
+        // first render only (later update() calls keep the user's state).
+        if (this.config.subRows && !this.expandInitialized && this.config.defaultExpanded) {
+            const key = this.config.subRows;
+            rows.forEach(row => {
+                if (Array.isArray(row[key]) && row[key].length) this.expandedRows.add(row);
+            });
+        }
+        this.expandInitialized = true;
+
+        // Fixed-mode measurement covers sub-rows too
+        const measureRows = this.config.subRows ? this.flattenRows(rows).flat : rows;
+
+        const columnWidths = this.config.layout === 'fixed' ?
+            this.calculateColumnWidths(measureRows, this.config.columns) : {};
+
+        // Fill layout: bar columns keep a label-aware min-width so the
+        // end-of-bar value label can never bleed into the next column.
+        this.barColumnMinWidths = {};
+        this.fillMinWidths = {};
+        if (this.config.layout !== 'fixed' && this.config.barColumns) {
+            this.config.barColumns.forEach(barCol => {
+                const col = this.config.columns.find(c => c.key === barCol.key);
+                if (col) {
+                    this.barColumnMinWidths[col.key] = this.computeBarColumnMinWidth(col, measureRows);
+                }
+            });
+            // The greedy bar column (width 99%) would otherwise crush the
+            // text columns to min-content (wrapped dates, ballooned rows) —
+            // give every non-bar column its measured width as a floor.
+            const measured = this.calculateColumnWidths(measureRows, this.config.columns);
+            const barKeys = new Set(this.config.barColumns.map(b => b.key));
+            const wrapFloor = parseInt(this.getCSSVar('--table-wrap-min-width', '110'));
+            Object.keys(measured).forEach(key => {
+                if (barKeys.has(key)) return;
+                const col = this.config.columns.find(c => c.key === key);
+                // A wrap column's whole point is shrinking below its
+                // unwrapped content width — floor it at its explicit
+                // minWidth (or the wrap-floor token), not the measurement.
+                this.fillMinWidths[key] = col?.wrap ?
+                    Math.min(measured[key], col.minWidth || wrapFloor) :
+                    measured[key];
+            });
+        }
+
+        this.renderHeaders(this.config.columns, columnWidths);
+        this.renderBody(rows, this.config.columns, columnWidths);
+        this.renderFooter(this.config.columns);
+        this.renderShowAllControl();
+        this.initializeSorting();
+        this.updateSortIndicators();
+        this.adjustBarColumnFlex();
+        this.observeContainerResize();
+
+        // Two-row sticky headers: the label row sticks below the group
+        // row, offset by the group row's measured height.
+        if (this.config.stickyHeader) {
+            const groupRow = this.container.select('thead tr.d3-table-group-row').node();
+            if (groupRow) {
+                const offset = groupRow.getBoundingClientRect().height;
+                this.container.selectAll('thead tr.d3-table-header-row th')
+                    .style('top', `${offset}px`);
+            }
+        }
+
+        // Page-level sticky header (no maxHeight): the horizontal scroll
+        // wrapper would swallow position: sticky, so — re-checked every
+        // render — a table that FITS its container gets real sticky via
+        // overflow-x: clip, and a table that OVERFLOWS gets the floating
+        // header (scroll-driven thead translate) instead.
+        if (this.config.stickyHeader && typeof this.config.maxHeight !== 'number') {
+            const node = this.container.node();
+            const scroll = node.closest('.d3-table-scroll');
+            if (scroll) {
+                const fits = node.scrollWidth <= scroll.clientWidth + 1;
+                scroll.classList.toggle('d3-table-scroll--clip', fits);
+                this.setFloatingHeader(!fits);
+            }
+        }
+
+        this.textMeasurer.destroy();
+    }
+
+    /**
+     * Grow fill-layout bar columns from their label-fit floor toward their
+     * cap (col.maxWidth or --bar-column-max-width) using the container
+     * slack actually available: with the table at fit-content width, the
+     * spare card width first widens the bars, and only what the bars
+     * can't use stays outside the table as whitespace. Runs after every
+     * render and on container resize; narrow containers keep the floor.
+     * @private
+     */
+    adjustBarColumnFlex() {
+        if (this.config.layout === 'fixed') return;
+        const barCols = (this.config.barColumns || [])
+            .map(b => this.config.columns.find(c => c.key === b.key))
+            .filter(Boolean);
+        if (!barCols.length) return;
+
+        const tbl = this.container.node();
+        if (!tbl || !tbl.isConnected) return;
+        const scroll = tbl.closest('.d3-table-scroll');
+        const avail = (scroll || tbl.parentElement)?.clientWidth || 0;
+        if (!avail) return;
+
+        const cellsFor = (col) => {
+            const idx = this.config.columns.indexOf(col) + 1;
+            return tbl.querySelectorAll(
+                `tr.d3-table-header-row > th:nth-child(${idx}), ` +
+                `tbody > tr > td:nth-child(${idx}), tfoot > tr > td:nth-child(${idx})`);
+        };
+
+        // Measure the table with every bar column at its floor…
+        barCols.forEach(col => {
+            const floor = this.barColumnMinWidths?.[col.key] || 0;
+            cellsFor(col).forEach(n => { n.style.width = floor ? `${floor}px` : ''; });
+        });
+        const slack = Math.max(0, avail - tbl.offsetWidth);
+        if (!slack) return;
+
+        // …then share the slack, capped per column.
+        const barMaxWidth = parseInt(this.getCSSVar('--bar-column-max-width', '250'));
+        barCols.forEach(col => {
+            const floor = this.barColumnMinWidths?.[col.key] || 0;
+            const cap = Math.max(floor, col.maxWidth || barMaxWidth);
+            const width = Math.min(cap, floor + Math.floor(slack / barCols.length));
+            cellsFor(col).forEach(n => { n.style.width = `${width}px`; });
+        });
+    }
+
+    /**
+     * Re-run the bar-column flex whenever the host container resizes.
+     * One observer per table instance; disconnected in destroy().
+     * @private
+     */
+    observeContainerResize() {
+        if (this._flexRO || typeof ResizeObserver === 'undefined') return;
+        const tbl = this.container.node();
+        const host = tbl?.closest('.d3-table-scroll')?.parentElement || tbl?.parentElement;
+        if (!host) return;
+        let scheduled = false;
+        this._flexRO = new ResizeObserver(() => {
+            if (scheduled) return;
+            scheduled = true;
+            requestAnimationFrame(() => {
+                scheduled = false;
+                this.adjustBarColumnFlex();
+            });
+        });
+        this._flexRO.observe(host);
+    }
+
+    /**
+     * Floating header: sticky emulation for tables that also scroll
+     * horizontally. position: sticky cannot escape the horizontal
+     * scroll container, so a page scroll/resize listener translates the
+     * thead down by however far the table top has passed the viewport
+     * top (clamped near the table bottom). Horizontal scroll still
+     * moves the header with its columns. The thead is re-queried on
+     * every tick so it survives re-renders. (Sports-reference solves
+     * the same problem the same way. Note: transforms on table-row-
+     * groups are solid in Chromium/Firefox; older Safari is the reason
+     * this stays behind the overflow check rather than replacing real
+     * position: sticky everywhere.)
+     * @private
+     */
+    setFloatingHeader(enable) {
+        if (!enable) {
+            if (this.floatingHeaderCleanup) {
+                this.floatingHeaderCleanup();
+                this.floatingHeaderCleanup = null;
+            }
+            return;
+        }
+        if (this.floatingHeaderCleanup) return;
+
+        const table = this.container.node();
+        const update = () => {
+            const thead = table.querySelector('thead');
+            if (!thead) return;
+            const rect = table.getBoundingClientRect();
+            const theadH = thead.getBoundingClientRect().height;
+            const maxOffset = Math.max(0, rect.height - theadH * 2);
+            const offset = Math.min(Math.max(0, -rect.top), maxOffset);
+            thead.style.transform = offset > 0 ? `translateY(${offset}px)` : '';
+            thead.classList.toggle('d3-table-thead--floating', offset > 0);
+        };
+        window.addEventListener('scroll', update, { passive: true });
+        window.addEventListener('resize', update, { passive: true });
+        update();
+
+        this.floatingHeaderCleanup = () => {
+            window.removeEventListener('scroll', update);
+            window.removeEventListener('resize', update);
+            const thead = table.querySelector('thead');
+            if (thead) {
+                thead.style.transform = '';
+                thead.classList.remove('d3-table-thead--floating');
+            }
+        };
+    }
+
+    /**
+     * Update table with new data
+     * @param {Array} data - New data array
+     */
+    update(data) {
+        this.render(data);
+    }
+
+    /**
+     * Re-render the current data in place; the active sort and expanded
+     * sub-rows are kept (render() re-applies sortState). Use after a theme
+     * change: bar and heatmap cell colors resolve design tokens at render
+     * time, so a [data-theme] flip needs a re-render to show up.
+     */
+    rerender() {
+        this.render(this.currentData);
+    }
+
+    /**
+     * Sort table by a column programmatically
+     * @param {string} columnKey - Column key to sort by
+     * @param {string} [direction='asc'] - Sort direction ('asc' or 'desc')
+     */
+    sort(columnKey, direction = 'asc') {
+        this.sortState.column = columnKey;
+        this.sortState.direction = direction;
+
+        const sortedData = this.sortData(columnKey, direction);
+        const columnWidths = this.config.layout === 'fixed' ?
+            this.calculateColumnWidths(sortedData, this.config.columns) : {};
+        this.renderBody(sortedData, this.config.columns, columnWidths);
+        this.adjustBarColumnFlex();
+        this.updateSortIndicators();
+    }
+
+    /**
+     * Reset table to original data order
+     */
+    reset() {
+        this.sortState.column = null;
+        this.sortState.direction = null;
+        this.userSorted = false;
+        this.currentData = [...this.sortState.originalOrder];
+
+        const columnWidths = this.config.layout === 'fixed' ?
+            this.calculateColumnWidths(this.currentData, this.config.columns) : {};
+        this.renderBody(this.currentData, this.config.columns, columnWidths);
+        this.adjustBarColumnFlex();
+        this.updateSortIndicators();
+    }
+
+    /**
+     * Destroy the table and clean up
+     */
+    destroy() {
+        this.textMeasurer.destroy();
+        this.setFloatingHeader(false);
+        if (this._flexRO) {
+            this._flexRO.disconnect();
+            this._flexRO = null;
+        }
+        // The show-all control lives OUTSIDE thead/tbody (a sibling of the
+        // scroll wrapper) — remove it explicitly or it outlives the table.
+        const node = this.container.node();
+        if (node) {
+            const scroll = node.closest('.d3-table-scroll');
+            const host = node.closest('.d3-table-wrapper') ||
+                (scroll ? scroll.parentElement : node.parentElement);
+            host?.querySelector(`.d3-table-showmore[data-for="${this.containerId}"]`)?.remove();
+        }
+        this.container.select('thead').selectAll('*').remove();
+        this.container.select('tbody').selectAll('*').remove();
+    }
+}
+
+// Default export
+export default D3Table;