photon-grid-core 2.0.1 → 2.0.5

package/renderer/header-renderer.js

@@ -1,11 +1,19 @@
+import { HeaderIconDisplay } from '../types/column.types';
 import { GridEventType } from '../types/event.types';
 import { ColumnMenu } from './column-menu';
 import { GroupContextMenu } from './group-context-menu';
 import { createDiv, toggleClass } from './dom-utils';
 import { resolveColumnRenderer } from './renderer-resolver';
+import { isTouchPointer, DRAG_THRESHOLD_MOUSE, DRAG_THRESHOLD_TOUCH, LONG_PRESS_MS, } from '../core/pointer-utils';
 export class HeaderRenderer {
     /** Read by grid-renderer's columns-store watcher to skip header destroy during drag */
     get isDraggingCol() { return this.isDragging; }
+    /**
+     * `true` while the header owns the pointer for a column reorder or resize.
+     * The ScrollController's touch-pan yields to this (see `setGestureGuard`) so a
+     * long-press reorder or an edge resize is never fought by kinetic scrolling.
+     */
+    get isBusy() { return this.isDragging || this._isResizingColumn; }
     /**
      * `true` between the resize-handle `mousedown` and the corresponding `mouseup`.
      * Grid-renderer uses this to suppress body `renderRows` during resize — column
@@ -91,8 +99,15 @@ export class HeaderRenderer {
         this.lastDragClientX = 0;
         /** Callback wired by GridRenderer to open a filter panel for a column. */
         this.openFilterPanelFn = null;
+        /** Callback wired by GridRenderer to open the Column Chooser dialog. */
+        this.openColumnChooserFn = null;
+        /** Callback wired by GridRenderer to re-run the data pipeline (e.g. after an aggregate change). */
+        this.columnDataRefreshFn = null;
         /** True while the user holds the resize handle and is actively moving the mouse. */
         this._isResizingColumn = false;
+        /** Column id and timestamp of the last resize-handle press, for double-click (auto-size) detection. */
+        this.lastResizeDownColId = '';
+        this.lastResizeDownAt = 0;
         // ─── Auto-scroll ──────────────────────────────────────────────────────────
         this.tickAutoScroll = () => {
             if (!this.isDragging || this.autoScrollSpeed === 0)
@@ -114,11 +129,11 @@ export class HeaderRenderer {
         };
         this.columnMenu = new ColumnMenu(columnModel, sortEngine, eventBus, iconRenderer, (action, colId) => this.onAction(action, colId));
         this.columnMenu.setMenuCallbacks({
-            onAutoSize: (colId) => this.onAction('autosize', colId),
-            onAutoSizeAll: () => this.onAction('autosize-all', ''),
-            onFitToGrid: () => this.onAction('fit-to-grid', ''),
-            onResetWidth: (colId) => this.onAction('reset-width', colId),
-            onOpenColumnChooser: () => this.onAction('column-chooser', ''),
+            onAutoSize: (colId) => { this.autoSizeColumns([colId]); this.onAction('autosize', colId); },
+            onAutoSizeAll: () => { this.autoSizeColumns(this.columnModel.getVisibleColumns().map((c) => c.colId)); this.onAction('autosize-all', ''); },
+            onFitToGrid: () => { this.fitColumnsToGrid(); this.onAction('fit-to-grid', ''); },
+            onResetWidth: (colId) => { this.resetColumnWidth(colId); this.onAction('reset-width', colId); },
+            onOpenColumnChooser: () => { this.openColumnChooserFn?.(); this.onAction('column-chooser', ''); },
             onOpenAdvancedFilter: (colDef, anchorEl) => {
                 this.openFilterPanelFn?.(colDef, anchorEl);
                 this.onAction('advanced-filter', colDef.colId);
@@ -130,12 +145,26 @@ export class HeaderRenderer {
             },
             onCopyColumn: (colDef) => this.onAction('copy-column', colDef.colId),
             onCopyValues: (colDef) => this.onAction('copy-values', colDef.colId),
-            onRename: (colDef) => this.onAction('rename', colDef.colId),
-            onDuplicate: (colDef) => this.onAction('duplicate', colDef.colId),
-            onFreezePosition: (colDef) => this.onAction('freeze', colDef.colId),
-            onLockColumn: (colDef) => this.onAction('lock', colDef.colId),
-            onResetColumn: (colDef) => this.onAction('reset-column', colDef.colId),
-            onAggregate: (colDef, func) => this.onAction(`aggregate-${func}`, colDef.colId),
+            onRename: (colDef) => { this.startHeaderRename(colDef.colId); this.onAction('rename', colDef.colId); },
+            onDuplicate: (colDef) => { this.columnModel.duplicateColumn(colDef.colId); this.onAction('duplicate', colDef.colId); },
+            onFreezePosition: (colDef) => { this.columnModel.toggleColumnFrozen(colDef.colId); this.onAction('freeze', colDef.colId); },
+            onLockColumn: (colDef) => { this.columnModel.toggleColumnLocked(colDef.colId); this.onAction('lock', colDef.colId); },
+            onResetColumn: (colDef) => { this.colStyles.clearUserWidth(colDef.colId); this.columnModel.resetColumn(colDef.colId); this.onAction('reset-column', colDef.colId); },
+            onAggregate: (colDef, func) => {
+                // Toggle: re-selecting the current function clears it.
+                const f = func;
+                const current = this.columnModel.getColumn(colDef.colId)?.aggFunc;
+                this.columnModel.setColumnAggFunc(colDef.colId, current === f ? null : f);
+                // aggFunc only affects the *grouped* aggregation display, so a data
+                // pipeline refresh is only needed when grouping is active. When it isn't,
+                // the change has no visible effect yet (it applies the next time rows are
+                // grouped) — so we skip refresh() to avoid rebuilding unrelated live
+                // views such as linked range charts, which watch `visibleRows`.
+                if (this.store.get('groupedColumnIds').length > 0) {
+                    this.columnDataRefreshFn?.();
+                }
+                this.onAction(`aggregate-${func}`, colDef.colId);
+            },
             onMoveLeft: (colId) => {
                 const cols = columnModel.getVisibleColumns();
                 const idx = cols.findIndex((c) => c.colId === colId);
@@ -171,6 +200,14 @@ export class HeaderRenderer {
         });
         this.boundMouseMove = this.onGlobalMouseMove.bind(this);
         this.boundMouseUp = this.onGlobalMouseUp.bind(this);
+        // Keep the sort arrows in sync in place. Sorting no longer rebuilds the
+        // header (that teardown fought the row animation), so the indicator is
+        // updated directly here — covering both header clicks and programmatic
+        // sorts. `colId === ''` (clear-all) clears every arrow.
+        this.eventBus.on(GridEventType.COLUMN_SORTED, (payload) => {
+            const p = payload;
+            this.updateSortIndicator(p.colId, p.order);
+        });
     }
     setScrollCallback(fn, canScrollX) {
         this.scrollByX = fn;
@@ -188,6 +225,25 @@ export class HeaderRenderer {
     setOpenFilterPanelCallback(fn) {
         this.openFilterPanelFn = fn;
     }
+    /**
+     * Registers the callback that opens the Column Chooser dialog, invoked from
+     * the column menu's and group menu's "Column Chooser…" items.
+     *
+     * @param fn - Opens the chooser (owned by `GridRenderer`).
+     */
+    setColumnChooserCallback(fn) {
+        this.openColumnChooserFn = fn;
+    }
+    /**
+     * Registers a callback that re-runs the grid's data pipeline (filter → sort →
+     * group → aggregate). Invoked after a column aggregate function changes so
+     * group aggregations recompute immediately when grouping is active.
+     *
+     * @param fn - Runs the pipeline + render (typically `GridApi.refresh`).
+     */
+    setColumnDataRefreshCallback(fn) {
+        this.columnDataRefreshFn = fn;
+    }
     /**
      * Wire the column-group model and DOM builder into the header renderer.
      *
@@ -214,7 +270,7 @@ export class HeaderRenderer {
         this.displayGroupEngine = engine;
         this.groupContextMenu = new GroupContextMenu(engine, this.iconRenderer);
         this.groupContextMenu.setCallbacks({
-            onOpenColumnChooser: () => this.onAction('column-chooser', ''),
+            onOpenColumnChooser: () => { this.openColumnChooserFn?.(); this.onAction('column-chooser', ''); },
             onAction: (action, groupId) => this.onAction(action, groupId),
         });
     }
@@ -397,13 +453,19 @@ export class HeaderRenderer {
         for (const row of rows) {
             for (const cell of Array.from(row.querySelectorAll('.pg-th[data-col-id]'))) {
                 const isTarget = cell.getAttribute('data-col-id') === colId;
+                const wasSorted = cell.classList.contains('pg-th--sorted');
                 toggleClass(cell, 'pg-th--sort-asc', isTarget && order === 'asc');
                 toggleClass(cell, 'pg-th--sort-desc', isTarget && order === 'desc');
                 toggleClass(cell, 'pg-th--sorted', isTarget && order !== null);
+                const iconEl = cell.querySelector('.pg-th__sort-icon');
+                if (!iconEl)
+                    continue;
                 if (isTarget) {
-                    const iconEl = cell.querySelector('.pg-th__sort-icon');
-                    if (iconEl)
-                        this.iconRenderer.updateIcon(iconEl, order === 'asc' ? 'sortAsc' : order === 'desc' ? 'sortDesc' : 'sortNone');
+                    this.iconRenderer.updateIcon(iconEl, order === 'asc' ? 'sortAsc' : order === 'desc' ? 'sortDesc' : 'sortNone');
+                }
+                else if (wasSorted) {
+                    // A different column just became the sort target — clear this one's arrow.
+                    this.iconRenderer.updateIcon(iconEl, 'sortNone');
                 }
             }
         }
@@ -423,8 +485,8 @@ export class HeaderRenderer {
         });
     }
     destroy() {
-        document.removeEventListener('mousemove', this.boundMouseMove);
-        document.removeEventListener('mouseup', this.boundMouseUp);
+        document.removeEventListener('pointermove', this.boundMouseMove);
+        document.removeEventListener('pointerup', this.boundMouseUp);
         this.columnMenu.destroy();
         this.groupContextMenu?.destroy();
         this.leftHeaderRowEl = null;
@@ -625,12 +687,17 @@ export class HeaderRenderer {
             }
             th.appendChild(content);
         }
-        // Filter icon — visible on hover; always visible when a filter is active.
-        if (col.filterable !== false) {
+        // Filter icon — reveal-on-hover by default; always visible when a filter is
+        // active, or when the column/grid opts into `HeaderIconDisplay.ALWAYS`.
+        // Skipped entirely when the mode is `HeaderIconDisplay.HIDDEN`.
+        const filterMode = col.filterIconDisplay ?? options.filterIconDisplay ?? HeaderIconDisplay.HOVER;
+        if (col.filterable !== false && filterMode !== HeaderIconDisplay.HIDDEN) {
             const filterBtn = createDiv('pg-th__filter-btn');
             const filterActive = col.filterActive === true;
             if (filterActive)
                 filterBtn.classList.add('pg-th__filter-btn--active');
+            if (filterMode === HeaderIconDisplay.ALWAYS)
+                filterBtn.classList.add('pg-th__filter-btn--always');
             filterBtn.innerHTML = this.iconRenderer.renderToString(filterActive ? 'filterActive' : 'filter', 14);
             filterBtn.title = 'Filter column';
             filterBtn.setAttribute('tabindex', '0');
@@ -641,8 +708,13 @@ export class HeaderRenderer {
             });
             th.appendChild(filterBtn);
         }
-        if (options.showColumnMenu !== false) {
+        // Column-menu "⋯" icon — hidden entirely when the mode is
+        // `HeaderIconDisplay.HIDDEN` (the header right-click menu still works).
+        const menuMode = col.menuIconDisplay ?? options.menuIconDisplay ?? HeaderIconDisplay.HOVER;
+        if (options.showColumnMenu !== false && menuMode !== HeaderIconDisplay.HIDDEN) {
             const menuBtn = createDiv('pg-th__menu-btn');
+            if (menuMode === HeaderIconDisplay.ALWAYS)
+                menuBtn.classList.add('pg-th__menu-btn--always');
             menuBtn.innerHTML = this.iconRenderer.renderToString('menuHorizontal', 14);
             menuBtn.title = 'Column options';
             menuBtn.setAttribute('tabindex', '0');
@@ -658,7 +730,27 @@ export class HeaderRenderer {
         if (col.resizable !== false) {
             const resizeHandle = createDiv('pg-th__resize-handle');
             // resizeHandle.innerHTML = '|';
-            resizeHandle.addEventListener('mousedown', (e) => { e.preventDefault(); e.stopPropagation(); this.startResize(e, col, th); });
+            resizeHandle.addEventListener('pointerdown', (e) => {
+                if (e.button !== 0)
+                    return;
+                e.preventDefault();
+                e.stopPropagation();
+                // Double-press on the same handle → auto-size the column (AG Grid
+                // convention). Detected by timing rather than the native `dblclick`
+                // event: the first press's mouseup can rebuild the header
+                // (COLUMNS_STATE_CHANGED) and replace this element, so a native dblclick
+                // would never fire on the original node. Keying on colId survives that.
+                if (this.lastResizeDownColId === col.colId && e.timeStamp - this.lastResizeDownAt < 350) {
+                    this.lastResizeDownColId = '';
+                    this.lastResizeDownAt = 0;
+                    this.autoSizeColumns([col.colId]);
+                    this.onAction('autosize', col.colId);
+                    return;
+                }
+                this.lastResizeDownColId = col.colId;
+                this.lastResizeDownAt = e.timeStamp;
+                this.startResize(e, col, th);
+            });
             th.appendChild(resizeHandle);
         }
         if (col.sortable !== false) {
@@ -710,30 +802,71 @@ export class HeaderRenderer {
         return row;
     }
     attachColumnDragListeners(th, col, _panelColumns, panelRowEl) {
-        th.addEventListener('mousedown', (e) => {
+        th.addEventListener('pointerdown', (e) => {
             if (e.target.closest('.pg-th__resize-handle, .pg-th__menu-btn, .pg-th__filter-btn, .pg-checkbox'))
                 return;
             if (col.draggable === false || e.button !== 0)
                 return;
             const startX = e.clientX;
-            let moved = false;
-            const onMoveCheck = (ev) => {
-                if (!moved && Math.abs(ev.clientX - startX) > 5) {
-                    moved = true;
-                    this.startColumnDrag(col, panelRowEl);
-                    document.removeEventListener('mousemove', onMoveCheck);
-                    document.addEventListener('mousemove', this.boundMouseMove);
-                    document.addEventListener('mouseup', this.boundMouseUp);
+            const startY = e.clientY;
+            const touch = isTouchPointer(e);
+            let started = false; // actual column drag engaged
+            let longPressTimer = 0;
+            // Tear down the pre-drag probe listeners + long-press timer + affordance.
+            const cleanupProbe = () => {
+                if (longPressTimer) {
+                    clearTimeout(longPressTimer);
+                    longPressTimer = 0;
+                }
+                th.classList.remove('pg-th--drag-armed');
+                document.removeEventListener('pointermove', onMoveCheck);
+                document.removeEventListener('pointerup', onUpEarly);
+            };
+            // Promote the press to a live column drag and hand movement over to the
+            // global drag handlers. Called by the mouse threshold or the touch
+            // long-press timer.
+            const beginDrag = () => {
+                if (started)
+                    return;
+                started = true;
+                if (longPressTimer) {
+                    clearTimeout(longPressTimer);
+                    longPressTimer = 0;
                 }
-                if (moved)
-                    this.onDragMove(ev.clientX);
+                th.classList.remove('pg-th--drag-armed');
+                this.startColumnDrag(col, panelRowEl);
+                document.removeEventListener('pointermove', onMoveCheck);
+                document.addEventListener('pointermove', this.boundMouseMove);
+                document.addEventListener('pointerup', this.boundMouseUp);
+                this.onDragMove(startX);
             };
-            const onUpEarly = () => {
-                document.removeEventListener('mousemove', onMoveCheck);
-                document.removeEventListener('mouseup', onUpEarly);
+            const onMoveCheck = (ev) => {
+                if (started)
+                    return; // global handlers own movement now
+                const dx = Math.abs(ev.clientX - startX);
+                const dy = Math.abs(ev.clientY - startY);
+                if (touch) {
+                    // Movement before the long-press fires means the user is swiping to
+                    // scroll, not reordering — abandon so the ScrollController pans.
+                    if (dx > DRAG_THRESHOLD_TOUCH || dy > DRAG_THRESHOLD_TOUCH)
+                        cleanupProbe();
+                }
+                else if (dx > DRAG_THRESHOLD_MOUSE) {
+                    beginDrag();
+                }
             };
-            document.addEventListener('mousemove', onMoveCheck);
-            document.addEventListener('mouseup', onUpEarly);
+            const onUpEarly = () => { if (!started)
+                cleanupProbe(); };
+            document.addEventListener('pointermove', onMoveCheck);
+            document.addEventListener('pointerup', onUpEarly);
+            if (touch) {
+                // Arm a long-press: hold ~400ms without swiping to pick the column up.
+                th.classList.add('pg-th--drag-armed');
+                longPressTimer = window.setTimeout(() => {
+                    longPressTimer = 0;
+                    beginDrag();
+                }, LONG_PRESS_MS);
+            }
         });
     }
     startColumnDrag(col, panelRowEl) {
@@ -1279,17 +1412,12 @@ export class HeaderRenderer {
         this.draggingPanelRowEl = null;
         document.body.style.cursor = '';
         document.body.style.userSelect = '';
-        document.removeEventListener('mousemove', this.boundMouseMove);
-        document.removeEventListener('mouseup', this.boundMouseUp);
+        document.removeEventListener('pointermove', this.boundMouseMove);
+        document.removeEventListener('pointerup', this.boundMouseUp);
     }
     startResize(e, col, thEl) {
         const startX = e.clientX;
         const startWidth = this.colStyles.getWidth(col.colId);
-        // Lock every flex column to its current pixel width up front, so dragging
-        // this one resizes only it — the others keep their widths (and the total
-        // may overflow into a horizontal scrollbar) instead of flex redistributing
-        // the container and collapsing them to minWidth.
-        this.colStyles.freezeFlexWidths();
         // Right-pinned columns anchor their right edge to the grid border, so their
         // resize handle sits on the *left* (inner) edge — the only edge free to move.
         // Dragging that edge left must therefore widen the column, so the pointer
@@ -1297,11 +1425,27 @@ export class HeaderRenderer {
         // their right-edge handle: dragging right widens.
         const dir = col.pinned === 'right' ? -1 : 1;
         const minWidth = col.minWidth ?? 60;
-        thEl.classList.add('pg-th--resizing');
         document.body.style.cursor = 'col-resize';
         document.body.style.userSelect = 'none';
         this._isResizingColumn = true;
+        // Only treat this as a resize once the pointer actually moves past a small
+        // threshold. A bare click (e.g. the first press of a double-click) must not
+        // resize, rebuild the header, or freeze flex columns — otherwise the handle
+        // element is replaced mid-gesture and the double-click auto-size is lost.
+        let moved = false;
         const onMove = (ev) => {
+            if (!moved) {
+                if (Math.abs(ev.clientX - startX) <= 2)
+                    return;
+                moved = true;
+                thEl.classList.add('pg-th--resizing');
+                // Lock every flex column to its current pixel width so dragging this one
+                // resizes only it — the others keep their widths (the total may overflow
+                // into a horizontal scrollbar) instead of flex redistributing and
+                // collapsing them to minWidth. Done here (not on mousedown) so a plain
+                // click never silently converts flex columns to fixed.
+                this.colStyles.freezeFlexWidths();
+            }
             this.colStyles.setWidth(col.colId, Math.max(minWidth, startWidth + (ev.clientX - startX) * dir));
             this.onResizeCb?.();
         };
@@ -1309,17 +1453,19 @@ export class HeaderRenderer {
             // Clear the flag BEFORE setColumnWidth fires an event so the final
             // post-resize render calls renderRows normally and the body is correct.
             this._isResizingColumn = false;
-            const newWidth = Math.max(minWidth, startWidth + (ev.clientX - startX) * dir);
-            this.colStyles.setWidth(col.colId, newWidth);
-            this.columnModel.setColumnWidth(col.colId, newWidth, true);
             thEl.classList.remove('pg-th--resizing');
             document.body.style.cursor = '';
             document.body.style.userSelect = '';
-            document.removeEventListener('mousemove', onMove);
-            document.removeEventListener('mouseup', onUp);
+            document.removeEventListener('pointermove', onMove);
+            document.removeEventListener('pointerup', onUp);
+            if (!moved)
+                return; // no drag occurred — leave widths untouched
+            const newWidth = Math.max(minWidth, startWidth + (ev.clientX - startX) * dir);
+            this.colStyles.setWidth(col.colId, newWidth);
+            this.columnModel.setColumnWidth(col.colId, newWidth, true);
         };
-        document.addEventListener('mousemove', onMove);
-        document.addEventListener('mouseup', onUp);
+        document.addEventListener('pointermove', onMove);
+        document.addEventListener('pointerup', onUp);
     }
     /**
      * Returns `true` when `colId` (at its new position `newIdx` in the visible
@@ -1343,6 +1489,169 @@ export class HeaderRenderer {
         const right = cols[newIdx + 1];
         return !(left && siblings.has(left.colId)) && !(right && siblings.has(right.colId));
     }
+    // ──────────────────── Column menu: resize operations ────────────────────
+    /** Resolves the owning `.pg-grid` element from any live header row, or `null`. */
+    getGridEl() {
+        return (this.centerHeaderRowEl ?? this.leftHeaderRowEl ?? this.rightHeaderRowEl)
+            ?.closest('.pg-grid') ?? null;
+    }
+    /**
+     * Starts an inline rename of a column: replaces the header label with a text
+     * input, committing on Enter/blur and cancelling on Escape. Committing calls
+     * {@link ColumnModel.setColumnHeader}, which rebuilds the header with the new
+     * text. A no-op when the header cell can't be found.
+     */
+    startHeaderRename(colId) {
+        const gridEl = this.getGridEl();
+        const th = gridEl?.querySelector(`.pg-th[data-col-id="${colId}"]`);
+        const label = th?.querySelector('.pg-th__label');
+        const col = this.columnModel.getColumn(colId);
+        if (!th || !label || !col)
+            return;
+        const input = document.createElement('input');
+        input.className = 'pg-th__rename-input';
+        input.type = 'text';
+        input.value = col.header;
+        input.setAttribute('aria-label', 'Rename column');
+        let done = false;
+        const commit = () => {
+            if (done)
+                return;
+            done = true;
+            const value = input.value.trim();
+            if (value && value !== col.header) {
+                this.columnModel.setColumnHeader(colId, value); // triggers header rebuild
+            }
+            else {
+                input.replaceWith(label); // unchanged → restore original label
+            }
+        };
+        const cancel = () => {
+            if (done)
+                return;
+            done = true;
+            input.replaceWith(label);
+        };
+        input.addEventListener('keydown', (e) => {
+            e.stopPropagation();
+            if (e.key === 'Enter') {
+                e.preventDefault();
+                commit();
+            }
+            else if (e.key === 'Escape') {
+                e.preventDefault();
+                cancel();
+            }
+        });
+        input.addEventListener('blur', commit);
+        // Don't let the input's own clicks reach the header's sort/drag handlers.
+        input.addEventListener('mousedown', (e) => e.stopPropagation());
+        input.addEventListener('click', (e) => e.stopPropagation());
+        label.replaceWith(input);
+        input.focus();
+        input.select();
+    }
+    /**
+     * Measures the pixel width needed to show a column's header plus every
+     * currently-rendered cell without truncation, clamped to the column's
+     * min/max. Only virtualized (on-screen) rows are measured, so the cost scales
+     * with the viewport, not the dataset. Uses one reused off-screen `<span>` so
+     * cell fonts/metrics match the grid.
+     */
+    measureColumnContentWidth(gridEl, col) {
+        const measurer = gridEl.ownerDocument.createElement('span');
+        measurer.style.cssText =
+            'position:absolute;top:-9999px;left:-9999px;visibility:hidden;white-space:nowrap;pointer-events:none;padding:0 12px;';
+        gridEl.appendChild(measurer);
+        measurer.textContent = col.header ?? '';
+        let maxWidth = measurer.offsetWidth + 24; // header text + sort/menu affordance headroom
+        const cells = gridEl.querySelectorAll(`.pg-cell[data-col-id="${col.colId}"]`);
+        for (let i = 0; i < cells.length; i++) {
+            measurer.textContent = cells[i].textContent ?? '';
+            const w = measurer.offsetWidth + 24;
+            if (w > maxWidth)
+                maxWidth = w;
+        }
+        measurer.remove();
+        const min = col.minWidth ?? 40;
+        const max = col.maxWidth ?? Infinity;
+        return Math.round(Math.min(max, Math.max(min, maxWidth)));
+    }
+    /**
+     * Auto-sizes the given columns to their content width. Measures each, then
+     * commits all widths in a single style flush + single render (via the batch
+     * setters), so "Auto Size All" stays cheap. A no-op if the grid DOM or the
+     * columns cannot be resolved.
+     */
+    autoSizeColumns(colIds) {
+        const gridEl = this.getGridEl();
+        if (!gridEl)
+            return;
+        const entries = [];
+        for (const colId of colIds) {
+            const col = this.columnModel.getColumn(colId);
+            if (!col)
+                continue;
+            entries.push([colId, this.measureColumnContentWidth(gridEl, col)]);
+        }
+        if (entries.length === 0)
+            return;
+        // Style manager first (immediate CSS width + marks fixed so flex can't
+        // override), then the model (persisted state + one COLUMNS_STATE_CHANGED
+        // that drives the re-render and scrollbar/content-width recompute).
+        this.colStyles.setWidths(entries);
+        this.columnModel.setColumnWidths(entries);
+    }
+    /**
+     * Distributes the center viewport width across the visible unpinned columns
+     * so they exactly fill the grid with no horizontal scroll (proportional to
+     * current widths, clamped to each column's min/max). Pinned columns keep
+     * their widths. A no-op when the center viewport can't be measured.
+     */
+    fitColumnsToGrid() {
+        const gridEl = this.getGridEl();
+        if (!gridEl)
+            return;
+        const centerBody = gridEl.querySelector('.pg-panel--center .pg-panel__body');
+        const available = centerBody?.clientWidth ?? 0;
+        if (available <= 0)
+            return;
+        const centerCols = this.columnModel
+            .getVisibleColumns()
+            .filter((c) => c.pinned !== 'left' && c.pinned !== 'right');
+        if (centerCols.length === 0)
+            return;
+        const totalCurrent = centerCols.reduce((sum, c) => sum + this.colStyles.getWidth(c.colId), 0) || 1;
+        const entries = [];
+        let allocated = 0;
+        for (const c of centerCols) {
+            const min = c.minWidth ?? 40;
+            const max = c.maxWidth ?? Infinity;
+            const w = Math.min(max, Math.max(min, Math.round((this.colStyles.getWidth(c.colId) / totalCurrent) * available)));
+            entries.push([c.colId, w]);
+            allocated += w;
+        }
+        // Absorb rounding/clamping drift into the last column so the total is exact.
+        const diff = available - allocated;
+        if (diff !== 0) {
+            const lastCol = centerCols[centerCols.length - 1];
+            const min = lastCol.minWidth ?? 40;
+            const max = lastCol.maxWidth ?? Infinity;
+            const last = entries[entries.length - 1];
+            entries[entries.length - 1] = [last[0], Math.min(max, Math.max(min, last[1] + diff))];
+        }
+        this.colStyles.setWidths(entries);
+        this.columnModel.setColumnWidths(entries);
+    }
+    /**
+     * Resets a column's width to its original definition. Clears the user-fixed
+     * override in the style manager (so a `flex` column resumes flexing) and
+     * restores the model's width, which re-renders via `COLUMNS_STATE_CHANGED`.
+     */
+    resetColumnWidth(colId) {
+        this.colStyles.clearUserWidth(colId);
+        this.columnModel.resetColumnWidth(colId);
+    }
     onAction(action, colId) {
         this.eventBus.emit(GridEventType.COLUMNS_STATE_CHANGED, {
             action, colId, states: this.columnModel.getColumnStates(),