@opencorestack/opengridx 2.0.4 → 2.1.0

package/lib/components/DataGrid/DataGrid.tsx

@@ -8,6 +8,8 @@ import { useGridColumns } from '../../hooks/core/useGridColumns';
 import { useGridVisibleRows } from '../../hooks/core/useGridVisibleRows';
 import { useGridScrollSync } from '../../hooks/core/useGridScrollSync';
 import { useGridStateSnapshot } from '../../hooks/core/useGridStateSnapshot';
+import { useGridDevWarnings } from '../../hooks/core/useGridDevWarnings';
+import { scrollRowIntoView } from '../../utils/scroll';
 import { GridAggregationFooter } from './GridAggregationFooter';
 import { GridEmptyState } from './GridEmptyState';
 import { GridErrorOverlay } from './GridErrorOverlay';
@@ -46,6 +48,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         rowSelectionModel: propRowSelectionModel,
         onRowSelectionModelChange: propOnRowSelectionModelChange,
         onRowClick,
+        onRowDoubleClick,
         onCellClick,
 
         filterModel: propFilterModel,
@@ -652,14 +655,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
             if (!el) return;
 
             if (rowIndex !== undefined && rowIndex >= 0) {
-                const rowTop = rowIndex > 0 ? layout.cumulativeHeights[rowIndex - 1] : 0;
-                const rowBottom = layout.cumulativeHeights[rowIndex] ?? rowTop;
-                const { scrollTop, clientHeight } = el;
-                if (rowTop < scrollTop) {
-                    el.scrollTop = rowTop;
-                } else if (rowBottom > scrollTop + clientHeight) {
-                    el.scrollTop = rowBottom - clientHeight;
-                }
+                scrollRowIntoView(el, rowIndex, layout.cumulativeHeights, layout.pinnedBottomHeight);
             }
 
             if (colIndex !== undefined && colIndex >= 0) {
@@ -779,6 +775,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         pageSize: effectivePaginationModel.pageSize,
         virtualization,
         viewportRef,
+        pinnedTopRowCount: pinnedTopRows.length,
     });
 
     const handleCellClick = useCallback((params: GridCellParams<R>) => {
@@ -811,6 +808,14 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         pagination,
     });
 
+    useGridDevWarnings({
+        paginationRequested: propPagination,
+        isRowGrouping,
+        autoHeight,
+        viewportHeight: state.dimensions.viewportHeight,
+        renderedRowCount: visibleRows.length,
+        totalRowCount: pinnedTopRows.length + (pagination ? paginatedUnpinnedRows.length : sortedUnpinnedRows.length) + pinnedBottomRows.length,
+    });
 
     const allSelected = rows.length > 0 && selectedRowIds.size === rows.length;
     const someSelected = selectedRowIds.size > 0 && selectedRowIds.size < rows.length;
@@ -820,6 +825,10 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
     const containerRef = React.useRef<HTMLDivElement>(null);
     const standalonePanelRef = React.useRef<HTMLDivElement>(null);
 
+    const NoRowsOverlaySlot = slots?.noRowsOverlay;
+    const LoadingOverlaySlot = slots?.loadingOverlay;
+    const FooterSlot = slots?.footer;
+
     const toolbarProps = React.useMemo(() => {
         if (!slots?.toolbar) return null;
         const reorderHandler = disableColumnReorder
@@ -932,6 +941,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                         paginationPage: localeText.paginationPage,
                     } : undefined}
                     onRowClick={handleRowClick}
+                    onRowDoubleClick={onRowDoubleClick}
                     onSelectionChange={handleSelectionChange}
                     onPaginationModelChange={handlePaginationModelChange}
                 />
@@ -1033,7 +1043,11 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
 
                         {/* Empty State Overlay (Standard View) — showing after header */}
                         {!effectiveLoading && !state.dataSource.error && filteredRows.length === 0 && (
-                            <GridEmptyState noRowsLabel={effectiveNoRowsLabel} width={virtualization.totalWidth} />
+                            <GridEmptyState
+                                noRowsLabel={effectiveNoRowsLabel}
+                                width={virtualization.totalWidth}
+                                overlay={NoRowsOverlaySlot ? <NoRowsOverlaySlot {...slotProps?.noRowsOverlay} /> : undefined}
+                            />
                         )}
 
                         <GridPinnedRows<R>
