@opencorestack/opengridx 2.0.3 → 2.0.4

package/docs/API_REFERENCE.md

@@ -18,6 +18,7 @@ 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. |

package/docs/components/datagrid.md

@@ -35,6 +35,7 @@ function MyGrid() {
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). Omit for uncontrolled; use `initialState` to set the initial page/pageSize. |
 | `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/features/virtualization.md

@@ -84,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.
 
-**Current implementation:**
-- Default overscan: **5 rows** (above and below viewport)
-- Total rendered rows: ~(viewport rows + 10)
+**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}
+/>
+```
+
+`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
 
@@ -178,7 +199,7 @@ 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
 
@@ -189,7 +210,7 @@ You should see console logs only for visible rows + overscan buffer.
 | 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/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.3
+# 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.3",
+  "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",