@trackunit/react-components 1.9.19 → 1.9.21

package/index.cjs.js

@@ -12,12 +12,12 @@ var IconSpriteSolid = require('@trackunit/ui-icons/icons-sprite-solid.svg');
 var stringTs = require('string-ts');
 var cssClassVarianceUtilities = require('@trackunit/css-class-variance-utilities');
 var reactSlot = require('@radix-ui/react-slot');
+var reactVirtual = require('@tanstack/react-virtual');
 var usehooksTs = require('usehooks-ts');
 var reactRouter = require('@tanstack/react-router');
 var react$1 = require('@floating-ui/react');
 var esToolkit = require('es-toolkit');
 var tailwindMerge = require('tailwind-merge');
-var reactTablePagination = require('@trackunit/react-table-pagination');
 var reactHelmetAsync = require('react-helmet-async');
 var reactTabs = require('@radix-ui/react-tabs');
 
@@ -993,6 +993,21 @@ const Badge = ({ color = "primary", size = "default", compact = false, className
     return (jsxRuntime.jsx("span", { className: cvaBadge({ color, size, className, compact, isSingleChar }), "data-testid": dataTestId, children: compact ? null : displayedCount }));
 };
 
+const noPagination = {
+    isLoading: false,
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    nextPage: () => { },
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    previousPage: () => { },
+    pageInfo: {
+        count: null,
+        hasNextPage: false,
+        hasPreviousPage: false,
+        endCursor: null,
+        startCursor: null,
+    },
+};
+
 /**
  * Custom hook to handle click outside events.
  *
@@ -1381,6 +1396,73 @@ const useHover = ({ debounced = false, delay = 100, direction = "out" } = { debo
     return { onMouseEnter, onMouseLeave, hovering: debounced ? debouncedHovering : hovering };
 };
 
+const OVERSCAN = 10;
+const DEFAULT_ROW_HEIGHT = 50;
+/**
+ * Custom hook for implementing infinite scrolling in a table using TanStack Virtual.
+ *
+ * @param props - The configuration object for the infinite scroll hook.
+ * @param props.pagination - The relay pagination object for managing data loading.
+ * @param props.scrollElementRef - Reference to the scrollable container element.
+ * @param props.count - Total number of items to virtualize.
+ * @param props.estimateSize - Optional function to estimate item height.
+ * @param props.overscan - Optional number of items to render outside the visible area.
+ * @param props.onChange - Optional callback when virtualizer changes.
+ * @returns {Virtualizer} The virtualizer instance with all its properties and methods.
+ * @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
+ * approaches the end of the available content.
+ * @example
+ * const virtualizer = useInfiniteScroll<HTMLDivElement, HTMLDivElement>({
+ *   pagination: relayPaginationObject,
+ *   scrollElementRef: tableScrollElementRef,
+ *   count: 50,
+ *   estimateSize: () => 35,
+ * });
+ */
+const useInfiniteScroll = ({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, }) => {
+    const handleChange = react.useCallback((virtualizer) => {
+        onChange?.(virtualizer);
+    }, [onChange]);
+    const handleEstimateSize = react.useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT, [estimateSize]);
+    const rowVirtualizer = reactVirtual.useVirtualizer({
+        count,
+        getScrollElement: () => scrollElementRef.current,
+        estimateSize: handleEstimateSize,
+        overscan: overscan ?? OVERSCAN,
+        onChange: handleChange,
+    });
+    const virtualItems = rowVirtualizer.getVirtualItems();
+    // Auto-load more data based on scroll position and content height
+    react.useEffect(() => {
+        if (pagination.pageInfo?.hasNextPage !== true || pagination.isLoading) {
+            return;
+        }
+        const container = scrollElementRef.current;
+        if (!container) {
+            return;
+        }
+        // Check if we should load more data based on virtual items (scroll-based loading)
+        const [lastItem] = [...virtualItems].reverse();
+        const shouldLoadFromScroll = lastItem !== undefined && lastItem.index >= count - 1;
+        // Check if content is insufficient to fill container (initial loading)
+        const shouldLoadFromInsufficientContent = container.scrollHeight <= container.clientHeight;
+        if (shouldLoadFromScroll || shouldLoadFromInsufficientContent) {
+            pagination.nextPage();
+        }
+    }, [
+        pagination.pageInfo?.hasNextPage,
+        pagination.nextPage,
+        pagination.isLoading,
+        pagination,
+        scrollElementRef,
+        virtualItems,
+        count,
+    ]);
+    return rowVirtualizer;
+};
+
 /**
  * Differentiate between the first and subsequent renders.
  *
@@ -1483,6 +1565,60 @@ const useModifierKey = ({ exclude = [] } = {}) => {
     return isModifierPressed;
 };
 
+const defaultPageSize = 50;
+/**
+ * Custom hook for handling Relay pagination in tables.
+ *
+ * @param {RelayPaginationProps} props - The props object containing pagination configuration.
+ * @returns {RelayPaginationSupport} An object containing functions and state for managing Relay pagination.
+ */
+const useRelayPagination = ({ onReset, pageSize } = { pageSize: defaultPageSize }) => {
+    const [variables, setVariables] = react.useState({ first: pageSize });
+    const [pageInfo, setPageInfo] = react.useState();
+    const [isLoading, setIsLoading] = react.useState(true);
+    const nextPage = react.useCallback(() => {
+        if (pageInfo?.hasNextPage === true) {
+            setVariables({
+                after: pageInfo.endCursor === null ? undefined : pageInfo.endCursor,
+                first: pageSize,
+            });
+        }
+    }, [pageInfo?.endCursor, pageInfo?.hasNextPage, pageSize]);
+    const previousPage = react.useCallback(() => {
+        if (pageInfo?.hasPreviousPage === true) {
+            setVariables({
+                before: pageInfo.startCursor === null ? undefined : pageInfo.startCursor,
+                last: pageSize,
+            });
+        }
+    }, [pageInfo?.hasPreviousPage, pageInfo?.startCursor, pageSize]);
+    const reset = react.useCallback(() => {
+        setVariables({
+            last: undefined,
+            before: undefined,
+            after: undefined,
+            first: pageSize,
+        });
+        if (onReset) {
+            onReset();
+        }
+    }, [onReset, pageSize, setVariables]);
+    return react.useMemo(() => {
+        return {
+            variables,
+            table: {
+                nextPage,
+                previousPage,
+                isLoading,
+                setIsLoading,
+                reset,
+                pageInfo: pageInfo === null ? undefined : pageInfo,
+                setPageInfo,
+            },
+        };
+    }, [variables, nextPage, previousPage, isLoading, reset, pageInfo]);
+};
+
 /**
  * Custom hook to handle window resize events and provide the current window size.
  *
@@ -3333,7 +3469,7 @@ const ListItemSkeleton = ({ hasThumbnail = DEFAULT_SKELETON_LIST_ITEM_PROPS.hasT
     return (jsxRuntime.jsxs("div", { className: cvaListItem$1({ className: "w-full" }), children: [jsxRuntime.jsxs("div", { className: cvaMainInformationClass({ hasThumbnail, className: "w-full" }), children: [hasThumbnail ? (jsxRuntime.jsx("div", { className: cvaThumbnailContainer({ className: "bg-gray-200" }), children: jsxRuntime.jsx("div", { className: tailwindMerge.twMerge("bg-gray-300", thumbnailShape === "circle" ? "rounded-full" : "rounded"), style: { width: 20, height: 20 } }) })) : null, jsxRuntime.jsxs("div", { className: "grid-rows-min-fr grid w-full items-center gap-1 text-sm", children: [jsxRuntime.jsx(SkeletonLines, { height: "0.875em", lines: 1, width: lineWidths.title }), hasDescription ? jsxRuntime.jsx(SkeletonLines, { height: "0.75em", lines: 1, width: lineWidths.description }) : null, hasMeta ? jsxRuntime.jsx(SkeletonLines, { height: "0.75em", lines: 1, width: lineWidths.meta }) : null] })] }), hasDetails ? (jsxRuntime.jsx("div", { className: "pl-2 text-sm", children: jsxRuntime.jsx(SkeletonLines, { height: "0.875em", lines: 1, width: lineWidths.details }) })) : null] }));
 };
 
-const cvaListContainer = cssClassVarianceUtilities.cvaMerge(["overflow-auto", "h-full"], {
+const cvaListContainer = cssClassVarianceUtilities.cvaMerge(["overflow-y-auto", "overflow-x-hidden", "h-full"], {
     variants: {
         withTopSeparator: {
             true: ["border-t", "border-neutral-200", "transition-colors duration-200 ease-in"],
@@ -3376,12 +3512,14 @@ const ListLoadingIndicator = ({ type, hasThumbnail, thumbnailShape, hasDescripti
     }
 };
 
-const DEFAULT_ROW_HEIGHT = 61; // 61px is the height of the ListItem component as of 2025-09-26
 /**
  * A performant virtualized list component with infinite scrolling support.
  *
  * ⚠️ **Important**: Requires a container with defined height to work properly.
  *
+ * **Usage Pattern**: Always use the `useList` hook in your component and spread the result into this component.
+ * This gives you access to the virtualizer state (scroll position, isScrolling, etc.) in the parent.
+ *
  * Features:
  * - Virtualized rendering using TanStack Virtual for performance with large datasets
  * - Automatic infinite scroll loading when approaching the end of the list
@@ -3390,24 +3528,143 @@ const DEFAULT_ROW_HEIGHT = 61; // 61px is the height of the ListItem component a
  * - Configurable loading indicators (skeleton, spinner, or custom)
  * - Scroll state detection and callbacks
  * - Variable-height item support via `estimateItemSize`
+ * - Dynamic measurement for accurate positioning of variable-height items
  *
  * The component automatically loads more data when:
  * - User scrolls to the last visible item
  * - Content height is insufficient to fill the container
+ *
+ * **Headers with Different Heights**: When using a header that differs in height from list items,
+ * provide `estimateHeaderSize` for optimal initial rendering. The list automatically measures
+ * actual heights on mount to ensure correct positioning.
+ *
+ * @example Basic usage
+ * ```tsx
+ * const list = useList({
+ *   count: items.length,
+ *   getItem: index => items[index],
+ *   estimateItemSize: () => 61,
+ * });
+ *
+ * return (
+ *   <List {...list}>
+ *     {({ key, listItemProps, item }) => (
+ *       <ListItem key={key} {...listItemProps} title={item?.name} />
+ *     )}
+ *   </List>
+ * );
+ * ```
+ * @example With header
+ * ```tsx
+ * const list = useList({
+ *   count: items.length,
+ *   getItem: index => items[index],
+ *   header: <KPI title="Total" value={42} />,
+ *   estimateHeaderSize: () => 72, // Actual KPI height
+ *   estimateItemSize: () => 61,   // Actual ListItem height
+ * });
+ *
+ * // Access virtualizer state in parent
+ * console.log('Scroll position:', list.scrollOffset);
+ * console.log('Is scrolling:', list.isScrolling);
+ *
+ * return (
+ *   <List {...list}>
+ *     {({ key, listItemProps, item }) => (
+ *       <ListItem key={key} {...listItemProps} title={item?.name} />
+ *     )}
+ *   </List>
+ * );
+ * ```
  */
