@trackunit/react-components 1.17.49 → 1.18.1

package/index.cjs.js

@@ -2208,7 +2208,7 @@ const Collapse = ({ id, variant = "primary", initialExpanded = false, onToggle,
         }
         setExpanded(!expanded);
     }, [expanded, onToggle]);
-    return (jsxRuntime.jsxs("div", { className: cvaCollapse({ variant: variant, className }), "data-testid": dataTestId, ref: ref, children: [jsxRuntime.jsx("div", { "aria-controls": id, "aria-expanded": expanded, className: cvaCollapseHeader({ expanded, variant, extraPadding, className: headerClassName }), onClick: handleClick, role: "button", children: jsxRuntime.jsxs("div", { className: cvaCollapseLabelContainer({ variant }), children: [jsxRuntime.jsx(Text, { className: cvaCollapseLabel({ variant }), id: LABEL_ID, size: variant === "secondary" ? "small" : "medium", type: "span", weight: "bold", children: label }), jsxRuntime.jsxs("div", { className: "flex items-center gap-2", children: [headerAddon !== null && headerAddon !== undefined && variant !== "secondary" ? headerAddon : null, jsxRuntime.jsx(Icon, { ariaLabelledBy: LABEL_ID, className: cvaChevronIcon({ expanded }), name: "ChevronUp", size: variant === "secondary" ? "small" : "medium" })] })] }) }), jsxRuntime.jsx(Collapsible, { expanded: expanded, extraPadding: extraPadding, id: id, variant: variant, children: expanded || animate ? children : null })] }));
+    return (jsxRuntime.jsxs("div", { className: cvaCollapse({ variant: variant, className }), "data-testid": dataTestId, ref: ref, children: [jsxRuntime.jsx("div", { "aria-controls": id, "aria-expanded": expanded, className: cvaCollapseHeader({ expanded, variant, extraPadding, className: headerClassName }), onClick: handleClick, role: "button", children: jsxRuntime.jsxs("div", { className: cvaCollapseLabelContainer({ variant }), children: [jsxRuntime.jsx(Text, { className: cvaCollapseLabel({ variant }), id: LABEL_ID, size: variant === "secondary" ? "small" : "medium", type: "span", weight: "bold", children: label }), jsxRuntime.jsxs("div", { className: "flex items-center gap-2", children: [headerAddon !== null && headerAddon !== undefined && variant !== "secondary" ? headerAddon : null, jsxRuntime.jsx(Icon, { ariaLabelledBy: LABEL_ID, className: cvaChevronIcon({ expanded }), name: "ChevronDown", size: variant === "secondary" ? "small" : "medium" })] })] }) }), jsxRuntime.jsx(Collapsible, { expanded: expanded, extraPadding: extraPadding, id: id, variant: variant, children: expanded || animate ? children : null })] }));
 };
 const Collapsible = ({ children, expanded, id, variant, extraPadding }) => {
     const { geometry, ref } = useMeasure();
@@ -5534,8 +5534,8 @@ const noPagination = {
     },
 };
 
