beautiful-grid 1.0.2 → 1.0.4

package/esm/components/Table.js

@@ -3,7 +3,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { useShallow } from 'zustand/react/shallow';
 import { useAppStore } from '../store';
 import { BGridDataItemStatus, } from '../types';
-import { getCellValueByRowKey, getFrozenColumnsWidth, getVisibleScrollableRowRange, isCheckboxValueChecked, markCellEdited, markCellValueChanged, resolveLogicalCell, shouldRenderBottomBar, } from '../utils';
+import { getCellValueByRowKey, getFrozenColumnsWidth, getVisibleScrollableRowRange, getVirtualScrollWindowMetrics, getVirtualScrollWindowPosition, isCheckboxValueChecked, markCellEdited, markCellValueChanged, rebaseVirtualScrollWindow, resolveLogicalCell, shouldRenderBottomBar, } from '../utils';
 import { clamp, ensureCellVisible } from '../utils/coordinate';
 import Loading from './Loading';
 import TableBody from './TableBody';
@@ -183,6 +183,23 @@ function Table(props) {
     const trHeight = itemHeight + itemPadding * 2;
     const scrollableBodyHeight = Math.max(contentBodyHeight - frozenRowsHeight, 0);
     const mainViewportWidth = Math.max(width - (frozenColumnsWidth ?? 0), 0);
+    const logicalBodyContentHeight = data.length * trHeight;
+    const virtualScrollWindowMetrics = React.useMemo(() => getVirtualScrollWindowMetrics({
+        logicalContentHeight: logicalBodyContentHeight,
+        viewportHeight: contentBodyHeight,
+        enabled: scrollbar.variant !== 'native',
+    }), [contentBodyHeight, logicalBodyContentHeight, scrollbar.variant]);
+    const [virtualScrollBase, setVirtualScrollBase] = React.useState(0);
+    const virtualScrollBaseRef = useRef(0);
+    const containerRef = useRef(null);
+    const searchPopoverRef = useRef(null);
+    const editorPortalRef = useRef(null);
+    const bodyContainerRef = useRef(null);
+    const scrollContainerRef = useRef(null);
+    const logicalVerticalScrollState = React.useMemo(() => ({
+        scrollTop,
+        scrollHeight: virtualScrollWindowMetrics.logicalContentHeight,
+    }), [scrollTop, virtualScrollWindowMetrics.logicalContentHeight]);
     const hasMultiCellSelection = React.useMemo(() => cellSelectionRanges.length > 1 ||
         cellSelectionRanges.some(range => {
             const normalized = normalizeCellSelectionRange(range);
@@ -273,7 +290,7 @@ function Table(props) {
                 top: topQuadrant ? 0 : scrollTop,
                 width: leftQuadrant ? frozenColumnsWidth ?? 0 : mainViewportWidth,
                 height: topQuadrant ? frozenRowsHeight : scrollableBodyHeight,
-            } }));
+            }, offsetTop: !topQuadrant && virtualScrollWindowMetrics.enabled ? virtualScrollBase : 0 }));
     };
     const visibleScrollableRows = React.useMemo(() => getVisibleScrollableRowRange({
         scrollTop,
@@ -288,15 +305,14 @@ function Table(props) {
         startRowIndex: visibleScrollableRows.startRowIndex,
         endRowIndex: visibleScrollableRows.endRowIndex,
     }), [visibleScrollableRows.endRowIndex, visibleScrollableRows.startRowIndex]);
-    const frozenScrollableBodyStyle = React.useMemo(() => ({ top: visibleScrollableRows.paddingTop }), [visibleScrollableRows.paddingTop]);
-    const containerRef = useRef(null);
-    const searchPopoverRef = useRef(null);
+    const frozenScrollableBodyStyle = React.useMemo(() => ({
+        top: virtualScrollWindowMetrics.enabled
+            ? visibleScrollableRows.paddingTop - virtualScrollBase
+            : visibleScrollableRows.paddingTop,
+    }), [virtualScrollBase, virtualScrollWindowMetrics.enabled, visibleScrollableRows.paddingTop]);
     const warnedContextMenuIdsRef = useRef(new Set());
     const warnedContextMenuFactoryRef = useRef(false);
-    const editorPortalRef = useRef(null);
     const editorPortalContext = React.useMemo(() => ({ gridRef: containerRef, portalRef: editorPortalRef }), []);
-    const bodyContainerRef = useRef(null);
-    const scrollContainerRef = useRef(null);
     const rowReorderController = useRowReorderController({
         containerRef,
         bodyContainerRef,
@@ -404,7 +420,8 @@ function Table(props) {
     const stickyBottomHeight = summary?.position === 'bottom' ? summaryHeight : 0;
     const stickyFixedHeight = stickyTopHeight + stickyBottomHeight;
     const scrollViewportHeight = contentBodyHeight + stickyFixedHeight;
-    const scrollPlaneHeight = stickyFixedHeight + frozenRowsHeight + visibleScrollableRows.scrollContentHeight;
+    const physicalScrollableRowsHeight = Math.max(virtualScrollWindowMetrics.physicalContentHeight - frozenRowsHeight, 0);
+    const scrollPlaneHeight = stickyFixedHeight + virtualScrollWindowMetrics.physicalContentHeight;
     const scrollPlaneContentWidth = (frozenColumnsWidth ?? 0) + scrollableColumnsWidth;
     const scrollPlaneWidth = Math.max(width, scrollPlaneContentWidth);
     const customVerticalScrollbarGutter = scrollbar.vertical.visible && scrollbar.variant === 'classic'
@@ -415,7 +432,18 @@ function Table(props) {
     const scrollPlaneMinWidth = customVerticalScrollbarGutter
         ? `max(100%, calc(${scrollPlaneContentWidth}px + ${customVerticalScrollbarGutter}))`
         : scrollPlaneWidth;
-    const scrollbarMetrics = useScrollbarMetrics(scrollContainerRef, [data.length, itemHeight, itemPadding, contentBodyHeight, width], scrollPlaneContentWidth, stickyFixedHeight);
+    const measuredScrollbarMetrics = useScrollbarMetrics(scrollContainerRef, [data.length, itemHeight, itemPadding, contentBodyHeight, width], scrollPlaneContentWidth, stickyFixedHeight);
+    const scrollbarMetrics = React.useMemo(() => virtualScrollWindowMetrics.enabled
+        ? {
+            ...measuredScrollbarMetrics,
+            vertical: {
+                viewportSize: contentBodyHeight,
+                contentSize: virtualScrollWindowMetrics.logicalContentHeight,
+                maxScroll: virtualScrollWindowMetrics.logicalMaxScroll,
+                hasOverflow: virtualScrollWindowMetrics.logicalMaxScroll > 1,
+            },
+        }
+        : measuredScrollbarMetrics, [contentBodyHeight, measuredScrollbarMetrics, virtualScrollWindowMetrics]);
     const measuredVerticalScrollbarGutter = customVerticalScrollbarGutter && scrollbarMetrics.horizontal.hasOverflow
         ? Math.max(scrollbarMetrics.horizontal.contentSize - scrollPlaneContentWidth, 0)
         : 0;
@@ -435,13 +463,16 @@ function Table(props) {
             scrollContainerRef.current.scrollLeft = offset;
         }
     }, []);
-    const handleScrollTopChange = useCallback((offset) => {
-        if (scrollContainerRef.current) {
-            scrollContainerRef.current.scrollTop = offset;
-        }
-    }, []);
     const latestScrollRef = useRef({ top: scrollTop, left: scrollLeft });
     const latestCommittedScrollRef = useRef({ top: scrollTop, left: scrollLeft });
+    const scrollPropsRef = useRef({ top: props.scrollTop, left: props.scrollLeft });
+    const syncedDataPropRef = useRef(props.data);
+    const [rowScrollRequest, setRowScrollRequest] = React.useState(null);
+    React.useImperativeHandle(props.ref, () => ({
+        scrollToRow(rowIndex, options) {
+            setRowScrollRequest({ rowIndex, align: options?.align ?? 'nearest' });
+        },
+    }), []);
     const scrollRafRef = useRef(null);
     const scrollIdleTimerRef = useRef(null);
     const selectionAutoScrollRafRef = useRef(null);
@@ -456,6 +487,7 @@ function Table(props) {
         frozenRowCount,
         frozenColumnsWidth: frozenColumnsWidth ?? 0,
         frozenRowsHeight,
+        scrollTop,
         trHeight,
     });
     useEffect(() => {
@@ -466,9 +498,10 @@ function Table(props) {
             frozenRowCount,
             frozenColumnsWidth: frozenColumnsWidth ?? 0,
             frozenRowsHeight,
+            scrollTop,
             trHeight,
         };
-    }, [columns, data.length, props.frozenColumnIndex, frozenColumnsWidth, frozenRowCount, frozenRowsHeight, trHeight]);
+    }, [columns, data.length, props.frozenColumnIndex, frozenColumnsWidth, frozenRowCount, frozenRowsHeight, scrollTop, trHeight]);
     const markScrollActive = useCallback(() => {
         containerRef.current?.setAttribute('data-bgrid-scrolling', 'true');
         if (scrollIdleTimerRef.current !== null)
@@ -478,6 +511,27 @@ function Table(props) {
             containerRef.current?.removeAttribute('data-bgrid-scrolling');
         }, SCROLL_IDLE_DELAY);
     }, []);
