@opencorestack/opengridx 2.0.4 → 3.0.0

package/lib/hooks/core/useGridScrollSync.ts

@@ -1,44 +1,62 @@
 import { useRef, useState, useCallback, useEffect } from 'react';
 import type { GridRowScrollEndParams } from '../../types';
+import { getRowsScrollEndParams } from '../../utils/scroll/scrollEnd';
 
 export interface UseGridScrollSyncParams {
     onRowsScrollEnd?: (params: GridRowScrollEndParams) => void;
     /** Minimum overscan rows — the adaptive algorithm never goes below this. Defaults to 3. */
     overscanRowCount?: number;
+    /**
+     * Number of scrolling (center) rows. A change re-arms `onRowsScrollEnd` and re-checks whether
+     * the end of the rows is in view (e.g. the first page does not fill the viewport).
+     */
+    rowCount?: number;
+    /** The viewport grows to its content and never scrolls itself: only scroll events can signal the end. */
+    autoHeight?: boolean;
 }
 
 export interface UseGridScrollSyncResult {
     scrollTop: number;
     scrollLeft: number;
-    /** Dynamically computed overscan row count based on current scroll velocity. */
+    /** Overscan row count: the velocity-based value, never below `overscanRowCount`. */
     overscanRows: number;
     handleScroll: (event: React.UIEvent<HTMLDivElement>) => void;
+    /**
+     * Callback ref for the viewport element. When the viewport remounts (list view switched off
+     * again), the last scroll position is restored onto the new element so the render window and
+     * the DOM agree.
+     */
+    attachViewport: (element: HTMLDivElement | null) => void;
 }
 
 /** Maps scroll velocity (px/ms) to an overscan row count. */
