@opencorestack/opengridx 2.0.4 → 3.0.0

package/lib/hooks/core/useLayout.ts

@@ -1,16 +1,24 @@
 import { useMemo } from 'react';
 import type { GridColDef, GridRowModel, GridRowId, GridColumnPinning, GridDetailPanelHeight } from '../../types';
-import { isColumnPinned } from '../../utils/pinning';
+import { getPinnedColumnGroups, SYSTEM_COLUMN_WIDTH } from '../../utils/pinning';
+import { clampColumnWidth } from '../../utils/columnWidth';
+import { callGetDetailPanelHeight, getDetailPanelLayoutHeight } from '../../utils/detailPanel';
 
 export interface UseLayoutParams<R extends GridRowModel> {
     rowHeight: number;
     pagination: boolean;
     paginatedUnpinnedRows: R[];
     sortedUnpinnedRows: R[];
+    /** Rows whose detail panel is open; the caller leaves out synthetic group rows (getDetailPanelRowIds). */
     expandedRowIds: Set<GridRowId>;
     getDetailPanelHeight?: (params: { row: R; id: GridRowId; rowIndex: number }) => GridDetailPanelHeight;
+    /** Rendered heights of `'auto'` detail panels, by row id (measured by the panels themselves). */
+    detailPanelHeights?: Map<GridRowId, number>;
     pinnedTopRowsLength: number;
     pinnedBottomRowsLength: number;
+    /** The pinned rows themselves; when given, their expanded detail panels count towards the pinned heights. */
+    pinnedTopRows?: R[];
+    pinnedBottomRows?: R[];
     visibleOrderedColumns: GridColDef<R>[];
     pinnedColumns?: GridColumnPinning;
     columnWidths: Record<string, number>;
@@ -24,15 +32,21 @@ export interface UseLayoutParams<R extends GridRowModel> {
     paginationMode: string;
     isLoading: boolean;
     pageSize: number;
+    /** Resolves a row's id (getRowId) for the expanded-detail-panel lookup; defaults to `row.id`. */
+    getRowId?: (row: R) => GridRowId;
 }
 
+const defaultGetRowId = <R extends GridRowModel>(row: R): GridRowId => row.id;
+
 export interface LayoutResult<R extends GridRowModel> {
     rowHeights: number[];
     cumulativeHeights: number[];
     unpinnedRowsHeight: number;
     pinnedTopHeight: number;
     pinnedBottomHeight: number;
+    /** Left-pinned columns in render order (`pinnedColumns.left` order) with resolved widths. */
     leftPinnedCols: (GridColDef<R> & { width: number; zIndex: number })[];
+    /** Right-pinned columns in render order (`pinnedColumns.right` order) with resolved widths. */
     rightPinnedCols: (GridColDef<R> & { width: number; zIndex: number })[];
     unpinnedColsWithWidth: (GridColDef<R> & { width: number })[];
     unpinnedColWidths: number[];
@@ -41,7 +55,10 @@ export interface LayoutResult<R extends GridRowModel> {
     leftWidth: number;
     rightWidth: number;
     unpinnedTotalWidth: number;
+    /** Width of all system columns (drag handle, detail toggle, checkbox). */
     systemColumnsWidth: number;
+    /** Width of the system columns that stay sticky on horizontal scroll. */
+    pinnedSystemColumnsWidth: number;
     pinnedTopRowsLength: number;
     pinnedBottomRowsLength: number;
     unpinnedRowsLength: number;
@@ -62,6 +79,144 @@ function parseWidth(width: number | string | undefined): { type: 'fixed' | 'perc
     return { type: 'fixed', value: 100 };
 }
 
+type WidthSpec =
+    | { kind: 'fixed'; width: number }
+    | { kind: 'percentage'; percentage: number }
+    | { kind: 'flex'; flex: number };
+
+/**
+ * Resolves every visible column to a pixel width. Pinned and unpinned columns follow the same
+ * rules, and every width is clamped to the column's minWidth / maxWidth (as the cell CSS is):
+ * - a number (or a manual resize) is used as is;
+ * - percentages are all taken of the same base: the data area left after the fixed-width columns;
+ * - flex and 'auto' columns share what is left after that.
+ */
+function resolveColumnWidths<R extends GridRowModel>(
+    columns: GridColDef<R>[],
+    columnWidths: Record<string, number>,
+    dataAreaWidth: number,
+): { widths: Map<string, number>; flexByField: Map<string, number> } {
+    const specs = new Map<string, WidthSpec>();
+    columns.forEach(col => {
+        const hasManualWidth = Object.prototype.hasOwnProperty.call(columnWidths, col.field);
+        if (!hasManualWidth && col.flex && col.flex > 0) {
+            specs.set(col.field, { kind: 'flex', flex: col.flex });
+            return;
+        }
+        const parsed = parseWidth(columnWidths[col.field] ?? col.width);
+        if (parsed.type === 'fixed') {
+            specs.set(col.field, { kind: 'fixed', width: clampColumnWidth(parsed.value, col.minWidth, col.maxWidth) });
+        } else if (parsed.type === 'percentage') {
+            specs.set(col.field, { kind: 'percentage', percentage: parsed.value });
+        } else {
+            specs.set(col.field, { kind: 'flex', flex: 1 });
+        }
+    });
+
+    // Widths the columns need before any sharing, so an overflowing grid scrolls instead of squashing.
+    const naturalWidth = columns.reduce((sum, col) => {
+        const spec = specs.get(col.field)!;
+        if (spec.kind === 'fixed') return sum + spec.width;
+        if (spec.kind === 'percentage') return sum + 100;
+        if (col.flex && col.flex > 0) {
+            const minWidth = col.minWidth ?? 150;
+            return sum + (minWidth || (typeof col.width === 'number' ? col.width : 150));
+        }
+        return sum + (col.minWidth ?? 150);
+    }, 0);
+
+    const availableWidth = Math.max(dataAreaWidth, naturalWidth);
+    const fixedWidth = columns.reduce((sum, col) => {
+        const spec = specs.get(col.field)!;
+        return spec.kind === 'fixed' ? sum + spec.width : sum;
+    }, 0);
+
+    const widths = new Map<string, number>();
+    const percentageBase = Math.max(0, availableWidth - fixedWidth);
+    let percentageTotal = 0;
+    columns.forEach(col => {
+        const spec = specs.get(col.field)!;
+        if (spec.kind === 'fixed') {
+            widths.set(col.field, spec.width);
+        } else if (spec.kind === 'percentage') {
+            const raw = (spec.percentage / 100) * percentageBase;
+            const width = clampColumnWidth(raw > 0 ? raw : 100, col.minWidth ?? 50, col.maxWidth);
+            widths.set(col.field, width);
+            percentageTotal += width;
+        }
+    });
+
+    const freeSpace = Math.max(0, percentageBase - percentageTotal);
+    const flexByField = new Map<string, number>();
+    const flexItems = columns.flatMap(col => {
+        const spec = specs.get(col.field)!;
+        if (spec.kind !== 'flex') return [];
+        flexByField.set(col.field, spec.flex);
+        return [{
+            field: col.field,
+            flex: spec.flex,
+            minWidth: col.minWidth ?? 50,
+            maxWidth: col.maxWidth ?? Infinity,
+            frozen: false,
+            computedWidth: 0,
+        }];
+    });
+
+    // Distributes the free space by flex weight, freezing items that hit their min/max and
+    // redistributing, the way CSS flexbox resolves flexible lengths.
+    let iterations = 0;
+    const maxIterations = flexItems.length * 2;
+    while (iterations < maxIterations) {
+        iterations++;
+        const unfrozen = flexItems.filter(f => !f.frozen);
+        if (unfrozen.length === 0) break;
+
+        const unfrozenFlexTotal = unfrozen.reduce((sum, f) => sum + f.flex, 0);
+        const frozenWidthTotal = flexItems.reduce((sum, f) => f.frozen ? sum + f.computedWidth : sum, 0);
+        const currentFreeSpace = Math.max(0, freeSpace - frozenWidthTotal);
+
+        if (unfrozenFlexTotal <= 0) {
+            unfrozen.forEach(f => { f.computedWidth = f.minWidth; f.frozen = true; });
+            break;
+        }
+
+        const pixelsPerFlex = currentFreeSpace / unfrozenFlexTotal;
+        let totalViolation = 0;
+        const minViolators: typeof flexItems = [];
+        const maxViolators: typeof flexItems = [];
+
+        unfrozen.forEach(f => {
+            const rawWidth = pixelsPerFlex * f.flex;
+            if (rawWidth < f.minWidth) {
+                totalViolation += f.minWidth - rawWidth;
+                minViolators.push(f);
+            } else if (rawWidth > f.maxWidth) {
+                totalViolation += f.maxWidth - rawWidth;
+                maxViolators.push(f);
+            } else {
+                f.computedWidth = rawWidth;
+            }
+        });
+
+        if (minViolators.length === 0 && maxViolators.length === 0) {
+            unfrozen.forEach(f => { f.frozen = true; });
+            break;
+        }
+
+        if (totalViolation > 0) {
+            minViolators.forEach(f => { f.computedWidth = f.minWidth; f.frozen = true; });
+        } else if (totalViolation < 0) {
+            maxViolators.forEach(f => { f.computedWidth = f.maxWidth; f.frozen = true; });
+        } else {
+            minViolators.forEach(f => { f.computedWidth = f.minWidth; f.frozen = true; });
+            maxViolators.forEach(f => { f.computedWidth = f.maxWidth; f.frozen = true; });
+        }
+    }
+    flexItems.forEach(f => widths.set(f.field, f.computedWidth));
+
+    return { widths, flexByField };
+}
+
 export function useLayout<R extends GridRowModel>(params: UseLayoutParams<R>): LayoutResult<R> {
     const {
         rowHeight,
@@ -70,8 +225,11 @@ export function useLayout<R extends GridRowModel>(params: UseLayoutParams<R>): L
         sortedUnpinnedRows,
         expandedRowIds,
         getDetailPanelHeight,
+        detailPanelHeights,
         pinnedTopRowsLength,
         pinnedBottomRowsLength,
+        pinnedTopRows,
+        pinnedBottomRows,
         visibleOrderedColumns,
         pinnedColumns,
         columnWidths,
@@ -79,22 +237,25 @@ export function useLayout<R extends GridRowModel>(params: UseLayoutParams<R>): L
         checkboxSelection,
         hasDetailPanel,
         rowReordering,
+        pinCheckboxColumn,
+        pinExpandColumn,
         paginationMode,
         isLoading,
         pageSize,
+        getRowId = defaultGetRowId,
     } = params;
 
     return useMemo<LayoutResult<R>>(() => {
         const unpinnedRows = pagination ? paginatedUnpinnedRows : sortedUnpinnedRows;
 
-        const rowHeights = unpinnedRows.map((row, index) => {
-            let height = rowHeight;
-            if (expandedRowIds.has(row.id)) {
-                const detailHeight = getDetailPanelHeight?.({ row, id: row.id, rowIndex: pinnedTopRowsLength + index }) ?? 200;
-                height += typeof detailHeight === 'number' ? detailHeight : parseInt(String(detailHeight), 10) || 200;
-            }
-            return height;
-        });
+        const heightOf = (row: R, rowIndex: number) => {
+            const id = getRowId(row);
+            if (!expandedRowIds.has(id)) return rowHeight;
+            const panelHeight = callGetDetailPanelHeight(getDetailPanelHeight, { row, id, rowIndex });
+            return rowHeight + getDetailPanelLayoutHeight(panelHeight, detailPanelHeights?.get(id));
+        };
+
+        const rowHeights = unpinnedRows.map((row, index) => heightOf(row, pinnedTopRowsLength + index));
 
         const cumulativeHeights = rowHeights.reduce((acc, height, index) => {
             acc.push((acc[index - 1] || 0) + height);
@@ -105,199 +266,51 @@ export function useLayout<R extends GridRowModel>(params: UseLayoutParams<R>): L
             ? Math.min(pageSize, 20)
             : 0;
         const unpinnedRowsHeight = (cumulativeHeights[cumulativeHeights.length - 1] || 0) + skeletonCount * rowHeight;
-        const pinnedTopHeight = pinnedTopRowsLength * rowHeight;
-        const pinnedBottomHeight = pinnedBottomRowsLength * rowHeight;
-
-        const rawLeftPinnedCols: GridColDef<R>[] = [];
-        const rawRightPinnedCols: GridColDef<R>[] = [];
-        const unpinnedCols: GridColDef<R>[] = [];
-        const unpinnedColWidths: number[] = [];
-
-        visibleOrderedColumns.forEach(col => {
-            const pinned = isColumnPinned(col.field, pinnedColumns);
-            if (pinned === 'left') {
-                rawLeftPinnedCols.push(col);
-            } else if (pinned === 'right') {
-                rawRightPinnedCols.push(col);
-            } else {
-                unpinnedCols.push(col);
-            }
-        });
-
-        const systemColumnsWidth = (checkboxSelection ? 48 : 0) + (hasDetailPanel ? 48 : 0) + (rowReordering ? 48 : 0);
-
-        const getColWidth = (c: GridColDef<R>) => columnWidths[c.field] ?? c.width;
-
-        const leftWidth = rawLeftPinnedCols.reduce((sum, c) => {
-            const parsed = parseWidth(getColWidth(c));
-            return sum + (parsed.type === 'fixed' ? parsed.value : 100);
-        }, 0);
-        const rightWidth = rawRightPinnedCols.reduce((sum, c) => {
-            const parsed = parseWidth(getColWidth(c));
-            return sum + (parsed.type === 'fixed' ? parsed.value : 100);
-        }, 0);
-
-        const naturalFlexWidth = unpinnedCols.reduce((sum, col) => {
-            const hasManualWidth = Object.prototype.hasOwnProperty.call(columnWidths, col.field);
-            if (!hasManualWidth && col.flex && col.flex > 0) {
-                const minWidth = col.minWidth ?? 150;
-                const w = typeof col.width === 'number' ? col.width : 150;
-                return sum + (minWidth || w);
-            }
-            const parsed = parseWidth(getColWidth(col));
-            if (parsed.type === 'fixed') return sum + parsed.value;
-            if (parsed.type === 'percentage') return sum + 100;
-            return sum + (col.minWidth ?? 150);
-        }, 0);
-
-        const availableWidth = Math.max(
-            viewportWidth - systemColumnsWidth - leftWidth - rightWidth,
-            naturalFlexWidth
+        // Pinned rows are indexed from 0 within their section (as GridPinnedRows renders them).
+        const pinnedBlockHeight = (rows: R[] | undefined, count: number) =>
+            rows ? rows.reduce((sum, row, index) => sum + heightOf(row, index), 0) : count * rowHeight;
+        const pinnedTopHeight = pinnedBlockHeight(pinnedTopRows, pinnedTopRowsLength);
+        const pinnedBottomHeight = pinnedBlockHeight(pinnedBottomRows, pinnedBottomRowsLength);
+
+        // Pinned columns render in pinnedColumns.left / .right order; unpinned ones in column order.
+        const { left: rawLeftPinnedCols, center: unpinnedCols, right: rawRightPinnedCols } =
+            getPinnedColumnGroups(visibleOrderedColumns, pinnedColumns);
+
+        const systemColumnsWidth =
+            (checkboxSelection ? SYSTEM_COLUMN_WIDTH : 0) +
+            (hasDetailPanel ? SYSTEM_COLUMN_WIDTH : 0) +
+            (rowReordering ? SYSTEM_COLUMN_WIDTH : 0);
+        const pinnedSystemColumnsWidth =
+            (rowReordering ? SYSTEM_COLUMN_WIDTH : 0) +
+            (hasDetailPanel && pinExpandColumn ? SYSTEM_COLUMN_WIDTH : 0) +
+            (checkboxSelection && pinCheckboxColumn ? SYSTEM_COLUMN_WIDTH : 0);
+
+        const { widths, flexByField } = resolveColumnWidths(
+            [...rawLeftPinnedCols, ...unpinnedCols, ...rawRightPinnedCols],
+            columnWidths,
+            viewportWidth - systemColumnsWidth,
         );
-
-        const fixedWidthCols: Array<{ col: GridColDef<R>; width: number }> = [];
-        const percentageCols: Array<{ col: GridColDef<R>; percentage: number }> = [];
-        const flexCols: Array<{ col: GridColDef<R>; flex: number }> = [];
-
-        unpinnedCols.forEach(col => {
-            const hasManualWidth = Object.prototype.hasOwnProperty.call(columnWidths, col.field);
-            const parsed = parseWidth(getColWidth(col));
-
-            if (!hasManualWidth && col.flex && col.flex > 0) {
-                flexCols.push({ col, flex: col.flex });
-                return;
-            }
-
-            if (parsed.type === 'fixed') {
-                fixedWidthCols.push({ col, width: parsed.value });
-            } else if (parsed.type === 'percentage') {
-                percentageCols.push({ col, percentage: parsed.value });
-            } else {
-                flexCols.push({ col, flex: 1 });
-            }
-        });
-
-        const fixedWidth = fixedWidthCols.reduce((sum, { width }) => sum + width, 0);
-        let remainingSpaceForFlex = Math.max(0, availableWidth - fixedWidth);
-
-        const percentageWidthMap = new Map<string, number>();
-        percentageCols.forEach(({ col, percentage }) => {
-            const calculatedWidth = (percentage / 100) * remainingSpaceForFlex;
-            percentageWidthMap.set(col.field, calculatedWidth);
-            remainingSpaceForFlex -= calculatedWidth;
-        });
-        remainingSpaceForFlex = Math.max(0, remainingSpaceForFlex);
-
-        const finalFlexWidths = new Map<string, number>();
-        const flexItems = flexCols.map(f => ({
-            ...f,
-            minWidth: f.col.minWidth ?? 50,
-            maxWidth: f.col.maxWidth ?? Infinity,
-            frozen: false,
-            computedWidth: 0
-        }));
-
-        const solveFlexAllocation = () => {
-            let iterations = 0;
-            const maxIterations = flexItems.length * 2;
-
-            while (iterations < maxIterations) {
-                iterations++;
-                const unfrozen = flexItems.filter(f => !f.frozen);
-                if (unfrozen.length === 0) break;
-
-                const unfrozenFlexTotal = unfrozen.reduce((sum, f) => sum + f.flex, 0);
-                const frozenWidthTotal = flexItems.reduce((sum, f) => f.frozen ? sum + f.computedWidth : sum, 0);
-                const currentFreeSpace = Math.max(0, remainingSpaceForFlex - frozenWidthTotal);
-
-                if (unfrozenFlexTotal <= 0) {
-                    unfrozen.forEach(f => { f.computedWidth = f.minWidth; f.frozen = true; });
-                    break;
-                }
-
-                const pixelsPerFlex = currentFreeSpace / unfrozenFlexTotal;
-                let totalViolation = 0;
-                const minViolators: typeof flexItems = [];
-                const maxViolators: typeof flexItems = [];
-
-                unfrozen.forEach(f => {
-                    const rawWidth = pixelsPerFlex * f.flex;
-                    if (rawWidth < f.minWidth) {
-                        totalViolation += f.minWidth - rawWidth;
-                        minViolators.push(f);
-                    } else if (rawWidth > f.maxWidth) {
-                        totalViolation += f.maxWidth - rawWidth;
-                        maxViolators.push(f);
-                    } else {
-                        f.computedWidth = rawWidth;
-                    }
-                });
-
-                if (minViolators.length === 0 && maxViolators.length === 0) {
-                    unfrozen.forEach(f => f.frozen = true);
-                    break;
-                }
-
-                if (totalViolation > 0) {
-                    minViolators.forEach(f => { f.computedWidth = f.minWidth; f.frozen = true; });
-                } else if (totalViolation < 0) {
-                    maxViolators.forEach(f => { f.computedWidth = f.maxWidth; f.frozen = true; });
-                } else {
-                    minViolators.forEach(f => { f.computedWidth = f.minWidth; f.frozen = true; });
-                    maxViolators.forEach(f => { f.computedWidth = f.maxWidth; f.frozen = true; });
-                }
-            }
-        };
-
-        solveFlexAllocation();
-        flexItems.forEach(f => finalFlexWidths.set(f.col.field, f.computedWidth));
-
-        const computedWidthMap = new Map<string, number>();
-        unpinnedCols.forEach(col => {
-            let computedWidth: number;
-            if (finalFlexWidths.has(col.field)) {
-                computedWidth = finalFlexWidths.get(col.field)!;
-            } else {
-                const fixedCol = fixedWidthCols.find(f => f.col.field === col.field);
-                const pctCol = percentageCols.find(p => p.col.field === col.field);
-                if (fixedCol) {
-                    computedWidth = fixedCol.width;
-                } else if (pctCol) {
-                    const rawPctWidth = percentageWidthMap.get(col.field) || 0;
-                    computedWidth = Math.max(col.minWidth ?? 50, rawPctWidth || 100);
-                } else {
-                    computedWidth = 100;
-                }
-            }
-            unpinnedColWidths.push(computedWidth);
-            computedWidthMap.set(col.field, computedWidth);
-        });
-
-        const unpinnedColsWithWidth = unpinnedCols.map(col => {
-            const flexItem = flexItems.find(f => f.col.field === col.field);
-            return {
-                ...col,
-                width: computedWidthMap.get(col.field) ?? (typeof col.width === 'number' ? col.width : 100),
-                flex: flexItem ? flexItem.flex : col.flex
-            };
+        const widthOf = (col: GridColDef<R>) => widths.get(col.field) ?? 100;
+        const withWidth = (col: GridColDef<R>) => ({
+            ...col,
+            width: widthOf(col),
+            flex: flexByField.get(col.field) ?? col.flex,
         });
 
         const baseLeftZ = 11;
-        const leftPinnedCols = rawLeftPinnedCols.map((col, i) => {
-            const parsed = parseWidth(getColWidth(col));
-            return { ...col, width: parsed.type === 'fixed' ? parsed.value : 100, zIndex: baseLeftZ + i };
-        });
+        const leftPinnedCols = rawLeftPinnedCols.map((col, i) => ({ ...withWidth(col), zIndex: baseLeftZ + i }));
 
         const baseRightZ = 11;
-        const rightPinnedCols = rawRightPinnedCols.map((col, i) => {
-            const parsed = parseWidth(getColWidth(col));
-            return {
-                ...col,
-                width: parsed.type === 'fixed' ? parsed.value : 100,
-                zIndex: baseRightZ + (rawRightPinnedCols.length - 1 - i)
-            };
-        });
+        const rightPinnedCols = rawRightPinnedCols.map((col, i) => ({
+            ...withWidth(col),
+            zIndex: baseRightZ + (rawRightPinnedCols.length - 1 - i),
+        }));
+
+        const unpinnedColsWithWidth = unpinnedCols.map(withWidth);
+        const unpinnedColWidths = unpinnedColsWithWidth.map(col => col.width);
 
+        const leftWidth = leftPinnedCols.reduce((sum, col) => sum + col.width, 0);
+        const rightWidth = rightPinnedCols.reduce((sum, col) => sum + col.width, 0);
         const unpinnedTotalWidth = unpinnedColWidths.reduce((sum, w) => sum + w, 0);
         const totalWidth = leftWidth + unpinnedTotalWidth + rightWidth + systemColumnsWidth;
         const unpinnedAccWidths = unpinnedColWidths.reduce((acc, w, i) => {
@@ -321,6 +334,7 @@ export function useLayout<R extends GridRowModel>(params: UseLayoutParams<R>): L
             rightWidth,
             unpinnedTotalWidth,
             systemColumnsWidth,
+            pinnedSystemColumnsWidth,
             pinnedTopRowsLength,
             pinnedBottomRowsLength,
             unpinnedRowsLength: unpinnedRows.length,
@@ -332,8 +346,11 @@ export function useLayout<R extends GridRowModel>(params: UseLayoutParams<R>): L
         sortedUnpinnedRows,
         expandedRowIds,
         getDetailPanelHeight,
+        detailPanelHeights,
         pinnedTopRowsLength,
         pinnedBottomRowsLength,
+        pinnedTopRows,
+        pinnedBottomRows,
         visibleOrderedColumns,
         pinnedColumns,
         columnWidths,
@@ -341,8 +358,11 @@ export function useLayout<R extends GridRowModel>(params: UseLayoutParams<R>): L
         checkboxSelection,
         hasDetailPanel,
         rowReordering,
+        pinCheckboxColumn,
+        pinExpandColumn,
         paginationMode,
         isLoading,
         pageSize,
+        getRowId,
     ]);
 }

package/lib/hooks/core/useRowsScrollEndLatch.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef } from 'react';
+import type React from 'react';
+import type { GridRowScrollEndParams } from '../../types';
+import { getRowsScrollEndParams } from '../../utils/scroll/scrollEnd';
+
+/**
+ * A scroll handler that calls `onRowsScrollEnd` once per arrival near the end of a row container.
+ * It re-arms when the container leaves the threshold or `rowCount` changes (new rows loaded), so a
+ * consumer that loads the next page from the callback is not flooded with calls while it loads.
+ * The grid viewport has the same rule built into useGridScrollSync; the list view uses this hook.
+ */
+export function useRowsScrollEndLatch(
+    onRowsScrollEnd: ((params: GridRowScrollEndParams) => void) | undefined,
+    rowCount: number,
+): ((event: React.UIEvent<HTMLElement>) => void) | undefined {
+    const armedRef = useRef(true);
+    const callbackRef = useRef(onRowsScrollEnd);
+
+    useEffect(() => {
+        callbackRef.current = onRowsScrollEnd;
+    }, [onRowsScrollEnd]);
+
+    useEffect(() => {
+        armedRef.current = true;
+    }, [rowCount]);
+
+    const handleScroll = useCallback((event: React.UIEvent<HTMLElement>) => {
+        const params = getRowsScrollEndParams(event.currentTarget);
+        if (!params) {
+            armedRef.current = true;
+            return;
+        }
+        if (!armedRef.current) return;
+        const callback = callbackRef.current;
+        if (!callback) return;
+        armedRef.current = false;
+        callback(params);
+    }, []);
+
+    return onRowsScrollEnd ? handleScroll : undefined;
+}

package/lib/hooks/core/useStableColumns.ts

@@ -0,0 +1,34 @@
+import { useState } from 'react';
+
+function shallowEqualObjects(a: object, b: object): boolean {
+    if (a === b) return true;
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length) return false;
+    const aRecord = a as Record<string, unknown>;
+    const bRecord = b as Record<string, unknown>;
+    return aKeys.every(key => Object.prototype.hasOwnProperty.call(b, key) && Object.is(aRecord[key], bRecord[key]));
+}
+
+/** Same length, and each column has the same own properties with identical values (functions by identity). */
+export function columnsShallowEqual<C extends object>(a: readonly C[], b: readonly C[]): boolean {
+    if (a === b) return true;
+    if (a.length !== b.length) return false;
+    return a.every((col, index) => shallowEqualObjects(col, b[index]));
+}
+
+/**
+ * The `columns` prop with a stable identity: while each column definition is shallowly equal to
+ * the previous one (same properties, same values, callbacks compared by identity), the previous
+ * array is returned. An inline `columns={[...]}` (a new but equal array on every parent render)
+ * then does not re-run the filter, sort, aggregation, grouping and spanning passes, which are all
+ * memoised on column identity. A changed property, including a new inline callback, is a new array.
+ *
+ * The previous array is held in state and replaced during render (React's "adjust state when a
+ * prop changes" pattern), so no ref is written during render.
+ */
+export function useStableColumns<T extends readonly object[]>(columns: T): T {
+    const [stable, setStable] = useState(columns);
+    const same = columnsShallowEqual(stable, columns);
+    if (!same) setStable(columns);
+    return same ? stable : columns;
+}