+    const commitScroll = useCallback((top, left) => {
+        const scrollContainer = scrollContainerRef.current;
+        if (!scrollContainer)
+            return;
+        const position = getVirtualScrollWindowPosition(top, virtualScrollWindowMetrics);
+        if (virtualScrollBaseRef.current !== position.base) {
+            virtualScrollBaseRef.current = position.base;
+            setVirtualScrollBase(position.base);
+        }
+        if (scrollContainer.scrollTop !== position.physicalScrollTop) {
+            scrollContainer.scrollTop = position.physicalScrollTop;
+        }
+        if (scrollContainer.scrollLeft !== left)
+            scrollContainer.scrollLeft = left;
+        latestScrollRef.current = { top: position.logicalScrollTop, left };
+        latestCommittedScrollRef.current = { top: position.logicalScrollTop, left };
+        setScroll(position.logicalScrollTop, left);
+    }, [setScroll, virtualScrollWindowMetrics]);
+    const handleScrollTopChange = useCallback((offset) => {
+        commitScroll(offset, scrollContainerRef.current?.scrollLeft ?? scrollLeft);
+    }, [commitScroll, scrollLeft]);
     const scheduleScrollFrame = useCallback(() => {
         if (scrollRafRef.current !== null)
             return;
@@ -486,90 +540,42 @@ function Table(props) {
             const scrollContainer = scrollContainerRef.current;
             if (!scrollContainer)
                 return;
-            const { scrollTop, scrollLeft } = scrollContainer;
-            latestScrollRef.current = { top: scrollTop, left: scrollLeft };
+            const { scrollTop: physicalScrollTop, scrollLeft } = scrollContainer;
+            const position = rebaseVirtualScrollWindow(virtualScrollBaseRef.current, physicalScrollTop, virtualScrollWindowMetrics);
+            if (virtualScrollBaseRef.current !== position.base) {
+                virtualScrollBaseRef.current = position.base;
+                setVirtualScrollBase(position.base);
+            }
+            if (physicalScrollTop !== position.physicalScrollTop) {
+                scrollContainer.scrollTop = position.physicalScrollTop;
+            }
+            const logicalScrollTop = position.logicalScrollTop;
+            latestScrollRef.current = { top: logicalScrollTop, left: scrollLeft };
             const { top: committedTop, left: committedLeft } = latestCommittedScrollRef.current;
-            if (committedTop !== scrollTop || committedLeft !== scrollLeft) {
-                latestCommittedScrollRef.current = { top: scrollTop, left: scrollLeft };
-                setScroll(scrollTop, scrollLeft);
+            if (committedTop !== logicalScrollTop || committedLeft !== scrollLeft) {
+                latestCommittedScrollRef.current = { top: logicalScrollTop, left: scrollLeft };
+                setScroll(logicalScrollTop, scrollLeft);
             }
             if (containerRef.current?.hasAttribute('data-bgrid-scrolling')) {
                 scrollRafRef.current = requestAnimationFrame(pollNativeScrollPosition);
             }
         };
         scrollRafRef.current = requestAnimationFrame(pollNativeScrollPosition);
-    }, [setScroll]);
+    }, [setScroll, virtualScrollWindowMetrics]);
     const onScroll = useCallback(() => {
         if (scrollContainerRef.current) {
-            const { scrollTop, scrollLeft } = scrollContainerRef.current;
-            latestScrollRef.current = { top: scrollTop, left: scrollLeft };
             markScrollActive();
             scheduleScrollFrame();
         }
     }, [markScrollActive, scheduleScrollFrame]);