-function velocityToOverscan(velocity: number, minOverscan: number): number {
-    let base: number;
-    if (velocity < 0.5)      base = 3;
-    else if (velocity < 3)   base = 5;
-    else if (velocity < 15)  base = 12;
-    else if (velocity < 40)  base = 20;
-    else                     base = 30;
-    return Math.max(base, minOverscan);
+function velocityToOverscan(velocity: number): number {
+    if (velocity < 0.5) return 3;
+    if (velocity < 3) return 5;
+    if (velocity < 15) return 12;
+    if (velocity < 40) return 20;
+    return 30;
 }
 
 export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrollSyncResult {
-    const { onRowsScrollEnd, overscanRowCount = 3 } = params;
+    const { onRowsScrollEnd, overscanRowCount = 3, rowCount = 0, autoHeight = false } = params;
 
     const pendingRef = useRef({ scrollTop: 0, scrollLeft: 0, velocity: 0 });
     const prevRef    = useRef({ scrollTop: 0, scrollLeft: 0, time: 0 });
     const rafRef     = useRef<number | null>(null);
     const decayRef   = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const elementRef = useRef<HTMLDivElement | null>(null);
+    /** Cleared when onRowsScrollEnd fires; set again once the viewport leaves the threshold or the rows change. */
+    const armedRef   = useRef(true);
+    const onRowsScrollEndRef = useRef(onRowsScrollEnd);
 
-    const [scrollState, setScrollState] = useState({
-        scrollTop: 0,
-        scrollLeft: 0,
-        overscanRows: overscanRowCount,
-    });
+    // velocityOverscan is 0 at rest; the prop floor is applied during render, so a new
+    // overscanRowCount takes effect without waiting for a scroll.
+    const [scrollState, setScrollState] = useState({ scrollTop: 0, scrollLeft: 0, velocityOverscan: 0 });
+
+    useEffect(() => {
+        onRowsScrollEndRef.current = onRowsScrollEnd;
+    }, [onRowsScrollEnd]);
 
     useEffect(() => {
         return () => {
@@ -47,6 +65,20 @@ export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrol
         };
     }, []);
 
+    /** Fires onRowsScrollEnd once per arrival within the threshold of the end. */
+    const checkRowsScrollEnd = useCallback((target: HTMLElement) => {
+        const endParams = getRowsScrollEndParams(target);
+        if (!endParams) {
+            armedRef.current = true;
+            return;
+        }
+        if (!armedRef.current) return;
+        const callback = onRowsScrollEndRef.current;
+        if (!callback) return;
+        armedRef.current = false;
+        callback(endParams);
+    }, []);
+
     const handleScroll = useCallback((event: React.UIEvent<HTMLDivElement>) => {
         const target = event.currentTarget;
         const now = performance.now();
@@ -56,6 +88,7 @@ export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrol
                        + Math.abs(target.scrollLeft - prevRef.current.scrollLeft);
         const deltaTime = now - prevRef.current.time;
         const velocity = deltaTime > 0 ? deltaPos / deltaTime : 0;
+        const movedVertically = target.scrollTop !== prevRef.current.scrollTop;
 
         prevRef.current = { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft, time: now };
         pendingRef.current = { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft, velocity };
@@ -64,36 +97,51 @@ export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrol
         rafRef.current = requestAnimationFrame(() => {
             rafRef.current = null;
             const { scrollTop, scrollLeft, velocity: v } = pendingRef.current;
-            setScrollState({
-                scrollTop,
-                scrollLeft,
-                overscanRows: velocityToOverscan(v, overscanRowCount),
-            });
+            setScrollState({ scrollTop, scrollLeft, velocityOverscan: velocityToOverscan(v) });
         });
 
         // Decay back to the minimum overscan 200ms after scrolling stops
         if (decayRef.current !== null) clearTimeout(decayRef.current);
         decayRef.current = setTimeout(() => {
             decayRef.current = null;
-            setScrollState(prev => ({ ...prev, overscanRows: overscanRowCount }));
+            setScrollState(prev => (prev.velocityOverscan === 0 ? prev : { ...prev, velocityOverscan: 0 }));
         }, 200);
 
-        if (onRowsScrollEnd) {
-            const { scrollTop, scrollHeight, clientHeight } = target;
-            if (scrollHeight - scrollTop - clientHeight < 100) {
-                onRowsScrollEnd({
-                    visibleTop: scrollTop,
-                    visibleBottom: scrollTop + clientHeight,
-                    viewportHeight: clientHeight,
-                });
-            }
+        // Horizontal-only scrolling never reaches (or leaves) the end of the rows.
+        if (movedVertically) checkRowsScrollEnd(target);
+    }, [checkRowsScrollEnd]);
+
+    // New rows re-arm the callback; if the end is still in view (the rows do not fill the
+    // viewport), no scroll event can happen, so check here.
+    useEffect(() => {
+        armedRef.current = true;
+        const el = elementRef.current;
+        if (!el || autoHeight || rowCount <= 0 || el.clientHeight === 0) return;
+        checkRowsScrollEnd(el);
+    }, [rowCount, autoHeight, checkRowsScrollEnd]);
+
+    const attachViewport = useCallback((element: HTMLDivElement | null) => {
+        elementRef.current = element;
+        if (!element) return;
+        const { scrollTop, scrollLeft } = pendingRef.current;
+        if (scrollTop === 0 && scrollLeft === 0) return;
+        element.scrollTop = scrollTop;
+        element.scrollLeft = scrollLeft;
+        // The browser clamps to the new content. If it did, sync the state to what the element
+        // shows (no scroll event fires when the position ends up unchanged).
+        const actual = { scrollTop: element.scrollTop, scrollLeft: element.scrollLeft };
+        if (actual.scrollTop !== scrollTop || actual.scrollLeft !== scrollLeft) {
+            pendingRef.current = { ...pendingRef.current, ...actual };
+            prevRef.current = { ...prevRef.current, ...actual };
+            setScrollState(prev => ({ ...prev, ...actual }));
         }
-    }, [onRowsScrollEnd, overscanRowCount]);
+    }, []);
 
     return {
         scrollTop:    scrollState.scrollTop,
         scrollLeft:   scrollState.scrollLeft,
-        overscanRows: scrollState.overscanRows,
+        overscanRows: Math.max(scrollState.velocityOverscan, overscanRowCount),
         handleScroll,
+        attachViewport,
     };
 }

