@opencorestack/opengridx 2.0.2 → 2.0.4

package/docs/API_REFERENCE.md

@@ -18,13 +18,14 @@ The main component for displaying and interacting with data.
 | `rowHeight` | `number` | `52` | Height of each row in pixels. |
 | `headerHeight` | `number` | `56` | Height of the header row. |
 | `autoHeight` | `boolean` | `false` | Adjust grid height to match row total. |
+| `overscanRowCount` | `number` | `3` | Minimum rows rendered outside the visible viewport. The grid adapts this upward automatically based on scroll velocity — this prop sets the floor. |
 | `loading` | `boolean` | `false` | Shows a loading skeleton overlay. |
 | `checkboxSelection` | `boolean` | `false` | Enable row selection via checkboxes. |
 | `pagination` | `boolean` | `false` | Enable the bottom pagination bar. |
 | `paginationMode` | `'client' \| 'server' \| 'infinite'` | `'client'` | How to handle paging. |
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). |
 | `onPaginationModelChange` | `(model: GridPaginationModel) => void` | — | Fired when page or page size changes. |
-| `pageSizeOptions` | `number[]` | `[10, 25, 50]` | Available page size options. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Available page size options. |
 | `rowCount` | `number` | — | Total rows (required for server-side paging). |
 | `height` | `number \| string` | `undefined` | Total height of the grid container. |
 | `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Visual row density. |
@@ -82,8 +83,8 @@ The main component for displaying and interacting with data.
 | `pinnedColumns` | `GridColumnPinning` | — | Columns pinned to the left or right viewport edges. See [Column & Row Pinning](#-column--row-pinning). |
 | `onPinnedColumnsChange` | `(model: GridColumnPinning) => void` | — | Fired when column pinning changes. |
 | `pinnedRows` | `GridRowPinning` | — | Row IDs pinned to the top or bottom of the viewport. |
-| `pinCheckboxColumn` | `boolean` | `false` | Keeps the checkbox column visible during horizontal scrolling. |
-| `pinExpandColumn` | `boolean` | `false` | Keeps the Master-Detail expansion column visible during horizontal scrolling. |
+| `pinCheckboxColumn` | `boolean` | `true` | Keeps the checkbox column visible during horizontal scrolling. |
+| `pinExpandColumn` | `boolean` | `true` | Keeps the Master-Detail expansion column visible during horizontal scrolling. |
 
 #### Inline Editing
 
@@ -138,7 +139,7 @@ The main component for displaying and interacting with data.
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `ariaLabel` | `string` | — | ARIA label for the grid container element. |
-| `noRowsLabel` | `string` | `'No rows'` | Message shown in the empty-state overlay when there are no rows. |
+| `noRowsLabel` | `string` | `'No Data'` | Message shown in the empty-state overlay when there are no rows. |
 | `className` | `string` | — | Additional CSS class applied to the outermost grid wrapper element. |
 | `style` | `React.CSSProperties` | — | Inline styles applied to the grid wrapper element. |
 
@@ -246,6 +247,8 @@ Access these methods via the `apiRef` prop.
 | `getAllColumns()` | `GridColDef[]` | Get all defined columns. |
 | `getAggregationResult()` | `Record<string, unknown> \| null` | Get current aggregation results. |
 | `getAggregationModel()` | `GridAggregationModel \| null` | Get the active aggregation configuration. |
+| `getAllFilteredRows()` | `GridRowModel[]` | Get all filtered+sorted rows regardless of the current pagination window. Use for full-dataset exports. |
+| `getGroupedExportRows()` | `GridGroupedExportRow[] \| null` | Get a flat ordered list reflecting the active row-grouping tree (group-header, leaf, subtotal, grand-total). Returns `null` when row grouping is not active. |
 | `copySelectedRows()` | `Promise<void>` | Copy selected rows to clipboard as TSV. |
 
 ---
@@ -593,6 +596,7 @@ interface GridRowMeta {
   treeDepth?: number;
   groupingField?: string;
   groupingValue?: unknown;
+  groupLabel?: string;
   descendantCount?: number;
   isExpanded?: boolean;
   isGroupRow?: boolean;
@@ -1245,6 +1249,7 @@ interface PdfExportOptions {
     aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
     filterModel?: GridFilterModel | null;
+    groupedRows?: GridGroupedExportRow[];
     alternateRowColor?: boolean;
     headerBackgroundColor?: string;
     headerTextColor?: string;
@@ -1262,6 +1267,7 @@ interface PdfExportOptions {
 | `aggregationResult` | `Record<string, unknown>` | — | From `apiRef.current.getAggregationResult()` |
 | `aggregationModel` | `GridAggregationModel` | — | From `apiRef.current.getAggregationModel()` |
 | `filterModel` | `GridFilterModel` | — | From `apiRef.current.getFilterModel()` |
+| `groupedRows` | `GridGroupedExportRow[]` | — | Pre-built grouped export rows from `apiRef.current.getGroupedExportRows()`. When provided, the PDF table reflects the grouping structure (group-header, indented leaves, subtotals, grand total). |
 | `alternateRowColor` | `boolean` | `true` | Alternating row background shading |
 | `headerBackgroundColor` | `string` | `'#4f46e5'` | Column header cell background (hex) |
 | `headerTextColor` | `string` | `'#ffffff'` | Column header cell text color (hex) |

package/docs/components/aggregation-footer.md

@@ -7,7 +7,7 @@ Internal component that renders the sticky aggregation totals row pinned to the
 | Prop | Type | Description |
 | :--- | :--- | :--- |
 | `columns` | `GridColDef[]` | Ordered list of visible column definitions used to lay out cells. |
-| `aggregationModel` | `GridAggregationModel` | Maps field names to function names (`'sum' \| 'avg' \| 'count' \| 'min' \| 'max'`). |
+| `aggregationModel` | `GridAggregationModel` | Maps field names to function names (`'sum' \| 'avg' \| 'count' \| 'min' \| 'max' \| 'unique'`). |
 | `aggregationResult` | `GridAggregationResult` | Computed values keyed by field name, produced by `useAggregation`. |
 | `columnWidths` | `Record<string, number>` | Runtime pixel widths for each field, kept in sync with user resize actions. |
 | `rowHeight` | `number` | Sets `min-height` on the footer row, matching the grid's configured row height. |

package/docs/components/column-group-header.md

@@ -40,16 +40,9 @@ While the grid uses this component internally, you can customize its appearance
 
 ---
 
-## 🎨 Slot Implementation
-Replace the system's group header with a custom one for specialized styling or interactions.
+## 🎨 Customization
 
-```tsx
-<DataGrid
-  slots={{
-    columnGroupHeader: MyCustomGroupHeader
-  }}
-/>
-```
+Column group headers are rendered internally; they cannot be replaced via the slots API. Style them through CSS targeting `.ogx__column-group-header`, or use the `columnGroupingModel` to control grouping structure.
 
 ## 📝 Best Practices
 - **Logical Labels**: Use clear, concise labels for groups like `2024 Performance` or `Contact Info`.

package/docs/components/column-resize.md

@@ -22,15 +22,14 @@ const columns: GridColDef[] = [
 ];
 ```
 