-const OVERSCAN = 10;
-const DEFAULT_ROW_HEIGHT = 50;
+const OVERSCAN$1 = 10;
+const DEFAULT_ROW_HEIGHT$1 = 50;
 /**
  * Custom hook for implementing infinite scrolling in a table using TanStack Virtual.
  *
@@ -5565,14 +5565,14 @@ const useInfiniteScroll = ({ pagination, scrollElementRef, count, estimateSize,
     const handleChange = react.useCallback((virtualizer) => {
         onChange?.(virtualizer);
     }, [onChange]);
-    const handleEstimateSize = react.useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT, [estimateSize]);
+    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-disable-next-line react-hooks/incompatible-library
     const rowVirtualizer = reactVirtual.useVirtualizer({
         count,
         getScrollElement: () => scrollElementRef.current,
         estimateSize: handleEstimateSize,
-        overscan: overscan ?? OVERSCAN,
+        overscan: overscan ?? OVERSCAN$1,
         onChange: handleChange,
         // 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
@@ -8415,6 +8415,111 @@ const useLocalStorageReducer = ({ key, defaultState, reducer, schema, onValidati
     return [state, dispatch];
 };
 
+const OVERSCAN = 10;
+const DEFAULT_ROW_HEIGHT = 50;
+/**
+ * Bidirectional infinite scroll hook that supports both forward (nextPage)
+ * and backward (previousPage) pagination with TanStack Virtual.
+ *
+ * Unlike `useInfiniteScroll` which only loads forward, this hook detects
+ * 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 onTopItemChangeRef = react.useRef(onTopItemChange);
+    react.useEffect(() => {
+        onTopItemChangeRef.current = onTopItemChange;
+    }, [onTopItemChange]);
+    const lastReportedTopIndex = react.useRef(-1);
+    const handleChange = react.useCallback((virtualizer) => {
+        onChange?.(virtualizer);
+        const scrollOffset = virtualizer.scrollOffset ?? 0;
+        const firstVisibleItem = virtualizer.getVirtualItems().find(item => item.start + item.size > scrollOffset);
+        if (firstVisibleItem !== undefined && firstVisibleItem.index !== lastReportedTopIndex.current) {
+            lastReportedTopIndex.current = firstVisibleItem.index;
+            onTopItemChangeRef.current?.(firstVisibleItem.index);
+        }
+    }, [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-disable-next-line react-hooks/incompatible-library
+    const rowVirtualizer = reactVirtual.useVirtualizer({
+        count,
+        getScrollElement: () => scrollElementRef.current,
+        estimateSize: handleEstimateSize,
+        overscan: overscan ?? OVERSCAN,
+        onChange: handleChange,
+        useAnimationFrameWithResizeObserver: true,
+    });
+    const virtualItems = rowVirtualizer.getVirtualItems();
+    // Track count before backward fetch so we can offset scroll position
+    // after items are prepended, preventing an infinite backward-load loop.
+    const prevCountRef = react.useRef(count);
+    const isLoadingBackwardRef = react.useRef(false);
+    react.useEffect(() => {
+        if (isLoadingBackwardRef.current && !pagination.isLoading && count > prevCountRef.current) {
+            const prependedCount = count - prevCountRef.current;
+            const container = scrollElementRef.current;
+            if (container) {
+                const estimatedRowHeight = estimateSize?.(0) ?? DEFAULT_ROW_HEIGHT;
+                container.scrollTop += prependedCount * estimatedRowHeight;
+            }
+            isLoadingBackwardRef.current = false;
+        }
+        prevCountRef.current = count;
+    }, [count, pagination.isLoading, scrollElementRef, estimateSize]);
+    // Forward loading: scroll reached bottom or insufficient content
+    react.useEffect(() => {
+        if (skip || pagination.pageInfo?.hasNextPage !== true || pagination.isLoading) {
+            return;
+        }
+        const container = scrollElementRef.current;
+        if (!container) {
+            return;
+        }
+        const [lastItem] = [...virtualItems].reverse();
+        const shouldLoadFromScroll = lastItem !== undefined && lastItem.index >= count - 1;
+        const shouldLoadFromInsufficientContent = container.scrollHeight <= container.clientHeight;
+        if (shouldLoadFromScroll || shouldLoadFromInsufficientContent) {
+            pagination.nextPage();
+        }
+    }, [
+        skip,
+        pagination.pageInfo?.hasNextPage,
+        pagination.nextPage,
+        pagination.isLoading,
+        pagination,
+        scrollElementRef,
+        virtualItems,
+        count,
+    ]);
+    // Backward loading: fires when the scroll container is at the very top.
+    // Uses scrollTop instead of virtualItems[0].index because after data
+    // prepends the scroll-offset effect adjusts scrollTop away from 0,
+    // which correctly prevents re-triggering. virtualItems[0].index would
+    // still be 0 (overscan always renders from the start) causing a loop.
+    react.useEffect(() => {
+        if (skip || pagination.pageInfo?.hasPreviousPage !== true || pagination.isLoading) {
+            return;
+        }
+        const container = scrollElementRef.current;
+        if (container !== null && container.scrollTop === 0) {
+            isLoadingBackwardRef.current = true;
+            pagination.previousPage();
+        }
+    }, [
+        skip,
+        pagination.pageInfo?.hasPreviousPage,
+        pagination.previousPage,
+        pagination.isLoading,
+        pagination,
+        scrollElementRef,
+        virtualItems,
+    ]);
+    return rowVirtualizer;
+};
+
 /**
  * Custom hook to handle click outside events.
  *
@@ -8603,6 +8708,53 @@ const useContinuousTimeout = ({ onTimeout, onMaxRetries, duration, maxRetries, }
     }), [startTimeouts, stopTimeouts, isRunning]);
 };
 
+const DEFAULT_PARAM_NAME = "cursor";
+const DEFAULT_DEBOUNCE_MS = 300;
+/**
+ * Reads a cursor from the URL search params on mount and provides a debounced
+ * updater for writing it back. Uses `replace: true` to avoid polluting browser
+ * history with every scroll position change.
+ *
+ * Wire `initialCursor` into `usePaginationQuery` and `updateCursor` into
+ * `useBidirectionalScroll`'s `onTopItemChange` callback (mapping index to cursor).
+ */
+const useCursorUrlSync = ({ paramName = DEFAULT_PARAM_NAME, debounceMs = DEFAULT_DEBOUNCE_MS, } = {}) => {
+    const search = reactRouter.useSearch({ strict: false });
+    const navigate = reactRouter.useNavigate();
+    const [initialCursor] = react.useState(() => {
+        const entry = Object.entries(search).find(([key]) => key === paramName);
+        return typeof entry?.[1] === "string" ? entry[1] : undefined;
+    });
+    const timerRef = react.useRef(undefined);
+    const paramNameRef = react.useRef(paramName);
+    react.useEffect(() => {
+        paramNameRef.current = paramName;
+    }, [paramName]);
+    const updateCursor = react.useCallback((cursor) => {
+        if (timerRef.current !== undefined) {
+            clearTimeout(timerRef.current);
+        }
+        timerRef.current = setTimeout(() => {
+            void navigate({
+                to: ".",
+                search: (prev) => ({
+                    ...prev,
+                    [paramNameRef.current]: cursor,
+                }),
+                replace: true,
+            });
+        }, debounceMs);
+    }, [debounceMs, navigate]);
+    react.useEffect(() => {
+        return () => {
+            if (timerRef.current !== undefined) {
+                clearTimeout(timerRef.current);
+            }
+        };
+    }, []);
+    return react.useMemo(() => ({ initialCursor, updateCursor }), [initialCursor, updateCursor]);
+};
+
 // Copied from https://github.com/rexxars/use-device-pixel-ratio
 /**
  * Get the device pixel ratio, potentially rounded and capped.
@@ -9263,9 +9415,12 @@ const defaultPageSize = 50;
  * @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 useRelayPagination = ({ onReset, pageSize, initialCursor } = { pageSize: defaultPageSize }) => {
+    const [variables, setVariables] = react.useState(() => ({
+        first: pageSize,
+        after: initialCursor,
+    }));
+    const [pageInfo, setPageInfo] = react.useState(() => initialCursor !== undefined ? { hasPreviousPage: true } : null);
     const [isLoading, setIsLoading] = react.useState(true);
     // Destructure pageInfo properties early to avoid depending on the entire object
     const { hasNextPage, endCursor, hasPreviousPage, startCursor } = pageInfo ?? {};
@@ -9725,10 +9880,12 @@ exports.iconColorNames = iconColorNames;
 exports.iconPalette = iconPalette;
 exports.noPagination = noPagination;
 exports.preferenceCardGrid = preferenceCardGrid;
+exports.useBidirectionalScroll = useBidirectionalScroll;
 exports.useClickOutside = useClickOutside;
 exports.useContainerBreakpoints = useContainerBreakpoints;
 exports.useContinuousTimeout = useContinuousTimeout;
 exports.useCopyToClipboard = useCopyToClipboard;
+exports.useCursorUrlSync = useCursorUrlSync;
 exports.useCustomEncoding = useCustomEncoding;
 exports.useDebounce = useDebounce;
 exports.useDevicePixelRatio = useDevicePixelRatio;

package/index.esm.js

@@ -10,7 +10,7 @@ import IconSpriteSolid from '@trackunit/ui-icons/icons-sprite-solid.svg';
 import { snakeCase, titleCase } from 'string-ts';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { Slot, Slottable } from '@radix-ui/react-slot';
-import { Link, useBlocker } from '@tanstack/react-router';
+import { Link, useBlocker, useSearch, useNavigate } from '@tanstack/react-router';
 import { isEqual, omit } from 'es-toolkit';
 import { twMerge } from 'tailwind-merge';
 import { useFloating, offset, flip, shift, size, autoUpdate, useClick, useDismiss, useHover as useHover$1, safePolygon, useRole, useInteractions, FloatingPortal, useMergeRefs as useMergeRefs$1, FloatingFocusManager, arrow, useTransitionStatus, FloatingArrow } from '@floating-ui/react';
@@ -2206,7 +2206,7 @@ const Collapse = ({ id, variant = "primary", initialExpanded = false, onToggle,
         }
         setExpanded(!expanded);
     }, [expanded, onToggle]);
-    return (jsxs("div", { className: cvaCollapse({ variant: variant, className }), "data-testid": dataTestId, ref: ref, children: [jsx("div", { "aria-controls": id, "aria-expanded": expanded, className: cvaCollapseHeader({ expanded, variant, extraPadding, className: headerClassName }), onClick: handleClick, role: "button", children: jsxs("div", { className: cvaCollapseLabelContainer({ variant }), children: [jsx(Text, { className: cvaCollapseLabel({ variant }), id: LABEL_ID, size: variant === "secondary" ? "small" : "medium", type: "span", weight: "bold", children: label }), jsxs("div", { className: "flex items-center gap-2", children: [headerAddon !== null && headerAddon !== undefined && variant !== "secondary" ? headerAddon : null, jsx(Icon, { ariaLabelledBy: LABEL_ID, className: cvaChevronIcon({ expanded }), name: "ChevronUp", size: variant === "secondary" ? "small" : "medium" })] })] }) }), jsx(Collapsible, { expanded: expanded, extraPadding: extraPadding, id: id, variant: variant, children: expanded || animate ? children : null })] }));
+    return (jsxs("div", { className: cvaCollapse({ variant: variant, className }), "data-testid": dataTestId, ref: ref, children: [jsx("div", { "aria-controls": id, "aria-expanded": expanded, className: cvaCollapseHeader({ expanded, variant, extraPadding, className: headerClassName }), onClick: handleClick, role: "button", children: jsxs("div", { className: cvaCollapseLabelContainer({ variant }), children: [jsx(Text, { className: cvaCollapseLabel({ variant }), id: LABEL_ID, size: variant === "secondary" ? "small" : "medium", type: "span", weight: "bold", children: label }), jsxs("div", { className: "flex items-center gap-2", children: [headerAddon !== null && headerAddon !== undefined && variant !== "secondary" ? headerAddon : null, jsx(Icon, { ariaLabelledBy: LABEL_ID, className: cvaChevronIcon({ expanded }), name: "ChevronDown", size: variant === "secondary" ? "small" : "medium" })] })] }) }), jsx(Collapsible, { expanded: expanded, extraPadding: extraPadding, id: id, variant: variant, children: expanded || animate ? children : null })] }));
 };
 const Collapsible = ({ children, expanded, id, variant, extraPadding }) => {
     const { geometry, ref } = useMeasure();
@@ -5532,8 +5532,8 @@ const noPagination = {
     },
 };
 
-const OVERSCAN = 10;
-const DEFAULT_ROW_HEIGHT = 50;
+const OVERSCAN$1 = 10;
+const DEFAULT_ROW_HEIGHT$1 = 50;
 /**
  * Custom hook for implementing infinite scrolling in a table using TanStack Virtual.
  *
@@ -5563,14 +5563,14 @@ const useInfiniteScroll = ({ pagination, scrollElementRef, count, estimateSize,
     const handleChange = useCallback((virtualizer) => {
         onChange?.(virtualizer);
     }, [onChange]);
-    const handleEstimateSize = useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT, [estimateSize]);
+    const handleEstimateSize = useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT$1, [estimateSize]);
     //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
     // eslint-disable-next-line react-hooks/incompatible-library
     const rowVirtualizer = useVirtualizer({
         count,
         getScrollElement: () => scrollElementRef.current,
         estimateSize: handleEstimateSize,
-        overscan: overscan ?? OVERSCAN,
+        overscan: overscan ?? OVERSCAN$1,
         onChange: handleChange,
         // 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
@@ -8413,6 +8413,111 @@ const useLocalStorageReducer = ({ key, defaultState, reducer, schema, onValidati
     return [state, dispatch];
 };
 
+const OVERSCAN = 10;
+const DEFAULT_ROW_HEIGHT = 50;
+/**
+ * Bidirectional infinite scroll hook that supports both forward (nextPage)
+ * and backward (previousPage) pagination with TanStack Virtual.
+ *
+ * Unlike `useInfiniteScroll` which only loads forward, this hook detects
+ * 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 onTopItemChangeRef = useRef(onTopItemChange);
+    useEffect(() => {
+        onTopItemChangeRef.current = onTopItemChange;
+    }, [onTopItemChange]);
+    const lastReportedTopIndex = useRef(-1);
+    const handleChange = useCallback((virtualizer) => {
+        onChange?.(virtualizer);
+        const scrollOffset = virtualizer.scrollOffset ?? 0;
+        const firstVisibleItem = virtualizer.getVirtualItems().find(item => item.start + item.size > scrollOffset);
+        if (firstVisibleItem !== undefined && firstVisibleItem.index !== lastReportedTopIndex.current) {
+            lastReportedTopIndex.current = firstVisibleItem.index;
+            onTopItemChangeRef.current?.(firstVisibleItem.index);
+        }
+    }, [onChange]);
+    const handleEstimateSize = useCallback((index) => estimateSize?.(index) ?? DEFAULT_ROW_HEIGHT, [estimateSize]);
+    //! TODO: remove this once Tanstack Virtual is updated to support React Compiler
+    // eslint-disable-next-line react-hooks/incompatible-library
+    const rowVirtualizer = useVirtualizer({
+        count,
+        getScrollElement: () => scrollElementRef.current,
+        estimateSize: handleEstimateSize,
+        overscan: overscan ?? OVERSCAN,
+        onChange: handleChange,
+        useAnimationFrameWithResizeObserver: true,
+    });
+    const virtualItems = rowVirtualizer.getVirtualItems();
+    // Track count before backward fetch so we can offset scroll position
+    // after items are prepended, preventing an infinite backward-load loop.
+    const prevCountRef = useRef(count);
+    const isLoadingBackwardRef = useRef(false);
+    useEffect(() => {
+        if (isLoadingBackwardRef.current && !pagination.isLoading && count > prevCountRef.current) {
+            const prependedCount = count - prevCountRef.current;
+            const container = scrollElementRef.current;
+            if (container) {
+                const estimatedRowHeight = estimateSize?.(0) ?? DEFAULT_ROW_HEIGHT;
+                container.scrollTop += prependedCount * estimatedRowHeight;
+            }
+            isLoadingBackwardRef.current = false;
+        }
+        prevCountRef.current = count;
+    }, [count, pagination.isLoading, scrollElementRef, estimateSize]);
+    // Forward loading: scroll reached bottom or insufficient content
+    useEffect(() => {
+        if (skip || pagination.pageInfo?.hasNextPage !== true || pagination.isLoading) {
+            return;
+        }
+        const container = scrollElementRef.current;
+        if (!container) {
+            return;
+        }
+        const [lastItem] = [...virtualItems].reverse();
+        const shouldLoadFromScroll = lastItem !== undefined && lastItem.index >= count - 1;
+        const shouldLoadFromInsufficientContent = container.scrollHeight <= container.clientHeight;
+        if (shouldLoadFromScroll || shouldLoadFromInsufficientContent) {
+            pagination.nextPage();
+        }
+    }, [
+        skip,
+        pagination.pageInfo?.hasNextPage,
+        pagination.nextPage,
+        pagination.isLoading,
+        pagination,
+        scrollElementRef,
+        virtualItems,
+        count,
+    ]);
+    // Backward loading: fires when the scroll container is at the very top.
+    // Uses scrollTop instead of virtualItems[0].index because after data
+    // prepends the scroll-offset effect adjusts scrollTop away from 0,
+    // which correctly prevents re-triggering. virtualItems[0].index would
+    // still be 0 (overscan always renders from the start) causing a loop.
+    useEffect(() => {
+        if (skip || pagination.pageInfo?.hasPreviousPage !== true || pagination.isLoading) {
+            return;
+        }
+        const container = scrollElementRef.current;
+        if (container !== null && container.scrollTop === 0) {
+            isLoadingBackwardRef.current = true;
+            pagination.previousPage();
+        }
+    }, [
+        skip,
+        pagination.pageInfo?.hasPreviousPage,
+        pagination.previousPage,
+        pagination.isLoading,
+        pagination,
+        scrollElementRef,
+        virtualItems,
+    ]);
+    return rowVirtualizer;
+};
+
 /**
  * Custom hook to handle click outside events.
  *
@@ -8601,6 +8706,53 @@ const useContinuousTimeout = ({ onTimeout, onMaxRetries, duration, maxRetries, }
     }), [startTimeouts, stopTimeouts, isRunning]);
 };
 
+const DEFAULT_PARAM_NAME = "cursor";
+const DEFAULT_DEBOUNCE_MS = 300;
+/**
+ * Reads a cursor from the URL search params on mount and provides a debounced
+ * updater for writing it back. Uses `replace: true` to avoid polluting browser
+ * history with every scroll position change.
+ *
+ * Wire `initialCursor` into `usePaginationQuery` and `updateCursor` into
+ * `useBidirectionalScroll`'s `onTopItemChange` callback (mapping index to cursor).
+ */
+const useCursorUrlSync = ({ paramName = DEFAULT_PARAM_NAME, debounceMs = DEFAULT_DEBOUNCE_MS, } = {}) => {
+    const search = useSearch({ strict: false });
+    const navigate = useNavigate();
+    const [initialCursor] = useState(() => {
+        const entry = Object.entries(search).find(([key]) => key === paramName);
+        return typeof entry?.[1] === "string" ? entry[1] : undefined;
+    });
+    const timerRef = useRef(undefined);
+    const paramNameRef = useRef(paramName);
+    useEffect(() => {
+        paramNameRef.current = paramName;
+    }, [paramName]);
+    const updateCursor = useCallback((cursor) => {
+        if (timerRef.current !== undefined) {
+            clearTimeout(timerRef.current);
+        }
+        timerRef.current = setTimeout(() => {
+            void navigate({
+                to: ".",
+                search: (prev) => ({
+                    ...prev,
+                    [paramNameRef.current]: cursor,
+                }),
+                replace: true,
+            });
+        }, debounceMs);
+    }, [debounceMs, navigate]);
+    useEffect(() => {
+        return () => {
+            if (timerRef.current !== undefined) {
+                clearTimeout(timerRef.current);
+            }
+        };
+    }, []);
+    return useMemo(() => ({ initialCursor, updateCursor }), [initialCursor, updateCursor]);
+};
+
 // Copied from https://github.com/rexxars/use-device-pixel-ratio
 /**
  * Get the device pixel ratio, potentially rounded and capped.
@@ -9261,9 +9413,12 @@ const defaultPageSize = 50;
  * @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] = useState({ first: pageSize });
-    const [pageInfo, setPageInfo] = useState();
+const useRelayPagination = ({ onReset, pageSize, initialCursor } = { pageSize: defaultPageSize }) => {
+    const [variables, setVariables] = useState(() => ({
+        first: pageSize,
+        after: initialCursor,
+    }));
+    const [pageInfo, setPageInfo] = useState(() => initialCursor !== undefined ? { hasPreviousPage: true } : null);
     const [isLoading, setIsLoading] = useState(true);
     // Destructure pageInfo properties early to avoid depending on the entire object
     const { hasNextPage, endCursor, hasPreviousPage, startCursor } = pageInfo ?? {};
@@ -9595,4 +9750,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
     return useMemo(() => ({ focused }), [focused]);
 };
 
-export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, SegmentedValueBar, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGeolocation, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };
+export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, SegmentedValueBar, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGeolocation, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.17.49",
+  "version": "1.18.1",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/hooks/useBidirectionalScroll.d.ts

@@ -0,0 +1,23 @@
+import { type Virtualizer } from "@tanstack/react-virtual";
+import { type RefObject } from "react";
+import type { RelayPagination } from "./useRelayPagination";
+interface BidirectionalScrollProps<TScrollElement extends Element, TItemElement extends Element> {
+    readonly pagination: RelayPagination;
+    readonly scrollElementRef: RefObject<TScrollElement | null>;
+    readonly count: number;
+    readonly estimateSize?: (index: number) => number;
+    readonly overscan?: number;
+    readonly onChange?: (virtualizer: Virtualizer<TScrollElement, TItemElement>) => void;
+    readonly skip?: boolean;
+    readonly onTopItemChange?: (index: number) => void;
+}
+/**
+ * Bidirectional infinite scroll hook that supports both forward (nextPage)
+ * and backward (previousPage) pagination with TanStack Virtual.
+ *
+ * Unlike `useInfiniteScroll` which only loads forward, this hook detects
+ * 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 {};

package/src/hooks/useCursorUrlSync.d.ts

@@ -0,0 +1,18 @@
+type UseCursorUrlSyncOptions = {
+    readonly paramName?: string;
+    readonly debounceMs?: number;
+};
+type UseCursorUrlSyncResult = {
+    readonly initialCursor: string | undefined;
+    readonly updateCursor: (cursor: string | undefined) => void;
+};
+/**
+ * Reads a cursor from the URL search params on mount and provides a debounced
+ * updater for writing it back. Uses `replace: true` to avoid polluting browser
+ * history with every scroll position change.
+ *
+ * Wire `initialCursor` into `usePaginationQuery` and `updateCursor` into
+ * `useBidirectionalScroll`'s `onTopItemChange` callback (mapping index to cursor).
+ */
+export declare const useCursorUrlSync: ({ paramName, debounceMs, }?: UseCursorUrlSyncOptions) => UseCursorUrlSyncResult;
+export {};