-const List = ({ count, pagination, children, className, dataTestId, separator = "line", loadingIndicator = { type: "skeleton", ...DEFAULT_SKELETON_LIST_ITEM_PROPS }, onRowClick, onScrollStateChange, topSeparatorOnScroll = false, estimateItemSize, header, getItem, }) => {
-    const parentRef = react.useRef(null);
-    // Calculate the actual count including header
-    const actualCount = count + (header ? 1 : 0);
-    // Helper function to get item for a given data index
-    const getItemAtIndex = react.useCallback((dataIndex) => {
-        return getItem(dataIndex);
-    }, [getItem]);
+const List = ({ children, className, dataTestId, topSeparatorOnScroll = false, separator = "line", 
+// UseListResult properties
+containerRef, listRef, rows, getListItemProps, header, loadingIndicator, shouldShowLoaderAtIndex, count, isScrolling, scrollOffset, 
+// Unused but part of UseListResult interface
+getTotalSize: _getTotalSize, getVirtualItems: _getVirtualItems, scrollToOffset: _scrollToOffset, scrollToIndex: _scrollToIndex, measure: _measure, }) => {
+    return (jsxRuntime.jsx("div", { className: cvaListContainer({
+            withTopSeparator: topSeparatorOnScroll && (scrollOffset ?? 0) > 0,
+            className,
+        }), "data-is-scrolling": isScrolling, "data-testid": dataTestId, ref: containerRef, children: jsxRuntime.jsx("ul", { className: cvaList(), ref: listRef, children: rows.map(row => {
+                // Generate list item props with separator styling
+                const listItemProps = getListItemProps(row, {
+                    className: cvaListItem({ separator }),
+                });
+                const key = row.virtualRow.key;
+                // Render loading row
+                if (row.type === "loader") {
+                    const loadingConfig = loadingIndicator ?? {
+                        type: "skeleton",
+                        ...DEFAULT_SKELETON_LIST_ITEM_PROPS,
+                    };
+                    // Use the total data count from useList, not visible rows (which are virtualized)
+                    const hasHeaderRow = !!header;
+                    const dataStartIndex = hasHeaderRow ? 1 : 0;
+                    const totalDataRows = dataStartIndex + count;
+                    const loaderIndex = row.virtualRow.index - totalDataRows;
+                    const shouldShowLoader = shouldShowLoaderAtIndex(loaderIndex);
+                    return (jsxRuntime.jsx("li", { ...listItemProps, children: shouldShowLoader ? jsxRuntime.jsx(ListLoadingIndicator, { ...loadingConfig }) : null }, key));
+                }
+                // Render header row
+                if (row.type === "header") {
+                    return (jsxRuntime.jsx("li", { ...listItemProps, children: header }, key));
+                }
+                // Render data row
+                return children({ key, listItemProps, item: row.item, index: row.dataIndex });
+            }) }) }));
+};
+
+const DEFAULT_LOADING_INDICATOR_CONFIG = {
+    type: "skeleton",
+    initialLoadingCount: 10,
+    scrollLoadingCount: 3,
+};
+/**
+ * A hook for managing virtualized list state and behavior.
+ *
+ * This hook encapsulates the logic for:
+ * - Virtualizing list items using TanStack Virtual
+ * - Managing infinite scroll pagination
+ * - Handling header, data, and loading rows
+ * - Calculating proper indices and measurements
+ *
+ * @example
+ * ```tsx
+ * const list = useList({
+ *   count: items.length,
+ *   getItem: index => items[index],
+ *   pagination,
+ *   header: <KPI title="Total" value={42} />,
+ *   estimateHeaderSize: () => 72, // Measure actual KPI height
+ *   estimateItemSize: () => 61,   // Measure actual ListItem height
+ * });
+ *
+ * return (
+ *   <div ref={list.containerRef}>
+ *     <ul style={{ height: `${list.getTotalSize()}px` }}>
+ *       {list.rows.map(row => {
+ *         const props = list.getListItemProps(row, { className: 'list-item' });
+ *         return <li {...props}>{row.item?.title}</li>;
+ *       })}
+ *     </ul>
+ *   </div>
+ * );
+ * ```
+ */
+const useList = ({ count, pagination, header, getItem, loadingIndicator = DEFAULT_LOADING_INDICATOR_CONFIG, onRowClick, onChange, estimateItemSize, estimateHeaderSize, overscan, }) => {
+    const containerRef = react.useRef(null);
+    const listRef = react.useRef(null);
+    const rowRefsMap = react.useRef(new Map());
+    // Calculate total count including header
+    const hasHeader = Boolean(header);
+    const dataStartIndex = hasHeader ? 1 : 0;
+    const dataCount = count;
+    const totalDataRows = dataStartIndex + dataCount;
     // Calculate how many loading rows we need
     const getLoadingRowsCount = react.useCallback(() => {
-        const { type: loadingIndicatorType } = loadingIndicator;
         if (pagination?.isLoading === false)
             return 0;
+        const { type: loadingIndicatorType } = loadingIndicator;
         switch (loadingIndicatorType) {
             case "none":
                 return 0;
@@ -3424,64 +3681,210 @@ const List = ({ count, pagination, children, className, dataTestId, separator =
                 throw new Error(`${loadingIndicatorType} is not known`);
             }
         }
-    }, [loadingIndicator, pagination]);
+    }, [loadingIndicator, pagination?.isLoading, pagination?.pageInfo]);
+    // Helper to determine if a specific loader index should be shown
+    const shouldShowLoaderAtIndex = react.useCallback((loaderIndex) => {
+        if (pagination?.isLoading === false)
+            return false;
+        const { type: loadingIndicatorType } = loadingIndicator;
+        let result;
+        switch (loadingIndicatorType) {
+            case "none":
+                result = false;
+                break;
+            case "spinner":
+                result = loaderIndex === 0;
+                break;
+            case "custom":
+            case "skeleton": {
+                const isInitialLoading = !pagination?.pageInfo;
+                const initialCount = loadingIndicator.initialLoadingCount ?? 10;
+                const scrollCount = loadingIndicator.scrollLoadingCount ?? 3;
+                const maxCount = isInitialLoading ? initialCount : scrollCount;
+                result = loaderIndex < maxCount;
+                break;
+            }
+            default: {
+                throw new Error(`${loadingIndicatorType} is not known`);
+            }
+        }
+        return result;
+    }, [loadingIndicator, pagination?.isLoading, pagination?.pageInfo]);
+    const totalRowCount = react.useMemo(() => {
+        // Only add the exact number of loading rows we want to show
+        const loadingRows = pagination?.isLoading === true ? getLoadingRowsCount() : 0;
+        const total = totalDataRows + loadingRows;
+        return total;
+    }, [totalDataRows, pagination?.isLoading, getLoadingRowsCount]);
+    // Estimate size for all rows (header, data, loading)
     const estimateSize = react.useCallback((index) => {
-        // Check if this is a loading row
-        if (index >= actualCount) {
-            const loaderIndex = index - actualCount;
-            const shouldShowLoader = pagination?.isLoading === true && loaderIndex < getLoadingRowsCount();
+        // Loading rows
+        if (index >= totalDataRows) {
+            const loaderIndex = index - totalDataRows;
+            const shouldShowLoader = shouldShowLoaderAtIndex(loaderIndex);
+            const estimatedHeight = shouldShowLoader ? estimateItemSize(0) : 0;
             // Empty loader rows should be estimated at 0 height to prevent blank space
-            return shouldShowLoader ? DEFAULT_ROW_HEIGHT : 0;
+            return estimatedHeight;
         }
-        // For data rows (including header), use custom estimator if provided
-        return estimateItemSize ? estimateItemSize(index) : DEFAULT_ROW_HEIGHT;
-    }, [estimateItemSize, actualCount, pagination?.isLoading, getLoadingRowsCount]);
-    const { getVirtualItems, getTotalSize, measureElement, scrollOffset } = reactTablePagination.useInfiniteScroll({
-        pagination: pagination || reactTablePagination.noPagination,
-        containerRef: parentRef,
-        count: actualCount + (pagination?.isLoading === true ? getLoadingRowsCount() : 0),
+        // Header row (if exists, it's always at index 0)
+        if (hasHeader && index === 0) {
+            // Use dedicated header size estimate if provided, otherwise fall back to first item estimate
+            return estimateHeaderSize ? estimateHeaderSize() : estimateItemSize(0);
+        }
+        // Data rows - calculate the data index
+        const dataIndex = index - dataStartIndex;
+        return estimateItemSize(dataIndex);
+    }, [estimateItemSize, estimateHeaderSize, totalDataRows, shouldShowLoaderAtIndex, hasHeader, dataStartIndex]);
+    // Set up virtualization
+    const virtualizer = useInfiniteScroll({
+        pagination: pagination ?? noPagination,
+        scrollElementRef: containerRef,
+        count: totalRowCount,
         estimateSize,
-        onChange: virtualizer => onScrollStateChange?.(virtualizer.scrollOffset ?? 0, virtualizer.isScrolling),
+        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);
+        },
     });