package/lib/hooks/core/useGridScrollToIndexesApi.ts

@@ -0,0 +1,45 @@
+import { useLayoutEffect, useRef } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import { scrollRowIntoView, scrollColumnIntoView } from '../../utils/scroll';
+import type { LayoutResult } from './useLayout';
+import type { GridApi, GridRowModel } from '../../types';
+
+export interface UseGridScrollToIndexesApiParams<R extends GridRowModel> {
+    apiRef: MutableRefObject<GridApi>;
+    viewportRef: RefObject<HTMLDivElement | null>;
+    layout: LayoutResult<R>;
+    rowHeight: number;
+}
+
+/**
+ * Installs `scrollToIndexes` on the API, in a layout effect reading the latest layout from a ref,
+ * so it is live in a parent's layout effect and never scrolls by a previous render's layout.
+ */
+export function useGridScrollToIndexesApi<R extends GridRowModel>(params: UseGridScrollToIndexesApiParams<R>): void {
+    const { apiRef } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    useLayoutEffect(() => {
+        apiRef.current.scrollToIndexes = ({ rowIndex, colIndex }) => {
+            const { viewportRef, layout, rowHeight } = latestRef.current;
+            const el = viewportRef.current;
+            if (!el) return;
+
+            if (rowIndex !== undefined && rowIndex >= 0) {
+                scrollRowIntoView(el, rowIndex, layout.cumulativeHeights, layout.pinnedBottomHeight, rowHeight);
+            }
+
+            if (colIndex !== undefined && colIndex >= 0) {
+                // colIndex is an index into all data columns: leftPinned + unpinned + rightPinned
+                const allDataCols = [...layout.leftPinnedCols, ...layout.unpinnedColsWithWidth, ...layout.rightPinnedCols];
+                const targetCol = allDataCols[colIndex];
+                if (!targetCol) return;
+                // A pinned column (index -1) is always visible: nothing to scroll.
+                scrollColumnIntoView(el, layout.unpinnedColsWithWidth.findIndex(c => c.field === targetCol.field), layout);
+            }
+        };
+    }, [apiRef]);
+}

package/lib/hooks/core/useGridStateSnapshot.ts

@@ -1,5 +1,5 @@
 import { useRef, useEffect, useLayoutEffect } from 'react';