-### Grid-Wide Control
-Disable resizing globally via the `DataGrid` props.
+### Disabling Resize Per Column
+There is no single grid-wide prop to disable all column resizing. Set `resizable: false` on each column definition individually:
 
 ```tsx
-<DataGrid
-  rows={rows}
-  columns={columns}
-  disableColumnResize
-/>
+const columns: GridColDef[] = [
+  { field: 'id', headerName: 'ID', resizable: false },
+  { field: 'status', headerName: 'Status', resizable: false },
+];
 ```
 
 ---
@@ -46,18 +45,18 @@ Disable resizing globally via the `DataGrid` props.
 
 ---
 
-## 🎨 Slot Implementation
-In the DataGrid, you can replace the default handle component for custom styling (e.g., a thicker line or different colors).
+## 🎨 Styling the Resize Handle
 
-```tsx
-<DataGrid
-  slots={{
-    columnResizeHandle: MyCustomHandle
-  }}
-/>
+The resize handle is not replaceable via the slots API. Style it through CSS:
+
+```css
+.ogx__resize-handle {
+  width: 4px;
+  background: #6366f1;
+}
 ```
 
 ## 📝 Best Practices
 - **Define Min Widths**: Always set a reasonable `minWidth` so columns don't accidentally become 0px wide.
-- **Persistence**: Listen to `onColumnWidthChange` to save the user's preferred layout for their next visit.
+- **Persistence**: Use `onStateChange` to capture the current `columnWidths` from the state snapshot and save the user's preferred layout for their next visit.
 - **Content Fit**: Remember that large data values might hide behind narrow columns; use tooltips for overflow coverage.

package/docs/components/column-visibility.md

@@ -45,14 +45,14 @@ You can also render it persistently beside the grid or within a custom modal.
 
 ---
 
-## 🎨 Slot Implementation
-In advanced scenarios, you can replace the default panel with your own implementation using the `columnVisibilityPanel` slot.
+## 🎨 Controlling Visibility Programmatically
+
+The column visibility panel is an internal component; it cannot be replaced via the slots API. Use the controlled props to drive visibility from outside:
 
 ```tsx
 <DataGrid