-    const onWheel = useCallback(evt => {
-        const scrollContainer = scrollContainerRef.current;
-        if (!scrollContainer)
-            return;
-        const delta = { x: 0, y: 0 };
-        if (evt.detail) {
-            delta.y = evt.detail * 10;
-        }
-        else if (typeof evt.deltaY === 'undefined') {
-            delta.y = -evt.wheelDelta;
-            delta.x = 0;
-        }
-        else {
-            delta.y = evt.deltaY;
-            delta.x = evt.deltaX;
-        }
-        if (evt.deltaMode === 1) {
-            delta.y = delta.y * 16;
-            delta.x = delta.x * 16;
-        }
-        else if (evt.deltaMode === 2) {
-            delta.y = delta.y * scrollContainer.clientHeight;
-            delta.x = delta.x * scrollContainer.clientWidth;
-        }
-        const maxScrollTop = Math.max(scrollContainer.scrollHeight - scrollContainer.clientHeight, 0);
-        const maxScrollLeft = Math.max(scrollContainer.scrollWidth - scrollContainer.clientWidth, 0);
-        const nextScrollTop = Math.min(maxScrollTop, Math.max(0, scrollContainer.scrollTop + delta.y));
-        const nextScrollLeft = Math.min(maxScrollLeft, Math.max(0, scrollContainer.scrollLeft + delta.x));
-        const didScrollTop = nextScrollTop !== scrollContainer.scrollTop;
-        const didScrollLeft = nextScrollLeft !== scrollContainer.scrollLeft;
-        const isVertical = Math.abs(delta.y) > Math.abs(delta.x);
-        if (isVertical) {
-            if (!didScrollTop)
-                return;
-        }
-        else {
-            if (!didScrollLeft)
-                return;
-        }
-        evt.preventDefault();
-        if (didScrollTop)
-            scrollContainer.scrollTop = nextScrollTop;
-        if (didScrollLeft)
-            scrollContainer.scrollLeft = nextScrollLeft;
-    }, []);
     const resetScrollPosition = useCallback((type) => {
-        if (type === 'all' || type === 'left')
-            scrollContainerRef.current?.scrollTo({ left: 0 });
-        if (type === 'all' || type === 'top')
-            scrollContainerRef.current?.scrollTo({ top: 0 });
-    }, []);
-    const commitScroll = useCallback((top, left) => {
         const scrollContainer = scrollContainerRef.current;
         if (!scrollContainer)
             return;
-        if (scrollContainer.scrollTop !== top)
-            scrollContainer.scrollTop = top;
-        if (scrollContainer.scrollLeft !== left)
-            scrollContainer.scrollLeft = left;
-        latestScrollRef.current = { top, left };
-        latestCommittedScrollRef.current = { top, left };
-        setScroll(top, left);
-    }, [setScroll]);
+        const nextTop = type === 'all' || type === 'top' ? 0 : latestScrollRef.current.top;
+        const nextLeft = type === 'all' || type === 'left' ? 0 : scrollContainer.scrollLeft;
+        commitScroll(nextTop, nextLeft);
+    }, [commitScroll]);
     useEffect(() => {
         if (!searchOpen || activeSearchMatchIndex === undefined)
             return;
@@ -593,6 +599,7 @@ function Table(props) {
             frozenRowCount,
             columns,
             rowHeight: trHeight,
+            verticalScrollState: logicalVerticalScrollState,
             viewportInsets,
         });
         if (result.didScroll)
@@ -602,6 +609,7 @@ function Table(props) {
         columns,
         commitScroll,
         frozenRowCount,
+        logicalVerticalScrollState,
         props.frozenColumnIndex,
         searchMatches,
         searchOpen,
@@ -833,18 +841,18 @@ function Table(props) {
         if (!dragState || !pointer || !scrollContainer || !bodyContainer)
             return;
         const delta = getSelectionAutoScrollDelta(pointer.clientX, pointer.clientY, bodyContainer, scrollContainer);
-        const maxScrollTop = Math.max(scrollContainer.scrollHeight - scrollContainer.clientHeight, 0);
+        const maxScrollTop = virtualScrollWindowMetrics.logicalMaxScroll;
         const maxScrollLeft = Math.max(scrollContainer.scrollWidth - scrollContainer.clientWidth, 0);
-        const nextScrollTop = clamp(scrollContainer.scrollTop + delta.y, 0, maxScrollTop);
+        const nextScrollTop = clamp(latestScrollRef.current.top + delta.y, 0, maxScrollTop);
         const nextScrollLeft = clamp(scrollContainer.scrollLeft + delta.x, 0, maxScrollLeft);
-        if (nextScrollTop !== scrollContainer.scrollTop || nextScrollLeft !== scrollContainer.scrollLeft) {
+        if (nextScrollTop !== latestScrollRef.current.top || nextScrollLeft !== scrollContainer.scrollLeft) {
             commitScroll(nextScrollTop, nextScrollLeft);
         }
         updateSelectionByPointer(pointer.clientX, pointer.clientY);
         if (cellSelectionDragRef.current && (delta.x !== 0 || delta.y !== 0)) {
             selectionAutoScrollRafRef.current = requestAnimationFrame(runSelectionAutoScroll);
         }
-    }, [commitScroll, updateSelectionByPointer]);
+    }, [commitScroll, updateSelectionByPointer, virtualScrollWindowMetrics.logicalMaxScroll]);
     const selectAllCells = useCallback(() => {
         if (!cellSelectionEnabled)
             return false;
@@ -1333,6 +1341,7 @@ function Table(props) {
                 setSourceData(props.sourceData);
             }
         }
+        syncedDataPropRef.current = props.data;
     }, [
         props.data,
         props.sourceData,
@@ -1411,8 +1420,11 @@ function Table(props) {
         setPage,
         setDisplayPaginationLength,
     ]);