-import type { GridState } from '../../state/types';
+import type { GridState, GridDensityState } from '../../state/types';
 import type {
     GridSortItem,
     GridFilterModel,
@@ -7,6 +7,23 @@ import type {
     GridColumnPinning,
 } from '../../types';
 
+/** Grid-owned columns that must never leak into the public state (and so into storage). */
+const SYNTHETIC_FIELDS: ReadonlySet<string> = new Set(['__group__']);
+const isUserField = (field: string) => !SYNTHETIC_FIELDS.has(field);
+
+function withoutSyntheticKeys<T>(record: Record<string, T>): Record<string, T> {
+    const keys = Object.keys(record);
+    if (keys.every(isUserField)) return record;
+    return Object.fromEntries(Object.entries(record).filter(([field]) => isUserField(field)));
+}
+
+function userPinnedColumns(pinned: GridColumnPinning): GridColumnPinning {
+    const result: GridColumnPinning = { ...pinned };
+    if (pinned.left) result.left = pinned.left.filter(isUserField);
+    if (pinned.right) result.right = pinned.right.filter(isUserField);
+    return result;
+}
+
 export interface UseGridStateSnapshotParams {
     onStateChange?: (state: GridState) => void;
     sortModel: GridSortItem[];
@@ -15,9 +32,17 @@ export interface UseGridStateSnapshotParams {
     columnWidths: Record<string, number>;
     effectiveColumnOrder: string[];
     columnVisibilityModel: Record<string, boolean>;
+    /** The user's pins (not the grid's effective pins, which add the synthetic group column). */
     pinnedColumns: GridColumnPinning;
+    density: GridDensityState['density'];
 }
 
+/**
+ * Emits the public GridState through onStateChange whenever its *value* changes.
+ * Inline model props get a new identity on every parent render, so the comparison is
+ * structural; otherwise an onStateChange that stores state in the parent re-renders
+ * the parent, which creates new inline props, which fires onStateChange again, forever.
+ */
 export function useGridStateSnapshot(params: UseGridStateSnapshotParams): void {
     const {
         onStateChange,
@@ -28,6 +53,7 @@ export function useGridStateSnapshot(params: UseGridStateSnapshotParams): void {
         effectiveColumnOrder,
         columnVisibilityModel,
         pinnedColumns,
+        density,
     } = params;
 
     const onStateChangeRef = useRef(onStateChange);
@@ -35,6 +61,8 @@ export function useGridStateSnapshot(params: UseGridStateSnapshotParams): void {
         onStateChangeRef.current = onStateChange;
     });
 
+    const lastEmittedRef = useRef<string | null>(null);
+
     useEffect(() => {
         if (!onStateChangeRef.current) return;
 
@@ -43,13 +71,19 @@ export function useGridStateSnapshot(params: UseGridStateSnapshotParams): void {
             filter: { filterModel },
             pagination: { paginationModel: effectivePaginationModel },
             columns: {
-                columnWidths,
-                columnOrder: effectiveColumnOrder,
-                columnVisibilityModel,
-                pinnedColumns,
+                columnWidths: withoutSyntheticKeys(columnWidths),
+                columnOrder: effectiveColumnOrder.filter(isUserField),
+                columnVisibilityModel: withoutSyntheticKeys(columnVisibilityModel),
+                pinnedColumns: userPinnedColumns(pinnedColumns),
             },
+            density: { density },
         };
 
+        // The snapshot only holds plain data, so its JSON is a faithful value key.
+        const serialized = JSON.stringify(snapshot);
+        if (serialized === lastEmittedRef.current) return;
+        lastEmittedRef.current = serialized;
+
         onStateChangeRef.current(snapshot);
     }, [
         sortModel,
@@ -59,5 +93,6 @@ export function useGridStateSnapshot(params: UseGridStateSnapshotParams): void {
         effectiveColumnOrder,
         columnVisibilityModel,
         pinnedColumns,
+        density,
     ]);
 }

package/lib/hooks/core/useGridThemeDimensions.ts

@@ -0,0 +1,49 @@
+import { useContext } from 'react';
+import { GridThemeContext } from '../../theme/gridThemeContext';
+import type { GridDensity } from './useGridControlledState';
+
+const DEFAULT_ROW_HEIGHT = 52;
+const DEFAULT_HEADER_HEIGHT = 56;
+const COMPACT_ROW_HEIGHT = 32;
+const COMFORTABLE_ROW_HEIGHT = 72;
+
+/** A theme height in pixels (`'36px'` or `'36'`); anything else (rem, calc, …) is ignored. */
+export function parseThemePixels(value: string | undefined): number | undefined {
+    if (value === undefined) return undefined;
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(px)?\s*$/.exec(value);
+    if (!match) return undefined;
+    const px = Number(match[1]);
+    return px > 0 ? px : undefined;
+}
+
+export interface UseGridThemeDimensionsParams {
+    rowHeight?: number;
+    headerHeight?: number;
+    density: GridDensity;
+}
+
+/**
+ * The row and header heights the grid lays out and renders with. The grid drives virtualization
+ * from these numbers, so a DataGridThemeProvider's `grid.rowHeight*` / `grid.headerHeight` are read
+ * here rather than left to CSS (which the grid's own inline heights would override). Precedence:
+ * the `rowHeight` / `headerHeight` props, then the theme, then the defaults. `density="compact"` /
+ * `"comfortable"` use the theme's compact / comfortable height, else 32 / 72.
+ */
+export function useGridThemeDimensions(params: UseGridThemeDimensionsParams): { rowHeight: number; headerHeight: number } {
+    const { rowHeight, headerHeight, density } = params;
+    const grid = useContext(GridThemeContext)?.grid;
+
+    let effectiveRowHeight: number;
+    if (density === 'compact') {
+        effectiveRowHeight = parseThemePixels(grid?.rowHeightCompact) ?? COMPACT_ROW_HEIGHT;
+    } else if (density === 'comfortable') {
+        effectiveRowHeight = parseThemePixels(grid?.rowHeightComfortable) ?? COMFORTABLE_ROW_HEIGHT;
+    } else {
+        effectiveRowHeight = rowHeight ?? parseThemePixels(grid?.rowHeightStandard) ?? DEFAULT_ROW_HEIGHT;
+    }
+
+    return {
+        rowHeight: effectiveRowHeight,
+        headerHeight: headerHeight ?? parseThemePixels(grid?.headerHeight) ?? DEFAULT_HEADER_HEIGHT,
+    };
+}

package/lib/hooks/core/useGridToolbarProps.ts

@@ -0,0 +1,97 @@
+import { useMemo } from 'react';
+import type { MutableRefObject } from 'react';
+import { canReorderWithinColumnGroups } from '../../utils/columnGroups';
+import type {
+    DataGridProps,
+    GridAggregationModel,
+    GridApi,
+    GridColDef,
+    GridColumnGroupingModel,
+    GridColumnVisibilityModel,
+    GridFilterModel,
+    GridPivotModel,
+    GridRowModel,
+    GridToolbarSlotProps,
+} from '../../types';
+
+type ToolbarSlot = NonNullable<DataGridProps['slots']>['toolbar'];
+type ToolbarSlotProps = NonNullable<DataGridProps['slotProps']>['toolbar'];
+
+export interface UseGridToolbarPropsParams<R extends GridRowModel> {
+    /** `slots.toolbar`: nothing is built without one. */
+    toolbar: ToolbarSlot;
+    /** `slotProps.toolbar`, merged over the grid's props. */
+    toolbarSlotProps: ToolbarSlotProps;
+    apiRef: MutableRefObject<GridApi>;
+    /** Columns in display order (`useGridColumns().orderedColumns`). */
+    orderedColumns: GridColDef<R>[];
+    /** The `columns` prop. */
+    baseColumns: GridColDef<R>[];
+    aggregationModel: GridAggregationModel;
+    onAggregationModelChange: (model: GridAggregationModel) => void;
+    /** The toolbar gets the pivot model only when the consumer uses the pivot (`pivotMode`, `pivotModel` or `onPivotModelChange`). */
+    pivotMode: boolean;
+    pivotModelProp: GridPivotModel | undefined;
+    onPivotModelChangeProp: ((model: GridPivotModel) => void) | undefined;
+    pivotModel: GridPivotModel;
+    onPivotModelChange: (model: GridPivotModel) => void;
+    filterModel: GridFilterModel;
+    onFilterModelChange: (model: GridFilterModel) => void;
+    columnVisibilityModel: GridColumnVisibilityModel;
+    onColumnVisibilityModelChange: (model: GridColumnVisibilityModel) => void;
+    disableColumnReorder: boolean;
+    columnGroupingModel: GridColumnGroupingModel | undefined;
+    moveColumn: (fromField: string, toField: string) => void;
+    resetColumnOrder: () => void;
+    /** `useGridColumnsPanel().toolbarPanelRequested`. */
+    forceColumnsOpen: boolean;
+    onColumnsPanelClose: () => void;
+}
+
+/** The props the grid passes to `slots.toolbar`, or null when there is no toolbar slot. */
+export function useGridToolbarProps<R extends GridRowModel>(
+    params: UseGridToolbarPropsParams<R>
+): (GridToolbarSlotProps & Record<string, unknown>) | null {
+    const {
+        toolbar, toolbarSlotProps, apiRef, orderedColumns, baseColumns, aggregationModel, onAggregationModelChange,
+        pivotMode, pivotModelProp, onPivotModelChangeProp, pivotModel, onPivotModelChange, filterModel,
+        onFilterModelChange, columnVisibilityModel, onColumnVisibilityModelChange, disableColumnReorder,
+        columnGroupingModel, moveColumn, resetColumnOrder, forceColumnsOpen, onColumnsPanelClose,
+    } = params;
+
+    return useMemo(() => {
+        if (!toolbar) return null;
+        const reorderHandler = disableColumnReorder
+            ? undefined
+            : (fromField: string, toField: string) => {
+                if (!canReorderWithinColumnGroups(columnGroupingModel, fromField, toField)) return;
+                moveColumn(fromField, toField);
+            };
+        return {
+            apiRef,
+            columns: orderedColumns as unknown as GridColDef[],
+            baseColumns: baseColumns as unknown as GridColDef[],
+            aggregationModel,
+            onAggregationModelChange,
+            ...(pivotMode || pivotModelProp || onPivotModelChangeProp ? {
+                pivotModel,
+                onPivotModelChange,
+            } : {}),
+            filterModel,
+            onFilterModelChange,
+            columnVisibilityModel,
+            onColumnVisibilityModelChange,
+            onColumnReorder: reorderHandler,
+            onColumnOrderReset: disableColumnReorder ? undefined : resetColumnOrder,
+            forceColumnsOpen,
+            onColumnsPanelClose,
+            ...toolbarSlotProps,
+        };
+    }, [
+        toolbar, disableColumnReorder, moveColumn, resetColumnOrder, orderedColumns, apiRef,
+        baseColumns, aggregationModel, onAggregationModelChange, pivotMode,
+        pivotModelProp, onPivotModelChangeProp, pivotModel, onPivotModelChange,
+        filterModel, onFilterModelChange, columnVisibilityModel,
+        onColumnVisibilityModelChange, forceColumnsOpen, onColumnsPanelClose, toolbarSlotProps, columnGroupingModel,
+    ]);
+}

package/lib/hooks/core/useGridViewport.ts

@@ -0,0 +1,38 @@
+import { useCallback } from 'react';
+import type { MutableRefObject } from 'react';
+import { useGridScrollSync, type UseGridScrollSyncParams } from './useGridScrollSync';
+import { useGridViewportSize } from './useGridViewportSize';
+
+export interface UseGridViewportParams extends UseGridScrollSyncParams {
+    /** Receives the viewport's measured content size. */
+    setDimensions: (width: number, height: number) => void;
+    /** Set to the mounted viewport element. */
+    viewportRef: MutableRefObject<HTMLDivElement | null>;
+}
+
+export interface UseGridViewportResult {
+    scrollTop: number;
+    scrollLeft: number;
+    overscanRows: number;
+    handleScroll: (event: React.UIEvent<HTMLDivElement>) => void;
+    /**
+     * Callback ref for the viewport: every viewport that mounts (list view switched off again)
+     * is measured and gets its scroll position back.
+     */
+    setViewportElement: (el: HTMLDivElement | null) => void;
+}
+
+/** The grid viewport: scroll position and velocity overscan, size measurement, and its callback ref. */
+export function useGridViewport(params: UseGridViewportParams): UseGridViewportResult {
+    const { setDimensions, viewportRef, ...scrollParams } = params;
+
+    const { scrollTop, scrollLeft, overscanRows, handleScroll, attachViewport } = useGridScrollSync(scrollParams);
+    const observeViewportSize = useGridViewportSize(setDimensions);
+    const setViewportElement = useCallback((el: HTMLDivElement | null) => {
+        viewportRef.current = el;
+        observeViewportSize(el);
+        attachViewport(el);
+    }, [viewportRef, observeViewportSize, attachViewport]);
+
+    return { scrollTop, scrollLeft, overscanRows, handleScroll, setViewportElement };
+}

package/lib/hooks/core/useGridViewportSize.ts

@@ -0,0 +1,26 @@
+import { useCallback, useRef } from 'react';
+
+/**
+ * Returns a callback ref that measures the element it is attached to with a ResizeObserver and
+ * reports its content size. Every element that mounts is observed (the grid viewport unmounts in
+ * list view and a new one mounts when list view is switched off); a detached element is released.
+ */
+export function useGridViewportSize(
+    setDimensions: (width: number, height: number) => void,
+): (element: HTMLElement | null) => void {
+    const observerRef = useRef<ResizeObserver | null>(null);
+
+    return useCallback((element: HTMLElement | null) => {
+        observerRef.current?.disconnect();
+        observerRef.current = null;
+        if (!element || typeof ResizeObserver === 'undefined') return;
+        const observer = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                const { width, height } = entry.contentRect;
+                setDimensions(width, height);
+            }
+        });
+        observer.observe(element);
+        observerRef.current = observer;
+    }, [setDimensions]);
+}