-  slots={{
-    columnVisibilityPanel: MyCustomVisibilityPanel
-  }}
+  columnVisibilityModel={model}
+  onColumnVisibilityModelChange={setModel}
 />
 ```
 

package/docs/components/datagrid.md

@@ -33,8 +33,9 @@ function MyGrid() {
 | `disableMultipleRowSelection` | `boolean` | `false` | When `true`, at most one row can be selected at a time. |
 | `pagination` | `boolean` | `false` | Enable/Disable bottom pagination bar. |
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). Omit for uncontrolled; use `initialState` to set the initial page/pageSize. |
-| `pageSizeOptions` | `number[]` | `[10, 25, 50]` | Available page size options. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Available page size options. |
 | `initialState` | `GridInitialState` | `undefined` | Initial configuration (sorting, columns, pagination, etc). |
+| `overscanRowCount` | `number` | `3` | Minimum rows rendered outside the visible viewport. The grid adapts this upward automatically based on scroll velocity — this prop sets the floor. |
 
 ## 🔃 Sorting
 

package/docs/components/empty-state.md

@@ -43,7 +43,7 @@ To only change the message text without replacing the whole component, use `noRo
 />
 ```
 
-Default value: `"No rows"`
+Default value: `"No Data"`
 
 ## 🔗 Related
 - [DataGrid](datagrid.md)

package/docs/components/tooltip.md

@@ -52,15 +52,12 @@ You can choose from four different placements: `top`, `bottom`, `left`, or `righ
 
 ---
 
-## 🎨 Slot Implementation
-In the DataGrid, specialized components like the Toolbar often use tooltips within their built-in actions. These can be customized or replaced using the slots API.
+## 🎨 Customization
+
+The internal tooltip component is not replaceable via the slots API. For column-header tooltips, set the `description` field on `GridColDef` — it renders as the native `title` attribute on the header cell (v2.0.0+):
 
 ```tsx
-<DataGrid
-  slots={{
-    tooltip: GridTooltip
-  }}
-/>
+{ field: 'revenue', headerName: 'Revenue', description: 'Total billed revenue for the period' }
 ```
 
 ## 📝 Accessibility

package/docs/features/aggregation-pivot.md

@@ -25,12 +25,12 @@ Aggregation allows you to calculate summary values (Sum, Avg, etc.) for groups o
 You can control where the aggregation results appear:
 - **`footer`**: A sticky row at the bottom of the grid.
 - **`inline`**: Values displayed within group headers (when Row Grouping is active).
-- **`both`**: Display in both locations.
+- **`null`**: Skip aggregation for this group.
 
 ```tsx
 <DataGrid
   aggregationModel={model}
-  getAggregationPosition={(groupNode) => 'both'}
+  getAggregationPosition={(groupNode) => groupNode ? 'inline' : 'footer'}
 />
 ```
 

package/docs/features/cell-spanning.md