@@ -1043,6 +1057,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                             selectedRowIds={selectedRowIds}
                             checkboxSelection={checkboxSelection}
                             onRowClick={handleRowClick}
+                            onRowDoubleClick={onRowDoubleClick}
                             onCellClick={handleCellClick}
                             onSelectionChange={handleSelectionChange}
                             columnWidths={columnWidths}
@@ -1077,6 +1092,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                             pinnedRows={pinnedRows}
                             selectedRowIds={selectedRowIds}
                             onRowClick={handleRowClick}
+                            onRowDoubleClick={onRowDoubleClick}
                             onCellClick={handleCellClick}
                             onSelectionChange={handleSelectionChange}
                             columnWidths={columnWidths}
@@ -1098,6 +1114,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                             infiniteScrollSkeletonCount={Math.min(effectivePaginationModel.pageSize, 20)}
                             unpinnedRowsLength={layout.unpinnedRowsLength}
                             rowMetaMap={rowMetaMap}
+                            loadingOverlay={LoadingOverlaySlot ? <LoadingOverlaySlot {...slotProps?.loadingOverlay} /> : undefined}
                         />
 
                         <GridPinnedRows<R>
@@ -1107,6 +1124,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                             selectedRowIds={selectedRowIds}
                             checkboxSelection={checkboxSelection}
                             onRowClick={handleRowClick}
+                            onRowDoubleClick={onRowDoubleClick}
                             onCellClick={handleCellClick}
                             onSelectionChange={handleSelectionChange}
                             columnWidths={columnWidths}
@@ -1147,7 +1165,21 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                 </div>
             )}
 