package/src/hooks/useRelayPagination.d.ts

@@ -2,6 +2,7 @@ import { Dispatch, SetStateAction } from "react";
 export interface RelayPaginationProps {
     pageSize?: number;
     onReset?: () => void;
+    initialCursor?: string;
 }
 export interface RelayPaginationQueryVariables {
     first?: number | null;
@@ -40,4 +41,4 @@ export declare const defaultPageSize = 50;
  * @param {RelayPaginationProps} props - The props object containing pagination configuration.
  * @returns {RelayPaginationSupport} An object containing functions and state for managing Relay pagination.
  */
-export declare const useRelayPagination: ({ onReset, pageSize }?: RelayPaginationProps) => RelayPaginationSupport;
+export declare const useRelayPagination: ({ onReset, pageSize, initialCursor }?: RelayPaginationProps) => RelayPaginationSupport;

package/src/index.d.ts

@@ -108,10 +108,12 @@ export * from "./hooks/encoding/useCustomEncoding";
 export * from "./hooks/localStorage/useLocalStorage";
 export * from "./hooks/localStorage/useLocalStorageReducer";
 export * from "./hooks/noPagination";
+export * from "./hooks/useBidirectionalScroll";
 export * from "./hooks/useClickOutside";
 export * from "./hooks/useContainerBreakpoints";
 export * from "./hooks/useContinuousTimeout";
 export * from "./hooks/useCopyToClipboard";
+export * from "./hooks/useCursorUrlSync";
 export * from "./hooks/useDebounce";
 export * from "./hooks/useDevicePixelRatio";
 export * from "./hooks/useElevatedReducer";