-    const isAtTop = scrollOffset <= 0;
-    return (jsxRuntime.jsx("div", { className: cvaListContainer({
-            withTopSeparator: topSeparatorOnScroll && !isAtTop,
-            className,
-        }), "data-testid": dataTestId, ref: parentRef, children: jsxRuntime.jsx("ul", { className: cvaList(), style: { height: `${getTotalSize()}px` }, children: getVirtualItems().map(virtualRow => {
-                const isLoaderRow = virtualRow.index >= actualCount;
-                const isHeaderRow = Boolean(header) && virtualRow.index === 0;
-                // Calculate data index: if header exists, subtract 1 from index for data items
-                const dataIndex = Boolean(header) && !isHeaderRow ? virtualRow.index - 1 : virtualRow.index;
-                // Calculate which loading indicator this is (for multiple loading indicators)
-                const loaderIndex = isLoaderRow ? virtualRow.index - actualCount : 0;
-                // Props required by the virtualizer for proper positioning and behavior
-                const listItemProps = {
-                    className: cvaListItem({ separator }), // List styling (separators, spacing)
-                    "data-index": isLoaderRow || isHeaderRow ? virtualRow.index : dataIndex, // For accessibility and debugging
-                    onClick: onRowClick && !isLoaderRow && !isHeaderRow
-                        ? () => {
-                            const clickedItem = getItemAtIndex(dataIndex);
-                            onRowClick(clickedItem, dataIndex);
-                        }
-                        : undefined, // Row-level click handling (skip header)
-                    ref: measureElement, // Required for virtualizer to measure item dimensions
-                    style: {
-                        transform: `translateY(${virtualRow.start}px)`, // Critical: positions item in virtual scroll
-                    },
-                    tabIndex: -1, // Keyboard navigation support
+    // Measure the list on mount
+    react.useLayoutEffect(() => {
+        // Automatically measure if header is present, or if explicitly requested
+        virtualizer.measure();
+        // This is straight out of the TanStack Virtual docs, so we'll trust it.
+        // eslint-disable-next-line react-hooks/react-compiler
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Transform virtual items into typed rows
+    const rows = react.useMemo(() => {
+        const virtualItems = virtualizer.getVirtualItems();
+        return virtualItems.map((virtualRow) => {
+            const { index } = virtualRow;
+            // Determine row type
+            const isLoaderRow = index >= totalDataRows;
+            const isHeaderRow = hasHeader && index === 0;
+            if (isLoaderRow) {
+                return {
+                    type: "loader",
+                    virtualRow,
+                    dataIndex: -1,
                 };
-                // Handle loading rows
-                if (isLoaderRow) {
-                    return (jsxRuntime.jsx("li", { ...listItemProps, children: pagination?.isLoading === true && loaderIndex < getLoadingRowsCount() ? (jsxRuntime.jsx(ListLoadingIndicator, { ...loadingIndicator })) : null }, virtualRow.index));
-                }
-                // Handle header row
-                if (isHeaderRow && header) {
-                    return (jsxRuntime.jsx("li", { ...listItemProps, children: header }, "header"));
+            }
+            if (isHeaderRow) {
+                return {
+                    type: "header",
+                    virtualRow,
+                    dataIndex: -1,
+                };
+            }
+            // Data row
+            const dataIndex = index - dataStartIndex;
+            const item = getItem(dataIndex);
+            return {
+                type: "data",
+                virtualRow,
+                item,
+                dataIndex,
+            };
+        });
+        // Call getVirtualItems() fresh each time to get updated measurements after virtualizer state changes
+    }, [virtualizer, totalDataRows, hasHeader, dataStartIndex, getItem]);
+    // Helper to create list item props
+    const getListItemProps = react.useCallback((row, options) => {
+        const { type, item, dataIndex } = row;
+        // Handle click for data rows
+        const handleClick = type === "data" && onRowClick && item !== undefined
+            ? () => {
+                onRowClick({ item, index: dataIndex });
+            }
+            : undefined;
+        const onClick = handleClick ?? options.onClick;
+        return {
+            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)`;
+                    }
                 }
-                // For regular children, call the children function with virtualization props and item data
-                const item = getItemAtIndex(dataIndex);
-                return children(listItemProps, item, dataIndex);
-            }) }) }));
+            },
+            tabIndex: -1,
+        };
+    }, [onRowClick, virtualizer]);
+    return {
+        ...virtualizer,
+        containerRef,
+        listRef,
+        rows,
+        getListItemProps,
+        header,
+        loadingIndicator,
+        shouldShowLoaderAtIndex,
+        count,
+    };
+};
+
+// Height constants (in pixels) - based on ListItem.variants.ts styling
+const MIN_ITEM_HEIGHT = 56; // min-h-14 = 56px (minimum height for ListItem)
+const VERTICAL_PADDING = 12 + 12; // py-3 = 12px top + 12px bottom = 24px
+const TITLE_LINE_HEIGHT = 20;
+const DESCRIPTION_LINE_HEIGHT = 16;
+const META_LINE_HEIGHT = 16 + 2; // 2px padding above meta line
+/**
+ * Hook that provides a memoized getListItemHeight function.
+ *
+ * Calculates the estimated height of a ListItem based on its configuration.
+ * This function adds up the heights of each visible line plus gaps between them.
+ * Height values are placeholders and need to be measured in browser DevTools.
+ *
+ * @returns {object} An object containing the memoized getListItemHeight function
+ * @example
+ * ```tsx
+ * const { getListItemHeight } = useListItemHeight();
+ *
+ * const estimateItemSize = () => getListItemHeight({
+ *   hasThumbnail: true,
+ *   hasDescription: true,
+ * });
+ * ```
+ */
+const useListItemHeight = () => {
+    const getListItemHeight = react.useCallback(({ hasThumbnail: _hasThumbnail = false, // does not affect height
+    hasDescription = false, hasMeta = false, hasDetails: _hasDetails = false, // does not affect height
+     }) => {
+        // Calculate content height (excluding padding)
+        let contentHeight = TITLE_LINE_HEIGHT;
+        // Add description line if present
+        if (hasDescription) {
+            contentHeight += DESCRIPTION_LINE_HEIGHT;
+        }
+        // Add meta line if present
+        if (hasMeta) {
+            contentHeight += META_LINE_HEIGHT;
+        }
+        // Add vertical padding
+        const totalHeight = contentHeight + VERTICAL_PADDING;
+        // Return the larger of calculated height or minimum height
+        return Math.max(totalHeight, MIN_ITEM_HEIGHT);
+    }, []);
+    return {
+        getListItemHeight,
+    };
 };
 
 /**
@@ -4842,12 +5245,14 @@ exports.cvaToggleItemContent = cvaToggleItemContent;
 exports.cvaToggleItemText = cvaToggleItemText;
 exports.cvaZStackContainer = cvaZStackContainer;
 exports.cvaZStackItem = cvaZStackItem;
+exports.defaultPageSize = defaultPageSize;
 exports.docs = docs;
 exports.getDevicePixelRatio = getDevicePixelRatio;
 exports.getResponsiveRandomWidthPercentage = getResponsiveRandomWidthPercentage;
 exports.getValueBarColorByValue = getValueBarColorByValue;
 exports.iconColorNames = iconColorNames;
 exports.iconPalette = iconPalette;
+exports.noPagination = noPagination;
 exports.useClickOutside = useClickOutside;
 exports.useContainerBreakpoints = useContainerBreakpoints;
 exports.useContinuousTimeout = useContinuousTimeout;
@@ -4857,13 +5262,17 @@ exports.useElevatedReducer = useElevatedReducer;
 exports.useElevatedState = useElevatedState;
 exports.useGeometry = useGeometry;
 exports.useHover = useHover;
+exports.useInfiniteScroll = useInfiniteScroll;
 exports.useIsFirstRender = useIsFirstRender;
 exports.useIsFullscreen = useIsFullscreen;
 exports.useIsTextTruncated = useIsTextTruncated;
+exports.useList = useList;
+exports.useListItemHeight = useListItemHeight;
 exports.useModifierKey = useModifierKey;
 exports.useOverflowItems = useOverflowItems;
 exports.usePopoverContext = usePopoverContext;
 exports.usePrompt = usePrompt;
+exports.useRelayPagination = useRelayPagination;
 exports.useResize = useResize;
 exports.useScrollDetection = useScrollDetection;
 exports.useSelfUpdatingRef = useSelfUpdatingRef;