@wallarm-org/design-system 0.51.2 → 0.52.0

package/dist/components/Table/TableBody/TableBody.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useTestId } from "../../../utils/testId.js";
+import { TABLE_PREPEND_SKELETON_ROWS } from "../lib/index.js";
 import { TBody } from "../primitives/index.js";
 import { useTableContext } from "../TableContext/index.js";
 import { TableLoadingState } from "../TableLoadingState.js";
@@ -7,7 +8,7 @@ import { TableRow } from "../TableRow.js";
 import { TableBodyVirtualizedContainer } from "./TableBodyVirtualizedContainer.js";
 import { TableBodyVirtualizedWindow } from "./TableBodyVirtualizedWindow.js";
 const TableBody = ()=>{
-    const { table, isLoading, virtualized, tbodyRef, virtualizerRef } = useTableContext();
+    const { table, isLoading, isLoadingPrevious, virtualized, tbodyRef, virtualizerRef } = useTableContext();
     const testId = useTestId('body');
     const rows = table.getRowModel().rows;
     const hasData = rows.length > 0;
@@ -20,6 +21,10 @@ const TableBody = ()=>{
         ref: tbodyRef,
         "data-testid": testId,
         children: [
+            isLoadingPrevious && /*#__PURE__*/ jsx(TableLoadingState, {
+                position: "start",
+                count: TABLE_PREPEND_SKELETON_ROWS
+            }),
             rows.map((row)=>/*#__PURE__*/ jsx(TableRow, {
                     row: row
                 }, row.id)),

package/dist/components/Table/TableBody/TableBodyVirtualizedContainer.js

@@ -1,8 +1,9 @@
 import { jsx } from "react/jsx-runtime";
 import { useCallback, useEffect } from "react";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { TABLE_VIRTUALIZATION_OVERSCAN } from "../lib/index.js";
+import { TABLE_VIRTUALIZATION_OVERSCAN, getRowKey } from "../lib/index.js";
 import { useTableContext } from "../TableContext/index.js";
+import { measureRowElement } from "./lib/measureRowElement.js";
 import { TableBodyVirtualizedCore } from "./TableBodyVirtualizedCore.js";
 import { useResetVirtualizerOnDataChange } from "./useResetVirtualizerOnDataChange.js";
 import { useSmoothScrollOnSort } from "./useSmoothScrollOnSort.js";
@@ -15,7 +16,11 @@ const TableBodyVirtualizedContainer = ()=>{
         count: table.getRowModel().rows.length,
         getScrollElement,
         estimateSize: estimateRowHeight ?? (()=>40),
-        overscan: overscan ?? TABLE_VIRTUALIZATION_OVERSCAN
+        overscan: overscan ?? TABLE_VIRTUALIZATION_OVERSCAN,
+        getItemKey: useCallback((index)=>getRowKey(table.getRowModel().rows, index), [
+            table
+        ]),
+        measureElement: measureRowElement
     });
     virtualizerRef.current = virtualizer;
     useEffect(()=>()=>{

package/dist/components/Table/TableBody/TableBodyVirtualizedCore.js

@@ -1,11 +1,12 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useTestId } from "../../../utils/testId.js";
+import { TABLE_PREPEND_SKELETON_ROWS } from "../lib/index.js";
 import { TBody, Td, Tr } from "../primitives/index.js";
 import { useTableContext } from "../TableContext/index.js";
 import { TableLoadingState } from "../TableLoadingState.js";
 import { TableRow } from "../TableRow.js";
 const TableBodyVirtualizedCore = ({ tbodyRef, virtualizer })=>{
-    const { table, isLoading } = useTableContext();
+    const { table, isLoading, isLoadingPrevious } = useTableContext();
     const testId = useTestId('body');
     const virtualRows = virtualizer.getVirtualItems();
     const totalSize = virtualizer.getTotalSize();
@@ -17,6 +18,10 @@ const TableBodyVirtualizedCore = ({ tbodyRef, virtualizer })=>{
         ref: tbodyRef,
         "data-testid": testId,
         children: [
+            isLoadingPrevious && /*#__PURE__*/ jsx(TableLoadingState, {
+                position: "start",
+                count: TABLE_PREPEND_SKELETON_ROWS
+            }),
             virtualRows.length > 0 && /*#__PURE__*/ jsx(Tr, {
                 children: /*#__PURE__*/ jsx(Td, {
                     style: {

package/dist/components/Table/TableBody/TableBodyVirtualizedWindow.js

@@ -1,9 +1,10 @@
 import { jsx } from "react/jsx-runtime";
 import { useCallback, useEffect } from "react";
 import { useWindowVirtualizer } from "@tanstack/react-virtual";
-import { TABLE_VIRTUALIZATION_OVERSCAN } from "../lib/index.js";
+import { TABLE_VIRTUALIZATION_OVERSCAN, getRowKey } from "../lib/index.js";
 import { useTableContext } from "../TableContext/index.js";
 import { getDocumentOffsetTop } from "./lib/getDocumentOffsetTop.js";
+import { measureRowElement } from "./lib/measureRowElement.js";
 import { TableBodyVirtualizedCore } from "./TableBodyVirtualizedCore.js";
 import { useResetVirtualizerOnDataChange } from "./useResetVirtualizerOnDataChange.js";
 import { useSmoothScrollOnSort } from "./useSmoothScrollOnSort.js";
@@ -13,7 +14,11 @@ const TableBodyVirtualizedWindow = ()=>{
         count: table.getRowModel().rows.length,
         estimateSize: estimateRowHeight ?? (()=>40),
         overscan: overscan ?? TABLE_VIRTUALIZATION_OVERSCAN,
-        scrollMargin: tbodyRef.current ? getDocumentOffsetTop(tbodyRef.current) : 0
+        scrollMargin: tbodyRef.current ? getDocumentOffsetTop(tbodyRef.current) : 0,
+        getItemKey: useCallback((index)=>getRowKey(table.getRowModel().rows, index), [
+            table
+        ]),
+        measureElement: measureRowElement
     });
     virtualizerRef.current = virtualizer;
     useEffect(()=>()=>{

package/dist/components/Table/TableBody/lib/measureRowElement.d.ts

@@ -0,0 +1,10 @@
+import { type Virtualizer } from '@tanstack/react-virtual';
+/**
+ * Row-measurement for the table virtualizers. TanStack's default reads
+ * `offsetHeight` when called without a ResizeObserver entry — i.e. on row
+ * mount mid-commit, forcing a reflow per new row while scrolling. That read is
+ * redundant: `observe()` delivers an initial `borderBoxSize` entry the same
+ * frame, post-layout. So entry-less we return the assumed size (cache/estimate)
+ * — a no-op — and let the observer entry supply the real one.
+ */
+export declare const measureRowElement: <TScrollElement extends Element | Window>(element: Element, entry: ResizeObserverEntry | undefined, instance: Virtualizer<TScrollElement, Element>) => number;

package/dist/components/Table/TableBody/lib/measureRowElement.js

@@ -0,0 +1,7 @@
+import { measureElement } from "@tanstack/react-virtual";
+const measureRowElement = (element, entry, instance)=>{
+    if (entry) return measureElement(element, entry, instance);
+    const index = instance.indexFromElement(element);
+    return instance.measurementsCache[index]?.size ?? instance.options.estimateSize(index);
+};
+export { measureRowElement };

package/dist/components/Table/TableBody/useResetVirtualizerOnDataChange.d.ts

@@ -1,8 +1,8 @@
 import type { Table } from '@tanstack/react-table';
 import type { Virtualizer } from '@tanstack/react-virtual';
 /**
- * Reset cached measurements when the data set changes so the virtualizer
- * does not retain stale heights from a previous data set.
- * Tracks first row ID to distinguish "new data" from "appended rows" (infinite scroll).
+ * Reset cached measurements only on a full dataset replacement. On a prepend
+ * (infinite scroll up) measurements are kept — usePrependScrollAnchor handles
+ * the position — so the virtualizer does not re-measure and jump.
  */
 export declare const useResetVirtualizerOnDataChange: (table: Table<unknown>, virtualizer: Virtualizer<Element, Element> | Virtualizer<Window, Element> | Virtualizer<HTMLElement, Element>) => void;

package/dist/components/Table/TableBody/useResetVirtualizerOnDataChange.js

@@ -1,15 +1,17 @@
 import { useEffect, useRef } from "react";
+import { detectDataChange } from "../lib/index.js";
 const useResetVirtualizerOnDataChange = (table, virtualizer)=>{
-    const rows = table.getRowModel().rows;
-    const firstRowId = rows[0]?.id;
+    const firstRowId = table.getRowModel().rows[0]?.id;
     const prevFirstRowIdRef = useRef(firstRowId);
     useEffect(()=>{
-        if (prevFirstRowIdRef.current !== firstRowId) {
-            prevFirstRowIdRef.current = firstRowId;
-            virtualizer.measure();
-        }
+        if (prevFirstRowIdRef.current === firstRowId) return;
+        const rows = table.getRowModel().rows;
+        const change = detectDataChange(prevFirstRowIdRef.current, rows);
+        prevFirstRowIdRef.current = firstRowId;
+        if ('replace' === change) virtualizer.measure();
     }, [
         firstRowId,
+        table,
         virtualizer
     ]);
 };

package/dist/components/Table/TableContext/TableProvider.js

@@ -8,7 +8,7 @@ import { useTableState } from "../hooks/index.js";
 import { TABLE_EXPAND_COLUMN_ID, TABLE_MIN_COLUMN_WIDTH, TABLE_SELECT_COLUMN_ID, TABLE_SKELETON_ROWS, TABLE_VIRTUALIZATION_OVERSCAN, createExpandColumn, createSelectionColumn } from "../lib/index.js";
 import { TableContext } from "./TableContext.js";
 const TableProvider = (props)=>{
-    const { data, columns, isLoading = false, skeletonCount = TABLE_SKELETON_ROWS, children, getRowId, sorting: sortingProp, onSortingChange, manualSorting = false, rowSelection: rowSelectionProp, onRowSelectionChange, columnSizing: columnSizingProp, onColumnSizingChange, columnPinning: columnPinningProp, onColumnPinningChange, columnOrder: columnOrderProp, onColumnOrderChange, grouping: groupingProp, onGroupingChange, expanded: expandedProp, onExpandedChange, renderGroupRow, getSubRows, renderExpandedRow, columnVisibility: columnVisibilityProp, onColumnVisibilityChange, defaultColumnVisibility, defaultColumnOrder, virtualized, estimateRowHeight, overscan = TABLE_VIRTUALIZATION_OVERSCAN, onEndReached, onEndReachedThreshold, onMasterCellClick, activeRowId: activeRowIdProp } = props;
+    const { data, columns, isLoading = false, isLoadingPrevious = false, skeletonCount = TABLE_SKELETON_ROWS, children, getRowId, sorting: sortingProp, onSortingChange, manualSorting = false, rowSelection: rowSelectionProp, onRowSelectionChange, columnSizing: columnSizingProp, onColumnSizingChange, columnPinning: columnPinningProp, onColumnPinningChange, columnOrder: columnOrderProp, onColumnOrderChange, grouping: groupingProp, onGroupingChange, expanded: expandedProp, onExpandedChange, renderGroupRow, getSubRows, renderExpandedRow, columnVisibility: columnVisibilityProp, onColumnVisibilityChange, defaultColumnVisibility, defaultColumnOrder, virtualized, estimateRowHeight, overscan = TABLE_VIRTUALIZATION_OVERSCAN, onEndReached, onEndReachedThreshold, onStartReached, onStartReachedThreshold, initialScrollToRowId, onMasterCellClick, activeRowId: activeRowIdProp } = props;
     const masterCellActiveRowId = activeRowIdProp ?? null;
     const sortingEnabled = !!onSortingChange;
     const selectionEnabled = !!onRowSelectionChange;
@@ -182,13 +182,13 @@ const TableProvider = (props)=>{
     });
     const allLeafColumns = table.getAllLeafColumns();
     const lastSelectedRowIndexRef = useRef(null);
-    const theadRef = useRef(null);
     const containerRef = useRef(null);
     const tbodyRef = useRef(null);
     const virtualizerRef = useRef(null);
     const contextValue = useMemo(()=>({
             table,
             isLoading,
+            isLoadingPrevious,
             skeletonCount,
             sortingEnabled,
             selectionEnabled,
@@ -209,17 +209,20 @@ const TableProvider = (props)=>{
             alwaysPinnedLeft,
             masterColumnId,
             lastSelectedRowIndexRef,
-            theadRef,
             containerRef,
             tbodyRef,
             virtualizerRef,
             onEndReached,
             onEndReachedThreshold,
+            onStartReached,
+            onStartReachedThreshold,
+            initialScrollToRowId,
             onMasterCellClick,
             activeRowId: masterCellActiveRowId
         }), [
         table,
         isLoading,
+        isLoadingPrevious,
         skeletonCount,
         sortingEnabled,
         selectionEnabled,
@@ -241,6 +244,9 @@ const TableProvider = (props)=>{
         masterColumnId,
         onEndReached,
         onEndReachedThreshold,
+        onStartReached,
+        onStartReachedThreshold,
+        initialScrollToRowId,
         masterCellActiveRowId,
         onMasterCellClick
     ]);

package/dist/components/Table/TableContext/types.d.ts

@@ -11,6 +11,7 @@ export type TableVirtualizerInstance = Virtualizer<Window, Element> | Virtualize
 export interface TableContextValue<T> {
     table: TanStackTable<T>;
     isLoading: boolean;
+    isLoadingPrevious: boolean;
     skeletonCount: number;
     sortingEnabled: boolean;
     selectionEnabled: boolean;
@@ -31,12 +32,14 @@ export interface TableContextValue<T> {
     lastSelectedRowIndexRef: RefObject<number | null>;
     alwaysPinnedLeft: string[];
     masterColumnId: string | null;
-    theadRef: RefObject<HTMLTableSectionElement | null>;
     containerRef: RefObject<HTMLDivElement | null>;
     tbodyRef: RefObject<HTMLTableSectionElement | null>;
     virtualizerRef: RefObject<TableVirtualizerInstance | null>;
     onEndReached?: () => void;
     onEndReachedThreshold?: number;
+    onStartReached?: () => void;
+    onStartReachedThreshold?: number;
+    initialScrollToRowId?: string;
     onMasterCellClick?: (rowId: string) => void;
     activeRowId: string | null;
 }

package/dist/components/Table/TableInner/TableInnerContainer.js

@@ -4,7 +4,7 @@ import { cn } from "../../../utils/cn.js";
 import { useTestId } from "../../../utils/testId.js";
 import { ScrollArea, ScrollAreaCorner, ScrollAreaScrollbar, ScrollAreaViewport } from "../../ScrollArea/index.js";
 import { tableContainerVariants } from "../classes.js";
-import { useEndReached } from "../hooks/index.js";
+import { useInfiniteScroll } from "../hooks/index.js";
 import { useContainerWidth } from "../lib/index.js";
 import { TableBody } from "../TableBody/index.js";
 import { TableColGroup } from "../TableColGroup.js";
@@ -12,15 +12,21 @@ import { useTableContext } from "../TableContext/index.js";
 import { TableHead } from "../TableHead.js";
 import { TableSettingsMenu } from "../TableSettingsMenu/index.js";
 const TableInnerContainer = ({ isEmpty, virtualized, showSettings, ariaLabel, children })=>{
-    const { containerRef, table, onEndReached, onEndReachedThreshold } = useTableContext();
+    const { containerRef, table, virtualizerRef, tbodyRef, onEndReached, onEndReachedThreshold, onStartReached, onStartReachedThreshold, initialScrollToRowId } = useTableContext();
     const testId = useTestId('container');
     const scrollRootRef = useRef(null);
     const containerWidth = useContainerWidth(containerRef);
-    useEndReached({
+    useInfiniteScroll({
         mode: 'container',
         scrollRef: containerRef,
+        table,
+        virtualizerRef,
+        tbodyRef,
         onEndReached,
-        threshold: onEndReachedThreshold
+        onEndReachedThreshold,
+        onStartReached,
+        onStartReachedThreshold,
+        initialScrollToRowId
     });
     useEffect(()=>{
         const viewport = containerRef.current;

package/dist/components/Table/TableInner/TableInnerWindow.js

@@ -2,7 +2,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
 import { useTestId } from "../../../utils/testId.js";
 import { ScrollArea, ScrollAreaScrollbar, ScrollAreaViewport } from "../../ScrollArea/index.js";
-import { useEndReached } from "../hooks/index.js";
+import { useInfiniteScroll } from "../hooks/index.js";
 import { useContainerWidth } from "../lib/index.js";
 import { TableBody } from "../TableBody/index.js";
 import { TableColGroup } from "../TableColGroup.js";
@@ -10,15 +10,21 @@ import { useTableContext } from "../TableContext/index.js";
 import { TableHead } from "../TableHead.js";
 import { TableSettingsMenu } from "../TableSettingsMenu/index.js";
 const TableInnerWindow = ({ isEmpty, showSettings, ariaLabel, children })=>{
-    const { table, onEndReached, onEndReachedThreshold } = useTableContext();
+    const { table, virtualizerRef, tbodyRef, onEndReached, onEndReachedThreshold, onStartReached, onStartReachedThreshold, initialScrollToRowId } = useTableContext();
     const testId = useTestId('window');
     const rootRef = useRef(null);
     const scrollRef = useRef(null);
     const containerWidth = useContainerWidth(rootRef);
-    useEndReached({
+    useInfiniteScroll({
         mode: 'window',
+        table,
+        virtualizerRef,
+        tbodyRef,
         onEndReached,
-        threshold: onEndReachedThreshold
+        onEndReachedThreshold,
+        onStartReached,
+        onStartReachedThreshold,
+        initialScrollToRowId
     });
     useEffect(()=>{
         const scrollEl = scrollRef.current;

package/dist/components/Table/TableLoadingState.d.ts

@@ -1,2 +1,13 @@
 import type { FC } from 'react';
-export declare const TableLoadingState: FC;
+interface TableLoadingStateProps {
+    /**
+     * Edge the skeletons sit at. 'end' (default) is the bottom loader; 'start'
+     * is the prepend loader above the rows — own test id + a data attribute the
+     * scroll compensation measures.
+     */
+    position?: 'start' | 'end';
+    /** Number of skeleton rows; defaults to the table-level skeletonCount. */
+    count?: number;
+}
+export declare const TableLoadingState: FC<TableLoadingStateProps>;
+export {};

package/dist/components/Table/TableLoadingState.js

@@ -3,17 +3,18 @@ import { useTestId } from "../../utils/testId.js";
 import { Skeleton } from "../Skeleton/index.js";
 import { Td, Tr } from "./primitives/index.js";
 import { useTableContext } from "./TableContext/index.js";
-const TableLoadingState = ()=>{
+const TableLoadingState = ({ position = 'end', count })=>{
     const { table, skeletonCount } = useTableContext();
-    const testId = useTestId('loading');
+    const testId = useTestId('start' === position ? 'loading-start' : 'loading');
     const columns = table.getVisibleLeafColumns();
     return /*#__PURE__*/ jsx(Fragment, {
         children: Array.from({
-            length: skeletonCount
+            length: count ?? skeletonCount
         }, (_, rowIdx)=>{
             const key = `skeleton-${rowIdx}`;
             return /*#__PURE__*/ jsx(Tr, {
                 "data-testid": 0 === rowIdx ? testId : void 0,
+                "data-loading-position": position,
                 children: columns.map((column)=>/*#__PURE__*/ jsx(Td, {
                         className: "px-16 py-8 border-b border-r border-border-primary-light",
                         style: {

package/dist/components/Table/hooks/index.d.ts

@@ -1,4 +1,4 @@
-export { useEndReached } from './useEndReached';
+export { useInfiniteScroll } from './infiniteScroll';
 export { useHorizontalScrollState } from './useHorizontalScrollState';
 export { useMasterCell } from './useMasterCell';
 export { useTableState } from './useTableState';

package/dist/components/Table/hooks/index.js

@@ -1,5 +1,5 @@
-import { useEndReached } from "./useEndReached.js";
+import { useInfiniteScroll } from "./infiniteScroll/index.js";
 import { useHorizontalScrollState } from "./useHorizontalScrollState.js";
 import { useMasterCell } from "./useMasterCell.js";
 import { useTableState } from "./useTableState.js";
-export { useEndReached, useHorizontalScrollState, useMasterCell, useTableState };
+export { useHorizontalScrollState, useInfiniteScroll, useMasterCell, useTableState };

package/dist/components/Table/hooks/infiniteScroll/index.d.ts

@@ -0,0 +1 @@
+export { useInfiniteScroll } from './useInfiniteScroll';

package/dist/components/Table/hooks/infiniteScroll/index.js

@@ -0,0 +1,2 @@
+import { useInfiniteScroll } from "./useInfiniteScroll.js";
+export { useInfiniteScroll };

package/dist/components/Table/hooks/infiniteScroll/useInfiniteScroll.d.ts

@@ -0,0 +1,19 @@
+import type { RefObject } from 'react';
+import type { Table } from '@tanstack/react-table';
+import type { TableVirtualizerInstance } from '../../TableContext/types';
+interface UseInfiniteScrollOptions<T> {
+    mode: 'container' | 'window';
+    /** Scroll element ref — required for `container` mode */
+    scrollRef?: RefObject<HTMLElement | null>;
+    table: Table<T>;
+    virtualizerRef: RefObject<TableVirtualizerInstance | null>;
+    tbodyRef?: RefObject<HTMLTableSectionElement | null>;
+    onStartReached?: () => void;
+    onStartReachedThreshold?: number;
+    onEndReached?: () => void;
+    onEndReachedThreshold?: number;
+    initialScrollToRowId?: string;
+}
+/** Single entry point for bidirectional infinite scroll behavior. */
+export declare const useInfiniteScroll: <T>({ mode, scrollRef, table, virtualizerRef, tbodyRef, onStartReached, onStartReachedThreshold, onEndReached, onEndReachedThreshold, initialScrollToRowId, }: UseInfiniteScrollOptions<T>) => void;
+export {};

package/dist/components/Table/hooks/infiniteScroll/useInfiniteScroll.js

@@ -0,0 +1,36 @@
+import { TABLE_END_REACHED_THRESHOLD, TABLE_START_REACHED_THRESHOLD } from "../../lib/index.js";
+import { useInitialAnchor } from "./useInitialAnchor.js";
+import { usePrependScrollAnchor } from "./usePrependScrollAnchor.js";
+import { useScrollEdge } from "./useScrollEdge.js";
+const useInfiniteScroll = ({ mode, scrollRef, table, virtualizerRef, tbodyRef, onStartReached, onStartReachedThreshold, onEndReached, onEndReachedThreshold, initialScrollToRowId })=>{
+    const rows = table.getRowModel().rows;
+    const ready = useInitialAnchor({
+        initialScrollToRowId,
+        rows,
+        virtualizerRef
+    });
+    usePrependScrollAnchor({
+        mode,
+        scrollRef,
+        rows,
+        virtualizerRef,
+        tbodyRef
+    });
+    useScrollEdge({
+        edge: 'start',
+        mode,
+        scrollRef,
+        onReached: onStartReached,
+        threshold: onStartReachedThreshold ?? TABLE_START_REACHED_THRESHOLD,
+        enabled: ready
+    });
+    useScrollEdge({
+        edge: 'end',
+        mode,
+        scrollRef,
+        onReached: onEndReached,
+        threshold: onEndReachedThreshold ?? TABLE_END_REACHED_THRESHOLD,
+        enabled: ready
+    });
+};
+export { useInfiniteScroll };

package/dist/components/Table/hooks/infiniteScroll/useInitialAnchor.d.ts

@@ -0,0 +1,16 @@
+import { type RefObject } from 'react';
+import type { TableVirtualizerInstance } from '../../TableContext/types';
+interface UseInitialAnchorOptions {
+    initialScrollToRowId?: string;
+    rows: {
+        id: string;
+    }[];
+    virtualizerRef: RefObject<TableVirtualizerInstance | null>;
+}
+/**
+ * Scrolls to the anchor row once on mount and returns `ready`, which gates the
+ * edge detectors until the initial scroll has settled. Without this, a table
+ * mounted at scrollTop 0 would fire `onStartReached` immediately.
+ */
+export declare const useInitialAnchor: ({ initialScrollToRowId, rows, virtualizerRef, }: UseInitialAnchorOptions) => boolean;
+export {};

package/dist/components/Table/hooks/infiniteScroll/useInitialAnchor.js

@@ -0,0 +1,28 @@
+import { useEffect, useRef, useState } from "react";
+const useInitialAnchor = ({ initialScrollToRowId, rows, virtualizerRef })=>{
+    const [ready, setReady] = useState(!initialScrollToRowId);
+    const doneRef = useRef(false);
+    useEffect(()=>{
+        if (doneRef.current || !initialScrollToRowId) return;
+        const virtualizer = virtualizerRef.current;
+        if (!virtualizer) {
+            doneRef.current = true;
+            setReady(true);
+            return;
+        }
+        const index = rows.findIndex((r)=>r.id === initialScrollToRowId);
+        if (index < 0) return;
+        virtualizer.scrollToIndex(index, {
+            align: 'center'
+        });
+        doneRef.current = true;
+        const raf = requestAnimationFrame(()=>setReady(true));
+        return ()=>cancelAnimationFrame(raf);
+    }, [
+        initialScrollToRowId,
+        rows,
+        virtualizerRef
+    ]);
+    return ready;
+};
+export { useInitialAnchor };

package/dist/components/Table/hooks/infiniteScroll/usePrependScrollAnchor.d.ts

@@ -0,0 +1,27 @@
+import { type RefObject } from 'react';
+import type { TableVirtualizerInstance } from '../../TableContext/types';
+interface UsePrependScrollAnchorOptions {
+    mode: 'container' | 'window';
+    scrollRef?: RefObject<HTMLElement | null>;
+    rows: {
+        id: string;
+    }[];
+    /** Preferred delta source: virtual-list offsets are immune to unrelated layout growth. */
+    virtualizerRef?: RefObject<TableVirtualizerInstance | null>;
+    /** Scopes the start-loader measurement to this table's body. */
+    tbodyRef?: RefObject<HTMLTableSectionElement | null>;
+}
+/**
+ * Keeps the viewport stable across a prepend, in a layout effect (pre-paint, no
+ * flicker). Delta = how far the previously-first row moved down the virtual list
+ * (`start` offset) — immune to unrelated page-height changes, unlike a
+ * scrollHeight diff, which matters in `window` mode. Falls back to scrollHeight
+ * when there's no virtualizer.
+ *
+ * Start-edge skeletons (`isLoadingPrevious`) sit above the rows but outside the
+ * virtual list, so the offset delta can't see them; their height is tracked per
+ * commit (hence no dep array) and its collapse joins the delta when the prepend
+ * lands in the same commit.
+ */
+export declare const usePrependScrollAnchor: ({ mode, scrollRef, rows, virtualizerRef, tbodyRef, }: UsePrependScrollAnchorOptions) => void;
+export {};

package/dist/components/Table/hooks/infiniteScroll/usePrependScrollAnchor.js

@@ -0,0 +1,70 @@
+import { useLayoutEffect, useRef } from "react";
+import { detectDataChange } from "../../lib/index.js";
+const usePrependScrollAnchor = ({ mode, scrollRef, rows, virtualizerRef, tbodyRef })=>{
+    const prevFirstRowIdRef = useRef(void 0);
+    const prevFirstRowStartRef = useRef(null);
+    const prevScrollHeightRef = useRef(null);
+    const prevLoaderRef = useRef({
+        count: 0,
+        height: 0
+    });
+    const seededRef = useRef(false);
+    useLayoutEffect(()=>{
+        const getScrollHeight = ()=>'window' === mode ? document.documentElement.scrollHeight : scrollRef?.current?.scrollHeight ?? 0;
+        const getStartLoaderHeight = ()=>{
+            const loaderRows = tbodyRef?.current?.querySelectorAll('tr[data-loading-position="start"]');
+            const count = loaderRows?.length ?? 0;
+            if (count !== prevLoaderRef.current.count) {
+                let height = 0;
+                loaderRows?.forEach((row)=>{
+                    height += row.offsetHeight;
+                });
+                prevLoaderRef.current = {
+                    count,
+                    height
+                };
+            }
+            return prevLoaderRef.current.height;
+        };
+        const getFirstRowStart = ()=>{
+            const start = virtualizerRef?.current?.measurementsCache[0]?.start;
+            return 'number' == typeof start ? start : null;
+        };
+        const trackScrollHeight = !virtualizerRef?.current;
+        if (!seededRef.current) {
+            seededRef.current = true;
+            prevScrollHeightRef.current = trackScrollHeight ? getScrollHeight() : null;
+            prevFirstRowStartRef.current = getFirstRowStart();
+            prevFirstRowIdRef.current = rows[0]?.id;
+            getStartLoaderHeight();
+            return;
+        }
+        const prevLoaderHeight = prevLoaderRef.current.height;
+        if ('prepend' === detectDataChange(prevFirstRowIdRef.current, rows)) {
+            const prevId = prevFirstRowIdRef.current;
+            const index = rows.findIndex((row)=>row.id === prevId);
+            const newStart = virtualizerRef?.current?.measurementsCache[index]?.start;
+            const useVirtualDelta = index >= 0 && 'number' == typeof newStart && null !== prevFirstRowStartRef.current;
+            if (useVirtualDelta) {
+                const rowDelta = newStart - prevFirstRowStartRef.current;
+                const loaderDelta = getStartLoaderHeight() - prevLoaderHeight;
+                const delta = rowDelta + loaderDelta;
+                if (0 !== delta) {
+                    if ('window' === mode) window.scrollBy(0, delta);
+                    else if (scrollRef?.current) scrollRef.current.scrollTop += delta;
+                }
+            } else if (null !== prevScrollHeightRef.current) {
+                const delta = getScrollHeight() - prevScrollHeightRef.current;
+                if (delta > 0) {
+                    if ('window' === mode) window.scrollBy(0, delta);
+                    else if (scrollRef?.current) scrollRef.current.scrollTop += delta;
+                }
+            }
+        }
+        prevFirstRowIdRef.current = rows[0]?.id;
+        prevFirstRowStartRef.current = getFirstRowStart();
+        prevScrollHeightRef.current = trackScrollHeight ? getScrollHeight() : null;
+        getStartLoaderHeight();
+    });
+};
+export { usePrependScrollAnchor };

package/dist/components/Table/hooks/infiniteScroll/useScrollEdge.d.ts

@@ -0,0 +1,20 @@
+import { type RefObject } from 'react';
+type ScrollMode = 'container' | 'window';
+type ScrollEdge = 'start' | 'end';
+interface UseScrollEdgeOptions {
+    edge: ScrollEdge;
+    mode: ScrollMode;
+    /** Scroll element ref — required for `container` mode */
+    scrollRef?: RefObject<HTMLElement | null>;
+    onReached?: () => void;
+    threshold: number;
+    /** When false, suppresses firing (e.g. while the initial anchor scroll settles) */
+    enabled?: boolean;
+}
+/**
+ * Fires `onReached` once when the user scrolls within `threshold` px of the
+ * given edge. Re-arms after scrolling back past the threshold. A cooldown
+ * guard prevents rapid re-fires when prepended/appended rows grow the content.
+ */
+export declare const useScrollEdge: ({ edge, mode, scrollRef, onReached, threshold, enabled, }: UseScrollEdgeOptions) => void;
+export {};

package/dist/components/Table/hooks/{useEndReached.js → infiniteScroll/useScrollEdge.js}

@@ -1,17 +1,20 @@
 import { useEffect, useRef } from "react";
-import { TABLE_END_REACHED_THRESHOLD } from "../lib/index.js";
-const COOLDOWN_MS = 200;
-const useEndReached = ({ mode, scrollRef, onEndReached, threshold = TABLE_END_REACHED_THRESHOLD })=>{
+import { SCROLL_EDGE_COOLDOWN_MS } from "../../lib/index.js";
+const useScrollEdge = ({ edge, mode, scrollRef, onReached, threshold, enabled = true })=>{
     const firedRef = useRef(false);
     const lastFiredAtRef = useRef(0);
-    const onEndReachedRef = useRef(onEndReached);
+    const onReachedRef = useRef(onReached);
     useEffect(()=>{
-        onEndReachedRef.current = onEndReached;
+        onReachedRef.current = onReached;
+    });
+    const enabledRef = useRef(enabled);
+    useEffect(()=>{
+        enabledRef.current = enabled;
     });
     useEffect(()=>{
         const check = ()=>{
-            const callback = onEndReachedRef.current;
-            if (!callback) return;
+            const callback = onReachedRef.current;
+            if (!callback || !enabledRef.current) return;
             let scrollTop;
             let clientHeight;
             let scrollHeight;
@@ -26,10 +29,10 @@ const useEndReached = ({ mode, scrollRef, onEndReached, threshold = TABLE_END_RE
                 clientHeight = el.clientHeight;
                 scrollHeight = el.scrollHeight;
             }
-            const distanceToBottom = scrollHeight - scrollTop - clientHeight;
-            if (distanceToBottom <= threshold) {
+            const distance = 'start' === edge ? scrollTop : scrollHeight - scrollTop - clientHeight;
+            if (distance <= threshold) {
                 const now = Date.now();
-                if (!firedRef.current && now - lastFiredAtRef.current >= COOLDOWN_MS) {
+                if (!firedRef.current && now - lastFiredAtRef.current >= SCROLL_EDGE_COOLDOWN_MS) {
                     firedRef.current = true;
                     lastFiredAtRef.current = now;
                     callback();
@@ -46,9 +49,10 @@ const useEndReached = ({ mode, scrollRef, onEndReached, threshold = TABLE_END_RE
             target.removeEventListener('scroll', check);
         };
     }, [
+        edge,
         mode,
         scrollRef,
         threshold
     ]);
 };
-export { useEndReached };
+export { useScrollEdge };

package/dist/components/Table/lib/constants.d.ts

@@ -1,4 +1,6 @@
 export declare const TABLE_SKELETON_ROWS = 12;
+/** Short on purpose: the prepend loader's height pushes visible rows down. */
+export declare const TABLE_PREPEND_SKELETON_ROWS = 6;
 export declare const TABLE_VIRTUALIZATION_OVERSCAN = 6;
 export declare const TABLE_MIN_COLUMN_WIDTH = 96;
 export declare const TABLE_SELECT_COLUMN_ID = "_selection";
@@ -6,6 +8,9 @@ export declare const TABLE_SELECT_COLUMN_WIDTH = 33;
 export declare const TABLE_EXPAND_COLUMN_ID = "_expand";
 export declare const TABLE_EXPAND_COLUMN_WIDTH = 33;
 export declare const TABLE_END_REACHED_THRESHOLD = 200;
+export declare const TABLE_START_REACHED_THRESHOLD = 200;
+/** Minimum time (ms) between successive edge-reached callbacks. */
+export declare const SCROLL_EDGE_COOLDOWN_MS = 200;
 /** Resolve text-align class from column meta */
 export declare const getAlignClass: (meta?: {
     align?: string;

package/dist/components/Table/lib/constants.js

@@ -1,4 +1,5 @@
 const TABLE_SKELETON_ROWS = 12;
+const TABLE_PREPEND_SKELETON_ROWS = 6;
 const TABLE_VIRTUALIZATION_OVERSCAN = 6;
 const TABLE_MIN_COLUMN_WIDTH = 96;
 const TABLE_SELECT_COLUMN_ID = '_selection';
@@ -6,6 +7,8 @@ const TABLE_SELECT_COLUMN_WIDTH = 33;
 const TABLE_EXPAND_COLUMN_ID = '_expand';
 const TABLE_EXPAND_COLUMN_WIDTH = 33;
 const TABLE_END_REACHED_THRESHOLD = 200;
+const TABLE_START_REACHED_THRESHOLD = 200;
+const SCROLL_EDGE_COOLDOWN_MS = 200;
 const RIGHT_ALIGNED_SORT_TYPES = new Set([
     'number',
     'score',
@@ -56,4 +59,4 @@ const SORT_LABELS = {
         'Smallest on top'
     ]
 };
-export { SORT_LABELS, TABLE_END_REACHED_THRESHOLD, TABLE_EXPAND_COLUMN_ID, TABLE_EXPAND_COLUMN_WIDTH, TABLE_MIN_COLUMN_WIDTH, TABLE_SELECT_COLUMN_ID, TABLE_SELECT_COLUMN_WIDTH, TABLE_SKELETON_ROWS, TABLE_VIRTUALIZATION_OVERSCAN, getAlignClass, getExpandBorderClass };
+export { SCROLL_EDGE_COOLDOWN_MS, SORT_LABELS, TABLE_END_REACHED_THRESHOLD, TABLE_EXPAND_COLUMN_ID, TABLE_EXPAND_COLUMN_WIDTH, TABLE_MIN_COLUMN_WIDTH, TABLE_PREPEND_SKELETON_ROWS, TABLE_SELECT_COLUMN_ID, TABLE_SELECT_COLUMN_WIDTH, TABLE_SKELETON_ROWS, TABLE_START_REACHED_THRESHOLD, TABLE_VIRTUALIZATION_OVERSCAN, getAlignClass, getExpandBorderClass };

package/dist/components/Table/lib/detectDataChange.d.ts

@@ -0,0 +1,4 @@
+/** Classifies a data change by comparing the previous first row id to the new rows. */
+export declare const detectDataChange: (prevFirstRowId: string | undefined, rows: {
+    id: string;
+}[]) => "prepend" | "replace" | "none";

package/dist/components/Table/lib/detectDataChange.js

@@ -0,0 +1,7 @@
+const detectDataChange = (prevFirstRowId, rows)=>{
+    const currentFirstId = rows[0]?.id;
+    if (void 0 === prevFirstRowId) return 'none';
+    if (currentFirstId === prevFirstRowId) return 'none';
+    return rows.some((r)=>r.id === prevFirstRowId) ? 'prepend' : 'replace';
+};
+export { detectDataChange };

package/dist/components/Table/lib/getRowKey.d.ts

@@ -0,0 +1,4 @@
+/** Stable virtualizer item key: the row id, or the index as fallback. */
+export declare const getRowKey: (rows: {
+    id: string;
+}[], index: number) => string | number;

package/dist/components/Table/lib/getRowKey.js

@@ -0,0 +1,2 @@
+const getRowKey = (rows, index)=>rows[index]?.id ?? index;
+export { getRowKey };

package/dist/components/Table/lib/index.d.ts

@@ -1,9 +1,11 @@
-export { getAlignClass, getExpandBorderClass, SORT_LABELS, TABLE_END_REACHED_THRESHOLD, TABLE_EXPAND_COLUMN_ID, TABLE_EXPAND_COLUMN_WIDTH, TABLE_MIN_COLUMN_WIDTH, TABLE_SELECT_COLUMN_ID, TABLE_SELECT_COLUMN_WIDTH, TABLE_SKELETON_ROWS, TABLE_VIRTUALIZATION_OVERSCAN, } from './constants';
+export { getAlignClass, getExpandBorderClass, SCROLL_EDGE_COOLDOWN_MS, SORT_LABELS, TABLE_END_REACHED_THRESHOLD, TABLE_EXPAND_COLUMN_ID, TABLE_EXPAND_COLUMN_WIDTH, TABLE_MIN_COLUMN_WIDTH, TABLE_PREPEND_SKELETON_ROWS, TABLE_SELECT_COLUMN_ID, TABLE_SELECT_COLUMN_WIDTH, TABLE_SKELETON_ROWS, TABLE_START_REACHED_THRESHOLD, TABLE_VIRTUALIZATION_OVERSCAN, } from './constants';
 export { createExpandColumn } from './createExpandColumn';
 export { createSelectionColumn } from './createSelectionColumn';
 export { createTableColumnHelper } from './createTableColumnHelper';
+export { detectDataChange } from './detectDataChange';
 export { getDndStyles } from './getDndStyles';
 export { getPinningStyles } from './getPinningStyles';
+export { getRowKey } from './getRowKey';
 export { isLastPinnedLeft } from './isLastPinnedLeft';
 export { useColumnDnd } from './useColumnDnd';
 export { useContainerWidth } from './useContainerWidth';

package/dist/components/Table/lib/index.js

@@ -1,10 +1,12 @@
-import { SORT_LABELS, TABLE_END_REACHED_THRESHOLD, TABLE_EXPAND_COLUMN_ID, TABLE_EXPAND_COLUMN_WIDTH, TABLE_MIN_COLUMN_WIDTH, TABLE_SELECT_COLUMN_ID, TABLE_SELECT_COLUMN_WIDTH, TABLE_SKELETON_ROWS, TABLE_VIRTUALIZATION_OVERSCAN, getAlignClass, getExpandBorderClass } from "./constants.js";
+import { SCROLL_EDGE_COOLDOWN_MS, SORT_LABELS, TABLE_END_REACHED_THRESHOLD, TABLE_EXPAND_COLUMN_ID, TABLE_EXPAND_COLUMN_WIDTH, TABLE_MIN_COLUMN_WIDTH, TABLE_PREPEND_SKELETON_ROWS, TABLE_SELECT_COLUMN_ID, TABLE_SELECT_COLUMN_WIDTH, TABLE_SKELETON_ROWS, TABLE_START_REACHED_THRESHOLD, TABLE_VIRTUALIZATION_OVERSCAN, getAlignClass, getExpandBorderClass } from "./constants.js";
 import { createExpandColumn } from "./createExpandColumn.js";
 import { createSelectionColumn } from "./createSelectionColumn.js";
 import { createTableColumnHelper } from "./createTableColumnHelper.js";
+import { detectDataChange } from "./detectDataChange.js";
 import { getDndStyles } from "./getDndStyles.js";
 import { getPinningStyles } from "./getPinningStyles.js";
+import { getRowKey } from "./getRowKey.js";
 import { isLastPinnedLeft } from "./isLastPinnedLeft.js";
 import { useColumnDnd } from "./useColumnDnd.js";
 import { useContainerWidth } from "./useContainerWidth.js";
-export { SORT_LABELS, TABLE_END_REACHED_THRESHOLD, TABLE_EXPAND_COLUMN_ID, TABLE_EXPAND_COLUMN_WIDTH, TABLE_MIN_COLUMN_WIDTH, TABLE_SELECT_COLUMN_ID, TABLE_SELECT_COLUMN_WIDTH, TABLE_SKELETON_ROWS, TABLE_VIRTUALIZATION_OVERSCAN, createExpandColumn, createSelectionColumn, createTableColumnHelper, getAlignClass, getDndStyles, getExpandBorderClass, getPinningStyles, isLastPinnedLeft, useColumnDnd, useContainerWidth };
+export { SCROLL_EDGE_COOLDOWN_MS, SORT_LABELS, TABLE_END_REACHED_THRESHOLD, TABLE_EXPAND_COLUMN_ID, TABLE_EXPAND_COLUMN_WIDTH, TABLE_MIN_COLUMN_WIDTH, TABLE_PREPEND_SKELETON_ROWS, TABLE_SELECT_COLUMN_ID, TABLE_SELECT_COLUMN_WIDTH, TABLE_SKELETON_ROWS, TABLE_START_REACHED_THRESHOLD, TABLE_VIRTUALIZATION_OVERSCAN, createExpandColumn, createSelectionColumn, createTableColumnHelper, detectDataChange, getAlignClass, getDndStyles, getExpandBorderClass, getPinningStyles, getRowKey, isLastPinnedLeft, useColumnDnd, useContainerWidth };

package/dist/components/Table/mocks.d.ts

@@ -59,3 +59,17 @@ export declare const useInfiniteData: () => {
     totalItems: number;
     fetchNextPage: () => void;
 };
+/**
+ * Mock for bidirectional infinite scroll: opens a window around an anchor row
+ * and exposes cursor-style fetchers for both directions.
+ */
+export declare const useBidirectionalData: () => {
+    data: SecurityEvent[];
+    anchorId: string | undefined;
+    isFetchingPrev: boolean;
+    isFetchingNext: boolean;
+    hasPrev: boolean;
+    hasNext: boolean;
+    fetchPrevPage: () => void;
+    fetchNextPage: () => void;
+};

package/dist/components/Table/mocks.js

@@ -953,6 +953,9 @@ const fullFeaturedColumns = headerColumns.map((col)=>{
 });
 const INFINITE_PAGE_SIZE = 50;
 const INFINITE_MAX_ITEMS = 500;
+const BIDIRECTIONAL_TOTAL = 500;
+const BIDIRECTIONAL_PAGE_SIZE = 50;
+const BIDIRECTIONAL_INITIAL_ANCHOR_INDEX = 250;
 const useInfiniteData = ()=>{
     const allData = useMemo(()=>createLargeSecurityEvents(INFINITE_MAX_ITEMS), []);
     const [data, setData] = useState(()=>allData.slice(0, INFINITE_PAGE_SIZE));
@@ -978,4 +981,61 @@ const useInfiniteData = ()=>{
         fetchNextPage
     };
 };
-export { createLargeGroupedData, createLargeSecurityEvents, fullFeaturedColumns, groupedHeaderData, headerColumnHelper, headerColumnIds, headerColumns, multiplySecurityEvents, renderSecurityPreviewContent, renderSecurityPreviewHeader, securityColumnHelper, securityColumnIds, securityColumns, securityEvents, useInfiniteData };
+const useBidirectionalData = ()=>{
+    const allData = useMemo(()=>createLargeSecurityEvents(BIDIRECTIONAL_TOTAL), []);
+    const initialStart = Math.max(0, BIDIRECTIONAL_INITIAL_ANCHOR_INDEX - BIDIRECTIONAL_PAGE_SIZE);
+    const initialEnd = Math.min(allData.length, BIDIRECTIONAL_INITIAL_ANCHOR_INDEX + BIDIRECTIONAL_PAGE_SIZE);
+    const [range, setRange] = useState({
+        start: initialStart,
+        end: initialEnd
+    });
+    const [isFetchingPrev, setIsFetchingPrev] = useState(false);
+    const [isFetchingNext, setIsFetchingNext] = useState(false);
+    const data = useMemo(()=>allData.slice(range.start, range.end), [
+        allData,
+        range
+    ]);
+    const anchorId = allData[BIDIRECTIONAL_INITIAL_ANCHOR_INDEX]?.id;
+    const hasPrev = range.start > 0;
+    const hasNext = range.end < allData.length;
+    const fetchPrevPage = useCallback(()=>{
+        if (isFetchingPrev || range.start <= 0) return;
+        setIsFetchingPrev(true);
+        setTimeout(()=>{
+            setRange((prev)=>({
+                    ...prev,
+                    start: Math.max(0, prev.start - BIDIRECTIONAL_PAGE_SIZE)
+                }));
+            setIsFetchingPrev(false);
+        }, 600);
+    }, [
+        isFetchingPrev,
+        range.start
+    ]);
+    const fetchNextPage = useCallback(()=>{
+        if (isFetchingNext || range.end >= allData.length) return;
+        setIsFetchingNext(true);
+        setTimeout(()=>{
+            setRange((prev)=>({
+                    ...prev,
+                    end: Math.min(allData.length, prev.end + BIDIRECTIONAL_PAGE_SIZE)
+                }));
+            setIsFetchingNext(false);
+        }, 600);
+    }, [
+        isFetchingNext,
+        range.end,
+        allData.length
+    ]);
+    return {
+        data,
+        anchorId,
+        isFetchingPrev,
+        isFetchingNext,
+        hasPrev,
+        hasNext,
+        fetchPrevPage,
+        fetchNextPage
+    };
+};
+export { createLargeGroupedData, createLargeSecurityEvents, fullFeaturedColumns, groupedHeaderData, headerColumnHelper, headerColumnIds, headerColumns, multiplySecurityEvents, renderSecurityPreviewContent, renderSecurityPreviewHeader, securityColumnHelper, securityColumnIds, securityColumns, securityEvents, useBidirectionalData, useInfiniteData };

package/dist/components/Table/types.d.ts

@@ -143,6 +143,12 @@ export interface TableProps<T> extends TestableProps {
     columns: TableColumnDef<T>[];
     /** Show skeleton rows */
     isLoading?: boolean;
+    /**
+     * Show skeleton rows above the first row while a previous page is being
+     * fetched (bidirectional infinite scroll — the start-edge counterpart of
+     * `isLoading`). Pair with `onStartReached`.
+     */
+    isLoadingPrevious?: boolean;
     /** Number of skeleton rows to display when loading (default: 6) */
     skeletonCount?: number;
     /** Slot for TableActionBar, TableEmptyState, and other compound components */
@@ -188,10 +194,20 @@ export interface TableProps<T> extends TestableProps {
     virtualized?: TableVirtualized;
     estimateRowHeight?: (index: number) => number;
     overscan?: number;
-    /** Callback fired when the user scrolls near the end of the table */
+    /** Callback fired when the user scrolls near the end (bottom) of the table */
     onEndReached?: () => void;
     /** Distance from the bottom (in px) to trigger onEndReached (default: 200) */
     onEndReachedThreshold?: number;
+    /** Callback fired when the user scrolls near the start (top) of the table */
+    onStartReached?: () => void;
+    /** Distance from the top (in px) to trigger onStartReached (default: 200) */
+    onStartReachedThreshold?: number;
+    /**
+     * Row id to anchor the initial scroll position to. The table scrolls this row
+     * into view on mount and arms the edge detectors only after that initial
+     * scroll settles. Use for deep-linking into the middle of a dataset.
+     */
+    initialScrollToRowId?: string;
     /** Callback fired when the master cell is clicked. Receives the row ID. */
     onMasterCellClick?: (rowId: string) => void;
     /** ID of the currently active (highlighted) row, or null. Controls row highlighting via data-preview-active attribute. */

package/dist/hooks/useOverflowItems.d.ts

@@ -1,5 +1,11 @@
 import { type ReactElement, type RefObject } from 'react';
 export interface UseOverflowItemsOptions<T> {
+    /**
+     * Invariant: a given `items` array identity must always render to the same
+     * widths. Measurements are cached by array identity regardless of the
+     * renderers/reserveSpace, so changing those to alter widths needs a fresh
+     * array.
+     */
     items: T[];
     renderItem: (item: T) => ReactElement;
     renderMeasurementItem?: (item: T) => ReactElement;

package/dist/hooks/useOverflowItems.js

@@ -1,17 +1,26 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useCallback, useLayoutEffect, useRef, useState } from "react";
 import { calculateVisibleCount } from "./useOverflowItems.helpers.js";
+import { scheduleOverflowMeasurement } from "./useOverflowItems.scheduler.js";
+const crossMountCache = new WeakMap();
 function useOverflowItems({ items, renderItem, renderMeasurementItem, overflowRenderer, reserveSpace = 60 }) {
     const containerRef = useRef(null);
-    const [visibleCount, setVisibleCount] = useState(items.length);
+    const [visibleCount, setVisibleCount] = useState(()=>{
+        const cached = items.length > 0 ? crossMountCache.get(items) : void 0;
+        if (cached) return Math.min(cached.lastCount, items.length);
+        return Math.min(items.length, 1);
+    });
+    const itemsRef = useRef(items);
+    itemsRef.current = items;
     const measurementRefs = useRef([]);
     const indicatorRef = useRef(null);
+    const measurementLayerRef = useRef(null);
     const cacheRef = useRef({
         widths: [],
         gap: 0,
         indicatorWidth: reserveSpace
     });
-    const recompute = useCallback(()=>{
+    const recompute = useCallback((availableWidth)=>{
         const container = containerRef.current;
         if (!container) return;
         const { widths, gap, indicatorWidth } = cacheRef.current;
@@ -19,13 +28,14 @@ function useOverflowItems({ items, renderItem, renderMeasurementItem, overflowRe
         const next = calculateVisibleCount({
             itemWidths: widths,
             gap,
-            availableWidth: container.offsetWidth,
+            availableWidth: availableWidth ?? container.offsetWidth,
             indicatorWidth
         });
+        const entry = crossMountCache.get(itemsRef.current);
+        if (entry) entry.lastCount = next;
         setVisibleCount((prev)=>prev === next ? prev : next);
     }, []);
     useLayoutEffect(()=>{
-        const container = containerRef.current;
         if (0 === items.length) {
             cacheRef.current = {
                 widths: [],
@@ -35,15 +45,34 @@ function useOverflowItems({ items, renderItem, renderMeasurementItem, overflowRe
             setVisibleCount(0);
             return;
         }
-        const gap = container ? Number.parseFloat(getComputedStyle(container).gap || '0') || 0 : 0;
-        const widths = measurementRefs.current.slice(0, items.length).map((ref)=>ref?.offsetWidth ?? 0);
-        const indicatorWidth = indicatorRef.current?.offsetWidth || reserveSpace;
-        cacheRef.current = {
-            widths,
-            gap,
-            indicatorWidth
-        };
-        recompute();
+        const cached = crossMountCache.get(items);
+        if (cached) {
+            cacheRef.current = cached;
+            return scheduleOverflowMeasurement(()=>{
+                const availableWidth = containerRef.current?.offsetWidth ?? 0;
+                return ()=>recompute(availableWidth);
+            });
+        }
+        measurementLayerRef.current?.style.removeProperty('display');
+        return scheduleOverflowMeasurement(()=>{
+            const container = containerRef.current;
+            const gap = container ? Number.parseFloat(getComputedStyle(container).gap || '0') || 0 : 0;
+            const widths = measurementRefs.current.slice(0, items.length).map((ref)=>ref?.offsetWidth ?? 0);
+            const indicatorWidth = indicatorRef.current?.offsetWidth || reserveSpace;
+            const availableWidth = container?.offsetWidth ?? 0;
+            return ()=>{
+                const entry = {
+                    widths,
+                    gap,
+                    indicatorWidth,
+                    lastCount: items.length
+                };
+                cacheRef.current = entry;
+                crossMountCache.set(items, entry);
+                recompute(availableWidth);
+                measurementLayerRef.current?.style.setProperty('display', 'none');
+            };
+        });
     }, [
         items,
         renderItem,
@@ -75,9 +104,10 @@ function useOverflowItems({ items, renderItem, renderMeasurementItem, overflowRe
     const hiddenItems = items.slice(visibleCount);
     const hiddenCount = hiddenItems.length;
     const MeasurementContainer = useCallback(()=>{
-        if (0 === items.length) return null;
+        if (0 === items.length || crossMountCache.has(items)) return null;
         const renderMeasure = renderMeasurementItem || renderItem;
         return /*#__PURE__*/ jsxs("div", {
+            ref: measurementLayerRef,
             className: "absolute invisible pointer-events-none",
             "aria-hidden": "true",
             children: [

package/dist/hooks/useOverflowItems.scheduler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared read/write batch for overflow measurements. Many instances mount in
+ * one commit (a virtualized row chunk × several overflow cells); measuring in
+ * each layout effect reflows per instance, since its setState flushes before
+ * the next reads `offsetWidth`. One pre-paint microtask runs all reads against
+ * clean layout, then all writes — React batches them, no interleaving.
+ */
+type WritePhase = () => void;
+type ReadPhase = () => WritePhase;
+/**
+ * Queue a measurement for the next pre-paint flush. Returns a cancel
+ * function — call it on effect cleanup so unmounted or re-rendered
+ * instances never measure stale refs.
+ */
+export declare const scheduleOverflowMeasurement: (read: ReadPhase) => (() => void);
+export {};

package/dist/hooks/useOverflowItems.scheduler.js

@@ -0,0 +1,25 @@
+const queue = new Set();
+let flushScheduled = false;
+const flush = ()=>{
+    flushScheduled = false;
+    const reads = Array.from(queue);
+    queue.clear();
+    const writes = [];
+    for (const read of reads)try {
+        writes.push(read());
+    } catch  {}
+    for (const write of writes)try {
+        write();
+    } catch  {}
+};
+const scheduleOverflowMeasurement = (read)=>{
+    queue.add(read);
+    if (!flushScheduled) {
+        flushScheduled = true;
+        queueMicrotask(flush);
+    }
+    return ()=>{
+        queue.delete(read);
+    };
+};
+export { scheduleOverflowMeasurement };

package/dist/metadata/components.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.51.1",
-  "generatedAt": "2026-06-02T15:56:09.933Z",
+  "version": "0.51.2",
+  "generatedAt": "2026-06-03T10:23:04.183Z",
   "components": [
     {
       "name": "Accordion",
@@ -51518,6 +51518,12 @@
           "description": "Show skeleton rows",
           "defaultValue": "false"
         },
+        {
+          "name": "isLoadingPrevious",
+          "type": "boolean | undefined",
+          "required": false,
+          "description": "Show skeleton rows above the first row while a previous page is being\nfetched (bidirectional infinite scroll — the start-edge counterpart of\n`isLoading`). Pair with `onStartReached`."
+        },
         {
           "name": "skeletonCount",
           "type": "number | undefined",
@@ -51618,6 +51624,12 @@
           "type": "number | undefined",
           "required": false
         },
+        {
+          "name": "initialScrollToRowId",
+          "type": "string | undefined",
+          "required": false,
+          "description": "Row id to anchor the initial scroll position to. The table scrolls this row\ninto view on mount and arms the edge detectors only after that initial\nscroll settles. Use for deep-linking into the middle of a dataset."
+        },
         {
           "name": "activeRowId",
           "type": "string | null | undefined",
@@ -51773,6 +51785,14 @@
           "name": "InfiniteScrollWindow",
           "code": "() => {\n  const { data, isFetching, hasMore, totalItems, fetchNextPage } = useInfiniteData();\n\n  return (\n    <VStack gap={8}>\n      <Text size='sm' color='secondary'>\n        Loaded {data.length} of {totalItems} rows {isFetching && '— loading...'}\n        {!hasMore && ' — all loaded'}\n      </Text>\n      <Table\n        data={data}\n        columns={securityColumns}\n        getRowId={row => row.id}\n        virtualized='window'\n        isLoading={isFetching}\n        onEndReached={fetchNextPage}\n        onEndReachedThreshold={300}\n      />\n    </VStack>\n  );\n}"
         },
+        {
+          "name": "BidirectionalInfiniteScroll",
+          "code": "() => {\n  const {\n    data,\n    anchorId,\n    isFetchingPrev,\n    isFetchingNext,\n    hasPrev,\n    hasNext,\n    fetchPrevPage,\n    fetchNextPage,\n  } = useBidirectionalData();\n\n  return (\n    <VStack gap={8}>\n      <Text size='sm' color='secondary'>\n        Window of {data.length} rows around the anchor — scroll up for top skeletons, down for\n        bottom ones{(isFetchingPrev || isFetchingNext) && ' — loading...'}\n        {!hasPrev && ' — top reached'}\n        {!hasNext && ' — bottom reached'}\n      </Text>\n      <Table\n        className='h-500'\n        data={data}\n        columns={securityColumns}\n        getRowId={row => row.id}\n        virtualized='container'\n        isLoading={isFetchingNext}\n        isLoadingPrevious={isFetchingPrev}\n        initialScrollToRowId={anchorId}\n        onStartReached={fetchPrevPage}\n        onStartReachedThreshold={200}\n        onEndReached={fetchNextPage}\n        onEndReachedThreshold={200}\n      />\n    </VStack>\n  );\n}"
+        },
+        {
+          "name": "BidirectionalInfiniteScrollWindow",
+          "code": "() => {\n  const {\n    data,\n    anchorId,\n    isFetchingPrev,\n    isFetchingNext,\n    hasPrev,\n    hasNext,\n    fetchPrevPage,\n    fetchNextPage,\n  } = useBidirectionalData();\n\n  return (\n    <VStack gap={8}>\n      <Text size='sm' color='secondary'>\n        Window of {data.length} rows around the anchor\n        {(isFetchingPrev || isFetchingNext) && ' — loading...'}\n        {!hasPrev && ' — top reached'}\n        {!hasNext && ' — bottom reached'}\n      </Text>\n      <Table\n        data={data}\n        columns={securityColumns}\n        getRowId={row => row.id}\n        virtualized='window'\n        isLoading={isFetchingNext}\n        isLoadingPrevious={isFetchingPrev}\n        initialScrollToRowId={anchorId}\n        onStartReached={fetchPrevPage}\n        onStartReachedThreshold={200}\n        onEndReached={fetchNextPage}\n        onEndReachedThreshold={200}\n      />\n    </VStack>\n  );\n}"
+        },
         {
           "name": "HeaderColumnDescription",
           "code": "() => {\n  const [sorting, setSorting] = useState<TableSortingState>([]);\n\n  const columns = useMemo<TableColumnDef<(typeof securityEvents)[number]>[]>(\n    () =>\n      securityColumns.map(col => {\n        const key = 'accessorKey' in col ? col.accessorKey : undefined;\n        if (key === 'objectName') {\n          return {\n            ...col,\n            meta: {\n              ...col.meta,\n              description: { type: 'text' as const, content: 'Target resource' },\n            },\n          };\n        }\n        if (key === 'sourceIp') {\n          return {\n            ...col,\n            meta: {\n              ...col.meta,\n              description: { type: 'tooltip' as const, content: 'Request origin IP' },\n            },\n          };\n        }\n        if (key === 'requests') {\n          return {\n            ...col,\n            meta: { ...col.meta, description: { type: 'tooltip' as const, content: 'Total hits' } },\n          };\n        }\n        if (key === 'parameter') {\n          return {\n            ...col,\n            meta: {\n              ...col.meta,\n              description: { type: 'text' as const, content: 'Affected param' },\n            },\n          };\n        }\n        return col;\n      }),\n    [],\n  );\n\n  return (\n    <Table\n      data={securityEvents}\n      columns={columns}\n      getRowId={row => row.id}\n      sorting={sorting}\n      onSortingChange={setSorting}\n    />\n  );\n}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wallarm-org/design-system",
-  "version": "0.51.2",
+  "version": "0.52.0",
   "description": "Core design system library with React components and Storybook documentation",
   "publishConfig": {
     "access": "public",

package/dist/components/Table/hooks/useEndReached.d.ts

@@ -1,19 +0,0 @@
-import { type RefObject } from 'react';
-type ScrollMode = 'container' | 'window';
-interface UseEndReachedOptions {
-    mode: ScrollMode;
-    /** Scroll element ref — required for `container` mode */
-    scrollRef?: RefObject<HTMLElement | null>;
-    onEndReached?: () => void;
-    threshold?: number;
-}
-/**
- * Fires `onEndReached` once when the user scrolls within `threshold` px
- * of the bottom. Re-arms automatically after the user scrolls back up
- * past the threshold or when the scroll height grows (new data loaded).
- *
- * A cooldown guard prevents rapid re-fires that can occur when new rows
- * are appended (scrollHeight grows → firedRef resets → still at bottom).
- */
-export declare const useEndReached: ({ mode, scrollRef, onEndReached, threshold, }: UseEndReachedOptions) => void;
-export {};