-            {!listView && pagination && (() => {
+            {!listView && FooterSlot && (
+                <FooterSlot
+                    apiRef={gridData.apiRef}
+                    aggregationModel={aggregationModel}
+                    aggregationResult={hasAggregation ? aggregationResult : null}
+                    rowCount={isRowGrouping ? effectiveRows.length : sortedUnpinnedRows.length}
+                    pagination={pagination}
+                    paginationModel={effectivePaginationModel}
+                    pageSizeOptions={pageSizeOptions}
+                    onPaginationModelChange={handlePaginationModelChange}
+                    {...slotProps?.footer}
+                />
+            )}
+
+            {!listView && !FooterSlot && pagination && (() => {
                 const PaginationComponent = slots?.pagination || Pagination;
                 return (
                     <PaginationComponent

package/lib/components/DataGrid/DataGrid.virtualization.browser.test.tsx

@@ -0,0 +1,183 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { useEffect } from 'react';
+import type { ReactNode } from 'react';
+import { DataGrid, useGridApiRef } from '../../index';
+import type { GridColDef } from '../../types';
+
+// Runs in real Chromium (vitest browser project). jsdom has no layout engine, so the
+// container-height behaviour these tests pin down cannot be reproduced there.
+
+type Row = { id: number; region: string; amount: number };
+
+const makeRows = (total: number, northCount: number): Row[] =>
+    Array.from({ length: total }, (_, i) => ({ id: i + 1, region: i < northCount ? 'North' : 'South', amount: i }));
+
+const columns: GridColDef<Row>[] = [
+    { field: 'region', width: 200 },
+    { field: 'amount', width: 150 },
+];
+
+// Bounded: a flex child with min-height: 0 cannot grow past the 600px parent.
+const Bounded = ({ children }: { children: ReactNode }) => (
+    <div style={{ height: 600, display: 'flex', flexDirection: 'column' }}>
+        <div style={{ flex: 1, minHeight: 0 }}>{children}</div>
+    </div>
+);
+
+// Unbounded: the classic trap — a flex child without min-height: 0 grows to fit its content.
+const Unbounded = ({ children }: { children: ReactNode }) => (
+    <div style={{ height: 600, display: 'flex', flexDirection: 'column' }}>
+        <div style={{ flex: 1 }}>{children}</div>
+    </div>
+);
+
+const domRowCount = (container: HTMLElement) => container.querySelectorAll('.ogx__rows [role="row"]').length;
+const firstRow = (container: HTMLElement) => container.querySelector<HTMLElement>('.ogx__rows [role="row"]')!;
+
+afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+});
+
+describe('DataGrid virtualization in a real browser', () => {
+    it('virtualizes a large flat dataset in a bounded container', async () => {
+        const { container } = render(<Bounded><DataGrid rows={makeRows(30000, 30000)} columns={columns} height="100%" /></Bounded>);
+        await expect.poll(() => domRowCount(container)).toBeGreaterThan(0);
+        expect(domRowCount(container)).toBeLessThan(60);
+    });
+
+    it('keeps DOM rows bounded after expanding a 25,000-row group', async () => {
+        const { container } = render(
+            <Bounded><DataGrid rows={makeRows(30000, 25000)} columns={columns} height="100%" rowGroupingModel={['region']} /></Bounded>
+        );
+        await expect.poll(() => domRowCount(container)).toBe(2);
+
+        firstRow(container).click();
+
+        await expect.poll(() => domRowCount(container)).toBeGreaterThan(2);
+        expect(domRowCount(container)).toBeLessThan(60);
+
+        const viewport = container.querySelector<HTMLElement>('.ogx__viewport')!;
+        viewport.scrollTop = viewport.scrollHeight / 2;
+        viewport.dispatchEvent(new Event('scroll'));
+        await expect.poll(() => container.querySelector('.ogx__rows [role="row"]')?.getAttribute('data-rowindex')).not.toBe('0');
+        expect(domRowCount(container)).toBeLessThan(80);
+    });
+
+    it('warns in development when an unbounded container defeats virtualization', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const { container } = render(
+            <Unbounded><DataGrid rows={makeRows(3000, 2500)} columns={columns} height="100%" rowGroupingModel={['region']} /></Unbounded>
+        );
+        await expect.poll(() => domRowCount(container)).toBe(2);
+        firstRow(container).click();
+
+        await expect.poll(() => warn.mock.calls.some(([msg]) => String(msg).includes('virtualization is effectively off'))).toBe(true);
+    });
+
+    it('warns in development that pagination is ignored under row grouping', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        render(<Bounded><DataGrid rows={makeRows(100, 50)} columns={columns} height="100%" pagination rowGroupingModel={['region']} /></Bounded>);
+        await expect.poll(() => warn.mock.calls.some(([msg]) => String(msg).includes('`pagination` is ignored'))).toBe(true);
+    });
+
+    it('positions every scrolled row correctly when rows are pinned to the top', async () => {
+        const rowHeight = 52;
+        const rows = Array.from({ length: 2000 }, (_, i) => ({ id: i + 1, region: 'r', amount: i }));
+        const { container } = render(
+            <Bounded>
+                <DataGrid rows={rows} columns={[{ field: 'id', width: 100 }, ...columns]} height="100%"
+                    rowHeight={rowHeight} pinnedRows={{ top: [1, 2] }} />
+            </Bounded>
+        );
+        await expect.poll(() => domRowCount(container)).toBeGreaterThan(0);
+
+        const viewport = container.querySelector<HTMLElement>('.ogx__viewport')!;
+        viewport.scrollTop = rowHeight * 500;
+        viewport.dispatchEvent(new Event('scroll'));
+        await expect.poll(() => Number(firstRow(container).getAttribute('data-rowindex'))).toBeGreaterThan(100);
+
+        const virtualContainer = container.querySelector<HTMLElement>('.ogx__virtual-container')!;
+        const containerTop = virtualContainer.getBoundingClientRect().top;
+        const centerRows = [...virtualContainer.querySelectorAll<HTMLElement>('[role="row"]')];
+        expect(centerRows.length).toBeGreaterThan(5);
+        for (const rowEl of centerRows) {
+            const id = Number(rowEl.querySelector('[data-field="id"]')!.textContent);
+            // ids 1 and 2 are pinned, so id N is unpinned index N - 3.
+            const expectedTop = (id - 3) * rowHeight;
+            expect(Math.round(rowEl.getBoundingClientRect().top - containerTop)).toBe(expectedTop);
+        }
+
+        // The viewport must be filled: the last rendered row reaches past the visible bottom.
+        const lastRendered = centerRows[centerRows.length - 1].getBoundingClientRect().bottom;
+        expect(lastRendered).toBeGreaterThanOrEqual(viewport.getBoundingClientRect().bottom - 1);
+    });
+
+    describe('keyboard navigation keeps the focused row fully visible', () => {
+        const rowHeight = 52;
+        const rows = Array.from({ length: 300 }, (_, i) => ({ id: i + 1, region: 'r', amount: i }));
+
+        const pressArrowDown = async (times: number) => {
+            const grid = document.querySelector<HTMLElement>('.ogx__viewport')!;
+            for (let i = 0; i < times; i++) {
+                grid.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+                await new Promise(r => requestAnimationFrame(() => r(null)));
+            }
+        };
+
+        const assertFocusedRowVisible = (container: HTMLElement) => {
+            const viewport = container.querySelector<HTMLElement>('.ogx__viewport')!;
+            const focused = container.querySelector<HTMLElement>('.ogx__cell--focused')!;
+            expect(focused).not.toBeNull();
+            const cell = focused.getBoundingClientRect();
+            const vp = viewport.getBoundingClientRect();
+            const stickyTop = [...container.querySelectorAll<HTMLElement>('.ogx__header-wrap, .ogx__pinned-rows--top')]
+                .reduce((max, el) => Math.max(max, el.getBoundingClientRect().bottom), vp.top);
+            const stickyBottom = [...container.querySelectorAll<HTMLElement>('.ogx__pinned-rows--bottom')]
+                .reduce((min, el) => Math.min(min, el.getBoundingClientRect().top), vp.top + viewport.clientHeight);
+            expect(cell.top).toBeGreaterThanOrEqual(stickyTop - 1);
+            expect(cell.bottom).toBeLessThanOrEqual(stickyBottom + 1);
+        };
+
+        for (const pinned of [false, true]) {
+            it(`after ArrowDown past the bottom edge${pinned ? ' with pinned top rows' : ''}`, async () => {
+                const { container } = render(
+                    <Bounded>
+                        <DataGrid rows={rows} columns={[{ field: 'id', width: 100 }, ...columns]} height="100%"
+                            rowHeight={rowHeight} pinnedRows={pinned ? { top: [1, 2] } : undefined} />
+                    </Bounded>
+                );
+                await expect.poll(() => domRowCount(container)).toBeGreaterThan(0);
+                const target = container.querySelector<HTMLElement>(`.ogx__virtual-container [data-field="id"]`)!;
+                target.click();
+                await pressArrowDown(20);
+                assertFocusedRowVisible(container);
+            });
+        }
+    });
+
+    it('apiRef.scrollToIndexes brings a row below the fold fully into view', async () => {
+        const rows = Array.from({ length: 300 }, (_, i) => ({ id: i + 1, region: 'r', amount: i }));
+        const onReady = vi.fn<(apiRef: ReturnType<typeof useGridApiRef>) => void>();
+        const Harness = ({ onApi }: { onApi: typeof onReady }) => {
+            const apiRef = useGridApiRef();
+            useEffect(() => { onApi(apiRef); }, [apiRef, onApi]);
+            return <DataGrid apiRef={apiRef} rows={rows} columns={[{ field: 'id', width: 100 }, ...columns]} height="100%" />;
+        };
+        const { container } = render(<Bounded><Harness onApi={onReady} /></Bounded>);
+        await expect.poll(() => domRowCount(container)).toBeGreaterThan(0);
+
+        onReady.mock.calls[0][0].current.scrollToIndexes({ rowIndex: 40 });
+        const viewport = container.querySelector<HTMLElement>('.ogx__viewport')!;
+        viewport.dispatchEvent(new Event('scroll'));
+        const rowEl = () => [...container.querySelectorAll<HTMLElement>('.ogx__virtual-container [role="row"]')]
+            .find(r => r.querySelector('[data-field="id"]')?.textContent === '41');
+        await expect.poll(() => Boolean(rowEl())).toBe(true);
+        const vp = viewport.getBoundingClientRect();
+        const header = container.querySelector<HTMLElement>('.ogx__header-wrap')!.getBoundingClientRect();
+        const r = rowEl()!.getBoundingClientRect();
+        expect(r.top).toBeGreaterThanOrEqual(header.bottom - 1);
+        expect(r.bottom).toBeLessThanOrEqual(vp.top + viewport.clientHeight + 1);
+    });
+});

package/lib/components/DataGrid/GridEmptyState.tsx

@@ -1,9 +1,15 @@
+import type React from 'react';
+
 interface GridEmptyStateProps {
     noRowsLabel: string;
     width: number;
+    overlay?: React.ReactNode;
 }
 
-export function GridEmptyState({ noRowsLabel, width }: GridEmptyStateProps) {
+export function GridEmptyState({ noRowsLabel, width, overlay }: GridEmptyStateProps) {
+    if (overlay) {
+        return <div className="ogx__empty" style={{ width }}>{overlay}</div>;
+    }
     return (
         <div className="ogx__empty" style={{ width }}>
             <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">

package/lib/components/DataGrid/GridListView.tsx

@@ -30,6 +30,7 @@ export interface GridListViewProps<R extends GridRowModel> {
     paginationSlotProps?: Record<string, unknown>;
     localeText?: Pick<GridLocaleText, 'paginationRowsPerPage' | 'paginationOf' | 'paginationPage'>;
     onRowClick: (params: GridRowParams<R>) => void;
+    onRowDoubleClick?: (params: GridRowParams<R>) => void;
     onSelectionChange: (rowId: GridRowId, isSelected: boolean) => void;
     onPaginationModelChange: (model: GridPaginationModel) => void;
 }
@@ -53,6 +54,7 @@ export function GridListView<R extends GridRowModel>({
     paginationSlotProps,
     localeText,
     onRowClick,
+    onRowDoubleClick,
     onSelectionChange,
     onPaginationModelChange,
 }: GridListViewProps<R>) {
@@ -97,6 +99,7 @@ export function GridListView<R extends GridRowModel>({
                             checkboxSelection={checkboxSelection}
                             rowHeight={rowHeight}
                             onRowClick={(r) => onRowClick({ row: r, id: r.id, rowIndex: idx })}
+                            onRowDoubleClick={onRowDoubleClick ? (r) => onRowDoubleClick({ row: r, id: r.id, rowIndex: idx }) : undefined}
                             onSelectionChange={onSelectionChange}
                         />
                     ))

package/lib/components/DataGrid/GridPinnedRows.tsx

@@ -21,6 +21,7 @@ export interface GridPinnedRowsProps<R extends GridRowModel> {
     selectedRowIds: Set<GridRowId>;
     checkboxSelection: boolean;
     onRowClick: (params: GridRowParams<R>) => void;
+    onRowDoubleClick?: (params: GridRowParams<R>) => void;
     onCellClick: (params: GridCellParams<R>) => void;
     onSelectionChange: (rowId: GridRowId, isSelected: boolean) => void;
     columnWidths: Record<string, number>;
@@ -47,6 +48,7 @@ export function GridPinnedRows<R extends GridRowModel>({
     selectedRowIds,
     checkboxSelection,
     onRowClick,
+    onRowDoubleClick,
     onCellClick,
     onSelectionChange,
     columnWidths,
@@ -78,6 +80,7 @@ export function GridPinnedRows<R extends GridRowModel>({
                     isSelected={selectedRowIds.has(row.id)}
                     checkboxSelection={checkboxSelection}
                     onRowClick={onRowClick}
+                    onRowDoubleClick={onRowDoubleClick}
                     onCellClick={onCellClick}
                     onSelectionChange={onSelectionChange}
                     columnWidths={columnWidths}

package/lib/components/DataGrid/GridVirtualRows.tsx

@@ -41,6 +41,7 @@ export interface GridVirtualRowsProps<R extends GridRowModel> {
     pinnedRows?: GridRowPinning;
     selectedRowIds: Set<GridRowId>;
     onRowClick: (params: GridRowParams<R>) => void;
+    onRowDoubleClick?: (params: GridRowParams<R>) => void;
     onCellClick: (params: GridCellParams<R>) => void;
     onSelectionChange: (rowId: GridRowId, isSelected: boolean) => void;
     columnWidths: Record<string, number>;
@@ -62,6 +63,7 @@ export interface GridVirtualRowsProps<R extends GridRowModel> {
     infiniteScrollSkeletonCount: number;
     unpinnedRowsLength: number;
     rowMetaMap: Map<GridRowId, GridRowMeta>;
+    loadingOverlay?: React.ReactNode;
 }
 
 export function GridVirtualRows<R extends GridRowModel>({
@@ -79,6 +81,7 @@ export function GridVirtualRows<R extends GridRowModel>({
     pinnedRows,
     selectedRowIds,
     onRowClick,
+    onRowDoubleClick,
     onCellClick,
     onSelectionChange,
     columnWidths,
@@ -100,6 +103,7 @@ export function GridVirtualRows<R extends GridRowModel>({
     infiniteScrollSkeletonCount,
     unpinnedRowsLength,
     rowMetaMap,
+    loadingOverlay,
 }: GridVirtualRowsProps<R>) {
     const skeletonColumns: GridColDef<R>[] = baseColumns.length > 0
         ? baseColumns
@@ -134,7 +138,9 @@ export function GridVirtualRows<R extends GridRowModel>({
                 style={{ transform: `translateY(${offsetTop}px)` }}
                 role="rowgroup"
             >
-                {effectiveLoading && visibleRows.length === 0 ? (
+                {effectiveLoading && visibleRows.length === 0 && loadingOverlay ? (
+                    <div className="ogx__loading-overlay" style={{ width: viewportWidth || undefined }}>{loadingOverlay}</div>
+                ) : effectiveLoading && visibleRows.length === 0 ? (
                     Array.from({ length: 10 }).map((_, index) => (
                         <SkeletonRow
                             key={`skeleton-${index}`}
@@ -155,6 +161,7 @@ export function GridVirtualRows<R extends GridRowModel>({
                             isSelected={selectedRowIds.has(row.id)}
                             checkboxSelection={checkboxSelection}
                             onRowClick={onRowClick}
+                            onRowDoubleClick={onRowDoubleClick}
                             onCellClick={onCellClick}
                             onSelectionChange={onSelectionChange}
                             columnWidths={columnWidths}

package/lib/components/ListView/ListViewRow.tsx

@@ -9,6 +9,7 @@ export interface ListViewRowProps<R extends GridRowModel = GridRowModel> {
     checkboxSelection?: boolean;
     rowHeight?: number;
     onRowClick?: (row: R) => void;
+    onRowDoubleClick?: (row: R) => void;
     onSelectionChange?: (rowId: GridRowId, isSelected: boolean) => void;
 }
 
@@ -20,6 +21,7 @@ export function ListViewRow<R extends GridRowModel = GridRowModel>({
     checkboxSelection = false,
     rowHeight,
     onRowClick,
+    onRowDoubleClick,
     onSelectionChange,
 }: ListViewRowProps<R>) {
     const params: GridRenderCellParams<R> = {
@@ -41,6 +43,7 @@ export function ListViewRow<R extends GridRowModel = GridRowModel>({
             className={`ogx-list-view__row${isSelected ? ' ogx-list-view__row--selected' : ''}`}
             style={rowHeight ? { minHeight: rowHeight } : undefined}
             onClick={() => onRowClick?.(row)}
+            onDoubleClick={onRowDoubleClick ? () => onRowDoubleClick(row) : undefined}
             role="row"
             aria-rowindex={rowIndex + 2}
             aria-selected={isSelected}

package/lib/components/Row/Row.tsx

@@ -17,6 +17,7 @@ export interface RowProps<R extends GridRowModel = GridRowModel> {
     isSelected?: boolean;
     checkboxSelection?: boolean;
     onRowClick?: (params: GridRowParams<R>) => void;
+    onRowDoubleClick?: (params: GridRowParams<R>) => void;
     onCellClick?: (params: GridCellParams<R>) => void;
     onSelectionChange?: (rowId: GridRowId, isSelected: boolean) => void;
     columnWidths?: Record<string, number>;
@@ -62,6 +63,7 @@ export function Row<R extends GridRowModel = GridRowModel>(props: RowProps<R>) {
         isSelected = false,
         checkboxSelection = false,
         onRowClick,
+        onRowDoubleClick,
         onCellClick,
         onSelectionChange,
         columnWidths = {},
@@ -167,6 +169,13 @@ export function Row<R extends GridRowModel = GridRowModel>(props: RowProps<R>) {
         onRowClick?.({ row, id: row.id, rowIndex });
     };
 
+    const handleRowDoubleClick = (event: React.MouseEvent) => {
+        if ((event.target as HTMLElement).closest('.ogx-checkbox-wrapper, .ogx-expand-icon, .ogx-drag-handle, .ogx__edit-cell')) {
+            return;
+        }
+        onRowDoubleClick?.({ row, id: row.id, rowIndex });
+    };
+
     const handleCheckboxChange = (event: React.ChangeEvent<HTMLInputElement>) => {
         event.stopPropagation();
         onSelectionChange?.(row.id, event.target.checked);
@@ -198,6 +207,7 @@ export function Row<R extends GridRowModel = GridRowModel>(props: RowProps<R>) {
             <div
                 className={classNames}
                 onClick={handleRowClick}
+                onDoubleClick={onRowDoubleClick ? handleRowDoubleClick : undefined}
                 role="row"
                 aria-rowindex={rowIndex + 1}
                 aria-selected={isSelected}

package/lib/hooks/core/useGridColumns.tsx

@@ -14,6 +14,11 @@ interface HierarchyHandlers {
     toggleExpansion: (id: GridRowId) => void;
 }
 
+// Injected hierarchy renderers replace the plain-cell path in Cell, so they must
+// render the formatted value themselves or valueFormatter is silently lost.
+const displayValue = <R extends GridRowModel>(cellParams: GridRenderCellParams<R>): React.ReactNode =>
+    cellParams.formattedValue ?? (cellParams.value as React.ReactNode);
+
 export interface UseGridColumnsParams<R extends GridRowModel> {
     activeColumns: GridColDef<R>[];
     isHierarchyEnabled: boolean;
@@ -83,7 +88,7 @@ export function useGridColumns<R extends GridRowModel>(
                         const descendantCount = meta?.descendantCount;
                         const isGroupRow = Boolean(meta?.isGroupRow);
 
-                        let content: React.ReactNode = col.renderCell ? col.renderCell(cellParams) : cellParams.value as React.ReactNode;
+                        let content: React.ReactNode = col.renderCell ? col.renderCell(cellParams) : displayValue(cellParams);
 
                         if (isTreeData && hasChildren && isGroupRow) {
                             content = (
@@ -137,12 +142,12 @@ export function useGridColumns<R extends GridRowModel>(
                     if (isRowGrouping && hasChildren) {
                         if (col.field === groupingField) return null;
                         if (cellParams.value !== undefined && cellParams.value !== null) {
-                            return col.renderCell ? col.renderCell(cellParams) : cellParams.value;
+                            return col.renderCell ? col.renderCell(cellParams) : displayValue(cellParams);
                         }
                         return null;
                     }
 
-                    return col.renderCell ? col.renderCell(cellParams) : cellParams.value;
+                    return col.renderCell ? col.renderCell(cellParams) : displayValue(cellParams);
                 }
             };
         }) as GridColDef<R>[];

package/lib/hooks/core/useGridDevWarnings.ts

@@ -0,0 +1,42 @@
+import { useEffect, useRef } from 'react';
+
+export interface UseGridDevWarningsParams {
+    paginationRequested: boolean;
+    isRowGrouping: boolean;
+    autoHeight: boolean;
+    viewportHeight: number;
+    renderedRowCount: number;
+    totalRowCount: number;
+}
+
+// Below this many rows, rendering everything is harmless, so an unbounded container is not worth a warning.
+const UNBOUNDED_WARN_THRESHOLD = 200;
+
+export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
+    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount } = params;
+    const warnedPaginationRef = useRef(false);
+    const warnedUnboundedRef = useRef(false);
+
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedPaginationRef.current) return;
+        if (paginationRequested && isRowGrouping) {
+            warnedPaginationRef.current = true;
+            console.warn(
+                '[OpenGridX] `pagination` is ignored while `rowGroupingModel` is active — all group rows render in one ' +
+                'scrollable view. Give the grid a bounded height so it virtualizes. See docs/features/tree-data-grouping.md.'
+            );
+        }
+    }, [paginationRequested, isRowGrouping]);
+
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedUnboundedRef.current || autoHeight) return;
+        if (viewportHeight > 0 && totalRowCount > UNBOUNDED_WARN_THRESHOLD && renderedRowCount >= totalRowCount) {
+            warnedUnboundedRef.current = true;
+            console.warn(
+                `[OpenGridX] The grid viewport is ${Math.round(viewportHeight)}px tall and is rendering all ${totalRowCount} rows, ` +
+                'so row virtualization is effectively off. The grid container has no bounded height: it grows to fit its ' +
+                'content. Give it a fixed height, or if it is a flex child add `min-height: 0`. See docs/features/virtualization.md.'
+            );
+        }
+    }, [autoHeight, viewportHeight, renderedRowCount, totalRowCount]);
+}

package/lib/hooks/core/useGridKeyboardNavigation.ts

@@ -1,4 +1,5 @@
 import { useState, useCallback } from 'react';
+import { scrollRowIntoView } from '../../utils/scroll';
 import type { GridRowModel, GridRowId, GridColDef, GridCellParams, GridSortItem, GridSortDirection } from '../../types';
 import type { GridEditingState } from '../features/useGridEditing';
 
@@ -14,6 +15,7 @@ interface ColumnMetrics {
 interface VirtualizationSnapshot {
     cumulativeHeights: number[];
     pinnedTopHeight: number;
+    pinnedBottomHeight: number;
     columnMetrics: ColumnMetrics | null;
 }
 
@@ -37,6 +39,8 @@ export interface UseGridKeyboardNavigationParams<R extends GridRowModel> {
     pageSize: number;
     virtualization: VirtualizationSnapshot;
     viewportRef: React.RefObject<HTMLDivElement | null>;
+    /** Number of top-pinned rows at the start of allRenderableRows. */
+    pinnedTopRowCount?: number;
 }
 
 export interface FocusedCell {
@@ -71,6 +75,7 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
         pageSize,
         virtualization,
         viewportRef,
+        pinnedTopRowCount = 0,
     } = params;
 
     const [focusedCell, setFocusedCell] = useState<FocusedCell | null>(null);
@@ -311,21 +316,13 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
 
                 const el = viewportRef.current;
                 if (el) {
-                    const { cumulativeHeights, pinnedTopHeight, columnMetrics } = virtualization;
-                    const { clientHeight, clientWidth, scrollTop, scrollLeft } = el;
-
-                    const rowTop = nextRowIndex <= 0 ? 0 : cumulativeHeights[nextRowIndex - 1];
-                    const rowBottom = cumulativeHeights[nextRowIndex];
-                    const visibleTop = scrollTop + pinnedTopHeight;
-                    const visibleBottom = scrollTop + clientHeight;
-
-                    let newScrollTop = scrollTop;
-                    if (rowTop < visibleTop) {
-                        newScrollTop = Math.max(0, rowTop - pinnedTopHeight);
-                    } else if (rowBottom > visibleBottom) {
-                        newScrollTop = rowBottom - clientHeight;
+                    const { cumulativeHeights, pinnedBottomHeight, columnMetrics } = virtualization;
+                    const { clientWidth, scrollLeft } = el;
+
+                    // allRenderableRows = pinned top + center + pinned bottom; pinned rows are sticky and always visible.
+                    if (nextRowIndex >= 0) {
+                        scrollRowIntoView(el, nextRowIndex - pinnedTopRowCount, cumulativeHeights, pinnedBottomHeight);
                     }
-                    if (newScrollTop !== scrollTop) el.scrollTop = newScrollTop;
 
                     if (columnMetrics) {
                         const { leftPinnedWidth, rightPinnedWidth, unpinnedAccWidths, unpinnedCols, totalSpecialsWidth, pinnedSpecialsWidth } = columnMetrics;
@@ -365,6 +362,7 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
         pagination,
         pageSize,
         viewportRef,
+        pinnedTopRowCount,
     ]);
 
     return { focusedCell, setFocusedCell, handleFocus, handleBlur, handleKeyDown };

package/lib/hooks/core/useGridVisibleRows.ts

@@ -43,8 +43,9 @@ export function useGridVisibleRows<R extends GridRowModel>(
             rowIndex: topPinnedCount + centerRows.length + index,
         }));
 
-        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)