+    const previousPageRef = useRef(props.page?.currentPage);
     useEffect(() => {
-        resetScrollPosition('top');
+        if (previousPageRef.current !== props.page?.currentPage)
+            resetScrollPosition('top');
+        previousPageRef.current = props.page?.currentPage;
     }, [resetScrollPosition, props.page?.currentPage]);
     // [Group 8] Row key & selection
     useEffect(() => {
@@ -1497,10 +1509,8 @@ function Table(props) {
         const containerRefCurrent = containerRef.current;
         const scrollContainerRefCurrent = scrollContainerRef?.current;
         if (scrollContainerRefCurrent) {
-            scrollContainerRefCurrent.removeEventListener('scroll', onScroll);
+            scrollContainerRefCurrent.removeEventListener('scroll', onScroll, true);
             scrollContainerRefCurrent.addEventListener('scroll', onScroll, { passive: true, capture: true });
-            // scrollContainerRefCurrent.removeEventListener('wheel', onWheel);
-            // scrollContainerRefCurrent.addEventListener('wheel', onWheel, { passive: false, capture: true });
         }
         return () => {
             if (scrollRafRef.current !== null) {
@@ -1512,20 +1522,56 @@ function Table(props) {
                 scrollIdleTimerRef.current = null;
             }
             containerRefCurrent?.removeAttribute('data-bgrid-scrolling');
-            scrollContainerRefCurrent?.removeEventListener('scroll', onScroll);
+            scrollContainerRefCurrent?.removeEventListener('scroll', onScroll, true);
         };
-    }, [onScroll, onWheel, setInitialized]);
+    }, [onScroll, setInitialized]);
     React.useLayoutEffect(() => {
         if (!scrollContainerRef.current)
             return;
-        if (props.scrollLeft !== undefined) {
-            scrollContainerRef.current.scrollLeft = props.scrollLeft;
-        }
-        if (props.scrollTop !== undefined) {
-            scrollContainerRef.current.scrollTop = props.scrollTop;
-        }
-    }, [props.scrollLeft, props.scrollTop]);
+        if (props.data !== syncedDataPropRef.current)
+            return;
+        // Resizing or changing the data also changes commitScroll. Only a changed
+        // scroll prop should override the user's current position.
+        const nextTop = props.scrollTop !== scrollPropsRef.current.top
+            ? props.scrollTop ?? latestScrollRef.current.top
+            : latestScrollRef.current.top;
+        const nextLeft = props.scrollLeft !== scrollPropsRef.current.left
+            ? props.scrollLeft ?? latestScrollRef.current.left
+            : latestScrollRef.current.left;
+        scrollPropsRef.current = { top: props.scrollTop, left: props.scrollLeft };
+        commitScroll(nextTop, nextLeft);
+    }, [commitScroll, data, props.data, props.scrollLeft, props.scrollTop]);
+    React.useLayoutEffect(() => {
+        if (!rowScrollRequest)
+            return;
+        // Prop data reaches the per-grid store in an effect. Wait for that render
+        // so appending a row and requesting it in the same event is supported.
+        if (props.data !== syncedDataPropRef.current)
+            return;
+        setRowScrollRequest(null);
+        const { rowIndex, align } = rowScrollRequest;
+        if (!Number.isInteger(rowIndex) || rowIndex < frozenRowCount || rowIndex >= data.length)
+            return;
+        if (scrollableBodyHeight <= 0)
+            return;
+        const rowTop = (rowIndex - frozenRowCount) * trHeight;
+        const rowBottom = rowTop + trHeight;
+        const { top, left } = latestScrollRef.current;
+        let nextTop = top;
+        if (align === 'start')
+            nextTop = rowTop;
+        else if (align === 'center')
+            nextTop = rowTop - (scrollableBodyHeight - trHeight) / 2;
+        else if (align === 'end')
+            nextTop = rowBottom - scrollableBodyHeight;
+        else if (rowTop < top)
+            nextTop = rowTop;
+        else if (rowBottom > top + scrollableBodyHeight)
+            nextTop = rowBottom - scrollableBodyHeight;
+        commitScroll(nextTop, left);
+    }, [commitScroll, data, frozenRowCount, props.data, rowScrollRequest, scrollableBodyHeight, trHeight]);
     useEffect(() => {
+        latestScrollRef.current = { top: scrollTop, left: scrollLeft };
         latestCommittedScrollRef.current = { top: scrollTop, left: scrollLeft };
     }, [scrollTop, scrollLeft]);
     useEffect(() => {
@@ -1606,6 +1652,7 @@ function Table(props) {
         searchOpen,
         searchOptions,
         trHeight,
+        verticalScrollState: logicalVerticalScrollState,
         viewportInsets: keyboardViewportInsets,
     });
     keyboardRuntimeRef.current = {
@@ -1638,6 +1685,7 @@ function Table(props) {
         searchOpen,
         searchOptions,
         trHeight,
+        verticalScrollState: logicalVerticalScrollState,
         viewportInsets: keyboardViewportInsets,
     };
     useEffect(() => {
@@ -1653,7 +1701,7 @@ function Table(props) {
             }
         };
         const moveWithArrowKey = (key, extendSelection, toBoundary = false) => {
-            const { activeCell, cellInteractionSession, cellNavigationOptions, cellSelectionEnabled, columns, commitScroll, dataLength, frozenColumnIndex, frozenRowCount, moveActiveCell, trHeight, viewportInsets, } = keyboardRuntimeRef.current;
+            const { activeCell, cellInteractionSession, cellNavigationOptions, cellSelectionEnabled, columns, commitScroll, dataLength, frozenColumnIndex, frozenRowCount, moveActiveCell, trHeight, verticalScrollState, viewportInsets, } = keyboardRuntimeRef.current;
             const container = containerRef.current;
             const activeElement = document.activeElement;
             if (!container ||
@@ -1687,6 +1735,7 @@ function Table(props) {
                 frozenRowCount,
                 columns,
                 rowHeight: trHeight,
+                verticalScrollState,
                 viewportInsets,
             });
             if (result.didScroll) {
@@ -1718,7 +1767,7 @@ function Table(props) {
             arrowRepeatFrame = requestAnimationFrame(runArrowRepeatFrame);
         };
         const handleKeyDown = (evt) => {
-            const { activeCell, cellInteractionSession, cellNavigationOptions, cellSelectionEnabled, clearCellSelection, clearCellSelectionOnEscape, columns, commitCheckboxCell, commitScroll, copySelectedCells, data, dataLength, editable, editItemIndex, endCellSelectionDrag, frozenColumnIndex, frozenRowCount, height, handleClick, moveActiveCell, openCellContextMenu, selectAllCells, setEditItem, requestSearchOpen, searchOpen, searchOptions, trHeight, viewportInsets, } = keyboardRuntimeRef.current;
+            const { activeCell, cellInteractionSession, cellNavigationOptions, cellSelectionEnabled, clearCellSelection, clearCellSelectionOnEscape, columns, commitCheckboxCell, commitScroll, copySelectedCells, data, dataLength, editable, editItemIndex, endCellSelectionDrag, frozenColumnIndex, frozenRowCount, height, handleClick, moveActiveCell, openCellContextMenu, selectAllCells, setEditItem, requestSearchOpen, searchOpen, searchOptions, trHeight, verticalScrollState, viewportInsets, } = keyboardRuntimeRef.current;
             const container = containerRef.current;
             const activeElement = document.activeElement;
             if (!container || (activeElement !== container && !container.contains(activeElement)))
@@ -1846,6 +1895,7 @@ function Table(props) {
                             frozenRowCount,
                             columns,
                             rowHeight: trHeight,
+                            verticalScrollState,
                             viewportInsets,
                         });
                         if (result.didScroll) {
@@ -1889,6 +1939,7 @@ function Table(props) {
                             frozenRowCount,
                             columns,
                             rowHeight: trHeight,
+                            verticalScrollState,
                             viewportInsets,
                         });
                         if (result.didScroll) {
@@ -1916,6 +1967,7 @@ function Table(props) {
                             frozenRowCount,
                             columns,
                             rowHeight: trHeight,
+                            verticalScrollState,
                             viewportInsets,
                         });
                         if (result.didScroll) {
@@ -2022,7 +2074,7 @@ function Table(props) {
                         event.stopPropagation();
                     }
                 } },
-                React.createElement(ScrollPlane, { style: { height: scrollPlaneHeight, minWidth: scrollPlaneMinWidth } },
+                React.createElement(ScrollPlane, { style: { height: scrollPlaneHeight, minWidth: scrollPlaneMinWidth }, "data-bgrid-virtual-scroll-window": virtualScrollWindowMetrics.enabled ? 'true' : undefined, "data-bgrid-logical-height": virtualScrollWindowMetrics.logicalContentHeight, "data-bgrid-physical-height": virtualScrollWindowMetrics.physicalContentHeight, "data-bgrid-logical-scroll-top": Math.round(scrollTop), "data-bgrid-virtual-scroll-base": virtualScrollWindowMetrics.enabled ? Math.round(virtualScrollBase) : undefined },
                     React.createElement(HeaderContainer, { style: { height: headerHeight, top: 0 }, role: 'rfdg-header-container' },
                         (frozenColumnsWidth ?? 0) > 0 && (React.createElement(FrozenHeader, { style: { width: frozenColumnsWidth }, role: 'rfdg-frozen-header' },
                             React.createElement(TableHeadFrozen, { container: containerRef }))),
@@ -2033,7 +2085,7 @@ function Table(props) {
                             React.createElement(TableSummaryFrozen, { position: 'top' }))),
                         React.createElement(Summary, { style: { left: frozenColumnsWidth }, role: 'rfdg-summary' },
                             React.createElement(TableSummary, { position: 'top' })))),
-                    React.createElement("div", { className: 'bgrid-body-scroll-content', style: { height: frozenRowsHeight + visibleScrollableRows.scrollContentHeight } },
+                    React.createElement("div", { className: 'bgrid-body-scroll-content', style: { height: virtualScrollWindowMetrics.physicalContentHeight } },
                         frozenRowCount > 0 && (React.createElement("div", { className: 'bgrid-frozen-rows-layer', style: { height: frozenRowsHeight, top: stickyTopHeight }, "data-bgrid-row-band": 'frozen' },
                             (frozenColumnsWidth ?? 0) > 0 && (React.createElement("div", { className: 'bgrid-frozen-rows-left bgrid-frozen-column-boundary', style: { width: frozenColumnsWidth }, role: 'rfdg-frozen-rows-left' },
                                 React.createElement(TableBodyFrozen, { scrollContainerRef: scrollContainerRef, rowRange: frozenRowRange, role: 'rfdg-body-top-frozen', quadrant: 'top-left', allowRowReorder: false }),
@@ -2041,17 +2093,19 @@ function Table(props) {
                             React.createElement("div", { className: 'bgrid-frozen-rows-main', style: { left: frozenColumnsWidth }, role: 'rfdg-frozen-rows-main' },
                                 React.createElement(TableBody, { scrollContainerRef: scrollContainerRef, rowRange: frozenRowRange, role: 'rfdg-body-top', quadrant: 'top-main', allowRowReorder: false }),
                                 renderSelectionOverlay('top-main')))),
-                        React.createElement("div", { className: 'bgrid-scrollable-rows-layer', style: { height: visibleScrollableRows.scrollContentHeight }, "data-bgrid-row-band": 'scrollable' },
+                        React.createElement("div", { className: 'bgrid-scrollable-rows-layer', style: { height: physicalScrollableRowsHeight }, "data-bgrid-row-band": 'scrollable' },
                             (frozenColumnsWidth ?? 0) > 0 && (React.createElement(FrozenScrollContent, { style: {
                                     width: frozenColumnsWidth,
-                                    height: visibleScrollableRows.scrollContentHeight,
+                                    height: physicalScrollableRowsHeight,
                                 }, role: 'rfdg-frozen-scroll-container' },
                                 React.createElement(TableBodyFrozen, { scrollContainerRef: scrollContainerRef, rowRange: scrollableRowRange, style: frozenScrollableBodyStyle, quadrant: 'body-left', onRowReorderPointerDown: rowReorderController.onPointerDown, onRowReorderKeyDown: rowReorderController.onKeyDown }),
                                 renderSelectionOverlay('body-left'))),
                             React.createElement(ScrollContent, { style: {
                                     left: frozenColumnsWidth,
-                                    paddingTop: visibleScrollableRows.paddingTop,
-                                    height: visibleScrollableRows.scrollContentHeight,
+                                    paddingTop: virtualScrollWindowMetrics.enabled
+                                        ? visibleScrollableRows.paddingTop - virtualScrollBase
+                                        : visibleScrollableRows.paddingTop,
+                                    height: physicalScrollableRowsHeight,
                                 } },
                                 React.createElement(TableBody, { scrollContainerRef: scrollContainerRef, rowRange: scrollableRowRange, quadrant: 'body-main' }),
                                 renderSelectionOverlay('body-main')))),
@@ -2141,7 +2195,7 @@ function getCellPositionFromPointer({ clientX, clientY, bodyContainer, scrollCon
     const rowIndex = metrics.frozenRowCount > 0 && clientY < frozenRowsBottom
         ? clamp(Math.floor((clientY - bodyRect.top) / metrics.trHeight), 0, metrics.frozenRowCount - 1)
         : clamp(metrics.frozenRowCount +
-            Math.floor((scrollContainer.scrollTop +
+            Math.floor((metrics.scrollTop +
                 clamp(clientY - scrollRect.top, 0, Math.max(scrollContainer.clientHeight - 1, 0))) /
                 metrics.trHeight), 0, metrics.dataLength - 1);
     const columnIndex = getColumnIndexFromPointer({

package/esm/components/selection/CellSelectionOverlayLayer.js

@@ -1,14 +1,14 @@
 import * as React from 'react';
 import { clipCellSelectionFragment, } from '../../utils/cellSelectionGeometry';
-export function CellSelectionOverlayLayer({ quadrant, selectionFragments, activeFragments, activeFill, activeRing, viewport, }) {
+export function CellSelectionOverlayLayer({ quadrant, selectionFragments, activeFragments, activeFill, activeRing, viewport, offsetTop = 0, }) {
     const quadrantSelectionFragments = getVisibleFragments(selectionFragments, quadrant, viewport);
     const quadrantActiveFragments = getVisibleFragments(activeFragments, quadrant, viewport);
     if (quadrantSelectionFragments.length === 0 && quadrantActiveFragments.length === 0)
         return null;
     return (React.createElement("div", { className: 'bgrid-cell-selection-overlay-layer', "data-bgrid-selection-quadrant": quadrant, "aria-hidden": 'true' },
-        quadrantSelectionFragments.map(fragment => (React.createElement("div", { key: `selection-${fragment.rangeIndex}`, className: 'bgrid-cell-selection-fragment', "data-bgrid-selection-fragment": 'true', "data-bgrid-selection-range-index": fragment.rangeIndex, "data-edge-top": fragment.edges.top ? 'true' : undefined, "data-edge-right": fragment.edges.right ? 'true' : undefined, "data-edge-bottom": fragment.edges.bottom ? 'true' : undefined, "data-edge-left": fragment.edges.left ? 'true' : undefined, style: getFragmentStyle(fragment) }))),
+        quadrantSelectionFragments.map(fragment => (React.createElement("div", { key: `selection-${fragment.rangeIndex}`, className: 'bgrid-cell-selection-fragment', "data-bgrid-selection-fragment": 'true', "data-bgrid-selection-range-index": fragment.rangeIndex, "data-edge-top": fragment.edges.top ? 'true' : undefined, "data-edge-right": fragment.edges.right ? 'true' : undefined, "data-edge-bottom": fragment.edges.bottom ? 'true' : undefined, "data-edge-left": fragment.edges.left ? 'true' : undefined, style: getFragmentStyle(fragment, offsetTop) }))),
         (activeFill || activeRing) &&
-            quadrantActiveFragments.map(fragment => (React.createElement("div", { key: `active-${fragment.rangeIndex}`, className: 'bgrid-cell-active-fragment', "data-bgrid-active-fragment": 'true', "data-active-fill": activeFill ? 'true' : undefined, "data-active-ring": activeRing ? 'true' : undefined, style: getFragmentStyle(fragment) })))));
+            quadrantActiveFragments.map(fragment => (React.createElement("div", { key: `active-${fragment.rangeIndex}`, className: 'bgrid-cell-active-fragment', "data-bgrid-active-fragment": 'true', "data-active-fill": activeFill ? 'true' : undefined, "data-active-ring": activeRing ? 'true' : undefined, style: getFragmentStyle(fragment, offsetTop) })))));
 }
 function getVisibleFragments(fragments, quadrant, viewport) {
     return fragments.flatMap(fragment => {
@@ -18,10 +18,10 @@ function getVisibleFragments(fragments, quadrant, viewport) {
         return visibleFragment ? [visibleFragment] : [];
     });
 }
-function getFragmentStyle(fragment) {
+function getFragmentStyle(fragment, offsetTop) {
     return {
         left: fragment.left,
-        top: fragment.top,
+        top: fragment.top - offsetTop,
         width: fragment.width,
         height: fragment.height,
     };

package/esm/utils/coordinate.js

@@ -41,8 +41,8 @@ export function getRowBottom(rowIndex, rowHeight) {
         return 0;
     return (rowIndex + 1) * rowHeight;
 }
-export function ensureCellVisible({ cell, scrollContainer, frozenColumnCount = 0, frozenRowCount = 0, columns, rowHeight, viewportInsets, }) {
-    const currentScrollTop = scrollContainer?.scrollTop ?? 0;
+export function ensureCellVisible({ cell, scrollContainer, frozenColumnCount = 0, frozenRowCount = 0, columns, rowHeight, verticalScrollState, viewportInsets, }) {
+    const currentScrollTop = verticalScrollState?.scrollTop ?? scrollContainer?.scrollTop ?? 0;
     const currentScrollLeft = scrollContainer?.scrollLeft ?? 0;
     let nextScrollTop = currentScrollTop;
     let nextScrollLeft = currentScrollLeft;
@@ -52,7 +52,7 @@ export function ensureCellVisible({ cell, scrollContainer, frozenColumnCount = 0
         const rowTop = getRowTop(targetRowIndex, rowHeight);
         const rowBottom = getRowBottom(targetRowIndex, rowHeight);
         const clientHeight = scrollContainer.clientHeight;
-        const scrollHeight = scrollContainer.scrollHeight;
+        const scrollHeight = verticalScrollState?.scrollHeight ?? scrollContainer.scrollHeight;
         const maxScrollTop = Math.max(0, scrollHeight - clientHeight);
         if (clientHeight > 0) {
             const topInset = clamp(viewportInsets?.top ?? 0, 0, clientHeight);
@@ -95,7 +95,7 @@ export function ensureCellVisible({ cell, scrollContainer, frozenColumnCount = 0
     const didScrollLeft = nextScrollLeft !== currentScrollLeft;
     const didScroll = didScrollTop || didScrollLeft;
     if (scrollContainer) {
-        if (didScrollTop) {
+        if (didScrollTop && !verticalScrollState) {
             scrollContainer.scrollTop = nextScrollTop;
         }
         if (didScrollLeft) {

package/esm/utils/index.js

@@ -15,6 +15,7 @@ export * from './scrollbar';
 export * from './number';
 export * from './buildHeaderMatrix';
 export * from './getVisibleScrollableRowRange';
+export * from './virtualScrollWindow';
 export * from './cellEditState';
 export * from './getCellSelectionAxisState';
 export * from './mergedCells';

package/esm/utils/virtualScrollWindow.js

@@ -0,0 +1,59 @@
+export const BGRID_MAX_PHYSICAL_SCROLL_HEIGHT = 1000000;
+export function getVirtualScrollWindowMetrics({ logicalContentHeight, viewportHeight, enabled, maxPhysicalHeight = BGRID_MAX_PHYSICAL_SCROLL_HEIGHT, }) {
+    const safeViewportHeight = Math.max(viewportHeight, 0);
+    const safeLogicalContentHeight = Math.max(logicalContentHeight, safeViewportHeight);
+    const safeMaxPhysicalHeight = Math.max(maxPhysicalHeight, safeViewportHeight);
+    const windowingEnabled = enabled && safeLogicalContentHeight > safeMaxPhysicalHeight;
+    const physicalContentHeight = windowingEnabled ? safeMaxPhysicalHeight : safeLogicalContentHeight;
+    return {
+        enabled: windowingEnabled,
+        logicalContentHeight: safeLogicalContentHeight,
+        physicalContentHeight,
+        logicalMaxScroll: Math.max(safeLogicalContentHeight - safeViewportHeight, 0),
+        physicalMaxScroll: Math.max(physicalContentHeight - safeViewportHeight, 0),
+    };
+}
+export function getLogicalScrollTop(base, physicalScrollTop, metrics) {
+    return clamp(base + physicalScrollTop, 0, metrics.logicalMaxScroll);
+}
+export function getVirtualScrollWindowPosition(logicalScrollTop, metrics) {
+    const logicalTop = clamp(logicalScrollTop, 0, metrics.logicalMaxScroll);
+    if (!metrics.enabled) {
+        return {
+            base: 0,
+            physicalScrollTop: logicalTop,
+            logicalScrollTop: logicalTop,
+        };
+    }
+    const preferredPhysicalTop = metrics.physicalMaxScroll / 2;
+    const maxBase = Math.max(metrics.logicalMaxScroll - metrics.physicalMaxScroll, 0);
+    const base = clamp(logicalTop - preferredPhysicalTop, 0, maxBase);
+    return {
+        base,
+        physicalScrollTop: logicalTop - base,
+        logicalScrollTop: logicalTop,
+    };
+}
+export function rebaseVirtualScrollWindow(base, physicalScrollTop, metrics) {
+    const logicalScrollTop = getLogicalScrollTop(base, physicalScrollTop, metrics);
+    if (!metrics.enabled || metrics.physicalMaxScroll <= 0) {
+        return getVirtualScrollWindowPosition(logicalScrollTop, metrics);
+    }
+    const lowerGuard = metrics.physicalMaxScroll * 0.25;
+    const upperGuard = metrics.physicalMaxScroll * 0.75;
+    const maxBase = Math.max(metrics.logicalMaxScroll - metrics.physicalMaxScroll, 0);
+    const canMoveBackward = base > 0;
+    const canMoveForward = base < maxBase;
+    if ((physicalScrollTop < lowerGuard && canMoveBackward) ||
+        (physicalScrollTop > upperGuard && canMoveForward)) {
+        return getVirtualScrollWindowPosition(logicalScrollTop, metrics);
+    }
+    return {
+        base,
+        physicalScrollTop: clamp(physicalScrollTop, 0, metrics.physicalMaxScroll),
+        logicalScrollTop,
+    };
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}