@@ -53,7 +53,7 @@ const columns: GridColDef<Row>[] = [
         // Disable conflicting features
         sortable: false,        // ✅ Disable sorting
         hideable: false,        // ✅ Disable column hiding
-        disableReorder: true,   // ✅ Disable column reordering
+        // Column reorder is disabled grid-wide via disableColumnReorder on <DataGrid>
         // Note: Avoid pinning this column
         renderCell: (params) => {
             if (params.row.isTotal) {

package/docs/features/loading-states.md

@@ -44,14 +44,14 @@ Unlike infinite scroll which appends data to the end, Lazy Loading fetches speci
 Quickly filter the entire dataset across all visible columns. This is managed via the `GridToolbar`.
 
 ### Basic Setup
+
+Add the toolbar and wire a filter model — the toolbar's search bar activates automatically when `onFilterModelChange` is wired:
+
 ```tsx
 <DataGrid
   slots={{ toolbar: GridToolbar }}
-  slotProps={{
-    toolbar: {
-       showQuickFilter: true
-    }
-  }}
+  filterModel={filterModel}
+  onFilterModelChange={setFilterModel}
 />
 ```
 

package/docs/features/selection.md

@@ -70,7 +70,7 @@ Use `disableMultipleRowSelection` to cap selection to one row at a time. Clickin
 | `disableMultipleRowSelection` | `boolean` | `false` | Restricts selection to a single row. |
 | `rowSelectionModel` | `GridRowId[]` | `[]` | Controlled array of selected IDs. |
 | `onRowSelectionModelChange` | `(model: GridRowSelectionModel) => void` | — | Fired when the selection changes. |
-| `pinCheckboxColumn` | `boolean` | `false` | Keep the checkbox column visible during horizontal scroll. |
+| `pinCheckboxColumn` | `boolean` | `true` | Keep the checkbox column visible during horizontal scroll. |
 
 ---
 

package/docs/features/sorting-pagination.md

@@ -90,7 +90,7 @@ When using `paginationMode="server"`, you must provide the `rowCount` and handle
 | `paginationMode` | `'client' \| 'server' \| 'infinite'` | `'client'` | Location of the pagination logic. |
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). |
 | `onPaginationModelChange` | `(model: GridPaginationModel) => void` | — | Fired when page or page size changes. |
-| `pageSizeOptions` | `number[]` | `[10, 25, 50]` | Options for the rows-per-page selector. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Options for the rows-per-page selector. |
 
 ---
 

package/docs/features/virtualization.md

@@ -54,6 +54,18 @@ The grid supports both fixed and variable row heights:
 />
 ```
 
+The `density` prop overrides `rowHeight` with preset values:
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  density="compact"      // 32px rows
+  // density="standard"  // uses rowHeight (default 52px)
+  // density="comfortable" // 72px rows
+/>
+```
+
 ### Auto Height
 
 Disable virtualization for small datasets:
@@ -72,16 +84,37 @@ Disable virtualization for small datasets:
 
 ### Overscan Buffer
 
-The overscan buffer determines how many extra rows are rendered outside the viewport. A larger buffer provides smoother scrolling but uses more memory.
+The overscan buffer determines how many extra rows are rendered outside the viewport. The grid adapts this buffer automatically based on scroll velocity so fast scrolls never produce blank flashes.
+
+**Adaptive algorithm (`useGridScrollSync`):**
+- Scroll velocity (px/ms) is measured on every scroll event
+- The overscan tier is chosen from the table below and applied immediately
+- 200 ms after scrolling stops the buffer decays back to `overscanRowCount`
+
+| Velocity (px/ms) | Overscan rows |
+|---|---|
+| < 0.5 | 3 |
+| 0.5 – 3 | 5 |
+| 3 – 15 | 12 |
+| 15 – 40 | 20 |
+| > 40 | 30 |
+
+**Configuring the floor:**
+
+```tsx
+// Never render fewer than 5 rows outside the viewport
+<DataGrid
+  rows={rows}
+  columns={columns}
+  overscanRowCount={5}
+/>
+```
 
-**Current implementation:**
-- Default overscan: **5 rows** (above and below viewport)
-- Total rendered rows: ~(viewport rows + 10)
+`overscanRowCount` (default `3`) sets the minimum — the adaptive algorithm always produces a value ≥ this floor.
 
 **Trade-offs:**
-- **Smaller overscan (1-3)**: Less memory, potential flickering during fast scrolling
-- **Larger overscan (5-8)**: More memory, smoother fast scrolling
-- **Very large overscan (10+)**: Diminishing returns, wasted rendering
+- **Smaller floor (1-3)**: Less idle memory, relies on adaptive headroom for fast scrolls
+- **Larger floor (5-8)**: Pre-renders more rows at rest, trades memory for smoother slow scrolls
 
 ### Scroll Performance
 
@@ -166,18 +199,18 @@ You should see console logs only for visible rows + overscan buffer.
 ## Future Improvements
 
 - [ ] Column virtualization for grids with 50+ columns
-- [ ] Adaptive overscan based on scroll velocity
+- [x] Adaptive overscan based on scroll velocity (`overscanRowCount` prop, v2.0.4)
 - [ ] Virtual scrollbar for extremely large datasets (millions of rows)
 - [ ] Intersection Observer API for better scroll detection
 
 ## Comparison with MUI X DataGrid
 
-| Feature | Aui DataGrid | MUI X DataGrid |
+| Feature | OpenGridX | MUI X DataGrid |
 |---------|--------------|----------------|
 | Row virtualization | ✅ Yes | ✅ Yes |
 | Column virtualization | ❌ Planned | ✅ Yes (Pro) |
 | Variable row heights | ✅ Yes | ✅ Yes |
-| Overscan buffer | 5 rows | 3-8 rows (adaptive) |
+| Overscan buffer | 3–30 rows (adaptive, velocity-based) | 3-8 rows (adaptive) |
 | Max recommended rows | 100,000+ | 100,000+ |
 
 ## Related Documentation

package/docs/roadmap.md

@@ -5,7 +5,7 @@ This document tracks the current status of features in `OpenGridX` and outlines
 ## ✅ Implemented Features
 
 ### Core
-*   **Virtualization**: High-performance row and column virtualization for handling large datasets.
+*   **Virtualization**: High-performance row virtualization for handling large datasets. Column virtualization is planned (currently all columns are rendered).
 *   **Sorting**: Client-side and server-side multi-column sorting.
 *   **Filtering**: Client-side filtering with support for various operators.
 *   **Pagination**: Client-side and server-side pagination with customizable page sizes.

package/lib/components/DataGrid/DataGrid.tsx

@@ -118,6 +118,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         noRowsLabel = 'No Data',
         localeText,
         apiRef: propApiRef,
+        overscanRowCount = 3,
     } = props;
 
     const effectiveNoRowsLabel = localeText?.noRowsLabel ?? noRowsLabel;
@@ -301,7 +302,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         setRowCount
     } = gridData;
 
