@wallarm-org/design-system 0.52.0-rc-feature-shell.1 → 0.52.0

package/dist/components/NavRail/NavRail.d.ts

@@ -4,6 +4,5 @@ export interface NavRailProps extends HTMLAttributes<HTMLElement>, TestableProps
     ref?: Ref<HTMLElement>;
     children?: ReactNode;
     collapsed?: boolean;
-    appeared?: boolean;
 }
 export declare const NavRail: FC<NavRailProps>;

package/dist/components/NavRail/NavRail.js

@@ -6,7 +6,7 @@ import { cn } from "../../utils/cn.js";
 import { TestIdProvider } from "../../utils/testId.js";
 import { navRailVariants } from "./classes.js";
 import { NavRailContextProvider } from "./NavRailContext.js";
-const NavRail = ({ ref, collapsed = false, appeared, className, children, 'data-testid': testId, ...props })=>{
+const NavRail = ({ ref, collapsed = false, className, children, 'data-testid': testId, ...props })=>{
     const internalRef = useRef(null);
     const focusPanel = useCallback(()=>{
         const panel = document.querySelector('[data-slot="nav-panel"]');
@@ -47,7 +47,7 @@ const NavRail = ({ ref, collapsed = false, appeared, className, children, 'data-
                 "data-testid": testId,
                 className: cn(navRailVariants({
                     collapsed
-                }), false === appeared && 'opacity-0', className),
+                }), className),
                 children: children
             })
         })

package/dist/components/NavRail/classes.js

@@ -1,5 +1,5 @@
 import { cva } from "class-variance-authority";
-const navRailVariants = cva('flex h-full shrink-0 flex-col overflow-hidden px-8 pt-6 pb-12 transition-[width] duration-200 ease-in-out transition-[width,opacity] duration-200 ease-in-out', {
+const navRailVariants = cva('flex h-full shrink-0 flex-col overflow-hidden px-8 pt-6 pb-12 transition-[width] duration-200 ease-in-out', {
     variants: {
         collapsed: {
             true: 'w-[48px]',

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 {};