@appius-fr/apx 2.7.0 → 2.8.0

package/modules/scrollableTable/scrollableTable.mjs

@@ -1,198 +1,594 @@
-import './css/scrollableTable.css';
-
-const DATA_KEY = '_apxScrollableTable';
-const CLASS_TABLE = 'apx-scrollable-table';
-
-const DEFAULT_MAX_HEIGHT = '200px';
-
-/**
- * Get number of columns from the first row that has cells (sum of colspan).
- * @param {HTMLTableSectionElement} section - thead, tbody, or tfoot
- * @returns {number}
- */
-function getColumnCountFromSection(section) {
-    const firstRow = section?.querySelector(':scope > tr');
-    if (!firstRow) return 0;
-    let cols = 0;
-    firstRow.querySelectorAll(':scope > th, :scope > td').forEach((cell) => {
-        cols += parseInt(cell.getAttribute('colspan'), 10) || 1;
-    });
-    return cols;
-}
-
-/**
- * Get total column count for the table (from thead or tbody first row).
- * @param {HTMLTableElement} table
- * @returns {number}
- */
-function getTableColumnCount(table) {
-    const thead = table.querySelector('thead');
-    const tbody = table.querySelector('tbody');
-    const countFromThead = thead ? getColumnCountFromSection(thead) : 0;
-    const countFromTbody = tbody ? getColumnCountFromSection(tbody) : 0;
-    return countFromThead || countFromTbody || 1;
-}
-
-/**
- * Count direct tr children in a section.
- * @param {HTMLTableSectionElement} section
- * @returns {number}
- */
-function getRowCount(section) {
-    if (!section) return 0;
-    return section.querySelectorAll(':scope > tr').length;
-}
-
-/**
- * Build a 2D grid of occupied slots for a section (for rowspan/colspan placement).
- * Place each cell in DOM order; return a list of { cell, row, col, colspan, rowspan }.
- * @param {HTMLTableSectionElement} section
- * @param {number} numRows
- * @param {number} numCols
- * @returns {{ cell: HTMLTableCellElement, row: number, col: number, colspan: number, rowspan: number }[]}
- */
-function computeCellPlacements(section, numRows, numCols) {
-    if (!section || numRows === 0 || numCols === 0) return [];
-    const occupied = Array.from({ length: numRows }, () => Array(numCols).fill(false));
-    const placements = [];
-    const rows = section.querySelectorAll(':scope > tr');
-
-    for (let r = 0; r < rows.length; r++) {
-        const tr = rows[r];
-        const cells = tr.querySelectorAll(':scope > th, :scope > td');
-        for (const cell of cells) {
-            const colspan = Math.min(parseInt(cell.getAttribute('colspan'), 10) || 1, numCols);
-            const rowspan = Math.min(parseInt(cell.getAttribute('rowspan'), 10) || 1, numRows - r);
-            let col = 0;
-            while (col < numCols) {
-                let free = true;
-                for (let rr = r; rr < r + rowspan && free; rr++) {
-                    for (let cc = col; cc < col + colspan && free; cc++) {
-                        if (occupied[rr]?.[cc]) free = false;
-                    }
-                }
-                if (free) break;
-                col++;
-            }
-            if (col + colspan > numCols) continue;
-            for (let rr = r; rr < r + rowspan; rr++) {
-                for (let cc = col; cc < col + colspan; cc++) {
-                    if (occupied[rr]) occupied[rr][cc] = true;
-                }
-            }
-            placements.push({ cell, row: r, col, colspan, rowspan });
-        }
-    }
-    return placements;
-}
-
-/**
- * Apply grid placement styles to a list of placements (1-based line numbers for CSS Grid).
- */
-function applyPlacements(placements) {
-    placements.forEach(({ cell, row, col, colspan, rowspan }) => {
-        cell.style.gridRow = `${row + 1} / span ${rowspan}`;
-        cell.style.gridColumn = `${col + 1} / span ${colspan}`;
-    });
-}
-
-/**
- * Clear grid placement styles from all th/td in a table (for refresh).
- * @param {HTMLTableElement} table
- */
-function clearPlacements(table) {
-    table.querySelectorAll('th, td').forEach((cell) => {
-        cell.style.gridRow = '';
-        cell.style.gridColumn = '';
-    });
-}
-
-/**
- * Normalize maxHeight option to a CSS length string.
- * @param {number|string} value
- * @returns {string}
- */
-function normalizeMaxHeight(value) {
-    if (value == null) return DEFAULT_MAX_HEIGHT;
-    if (typeof value === 'number') return `${value}px`;
-    return String(value);
-}
-
-/**
- * Apply scrollable table layout to a single table.
- * @param {HTMLTableElement} table
- * @param {{ maxHeight?: number|string }} options
- */
-function applyScrollableTable(table, options) {
-    const thead = table.querySelector('thead');
-    const tbody = table.querySelector('tbody');
-    const tfoot = table.querySelector('tfoot');
-
-    const numCols = getTableColumnCount(table);
-    if (numCols === 0) return;
-
-    const theadRows = getRowCount(thead);
-    const tbodyRows = getRowCount(tbody);
-    const tfootRows = getRowCount(tfoot);
-
-    table.style.setProperty('--apx-scrollable-cols', String(numCols));
-    table.style.setProperty('--apx-scrollable-thead-rows', String(Math.max(1, theadRows)));
-    table.style.setProperty('--apx-scrollable-tbody-rows', String(Math.max(1, tbodyRows)));
-    table.style.setProperty('--apx-scrollable-tfoot-rows', String(Math.max(1, tfootRows)));
-    table.style.setProperty('--apx-scrollable-body-max-height', normalizeMaxHeight(options.maxHeight));
-
-    table.classList.add(CLASS_TABLE);
-    table.classList.toggle('apx-scrollable-table--has-tfoot', !!(tfoot && tfootRows > 0));
-    table.classList.toggle('apx-scrollable-table--no-thead', !(thead && theadRows > 0));
-
-    clearPlacements(table);
-
-    const sections = [
-        { section: thead, rows: Math.max(1, theadRows) },
-        { section: tbody, rows: Math.max(1, tbodyRows) },
-        { section: tfoot, rows: Math.max(1, tfootRows) }
-    ];
-    sections.forEach(({ section, rows }) => {
-        if (!section) return;
-        const placements = computeCellPlacements(section, rows, numCols);
-        applyPlacements(placements);
-    });
-}
-
-/**
- * Augments the APX object with scrollableTable(options | 'refresh').
- * Makes the tbody of a table scrollable while keeping thead/tfoot fixed and columns aligned (CSS Grid + subgrid).
- *
- * @param {Object} apx - The APX object to augment.
- * @example
- * APX('table.data-grid').scrollableTable({ maxHeight: 300 });
- * APX('table.data-grid').scrollableTable('refresh');
- */
-export default function augmentWithScrollableTable(apx) {
-    apx.scrollableTable = function (optionsOrAction) {
-        const isRefresh = optionsOrAction === 'refresh';
-        const options = isRefresh ? null : (optionsOrAction && typeof optionsOrAction === 'object' ? optionsOrAction : {});
-
-        apx.elements.forEach((element) => {
-            if (element.tagName !== 'TABLE') return;
-            const table = /** @type {HTMLTableElement} */ (element);
-
-            const ref = table[DATA_KEY];
-            if (ref) {
-                if (isRefresh) {
-                    applyScrollableTable(table, ref.options);
-                } else if (options && Object.keys(options).length > 0) {
-                    ref.options = { ...ref.options, ...options };
-                    applyScrollableTable(table, ref.options);
-                }
-                return;
-            }
-            if (isRefresh) return;
-
-            applyScrollableTable(table, options);
-            table[DATA_KEY] = { options: { ...options } };
-        });
-
-        return apx;
-    };
-}
+import './css/scrollableTable.css';
+import { getScrollbarSize } from '../tools/getScrollbarSize.mjs';
+
+const DATA_KEY = '_apxScrollableTable';
+const CLASS_TABLE = 'apx-scrollable-table';
+
+const DEFAULT_MAX_HEIGHT = '200px';
+const DEFAULT_GUTTER_PX = 17;
+
+const THROTTLE_MS = 16;
+
+/** @type {Set<HTMLTableElement>} */
+const dynamicTables = new Set();
+/** @type {Map<Element, Set<HTMLTableElement>>} */
+const scrollSourceToTables = new Map();
+/** @type {Map<Element, Set<HTMLTableElement>>} */
+const resizeSourceToTables = new Map();
+/** @type {boolean} */
+let resizeWindowAttached = false;
+/** @type {ResizeObserver|null} */
+let resizeObserver = null;
+/** @type {number} */
+let throttleLast = 0;
+/** @type {number|null} */
+let throttleRaf = null;
+
+/**
+ * Sum of colspans for one row (direct th/td children of tr).
+ * @param {HTMLTableRowElement} tr
+ * @returns {number}
+ */
+function getRowColumnCount(tr) {
+    let cols = 0;
+    tr.querySelectorAll(':scope > th, :scope > td').forEach((cell) => {
+        cols += parseInt(cell.getAttribute('colspan'), 10) || 1;
+    });
+    return cols;
+}
+
+/**
+ * Get maximum column count in a section (max sum of colspans across all rows).
+ * @param {HTMLTableSectionElement} section - thead, tbody, or tfoot
+ * @returns {number}
+ */
+function getColumnCountFromSection(section) {
+    if (!section) return 0;
+    const rows = section.querySelectorAll(':scope > tr');
+    let maxCols = 0;
+    rows.forEach((tr) => {
+        const sum = getRowColumnCount(tr);
+        if (sum > maxCols) maxCols = sum;
+    });
+    return maxCols;
+}
+
+/**
+ * Get total column count for the table (max across thead, tbody, tfoot).
+ * @param {HTMLTableElement} table
+ * @returns {number}
+ */
+function getTableColumnCount(table) {
+    const thead = table.querySelector('thead');
+    const tbody = table.querySelector('tbody');
+    const tfoot = table.querySelector('tfoot');
+    const countThead = thead ? getColumnCountFromSection(thead) : 0;
+    const countTbody = tbody ? getColumnCountFromSection(tbody) : 0;
+    const countTfoot = tfoot ? getColumnCountFromSection(tfoot) : 0;
+    return Math.max(countThead, countTbody, countTfoot, 1);
+}
+
+/**
+ * Measure current column widths from the table in its natural layout (before applying scrollable class).
+ * Prefers a row where each cell has colspan 1 so we get one width per column; otherwise splits cell widths by colspan.
+ * @param {HTMLTableElement} table - table not yet with scrollable class
+ * @param {number} numCols
+ * @returns {number[]} pixel widths per column
+ */
+function measureColumnWidths(table, numCols) {
+    const thead = table.querySelector('thead');
+    const tbody = table.querySelector('tbody');
+    const sections = [thead, tbody].filter(Boolean);
+    /** @type {HTMLTableRowElement|null} */
+    let bestRow = null;
+    for (const section of sections) {
+        const rows = section.querySelectorAll(':scope > tr');
+        for (const tr of rows) {
+            const cells = tr.querySelectorAll(':scope > th, :scope > td');
+            if (getRowColumnCount(tr) !== numCols) continue;
+            const allSingle = Array.from(cells).every((c) => (parseInt(c.getAttribute('colspan'), 10) || 1) === 1);
+            if (allSingle && cells.length === numCols) {
+                bestRow = tr;
+                break;
+            }
+            if (!bestRow) bestRow = tr;
+        }
+        if (bestRow && Array.from(bestRow.querySelectorAll(':scope > th, :scope > td')).every((c) => (parseInt(c.getAttribute('colspan'), 10) || 1) === 1))
+            break;
+    }
+    if (!bestRow) return [];
+
+    const widths = new Array(numCols).fill(0);
+    const cells = bestRow.querySelectorAll(':scope > th, :scope > td');
+    let col = 0;
+    for (const cell of cells) {
+        const span = Math.min(parseInt(cell.getAttribute('colspan'), 10) || 1, numCols - col);
+        if (span <= 0) break;
+        const w = cell.getBoundingClientRect().width;
+        const perCol = w / span;
+        for (let i = 0; i < span; i++) widths[col + i] = perCol;
+        col += span;
+    }
+    if (col === 0) return [];
+    const fallback = widths.some((w) => w > 0) ? Math.max(80, ...widths.filter((w) => w > 0)) / 2 : 80;
+    for (let i = 0; i < numCols; i++) if (widths[i] <= 0) widths[i] = fallback;
+    return widths.slice(0, numCols);
+}
+
+/**
+ * Count direct tr children in a section.
+ * @param {HTMLTableSectionElement} section
+ * @returns {number}
+ */
+function getRowCount(section) {
+    if (!section) return 0;
+    return section.querySelectorAll(':scope > tr').length;
+}
+
+/**
+ * Build a 2D grid of occupied slots for a section (for rowspan/colspan placement).
+ * Place each cell in DOM order; return a list of { cell, row, col, colspan, rowspan }.
+ * @param {HTMLTableSectionElement} section
+ * @param {number} numRows
+ * @param {number} numCols
+ * @returns {{ cell: HTMLTableCellElement, row: number, col: number, colspan: number, rowspan: number }[]}
+ */
+function computeCellPlacements(section, numRows, numCols) {
+    if (!section || numRows === 0 || numCols === 0) return [];
+    const occupied = Array.from({ length: numRows }, () => Array(numCols).fill(false));
+    const placements = [];
+    const rows = section.querySelectorAll(':scope > tr');
+
+    for (let r = 0; r < rows.length; r++) {
+        const tr = rows[r];
+        const cells = tr.querySelectorAll(':scope > th, :scope > td');
+        for (const cell of cells) {
+            const colspan = Math.min(parseInt(cell.getAttribute('colspan'), 10) || 1, numCols);
+            const rowspan = Math.min(parseInt(cell.getAttribute('rowspan'), 10) || 1, numRows - r);
+            let col = 0;
+            while (col < numCols) {
+                let free = true;
+                for (let rr = r; rr < r + rowspan && free; rr++) {
+                    for (let cc = col; cc < col + colspan && free; cc++) {
+                        if (occupied[rr]?.[cc]) free = false;
+                    }
+                }
+                if (free) break;
+                col++;
+            }
+            if (col + colspan > numCols) continue;
+            for (let rr = r; rr < r + rowspan; rr++) {
+                for (let cc = col; cc < col + colspan; cc++) {
+                    if (occupied[rr]) occupied[rr][cc] = true;
+                }
+            }
+            placements.push({ cell, row: r, col, colspan, rowspan });
+        }
+    }
+    return placements;
+}
+
+/**
+ * Apply grid placement styles to a list of placements (1-based line numbers for CSS Grid).
+ */
+function applyPlacements(placements) {
+    placements.forEach(({ cell, row, col, colspan, rowspan }) => {
+        cell.style.gridRow = `${row + 1} / span ${rowspan}`;
+        cell.style.gridColumn = `${col + 1} / span ${colspan}`;
+    });
+}
+
+/**
+ * Clear grid placement styles from all th/td in a table (for refresh).
+ * @param {HTMLTableElement} table
+ */
+function clearPlacements(table) {
+    table.querySelectorAll('th, td').forEach((cell) => {
+        cell.style.gridRow = '';
+        cell.style.gridColumn = '';
+    });
+}
+
+/**
+ * Normalize height/maxHeight option to a CSS length string.
+ * @param {number|string} value
+ * @returns {string}
+ */
+function normalizeHeight(value) {
+    if (value == null) return DEFAULT_MAX_HEIGHT;
+    if (typeof value === 'number') return `${value}px`;
+    return String(value);
+}
+
+/**
+ * Resolve current body height from options: either bodyHeightDynamic.get(table) or static height/maxHeight.
+ * @param {Object} options - scrollableTable options (may include bodyHeightDynamic, height, maxHeight)
+ * @param {HTMLTableElement} table
+ * @returns {{ bodySize: string, useFixedHeight: boolean }}
+ */
+function resolveBodyHeight(options, table) {
+    const dyn = options.bodyHeightDynamic;
+    if (dyn && typeof dyn.get === 'function') {
+        const value = dyn.get(table);
+        const bodySize = normalizeHeight(value);
+        const useFixedHeight = dyn.useAs === 'height';
+        return { bodySize, useFixedHeight };
+    }
+    const useFixedHeight = options.height != null;
+    const raw = useFixedHeight ? options.height : options.maxHeight;
+    const bodySize = normalizeHeight(raw);
+    return { bodySize, useFixedHeight };
+}
+
+/**
+ * Update only the tbody height CSS variable and class (used on scroll/resize for dynamic height).
+ * @param {HTMLTableElement} table
+ * @param {Object} options - full scrollableTable options (with ref.options when called from throttle)
+ */
+function updateTableBodyHeight(table, options) {
+    const { bodySize, useFixedHeight } = resolveBodyHeight(options, table);
+    table.style.setProperty('--apx-scrollable-body-max-height', bodySize);
+    table.classList.toggle('apx-scrollable-table--body-height', useFixedHeight);
+}
+
+/**
+ * Run lazy cleanup then updateTableBodyHeight for all tables still in dynamicTables. (Called by throttled entry point or RAF.)
+ */
+function flushDynamicHeightUpdate() {
+    const toRemove = [];
+    dynamicTables.forEach((table) => {
+        if (!table.isConnected) toRemove.push(table);
+    });
+    toRemove.forEach((table) => removeTableFromDynamicSources(table));
+    dynamicTables.forEach((table) => {
+        const ref = table[DATA_KEY];
+        if (ref?.options) updateTableBodyHeight(table, ref.options);
+    });
+}
+
+/**
+ * Throttled entry: run flushDynamicHeightUpdate now or schedule with RAF.
+ */
+function runDynamicHeightUpdate() {
+    const now = Date.now();
+    if (now - throttleLast < THROTTLE_MS) {
+        if (!throttleRaf) {
+            throttleRaf = requestAnimationFrame(() => {
+                throttleRaf = null;
+                throttleLast = Date.now();
+                flushDynamicHeightUpdate();
+            });
+        }
+        return;
+    }
+    throttleLast = now;
+    flushDynamicHeightUpdate();
+}
+
+/**
+ * Resolve updateOn into scroll targets (Element[]) and resize: { window: boolean, elements: Element[] }.
+ * @param {Object} options - options.bodyHeightDynamic.updateOn
+ * @returns {{ scrollTargets: Element[], resizeWindow: boolean, resizeElements: Element[] }}
+ */
+function resolveUpdateOn(options) {
+    const u = options?.bodyHeightDynamic?.updateOn;
+    const scrollOn = u?.scrollOn;
+    const resizeOn = u?.resizeOn;
+    const scrollTargets = [];
+    if (scrollOn != null && Array.isArray(scrollOn) && scrollOn.length > 0) {
+        scrollOn.forEach((x) => {
+            if (x === 'document') scrollTargets.push(document.documentElement);
+            else if (x && typeof x.addEventListener === 'function') scrollTargets.push(x);
+        });
+    } else if (u?.scroll === true) {
+        scrollTargets.push(document.documentElement);
+        scrollTargets.push(typeof window !== 'undefined' ? window : document.documentElement);
+    }
+    let resizeWindow = false;
+    const resizeElements = [];
+    if (resizeOn != null && Array.isArray(resizeOn) && resizeOn.length > 0) {
+        resizeOn.forEach((x) => {
+            if (x === 'window') resizeWindow = true;
+            else if (x && typeof x.addEventListener === 'function') resizeElements.push(x);
+        });
+    } else if (u?.resize !== false) {
+        resizeWindow = true;
+        resizeElements.push(document.documentElement);
+    }
+    return { scrollTargets, resizeWindow, resizeElements };
+}
+
+/**
+ * Remove table from dynamicTables and from all scroll/resize Maps; detach listeners if Set becomes empty.
+ * @param {HTMLTableElement} table
+ */
+function removeTableFromDynamicSources(table) {
+    dynamicTables.delete(table);
+    scrollSourceToTables.forEach((set, el) => {
+        set.delete(table);
+        if (set.size === 0) {
+            scrollSourceToTables.delete(el);
+            el.removeEventListener('scroll', onScrollThrottled);
+        }
+    });
+    resizeSourceToTables.forEach((set, el) => {
+        set.delete(table);
+        if (set.size === 0) {
+            resizeSourceToTables.delete(el);
+            if (resizeObserver) resizeObserver.unobserve(el);
+        }
+    });
+    if (resizeWindowAttached && dynamicTables.size === 0) {
+        window.removeEventListener('resize', onResizeThrottled);
+        resizeWindowAttached = false;
+    }
+}
+
+function onScrollThrottled() {
+    runDynamicHeightUpdate();
+}
+
+function onResizeThrottled() {
+    runDynamicHeightUpdate();
+}
+
+/**
+ * Register a table with bodyHeightDynamic: add to Set and attach scroll/resize listeners per updateOn.
+ * @param {HTMLTableElement} table
+ * @param {Object} options - full options (ref.options)
+ */
+function registerDynamicTable(table, options) {
+    const { scrollTargets, resizeWindow, resizeElements } = resolveUpdateOn(options);
+    dynamicTables.add(table);
+    scrollTargets.forEach((el) => {
+        let set = scrollSourceToTables.get(el);
+        if (!set) {
+            set = new Set();
+            scrollSourceToTables.set(el, set);
+            el.addEventListener('scroll', onScrollThrottled, { passive: true });
+        }
+        set.add(table);
+    });
+    if (resizeWindow) {
+        if (!resizeWindowAttached) {
+            resizeWindowAttached = true;
+            window.addEventListener('resize', onResizeThrottled, { passive: true });
+        }
+    }
+    resizeElements.forEach((el) => {
+        let set = resizeSourceToTables.get(el);
+        if (!set) {
+            set = new Set();
+            resizeSourceToTables.set(el, set);
+            if (!resizeObserver) resizeObserver = new ResizeObserver(onResizeThrottled);
+            resizeObserver.observe(el);
+        }
+        set.add(table);
+    });
+}
+
+/**
+ * Build grid-template-columns from measured widths and optional overrides per column.
+ * @param {number} numCols
+ * @param {number[]} columnWidths
+ * @param {Object<number, string>|(string|null)[]} columnOverrides - map column index → CSS value (e.g. '2fr'), or array; null/empty = use measured
+ * @param {string} [unit='fr'] - CSS unit for measured widths ('fr' or 'px')
+ * @returns {string}
+ */
+function buildTemplateColumns(numCols, columnWidths, columnOverrides, unit = 'fr') {
+    if (!columnWidths || columnWidths.length !== numCols) return '';
+    const get = (i) =>
+        Array.isArray(columnOverrides) ? columnOverrides[i] : columnOverrides[i];
+    const parts = [];
+    for (let i = 0; i < numCols; i++) {
+        const ov = get(i);
+        if (ov != null && typeof ov === 'string' && ov.trim() !== '') {
+            parts.push(ov.trim());
+        } else {
+            parts.push(`${Math.round(columnWidths[i])}${unit}`);
+        }
+    }
+    return parts.join(' ');
+}
+
+/**
+ * Build grid-template-rows from measured heights and optional overrides per row.
+ * @param {number} numRows
+ * @param {number[]} rowHeights
+ * @param {Object<number, string>|(string|null)[]} rowOverrides - map row index → CSS value (e.g. '48px', '2fr'), or array; null/empty = use measured
+ * @param {string} [unit='px'] - CSS unit for measured heights ('px' or 'fr')
+ * @returns {string}
+ */
+function buildTemplateRows(numRows, rowHeights, rowOverrides, unit = 'px') {
+    if (!rowHeights || rowHeights.length < numRows) return '';
+    const get = (i) =>
+        Array.isArray(rowOverrides) ? rowOverrides[i] : rowOverrides?.[i];
+    const parts = [];
+    for (let i = 0; i < numRows; i++) {
+        const ov = get(i);
+        if (ov != null && typeof ov === 'string' && ov.trim() !== '') {
+            parts.push(ov.trim());
+        } else {
+            parts.push(`${Math.round(rowHeights[i] ?? 0)}${unit}`);
+        }
+    }
+    return parts.join(' ');
+}
+
+/**
+ * Measure each tr height in a section (table must not yet have scrollable class).
+ * @param {HTMLTableSectionElement|null} section
+ * @returns {number[]}
+ */
+function measureRowHeights(section) {
+    if (!section) return [];
+    const rows = section.querySelectorAll(':scope > tr');
+    return Array.from(rows).map((tr) => tr.getBoundingClientRect().height);
+}
+
+/**
+ * Apply scrollable table layout to a single table.
+ * @param {HTMLTableElement} table
+ * @param {Object} options - scrollableTable options
+ * @param {number|string} [options.maxHeight] - Max height of tbody (default '200px'). Ignored when height or bodyHeightDynamic is set.
+ * @param {number|string} [options.height] - Fixed height of tbody. Ignored when bodyHeightDynamic is set.
+ * @param {{ get: (function(HTMLTableElement): number|string), useAs: 'height'|'maxHeight', updateOn?: { scroll?: boolean, resize?: boolean, scrollOn?: ('document'|Element)[], resizeOn?: ('window'|Element)[] } }} [options.bodyHeightDynamic] - When set, body size is computed by get(table) and re-applied when scroll/resize sources fire. updateOn: scrollOn/resizeOn list elements (sentinels 'document'/'window'); or use scroll (default false) / resize (default true) booleans.
+ * @param {string} [options.gridTemplateColumns]
+ * @param {{ thead?: string, tbody?: string, tfoot?: string }} [options.gridTemplateRows]
+ * @param {{ thead?: Object<number, string>|(string|null)[], tbody?: Object<number, string>|(string|null)[], tfoot?: Object<number, string>|(string|null)[] }} [options.rowOverrides]
+ * @param {Object<number, string>|(string|null)[]} [options.columnOverrides]
+ * @param {{ cols?: string, rows?: string }} [options.defaultSizingUnit] - CSS unit for measured widths/heights. cols defaults to 'fr', rows defaults to 'px'.
+ * @param {{ columnWidths?: number[], rowHeights?: { thead?: number[], tbody?: number[], tfoot?: number[] } } | undefined} ref - existing ref when refreshing
+ */
+function applyScrollableTable(table, options, ref) {
+    const thead = table.querySelector('thead');
+    const tbody = table.querySelector('tbody');
+    const tfoot = table.querySelector('tfoot');
+
+    const numCols = getTableColumnCount(table);
+    if (numCols === 0) return;
+
+    const alreadyScrollable = table.classList.contains(CLASS_TABLE);
+    const customTemplate = typeof options.gridTemplateColumns === 'string' && options.gridTemplateColumns.trim().length > 0;
+    const columnWidths = customTemplate
+        ? null
+        : (ref?.columnWidths ?? (alreadyScrollable ? null : measureColumnWidths(table, numCols)));
+
+    const theadRows = getRowCount(thead);
+    const tbodyRows = getRowCount(tbody);
+    const tfootRows = getRowCount(tfoot);
+
+    const rowHeights =
+        ref?.rowHeights ??
+        (alreadyScrollable
+            ? null
+            : {
+                  thead: measureRowHeights(thead),
+                  tbody: measureRowHeights(tbody),
+                  tfoot: measureRowHeights(tfoot)
+              });
+
+    table.style.setProperty('--apx-scrollable-cols', String(numCols));
+    table.style.setProperty('--apx-scrollable-thead-rows', String(Math.max(1, theadRows)));
+    table.style.setProperty('--apx-scrollable-tbody-rows', String(Math.max(1, tbodyRows)));
+    table.style.setProperty('--apx-scrollable-tfoot-rows', String(Math.max(1, tfootRows)));
+    const { bodySize, useFixedHeight } = resolveBodyHeight(options, table);
+    table.style.setProperty('--apx-scrollable-body-max-height', bodySize);
+    table.classList.toggle('apx-scrollable-table--body-height', useFixedHeight);
+
+    table.classList.add(CLASS_TABLE);
+    table.classList.toggle('apx-scrollable-table--has-tfoot', !!(tfoot && tfootRows > 0));
+    table.classList.toggle('apx-scrollable-table--no-thead', !(thead && theadRows > 0));
+
+    // Force reflow so the grid layout is established before setting measured template-columns.
+    // Without this, the browser batches class + template into one pass and the tbody overflows horizontally.
+    table.offsetHeight; // eslint-disable-line no-unused-expressions
+
+    const colUnit = options.defaultSizingUnit?.cols || 'fr';
+    const rowUnit = options.defaultSizingUnit?.rows || 'px';
+
+    let gutterFallbackPx = DEFAULT_GUTTER_PX;
+    try {
+        const measured = getScrollbarSize('vertical');
+        if (typeof measured === 'number' && Number.isFinite(measured) && measured >= 0) {
+            gutterFallbackPx = measured;
+        }
+    } catch (_) {
+        /* use DEFAULT_GUTTER_PX */
+    }
+    const gutterSuffix = ` minmax(var(--apx-scrollable-gutter-width, ${gutterFallbackPx}px), var(--apx-scrollable-gutter-width, ${gutterFallbackPx}px))`;
+    if (customTemplate) {
+        table.style.setProperty('--apx-scrollable-template-columns', options.gridTemplateColumns.trim() + gutterSuffix);
+    } else if (columnWidths && columnWidths.length === numCols) {
+        const template =
+            options.columnOverrides != null
+                ? buildTemplateColumns(numCols, columnWidths, options.columnOverrides, colUnit)
+                : columnWidths.map((w) => `${Math.round(w)}${colUnit}`).join(' ');
+        table.style.setProperty('--apx-scrollable-template-columns', template + gutterSuffix);
+    } else {
+        table.style.removeProperty('--apx-scrollable-template-columns');
+    }
+
+    clearPlacements(table);
+
+    const sections = [
+        { section: thead, rows: Math.max(1, theadRows), heights: rowHeights?.thead, key: 'thead' },
+        { section: tbody, rows: Math.max(1, tbodyRows), heights: rowHeights?.tbody, key: 'tbody' },
+        { section: tfoot, rows: Math.max(1, tfootRows), heights: rowHeights?.tfoot, key: 'tfoot' }
+    ];
+    const customRows = options.gridTemplateRows && typeof options.gridTemplateRows === 'object' ? options.gridTemplateRows : null;
+    const rowOverrides = options.rowOverrides && typeof options.rowOverrides === 'object' ? options.rowOverrides : null;
+    sections.forEach(({ section, rows, heights, key }) => {
+        if (!section) return;
+        const varName = `--apx-scrollable-${key}-template-rows`;
+        const custom = customRows?.[key];
+        const overrides = rowOverrides?.[key];
+        if (typeof custom === 'string' && custom.trim().length > 0) {
+            section.style.setProperty(varName, custom.trim());
+        } else if (heights && heights.length >= rows) {
+            const template =
+                overrides != null
+                    ? buildTemplateRows(rows, heights.slice(0, rows), overrides, rowUnit)
+                    : heights
+                          .slice(0, rows)
+                          .map((h) => `${Math.round(h)}${rowUnit}`)
+                          .join(' ');
+            section.style.setProperty(varName, template);
+        } else {
+            section.style.removeProperty(varName);
+        }
+        const placements = computeCellPlacements(section, rows, numCols);
+        applyPlacements(placements);
+    });
+
+    return { columnWidths, rowHeights };
+}
+
+/**
+ * Augments the APX object with scrollableTable(options | 'refresh').
+ * Makes the tbody of a table scrollable while keeping thead/tfoot fixed and columns aligned (CSS Grid + subgrid).
+ *
+ * @param {Object} apx - The APX object to augment.
+ * @example
+ * APX('table.data-grid').scrollableTable({ maxHeight: 300 });
+ * APX('table.data-grid').scrollableTable('refresh');
+ */
+export default function augmentWithScrollableTable(apx) {
+    apx.scrollableTable = function (optionsOrAction) {
+        const isRefresh = optionsOrAction === 'refresh';
+        const options = isRefresh ? null : (optionsOrAction && typeof optionsOrAction === 'object' ? optionsOrAction : {});
+
+        apx.elements.forEach((element) => {
+            if (element.tagName !== 'TABLE') return;
+            const table = /** @type {HTMLTableElement} */ (element);
+
+            const ref = table[DATA_KEY];
+            if (ref) {
+                if (isRefresh) {
+                    applyScrollableTable(table, ref.options, ref);
+                } else if (options && Object.keys(options).length > 0) {
+                    ref.options = { ...ref.options, ...options };
+                    const result = applyScrollableTable(table, ref.options, ref);
+                    if (result?.columnWidths) ref.columnWidths = result.columnWidths;
+                    if (result?.rowHeights) ref.rowHeights = result.rowHeights;
+                }
+                const currentOptions = ref.options;
+                if (currentOptions?.bodyHeightDynamic) registerDynamicTable(table, currentOptions);
+                else removeTableFromDynamicSources(table);
+                return;
+            }
+            if (isRefresh) return;
+
+            console.log('[APX scrollableTable] create', table);
+            const result = applyScrollableTable(table, options, undefined);
+            table[DATA_KEY] = {
+                options: { ...options },
+                columnWidths: result?.columnWidths || undefined,
+                rowHeights: result?.rowHeights || undefined
+            };
+            if (options?.bodyHeightDynamic) registerDynamicTable(table, options);
+        });
+
+        return apx;
+    };
+}