-    const { scrollTop, scrollLeft, handleScroll } = useGridScrollSync({ onRowsScrollEnd });
+    const { scrollTop, scrollLeft, overscanRows, handleScroll } = useGridScrollSync({ onRowsScrollEnd, overscanRowCount });
 
     useEffect(() => {
         if (propApiRef) {
@@ -693,6 +694,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         checkboxSelection,
         pinCheckboxColumn,
         pinExpandColumn,
+        overscanRows,
     });
 
 

package/lib/hooks/core/useGridScrollSync.ts

@@ -3,42 +3,84 @@ import type { GridRowScrollEndParams } from '../../types';
 
 export interface UseGridScrollSyncParams {
     onRowsScrollEnd?: (params: GridRowScrollEndParams) => void;
+    /** Minimum overscan rows — the adaptive algorithm never goes below this. Defaults to 3. */
+    overscanRowCount?: number;
 }
 
 export interface UseGridScrollSyncResult {
     scrollTop: number;
     scrollLeft: number;
+    /** Dynamically computed overscan row count based on current scroll velocity. */
+    overscanRows: number;
     handleScroll: (event: React.UIEvent<HTMLDivElement>) => 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);
+}
+
 export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrollSyncResult {
-    const { onRowsScrollEnd } = params;
+    const { onRowsScrollEnd, overscanRowCount = 3 } = params;
 
-    const pendingScrollRef = useRef({ scrollTop: 0, scrollLeft: 0 });
-    const scrollRafRef = useRef<number | null>(null);
-    const [scrollPos, setScrollPos] = useState({ scrollTop: 0, scrollLeft: 0 });
+    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 [scrollState, setScrollState] = useState({
+        scrollTop: 0,
+        scrollLeft: 0,
+        overscanRows: overscanRowCount,
+    });
 
     useEffect(() => {
         return () => {
-            if (scrollRafRef.current !== null) cancelAnimationFrame(scrollRafRef.current);
+            if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
+            if (decayRef.current !== null) clearTimeout(decayRef.current);
         };
     }, []);
 
     const handleScroll = useCallback((event: React.UIEvent<HTMLDivElement>) => {
         const target = event.currentTarget;
-        pendingScrollRef.current = { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft };
+        const now = performance.now();
+
+        // Velocity: total positional delta / elapsed time (px/ms)
+        const deltaPos = Math.abs(target.scrollTop  - prevRef.current.scrollTop)
+                       + Math.abs(target.scrollLeft - prevRef.current.scrollLeft);
+        const deltaTime = now - prevRef.current.time;
+        const velocity = deltaTime > 0 ? deltaPos / deltaTime : 0;
 
-        if (scrollRafRef.current !== null) cancelAnimationFrame(scrollRafRef.current);
-        scrollRafRef.current = requestAnimationFrame(() => {
-            scrollRafRef.current = null;
-            setScrollPos(pendingScrollRef.current);
+        prevRef.current = { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft, time: now };
+        pendingRef.current = { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft, velocity };
+
+        if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
+        rafRef.current = requestAnimationFrame(() => {
+            rafRef.current = null;
+            const { scrollTop, scrollLeft, velocity: v } = pendingRef.current;
+            setScrollState({
+                scrollTop,
+                scrollLeft,
+                overscanRows: velocityToOverscan(v, overscanRowCount),
+            });
         });
 
+        // 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 }));
+        }, 200);
+
         if (onRowsScrollEnd) {
             const { scrollTop, scrollHeight, clientHeight } = target;
-            const scrollThreshold = 100;
-
-            if (scrollHeight - scrollTop - clientHeight < scrollThreshold) {
+            if (scrollHeight - scrollTop - clientHeight < 100) {
                 onRowsScrollEnd({
                     visibleTop: scrollTop,
                     visibleBottom: scrollTop + clientHeight,
@@ -46,7 +88,12 @@ export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrol
                 });
             }
         }
-    }, [onRowsScrollEnd]);
+    }, [onRowsScrollEnd, overscanRowCount]);
 