package/lib/hooks/core/useGridVisibleRows.ts

@@ -13,13 +13,21 @@ export interface UseGridVisibleRowsParams<R extends GridRowModel> {
     paginatedUnpinnedRows: R[];
     sortedUnpinnedRows: R[];
     pagination: boolean;
+    /** Resolves a row's id (rows are not guaranteed to carry it in `row.id`); defaults to `row.id`. */
+    getRowId?: (row: R) => GridRowId;
 }
 
 export interface GridVisibleRow<R extends GridRowModel> {
     row: R;
+    /** The row's id (getRowId), resolved once for everything that renders the row. */
+    id: GridRowId;
     rowIndex: number;
+    /** Set on the rows of the top / bottom pinned sections, which render outside the scrolling rows. */
+    pinned?: 'top' | 'bottom';
 }
 
+const defaultGetRowId = <R extends GridRowModel>(row: R): GridRowId => row.id;
+
 export function useGridVisibleRows<R extends GridRowModel>(
     params: UseGridVisibleRowsParams<R>
 ): GridVisibleRow<R>[] {
@@ -30,6 +38,7 @@ export function useGridVisibleRows<R extends GridRowModel>(
         paginatedUnpinnedRows,
         sortedUnpinnedRows,
         pagination,
+        getRowId = defaultGetRowId,
     } = params;
 
     return useMemo<GridVisibleRow<R>[]>(() => {
@@ -37,30 +46,34 @@ export function useGridVisibleRows<R extends GridRowModel>(
         const centerRows = pagination ? paginatedUnpinnedRows : sortedUnpinnedRows;
         const topPinnedCount = pinnedTopRows.length;
 
-        const topPinned = pinnedTopRows.map((row, index) => ({ row, rowIndex: index }));
+        const topPinned = pinnedTopRows.map((row, index) => ({ row, id: getRowId(row), rowIndex: index, pinned: 'top' as const }));
         const bottomPinned = pinnedBottomRows.map((row, index) => ({
             row,
+            id: getRowId(row),
             rowIndex: topPinnedCount + centerRows.length + index,
+            pinned: 'bottom' as const,
         }));
 
-        const centerStartIndex = Math.max(0, firstRowIndex - topPinnedCount);
-        const centerEndIndex = Math.min(centerRows.length, lastRowIndex - topPinnedCount + 1);
+        // renderContext indices come from the unpinned-row layout, so they index centerRows directly.
+        const centerStartIndex = Math.max(0, firstRowIndex);
+        const centerEndIndex = Math.min(centerRows.length, lastRowIndex + 1);
 
         const centerVisible = centerRows
             .slice(centerStartIndex, centerEndIndex)
             .map((row, index) => ({
                 row,
+                id: getRowId(row),
                 rowIndex: topPinnedCount + centerStartIndex + index,
             }));
 
-        const combined = [...topPinned, ...centerVisible, ...bottomPinned];
+        const combined: GridVisibleRow<R>[] = [...topPinned, ...centerVisible, ...bottomPinned];
 
         // Deduplication guard: a row ID in both pinnedRows and rows would cause React key collisions
         const seenIds = new Set<GridRowId>();
         return combined.filter(item => {
-            if (seenIds.has(item.row.id)) return false;
-            seenIds.add(item.row.id);
+            if (seenIds.has(item.id)) return false;
+            seenIds.add(item.id);
             return true;
         });
-    }, [renderContext, pinnedTopRows, pinnedBottomRows, paginatedUnpinnedRows, sortedUnpinnedRows, pagination]);
+    }, [renderContext, pinnedTopRows, pinnedBottomRows, paginatedUnpinnedRows, sortedUnpinnedRows, pagination, getRowId]);
 }