@trackunit/react-components 2.1.64 → 2.2.0

package/index.cjs.js

@@ -5733,14 +5733,17 @@ const ListLoadingIndicator = ({ type, hasThumbnail, thumbnailShape, hasDescripti
  */
 const List = ({ children, className, "data-testid": dataTestId, style, ref, 
 // UseListResult properties
-containerRef, listRef, rows, getListItemProps, header, loadingIndicator, shouldShowLoaderAtIndex, count, isScrolling, separator, topSeparatorOnScroll, isAtTop, contentFillsContainer, 
+containerRef, listRef, listContainerRef, rows, getListItemProps, header, loadingIndicator, shouldShowLoaderAtIndex, count, isScrolling, separator, topSeparatorOnScroll, isAtTop, contentFillsContainer, 
 // Unused but part of UseListResult interface (can be used from parent)
 scrollOffset: _scrollOffset, getTotalSize: _getTotalSize, getVirtualItems: _getVirtualItems, scrollToOffset: _scrollToOffset, scrollToIndex: _scrollToIndex, measure: _measure, }) => {
     const mergedContainerRef = useMergeRefs([containerRef, ref]);
+    // The virtualizer owns the `<ul>` height + item positions via directDomUpdates,
+    // so its container callback must be attached to the `<ul>` (alongside listRef).
+    const mergedListRef = useMergeRefs([listRef, listContainerRef]);
     return (jsxRuntime.jsx("div", { className: cvaListContainer({
             withTopSeparator: topSeparatorOnScroll && !isAtTop,
             className,
-        }), "data-is-scrolling": isScrolling, "data-testid": dataTestId, ref: mergedContainerRef, style: style, children: jsxRuntime.jsx("ul", { className: cvaList(), ref: listRef, children: rows.map(row => {
+        }), "data-is-scrolling": isScrolling, "data-testid": dataTestId, ref: mergedContainerRef, style: style, children: jsxRuntime.jsx("ul", { className: cvaList(), ref: mergedListRef, children: rows.map(row => {
                 // Generate list item props with clean separator styling
                 const listItemProps = getListItemProps(row, {
                     className: cvaListItem$1({
@@ -5794,7 +5797,7 @@ const DEFAULT_ROW_HEIGHT$1 = 50;
  * @param props.overscan - Optional number of items to render outside the visible area.
  * @param props.onChange - Optional callback when virtualizer changes.
  * @param props.skip - Whether to skip automatic loading of more data (default: false).
- * @returns {Virtualizer} The virtualizer instance with all its properties and methods.
+ * @returns {ReactVirtualizer} The virtualizer instance with all its properties and methods, including `containerRef` for direct DOM positioning.
  * @description
  * This hook is used to implement infinite scrolling in a table. It uses TanStack Virtual's
  * built-in capabilities for virtualization and automatically loads more data when scrolling
@@ -5808,12 +5811,14 @@ const DEFAULT_ROW_HEIGHT$1 = 50;
  * });
  */
 const useInfiniteScroll = ({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip = false, }) => {
-    "use no memo"; //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
     const handleChange = react.useCallback((virtualizer) => {
         onChange?.(virtualizer);
     }, [onChange]);
     const handleEstimateSize = react.useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT$1, [estimateSize]);
-    //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
+    // eslint-plugin-react-hooks hardcodes `useVirtualizer` as a known-incompatible
+    // API (its returned functions can't be memoized), so this warning is emitted
+    // regardless of the installed version. The React Compiler already auto-skips
+    // memoizing this hook, so the behaviour is safe.
     // eslint-disable-next-line react-hooks/incompatible-library
     const rowVirtualizer = reactVirtual.useVirtualizer({
         count,
@@ -5824,6 +5829,12 @@ const useInfiniteScroll = ({ pagination, scrollElementRef, count, estimateSize,
         // This option enables wrapping ResizeObserver measurements in requestAnimationFrame for smoother updates and reduced layout thrashing.
         // It helps prevent the "ResizeObserver loop completed with undelivered notifications" error by ensuring that measurements align with the rendering cycle
         useAnimationFrameWithResizeObserver: true,
+        // Let the virtualizer write item positions and container size straight to
+        // the DOM, only re-rendering when the visible index range changes. This
+        // removes the imperative transform/height races that made scrolling jumpy.
+        directDomUpdates: true,
+        directDomUpdatesMode: "transform",
+        useFlushSync: false,
     });
     const virtualItems = rowVirtualizer.getVirtualItems();
     // Auto-load more data based on scroll position and content height
@@ -5883,7 +5894,7 @@ const DEFAULT_LOADING_INDICATOR_CONFIG = {
  *
  * return (
  *   <div ref={list.containerRef}>
- *     <ul style={{ height: `${list.getTotalSize()}px` }}>
+ *     <ul ref={list.listContainerRef} className="relative">
  *       {list.rows.map(row => {
  *         const props = list.getListItemProps(row, { className: 'list-item' });
  *         return <li {...props}>{row.item?.title}</li>;
@@ -5896,7 +5907,6 @@ const DEFAULT_LOADING_INDICATOR_CONFIG = {
 const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAULT_LOADING_INDICATOR_CONFIG, onRowClick, onChange, estimateItemSize, estimateHeaderSize, overscan, separator = "line", topSeparatorOnScroll = false, }) => {
     const containerRef = react.useRef(null);
     const listRef = react.useRef(null);
-    const rowRefsMap = react.useRef(new Map());
     const virtualizerRef = react.useRef(null);
     const hasMeasuredOnMount = react.useRef(false);
     // Resolve loading indicator once to avoid unnecessary re-renders
@@ -5988,19 +5998,10 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
         count: totalRowCount,
         estimateSize,
         overscan,
-        onChange: instance => {
-            if (listRef.current) {
-                listRef.current.style.height = `${instance.getTotalSize()}px`;
-            }
-            // Apply transforms to all virtual items
-            instance.getVirtualItems().forEach(virtualRow => {
-                const rowRef = rowRefsMap.current.get(virtualRow.index);
-                if (rowRef) {
-                    rowRef.style.transform = `translateY(${virtualRow.start}px)`;
-                }
-            });
-            onChange?.(instance);
-        },
+        // Item positions and the `<ul>` size are written directly to the DOM by
+        // the virtualizer (directDomUpdates), so this callback only forwards the
+        // change to consumers.
+        onChange,
     });
     // Keep ref updated with latest virtualizer instance
     react.useEffect(() => {
@@ -6024,9 +6025,9 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
         }
         previousCountRef.current = currentCount;
     }, [virtualizer, pagination?.pageInfo?.count]);
+    const virtualItems = virtualizer.getVirtualItems();
     // Transform virtual items into typed rows
     const rows = react.useMemo(() => {
-        const virtualItems = virtualizer.getVirtualItems();
         return virtualItems.map((virtualRow) => {
             const { index } = virtualRow;
             // Determine row type
@@ -6056,8 +6057,7 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
                 dataIndex,
             };
         });
-        // Call getVirtualItems() fresh each time to get updated measurements after virtualizer state changes
-    }, [virtualizer, totalDataRows, hasHeader, dataStartIndex, getItem]);
+    }, [virtualItems, totalDataRows, hasHeader, dataStartIndex, getItem]);
     // Helper to create list item props
     const getListItemProps = react.useCallback((row, options) => {
         const { type, item, dataIndex } = row;
@@ -6072,17 +6072,9 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
             className: options.className,
             "data-index": row.virtualRow.index,
             onClick,
-            ref: el => {
-                if (el) {
-                    virtualizer.measureElement(el);
-                    rowRefsMap.current.set(row.virtualRow.index, el);
-                    // Apply transform immediately when element is added to map
-                    const virtualRow = virtualizer.getVirtualItems().find(vr => vr.index === row.virtualRow.index);
-                    if (virtualRow) {
-                        el.style.transform = `translateY(${virtualRow.start}px)`;
-                    }
-                }
-            },
+            // The virtualizer positions rows itself (directDomUpdates); the ref
+            // only needs to register the element for dynamic height measurement.
+            ref: virtualizer.measureElement,
             tabIndex: -1,
         };
     }, [onRowClick, virtualizer]);
@@ -6096,7 +6088,11 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
     }, [totalSize]);
     return react.useMemo(() => ({
         ...virtualizer,
+        // `containerRef` (scroll element) intentionally overrides the spread
+        // `virtualizer.containerRef`; the latter is re-exposed as
+        // `listContainerRef` for the inner `<ul>` size container.
         containerRef,
+        listContainerRef: virtualizer.containerRef,
         listRef,
         rows,
         getListItemProps,
@@ -12124,8 +12120,7 @@ const DEFAULT_ROW_HEIGHT = 50;
  * scroll position at both ends and triggers the appropriate pagination
  * direction.
  */
-const useBidirectionalScroll = ({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip = false, onTopItemChange, }) => {
-    "use no memo"; //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
+const useBidirectionalScroll = ({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip = false, onTopItemChange, getItemKey, }) => {
     const onTopItemChangeRef = react.useRef(onTopItemChange);
     react.useEffect(() => {
         onTopItemChangeRef.current = onTopItemChange;
@@ -12141,7 +12136,10 @@ const useBidirectionalScroll = ({ pagination, scrollElementRef, count, estimateS
         }
     }, [onChange]);
     const handleEstimateSize = react.useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT, [estimateSize]);
-    //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
+    // eslint-plugin-react-hooks hardcodes `useVirtualizer` as a known-incompatible
+    // API (its returned functions can't be memoized), so this warning is emitted
+    // regardless of the installed version. The React Compiler already auto-skips
+    // memoizing this hook, so the behaviour is safe.
     // eslint-disable-next-line react-hooks/incompatible-library
     const rowVirtualizer = reactVirtual.useVirtualizer({
         count,
@@ -12149,7 +12147,14 @@ const useBidirectionalScroll = ({ pagination, scrollElementRef, count, estimateS
         estimateSize: handleEstimateSize,
         overscan: overscan ?? OVERSCAN,
         onChange: handleChange,
+        getItemKey,
         useAnimationFrameWithResizeObserver: true,
+        // Let the virtualizer write item positions and container size straight to
+        // the DOM, only re-rendering when the visible index range changes. This
+        // removes the imperative transform/height races that made scrolling jumpy.
+        directDomUpdates: true,
+        directDomUpdatesMode: "transform",
+        useFlushSync: false,
     });
     const virtualItems = rowVirtualizer.getVirtualItems();
     // Track count before backward fetch so we can offset scroll position

package/index.esm.js

@@ -5731,14 +5731,17 @@ const ListLoadingIndicator = ({ type, hasThumbnail, thumbnailShape, hasDescripti
  */
 const List = ({ children, className, "data-testid": dataTestId, style, ref, 
 // UseListResult properties
-containerRef, listRef, rows, getListItemProps, header, loadingIndicator, shouldShowLoaderAtIndex, count, isScrolling, separator, topSeparatorOnScroll, isAtTop, contentFillsContainer, 
+containerRef, listRef, listContainerRef, rows, getListItemProps, header, loadingIndicator, shouldShowLoaderAtIndex, count, isScrolling, separator, topSeparatorOnScroll, isAtTop, contentFillsContainer, 
 // Unused but part of UseListResult interface (can be used from parent)
 scrollOffset: _scrollOffset, getTotalSize: _getTotalSize, getVirtualItems: _getVirtualItems, scrollToOffset: _scrollToOffset, scrollToIndex: _scrollToIndex, measure: _measure, }) => {
     const mergedContainerRef = useMergeRefs([containerRef, ref]);
+    // The virtualizer owns the `<ul>` height + item positions via directDomUpdates,
+    // so its container callback must be attached to the `<ul>` (alongside listRef).
+    const mergedListRef = useMergeRefs([listRef, listContainerRef]);
     return (jsx("div", { className: cvaListContainer({
             withTopSeparator: topSeparatorOnScroll && !isAtTop,
             className,
-        }), "data-is-scrolling": isScrolling, "data-testid": dataTestId, ref: mergedContainerRef, style: style, children: jsx("ul", { className: cvaList(), ref: listRef, children: rows.map(row => {
+        }), "data-is-scrolling": isScrolling, "data-testid": dataTestId, ref: mergedContainerRef, style: style, children: jsx("ul", { className: cvaList(), ref: mergedListRef, children: rows.map(row => {
                 // Generate list item props with clean separator styling
                 const listItemProps = getListItemProps(row, {
                     className: cvaListItem$1({
@@ -5792,7 +5795,7 @@ const DEFAULT_ROW_HEIGHT$1 = 50;
  * @param props.overscan - Optional number of items to render outside the visible area.
  * @param props.onChange - Optional callback when virtualizer changes.
  * @param props.skip - Whether to skip automatic loading of more data (default: false).
- * @returns {Virtualizer} The virtualizer instance with all its properties and methods.
+ * @returns {ReactVirtualizer} The virtualizer instance with all its properties and methods, including `containerRef` for direct DOM positioning.
  * @description
  * This hook is used to implement infinite scrolling in a table. It uses TanStack Virtual's
  * built-in capabilities for virtualization and automatically loads more data when scrolling
@@ -5806,12 +5809,14 @@ const DEFAULT_ROW_HEIGHT$1 = 50;
  * });
  */
 const useInfiniteScroll = ({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip = false, }) => {
-    "use no memo"; //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
     const handleChange = useCallback((virtualizer) => {
         onChange?.(virtualizer);
     }, [onChange]);
     const handleEstimateSize = useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT$1, [estimateSize]);
-    //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
+    // eslint-plugin-react-hooks hardcodes `useVirtualizer` as a known-incompatible
+    // API (its returned functions can't be memoized), so this warning is emitted
+    // regardless of the installed version. The React Compiler already auto-skips
+    // memoizing this hook, so the behaviour is safe.
     // eslint-disable-next-line react-hooks/incompatible-library
     const rowVirtualizer = useVirtualizer({
         count,
@@ -5822,6 +5827,12 @@ const useInfiniteScroll = ({ pagination, scrollElementRef, count, estimateSize,
         // This option enables wrapping ResizeObserver measurements in requestAnimationFrame for smoother updates and reduced layout thrashing.
         // It helps prevent the "ResizeObserver loop completed with undelivered notifications" error by ensuring that measurements align with the rendering cycle
         useAnimationFrameWithResizeObserver: true,
+        // Let the virtualizer write item positions and container size straight to
+        // the DOM, only re-rendering when the visible index range changes. This
+        // removes the imperative transform/height races that made scrolling jumpy.
+        directDomUpdates: true,
+        directDomUpdatesMode: "transform",
+        useFlushSync: false,
     });
     const virtualItems = rowVirtualizer.getVirtualItems();
     // Auto-load more data based on scroll position and content height
@@ -5881,7 +5892,7 @@ const DEFAULT_LOADING_INDICATOR_CONFIG = {
  *
  * return (
  *   <div ref={list.containerRef}>
- *     <ul style={{ height: `${list.getTotalSize()}px` }}>
+ *     <ul ref={list.listContainerRef} className="relative">
  *       {list.rows.map(row => {
  *         const props = list.getListItemProps(row, { className: 'list-item' });
  *         return <li {...props}>{row.item?.title}</li>;
@@ -5894,7 +5905,6 @@ const DEFAULT_LOADING_INDICATOR_CONFIG = {
 const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAULT_LOADING_INDICATOR_CONFIG, onRowClick, onChange, estimateItemSize, estimateHeaderSize, overscan, separator = "line", topSeparatorOnScroll = false, }) => {
     const containerRef = useRef(null);
     const listRef = useRef(null);
-    const rowRefsMap = useRef(new Map());
     const virtualizerRef = useRef(null);
     const hasMeasuredOnMount = useRef(false);
     // Resolve loading indicator once to avoid unnecessary re-renders
@@ -5986,19 +5996,10 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
         count: totalRowCount,
         estimateSize,
         overscan,
-        onChange: instance => {
-            if (listRef.current) {
-                listRef.current.style.height = `${instance.getTotalSize()}px`;
-            }
-            // Apply transforms to all virtual items
-            instance.getVirtualItems().forEach(virtualRow => {
-                const rowRef = rowRefsMap.current.get(virtualRow.index);
-                if (rowRef) {
-                    rowRef.style.transform = `translateY(${virtualRow.start}px)`;
-                }
-            });
-            onChange?.(instance);
-        },
+        // Item positions and the `<ul>` size are written directly to the DOM by
+        // the virtualizer (directDomUpdates), so this callback only forwards the
+        // change to consumers.
+        onChange,
     });
     // Keep ref updated with latest virtualizer instance
     useEffect(() => {
@@ -6022,9 +6023,9 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
         }
         previousCountRef.current = currentCount;
     }, [virtualizer, pagination?.pageInfo?.count]);
+    const virtualItems = virtualizer.getVirtualItems();
     // Transform virtual items into typed rows
     const rows = useMemo(() => {
-        const virtualItems = virtualizer.getVirtualItems();
         return virtualItems.map((virtualRow) => {
             const { index } = virtualRow;
             // Determine row type
@@ -6054,8 +6055,7 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
                 dataIndex,
             };
         });
-        // Call getVirtualItems() fresh each time to get updated measurements after virtualizer state changes
-    }, [virtualizer, totalDataRows, hasHeader, dataStartIndex, getItem]);
+    }, [virtualItems, totalDataRows, hasHeader, dataStartIndex, getItem]);
     // Helper to create list item props
     const getListItemProps = useCallback((row, options) => {
         const { type, item, dataIndex } = row;
@@ -6070,17 +6070,9 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
             className: options.className,
             "data-index": row.virtualRow.index,
             onClick,
-            ref: el => {
-                if (el) {
-                    virtualizer.measureElement(el);
-                    rowRefsMap.current.set(row.virtualRow.index, el);
-                    // Apply transform immediately when element is added to map
-                    const virtualRow = virtualizer.getVirtualItems().find(vr => vr.index === row.virtualRow.index);
-                    if (virtualRow) {
-                        el.style.transform = `translateY(${virtualRow.start}px)`;
-                    }
-                }
-            },
+            // The virtualizer positions rows itself (directDomUpdates); the ref
+            // only needs to register the element for dynamic height measurement.
+            ref: virtualizer.measureElement,
             tabIndex: -1,
         };
     }, [onRowClick, virtualizer]);
@@ -6094,7 +6086,11 @@ const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAUL
     }, [totalSize]);
     return useMemo(() => ({
         ...virtualizer,
+        // `containerRef` (scroll element) intentionally overrides the spread
+        // `virtualizer.containerRef`; the latter is re-exposed as
+        // `listContainerRef` for the inner `<ul>` size container.
         containerRef,
+        listContainerRef: virtualizer.containerRef,
         listRef,
         rows,
         getListItemProps,
@@ -12122,8 +12118,7 @@ const DEFAULT_ROW_HEIGHT = 50;
  * scroll position at both ends and triggers the appropriate pagination
  * direction.
  */
-const useBidirectionalScroll = ({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip = false, onTopItemChange, }) => {
-    "use no memo"; //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
+const useBidirectionalScroll = ({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip = false, onTopItemChange, getItemKey, }) => {
     const onTopItemChangeRef = useRef(onTopItemChange);
     useEffect(() => {
         onTopItemChangeRef.current = onTopItemChange;
@@ -12139,7 +12134,10 @@ const useBidirectionalScroll = ({ pagination, scrollElementRef, count, estimateS
         }
     }, [onChange]);
     const handleEstimateSize = useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT, [estimateSize]);
-    //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
+    // eslint-plugin-react-hooks hardcodes `useVirtualizer` as a known-incompatible
+    // API (its returned functions can't be memoized), so this warning is emitted
+    // regardless of the installed version. The React Compiler already auto-skips
+    // memoizing this hook, so the behaviour is safe.
     // eslint-disable-next-line react-hooks/incompatible-library
     const rowVirtualizer = useVirtualizer({
         count,
@@ -12147,7 +12145,14 @@ const useBidirectionalScroll = ({ pagination, scrollElementRef, count, estimateS
         estimateSize: handleEstimateSize,
         overscan: overscan ?? OVERSCAN,
         onChange: handleChange,
+        getItemKey,
         useAnimationFrameWithResizeObserver: true,
+        // Let the virtualizer write item positions and container size straight to
+        // the DOM, only re-rendering when the visible index range changes. This
+        // removes the imperative transform/height races that made scrolling jumpy.
+        directDomUpdates: true,
+        directDomUpdatesMode: "transform",
+        useFlushSync: false,
     });
     const virtualItems = rowVirtualizer.getVirtualItems();
     // Track count before backward fetch so we can offset scroll position

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "2.1.64",
+  "version": "2.2.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -14,17 +14,17 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.13.57",
-    "@trackunit/css-class-variance-utilities": "1.13.58",
-    "@trackunit/shared-utils": "1.15.60",
-    "@trackunit/ui-icons": "1.13.59",
+    "@trackunit/ui-design-tokens": "1.13.58",
+    "@trackunit/css-class-variance-utilities": "1.13.59",
+    "@trackunit/shared-utils": "1.15.62",
+    "@trackunit/ui-icons": "1.13.60",
     "es-toolkit": "^1.39.10",
-    "@tanstack/react-virtual": "3.13.12",
+    "@tanstack/react-virtual": "^3.14.3",
     "dequal": "^2.0.3",
     "fflate": "^0.8.2",
     "superjson": "^2.2.6",
     "zod": "^3.25.76",
-    "@trackunit/i18n-library-translation": "2.0.62"
+    "@trackunit/i18n-library-translation": "2.1.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/List/List.d.ts

@@ -93,4 +93,4 @@ export interface ListProps<TItem = unknown> extends CommonProps, Styleable, Refa
  * );
  * ```
  */
-export declare const List: <TItem = unknown>({ children, className, "data-testid": dataTestId, style, ref, containerRef, listRef, rows, getListItemProps, header, loadingIndicator, shouldShowLoaderAtIndex, count, isScrolling, separator, topSeparatorOnScroll, isAtTop, contentFillsContainer, scrollOffset: _scrollOffset, getTotalSize: _getTotalSize, getVirtualItems: _getVirtualItems, scrollToOffset: _scrollToOffset, scrollToIndex: _scrollToIndex, measure: _measure, }: ListProps<TItem>) => ReactElement;
+export declare const List: <TItem = unknown>({ children, className, "data-testid": dataTestId, style, ref, containerRef, listRef, listContainerRef, rows, getListItemProps, header, loadingIndicator, shouldShowLoaderAtIndex, count, isScrolling, separator, topSeparatorOnScroll, isAtTop, contentFillsContainer, scrollOffset: _scrollOffset, getTotalSize: _getTotalSize, getVirtualItems: _getVirtualItems, scrollToOffset: _scrollToOffset, scrollToIndex: _scrollToIndex, measure: _measure, }: ListProps<TItem>) => ReactElement;

package/src/components/List/ListLoadingIndicator.d.ts

@@ -28,13 +28,13 @@ type CustomLoadingIndicator = {
     /**
      * Number of loading indicators to show on initial load
      *
-     * @default 3
+     * @default 10
      */
     initialLoadingCount?: number;
     /**
      * Number of loading indicators to show when loading more items during scroll
      *
-     * @default 10
+     * @default 3
      */
     scrollLoadingCount?: number;
     hasThumbnail?: never;
@@ -54,13 +54,13 @@ type SkeletonLoadingIndicator = {
     /**
      * Number of loading indicators to show on initial load
      *
-     * @default 3
+     * @default 10
      */
     initialLoadingCount?: number;
     /**
      * Number of loading indicators to show when loading more items during scroll
      *
-     * @default 10
+     * @default 3
      */
     scrollLoadingCount?: number;
 };

package/src/components/List/useList.d.ts

@@ -132,6 +132,13 @@ export interface UseListResult<TItem> extends Pick<Virtualizer<HTMLDivElement, H
     containerRef: RefObject<HTMLDivElement | null>;
     /** Reference to attach to the list */
     listRef: RefObject<HTMLUListElement | null>;
+    /**
+     * Callback ref for the inner size container (`<ul>`). The virtualizer writes
+     * the container's height and item positions directly to the DOM
+     * (directDomUpdates), so this MUST be attached to the `<ul>` and the `<ul>`
+     * must not set its own height.
+     */
+    listContainerRef: (node: HTMLElement | null) => void;
     /** Array of row data to render */
     readonly rows: ReadonlyArray<ListRow<TItem>>;
     /** Helper to create list item props for a given row */
@@ -178,7 +185,7 @@ export interface UseListResult<TItem> extends Pick<Virtualizer<HTMLDivElement, H
  *
  * return (
  *   <div ref={list.containerRef}>
- *     <ul style={{ height: `${list.getTotalSize()}px` }}>
+ *     <ul ref={list.listContainerRef} className="relative">
  *       {list.rows.map(row => {
  *         const props = list.getListItemProps(row, { className: 'list-item' });
  *         return <li {...props}>{row.item?.title}</li>;

package/src/hooks/useBidirectionalScroll.d.ts

@@ -1,4 +1,4 @@
-import { type Virtualizer } from "@tanstack/react-virtual";
+import { type ReactVirtualizer, type Virtualizer } from "@tanstack/react-virtual";
 import { type RefObject } from "react";
 import type { RelayPagination } from "./useRelayPagination";
 interface BidirectionalScrollProps<TScrollElement extends Element, TItemElement extends Element> {
@@ -10,6 +10,15 @@ interface BidirectionalScrollProps<TScrollElement extends Element, TItemElement
     readonly onChange?: (virtualizer: Virtualizer<TScrollElement, TItemElement>) => void;
     readonly skip?: boolean;
     readonly onTopItemChange?: (index: number) => void;
+    /**
+     * Derives a stable per-item key from the index. Must agree with the React
+     * `key` used by the consumer's rendered items, otherwise the virtualizer's
+     * `elementsCache` (keyed by this value) and React's reconciliation (keyed
+     * by the rendered `key`) can disagree when indexes shift without a remount
+     * (e.g. sorting, filtering, or prepending pages), causing `directDomUpdates`
+     * to position rows incorrectly. Defaults to the item index.
+     */
+    readonly getItemKey?: (index: number) => string | number;
 }
 /**
  * Bidirectional infinite scroll hook that supports both forward (nextPage)
@@ -19,5 +28,5 @@ interface BidirectionalScrollProps<TScrollElement extends Element, TItemElement
  * scroll position at both ends and triggers the appropriate pagination
  * direction.
  */
-export declare const useBidirectionalScroll: <TScrollElement extends Element, TItemElement extends Element>({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip, onTopItemChange, }: BidirectionalScrollProps<TScrollElement, TItemElement>) => Virtualizer<TScrollElement, TItemElement>;
+export declare const useBidirectionalScroll: <TScrollElement extends Element, TItemElement extends Element>({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip, onTopItemChange, getItemKey, }: BidirectionalScrollProps<TScrollElement, TItemElement>) => ReactVirtualizer<TScrollElement, TItemElement>;
 export {};

package/src/hooks/useInfiniteScroll.d.ts

@@ -1,4 +1,4 @@
-import { type Virtualizer } from "@tanstack/react-virtual";
+import { type ReactVirtualizer, type Virtualizer } from "@tanstack/react-virtual";
 import { RefObject } from "react";
 import { RelayPagination } from "./useRelayPagination";
 interface InfiniteScrollProps<TScrollElement extends Element, TItemElement extends Element> {
@@ -21,7 +21,7 @@ interface InfiniteScrollProps<TScrollElement extends Element, TItemElement exten
  * @param props.overscan - Optional number of items to render outside the visible area.
  * @param props.onChange - Optional callback when virtualizer changes.
  * @param props.skip - Whether to skip automatic loading of more data (default: false).
- * @returns {Virtualizer} The virtualizer instance with all its properties and methods.
+ * @returns {ReactVirtualizer} The virtualizer instance with all its properties and methods, including `containerRef` for direct DOM positioning.
  * @description
  * This hook is used to implement infinite scrolling in a table. It uses TanStack Virtual's
  * built-in capabilities for virtualization and automatically loads more data when scrolling
@@ -34,5 +34,5 @@ interface InfiniteScrollProps<TScrollElement extends Element, TItemElement exten
  *   estimateSize: () => 35,
  * });
  */
-export declare const useInfiniteScroll: <TScrollElement extends Element, TItemElement extends Element>({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip, }: InfiniteScrollProps<TScrollElement, TItemElement>) => Virtualizer<TScrollElement, TItemElement>;
+export declare const useInfiniteScroll: <TScrollElement extends Element, TItemElement extends Element>({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, skip, }: InfiniteScrollProps<TScrollElement, TItemElement>) => ReactVirtualizer<TScrollElement, TItemElement>;
 export {};