-    return { scrollTop: scrollPos.scrollTop, scrollLeft: scrollPos.scrollLeft, handleScroll };
+    return {
+        scrollTop:    scrollState.scrollTop,
+        scrollLeft:   scrollState.scrollLeft,
+        overscanRows: scrollState.overscanRows,
+        handleScroll,
+    };
 }

package/lib/hooks/core/useGridVirtualization.ts

@@ -14,6 +14,8 @@ export interface UseGridVirtualizationParams<R extends GridRowModel> {
     checkboxSelection: boolean;
     pinCheckboxColumn: boolean;
     pinExpandColumn: boolean;
+    /** Adaptive overscan row count from useGridScrollSync. Defaults to 5. */
+    overscanRows?: number;
 }
 
 export interface GridVirtualizationResult<R extends GridRowModel = GridRowModel> {
@@ -57,6 +59,7 @@ export function useGridVirtualization<R extends GridRowModel>(
         checkboxSelection,
         pinCheckboxColumn,
         pinExpandColumn,
+        overscanRows = 5,
     } = params;
 
     return useMemo<GridVirtualizationResult<R>>(() => {
@@ -120,7 +123,6 @@ export function useGridVirtualization<R extends GridRowModel>(
         const scrollbarBuffer = hasHorizontalScroll ? 16 : 0;
         const totalHeight = pinnedTopHeight + unpinnedRowsHeight + pinnedBottomHeight + scrollbarBuffer + 2;
 
-        const overscanRows = 5;
         let firstRowIndex = 0;
         let lastRowIndex  = unpinnedRowsLength - 1;
         let offsetTop     = 0;
@@ -182,5 +184,6 @@ export function useGridVirtualization<R extends GridRowModel>(
         checkboxSelection,
         pinCheckboxColumn,
         pinExpandColumn,
+        overscanRows,
     ]);
 }

package/lib/types/index.ts

@@ -608,6 +608,13 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   headerHeight?: number;
   /** If true, the grid height will adjust to match the total height of its rows. */
   autoHeight?: boolean;
+  /**
+   * Minimum number of rows to render outside the visible viewport (overscan buffer).
+   * The grid adapts this value upward automatically based on scroll velocity to prevent
+   * blank flashes during fast scrolling. This prop sets the floor — the buffer never
+   * drops below this value regardless of scroll speed. Defaults to `3`.
+   */
+  overscanRowCount?: number;
 
   /** Sorting mode: 'client' (default) or 'server'. */
   sortingMode?: 'client' | 'server';

package/llms.txt

@@ -1,6 +1,6 @@
 # OpenGridX — AI Agent Context
 # Package: @opencorestack/opengridx
-# Version: 2.0.2
+# Version: 2.0.4
 # Docs: https://opencorestack.github.io/OpenGridX/
 # This file is machine-readable. AI developers: start here.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencorestack/opengridx",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "OpenGridX: High-performance React data infrastructure. Unlock advanced Row Grouping, Excel Export, and Column Pinning without the usual \"Pro\" gatekeeping. Built for speed, scale, and complete architectural freedom. Fully open, virtualization-ready, and feature-complete.",
   "type": "module",
   "main": "./dist/opengridx.umd.js",