@trackunit/react-components 1.9.19 → 1.9.21

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

@@ -1,112 +1,48 @@
 import { VariantProps } from "@trackunit/css-class-variance-utilities";
-import { RelayPagination } from "@trackunit/react-table-pagination";
-import { CSSProperties, ReactElement, Ref } from "react";
+import { ReactElement } from "react";
 import { CommonProps } from "../../common/CommonProps";
 import { cvaListItem } from "./List.variants";
-import { ListLoadingIndicatorProps } from "./ListLoadingIndicator";
+import { UseListResult, VirtualizationListItemProps } from "./useList";
 type Separator = NonNullable<VariantProps<typeof cvaListItem>["separator"]>;
-/**
- * Props that must be spread onto list items for proper virtualization.
- * These handle positioning, measurement, accessibility, and interaction.
- *
- * **Important**: Consumers must add a `key` prop to their list items using the index parameter.
- */ export interface VirtualizationListItemProps {
-    /** CSS classes for list styling and separators */
-    className: string;
-    /** Critical positioning styles for virtual scrolling */
-    style: CSSProperties;
-    /** Element ref for virtualization measurement */
-    ref?: Ref<any>;
-    /** Click handler for row-level interactions */
-    onClick?: () => void;
-    /** Data attribute for accessibility and debugging */
-    "data-index": number;
-    /** Tab index for keyboard navigation */
-    tabIndex: number;
-}
-export interface ListProps<TItem = unknown> extends CommonProps {
-    /**
-     * Number of items in the list (excluding header if provided).
-     */
-    count: number;
-    /**
-     * Pagination configuration for infinite scrolling.
-     */
-    pagination?: RelayPagination;
-    /**
-     * Optional header element displayed at the top of the list.
-     *
-     * @example
-     * ```tsx
-     * <List header={<KPI title="Total" value={42} />} ... />
-     * ```
-     */
-    header?: ReactElement;
+export type { VirtualizationListItemProps } from "./useList";
+export interface ListProps<TItem = unknown> extends CommonProps, UseListResult<TItem> {
     /**
-     * Function that returns the item data for a given index.
+     * Function that renders each list item. Must spread `listItemProps` onto your element
+     * and use the provided `key` prop for React's reconciliation.
      *
-     * @example
-     * ```tsx
-     * getItem={index => items[index]}
-     * ```
-     */
-    getItem: (index: number) => TItem;
-    /**
-     * Function that renders each list item. Must spread `listItemProps` onto your element and apply a `key` prop.
+     * **Note**: `item` may be undefined if `getItem` returns undefined (legacy pattern).
+     * Consumers are responsible for handling this case.
      *
      * @example
      * ```tsx
-     * {(listItemProps, item, index) => (
-     *   <ListItem key={index} {...listItemProps} title={item.name} />
+     * {({ key, listItemProps, item, index }) => (
+     *   <ListItem key={key} {...listItemProps} title={item?.name} />
      * )}
      * ```
      */
-    children: (listItemProps: VirtualizationListItemProps, item: TItem, index: number) => ReactElement | null;
+    children: (params: {
+        key: string | number | bigint;
+        listItemProps: VirtualizationListItemProps;
+        item: TItem | undefined;
+        index: number;
+    }) => ReactElement | null;
     /**
      * Separator style between list items.
      */
     separator?: Separator;
-    /**
-     * Loading indicator configuration for pagination loading.
-     */
-    loadingIndicator?: ListLoadingIndicatorProps;
-    /**
-     * Callback fired when a row is clicked.
-     */
-    onRowClick?: (item: TItem, index: number) => void;
-    /**
-     * Callback for scroll state changes.
-     */
-    onScrollStateChange?: (scrollOffset: number, isScrolling: boolean) => void;
     /**
      * Show a top separator when the list is scrolled.
      */
     topSeparatorOnScroll?: boolean;
-    /**
-     * Function to estimate item height for scroll performance.
-     *
-     * **Best Practice:** Always provide this function, even for fixed-height items.
-     * Measure the actual height in browser DevTools and return that value for optimal scrolling.
-     *
-     * The virtualizer uses these estimates for scroll calculations and viewport positioning.
-     * More accurate estimates result in smoother scrolling.
-     *
-     * @example Fixed height
-     * ```tsx
-     * estimateItemSize={() => 61} // Measured ListItem height
-     * ```
-     * @example Variable height
-     * ```tsx
-     * estimateItemSize={(index) => items[index]?.hasDescription ? 80 : 50}
-     * ```
-     */
-    estimateItemSize?: (index: number) => number;
 }
 /**
  * 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
@@ -115,10 +51,53 @@ export interface ListProps<TItem = unknown> extends CommonProps {
  * - 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>
+ * );
+ * ```
  */
-export declare const List: <TItem = unknown>({ count, pagination, children, className, dataTestId, separator, loadingIndicator, onRowClick, onScrollStateChange, topSeparatorOnScroll, estimateItemSize, header, getItem, }: ListProps<TItem>) => ReactElement;
-export {};
+export declare const List: <TItem = unknown>({ children, className, dataTestId, topSeparatorOnScroll, separator, containerRef, listRef, rows, getListItemProps, header, loadingIndicator, shouldShowLoaderAtIndex, count, isScrolling, scrollOffset, getTotalSize: _getTotalSize, getVirtualItems: _getVirtualItems, scrollToOffset: _scrollToOffset, scrollToIndex: _scrollToIndex, measure: _measure, }: ListProps<TItem>) => ReactElement;

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

@@ -0,0 +1,171 @@
+import type { VirtualItem, Virtualizer } from "@tanstack/react-virtual";
+import { ReactElement, RefObject } from "react";
+import { RelayPagination } from "../../hooks";
+import { ListLoadingIndicatorProps } from "./ListLoadingIndicator";
+/**
+ * Props that must be spread onto list items for proper virtualization.
+ * These handle positioning, measurement, accessibility, and interaction.
+ *
+ * **Important**: Consumers must add a `key` prop to their list items using the index parameter.
+ */
+export interface VirtualizationListItemProps {
+    /** CSS classes for list styling and separators */
+    className: string;
+    /** Element ref for virtualization measurement and setting positioning transform styles */
+    ref?: (node: HTMLLIElement | null) => void;
+    /** Click handler for row-level interactions */
+    onClick?: () => void;
+    /** Data attribute for accessibility and debugging */
+    "data-index": number;
+    /** Tab index for keyboard navigation */
+    tabIndex: number;
+}
+export interface UseListOptions<TItem = unknown> {
+    /**
+     * Number of data items in the list (excluding header if provided).
+     */
+    count: number;
+    /**
+     * Pagination configuration for infinite scrolling.
+     */
+    pagination?: RelayPagination;
+    /**
+     * Optional header element displayed at the top of the list.
+     */
+    header?: ReactElement;
+    /**
+     * Function that returns the item data for a given data index.
+     *
+     * @example
+     * ```tsx
+     * getItem={index => items[index]}
+     * ```
+     */
+    getItem: (index: number) => TItem;
+    /**
+     * Loading indicator configuration for pagination loading.
+     */
+    loadingIndicator?: ListLoadingIndicatorProps;
+    /**
+     * Callback fired when a row is clicked.
+     */
+    onRowClick?: (params: {
+        item: TItem;
+        index: number;
+    }) => void;
+    /**
+     * Callback for scroll state changes.
+     */
+    onChange?: (virtualizer: Virtualizer<HTMLDivElement, HTMLLIElement>) => void;
+    /**
+     * Function to estimate item height for scroll performance.
+     *
+     * Measure the actual height in browser DevTools and return that value for optimal scrolling.
+     *
+     * The virtualizer uses these estimates for scroll calculations and viewport positioning.
+     * More accurate estimates result in smoother scrolling.
+     *
+     * **Important**: If providing a header, also provide `estimateHeaderSize` to avoid overlap issues.
+     *
+     * @example Fixed height
+     * ```tsx
+     * estimateItemSize={() => 61} // Measured ListItem height
+     * ```
+     * @example Variable height
+     * ```tsx
+     * estimateItemSize={(index) => items[index]?.hasDescription ? 80 : 50}
+     * ```
+     */
+    estimateItemSize: (index: number) => number;
+    /**
+     * Function to estimate the header height for scroll performance.
+     *
+     * Only used when `header` is provided. If not specified, falls back to `estimateItemSize(0)`.
+     *
+     * Measure the actual header height in browser DevTools for optimal positioning.
+     *
+     * @example
+     * ```tsx
+     * header: <KPI title="Total" value={42} />,
+     * estimateHeaderSize: () => 72, // Measured KPI height
+     * estimateItemSize: () => 61,   // Measured ListItem height
+     * ```
+     */
+    estimateHeaderSize?: () => number;
+    /**
+     * Additional overscan for virtualization (items to render outside viewport).
+     * Higher values reduce blank areas during fast scrolling but increase memory usage.
+     */
+    overscan?: number;
+}
+export type ListRowType = "header" | "data" | "loader";
+export type ListRow<TItem> = {
+    type: "header";
+    virtualRow: VirtualItem;
+    item?: never;
+    dataIndex: -1;
+} | {
+    type: "loader";
+    virtualRow: VirtualItem;
+    item?: never;
+    dataIndex: -1;
+} | {
+    type: "data";
+    virtualRow: VirtualItem;
+    item: TItem | undefined;
+    dataIndex: number;
+};
+export interface UseListResult<TItem> extends Pick<Virtualizer<HTMLDivElement, HTMLLIElement>, "scrollOffset" | "isScrolling" | "getTotalSize" | "getVirtualItems" | "scrollToOffset" | "scrollToIndex" | "measure"> {
+    /** Reference to attach to the scrollable container */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** Reference to attach to the list */
+    listRef: RefObject<HTMLUListElement | null>;
+    /** Array of row data to render */
+    readonly rows: ReadonlyArray<ListRow<TItem>>;
+    /** Helper to create list item props for a given row */
+    readonly getListItemProps: (row: ListRow<TItem>, options: {
+        className: string;
+        onClick?: () => void;
+    }) => VirtualizationListItemProps;
+    /** Header element (if provided) */
+    readonly header?: ReactElement;
+    /** Loading indicator configuration */
+    readonly loadingIndicator?: ListLoadingIndicatorProps;
+    /** Helper to determine if a specific loader index should be shown */
+    readonly shouldShowLoaderAtIndex: (loaderIndex: number) => boolean;
+    /** Total number of data items (for consistent calculations) */
+    readonly count: number;
+}
+/**
+ * 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>
+ * );
+ * ```
+ */
+export declare const useList: <TItem = unknown>({ count, pagination, header, getItem, loadingIndicator, onRowClick, onChange, estimateItemSize, estimateHeaderSize, overscan, }: UseListOptions<TItem>) => UseListResult<TItem>;

package/src/components/ListItem/useListItemHeight.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Configuration for calculating ListItem height based on visible content.
+ * These props match the optional content sections of ListItem.
+ */
+export interface ListItemHeightConfig {
+    /** Whether the item has a thumbnail (icon or image) */
+    hasThumbnail?: boolean;
+    /** Whether the item has a description line */
+    hasDescription?: boolean;
+    /** Whether the item has a meta line */
+    hasMeta?: boolean;
+    /** Whether the item has details on the right side (doesn't affect height) */
+    hasDetails?: boolean;
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+export declare const useListItemHeight: () => {
+    getListItemHeight: (config: ListItemHeightConfig) => number;
+};

package/src/components/index.d.ts

@@ -20,6 +20,8 @@ export * from "./KPI/KPI";
 export * from "./KPICard/KPICard";
 export * from "./List/List";
 export * from "./List/List.variants";
+export * from "./List/useList";
+export * from "./ListItem/useListItemHeight";
 export * from "./ListItem/ListItem";
 export * from "./Menu";
 export * from "./Notice";

package/src/hooks/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./noPagination";
 export * from "./useClickOutside";
 export * from "./useContainerBreakpoints";
 export * from "./useContinuousTimeout";
@@ -7,10 +8,12 @@ export * from "./useElevatedReducer";
 export * from "./useElevatedState";
 export * from "./useGeometry";
 export * from "./useHover";
+export * from "./useInfiniteScroll";
 export * from "./useIsFirstRender";
 export * from "./useIsFullScreen";
 export * from "./useIsTextTruncated";
 export * from "./useModifierKey";
+export * from "./useRelayPagination";
 export * from "./useResize";
 export * from "./useScrollDetection";
 export * from "./useSelfUpdatingRef";

package/src/hooks/noPagination.d.ts

@@ -0,0 +1,2 @@
+import { RelayPagination } from "./useRelayPagination";
+export declare const noPagination: RelayPagination;

package/src/hooks/useInfiniteScroll.d.ts

@@ -0,0 +1,36 @@
+import { type Virtualizer } from "@tanstack/react-virtual";
+import { RefObject } from "react";
+import { RelayPagination } from "./useRelayPagination";
+interface InfiniteScrollProps<TScrollElement extends Element, TItemElement extends Element> {
+    pagination: RelayPagination;
+    scrollElementRef: RefObject<TScrollElement | null>;
+    count: number;
+    estimateSize?: (index: number) => number;
+    overscan?: number;
+    onChange?: (virtualizer: Virtualizer<TScrollElement, TItemElement>) => void;
+}
+/**
+ * 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,
+ * });
+ */
+export declare const useInfiniteScroll: <TScrollElement extends Element, TItemElement extends Element>({ pagination, scrollElementRef, count, estimateSize, overscan, onChange, }: InfiniteScrollProps<TScrollElement, TItemElement>) => Virtualizer<TScrollElement, TItemElement>;
+export {};

package/src/hooks/useRelayPagination.d.ts

@@ -0,0 +1,43 @@
+import { Dispatch, SetStateAction } from "react";
+export interface RelayPaginationProps {
+    pageSize?: number;
+    onReset?: () => void;
+}
+export interface RelayPaginationQueryVariables {
+    first?: number | null;
+    last?: number | null;
+    before?: string | null;
+    after?: string | null;
+}
+export interface RelayPageInfo {
+    count?: number | null;
+    endCursor?: string | null;
+    hasNextPage?: boolean;
+    hasPreviousPage?: boolean;
+    startCursor?: string | null;
+    isCountCapped?: boolean;
+}
+export interface RelayPagination {
+    nextPage: () => void;
+    previousPage: () => void;
+    pageInfo?: RelayPageInfo;
+    isLoading: boolean;
+}
+export interface RelayTableSupport extends RelayPagination {
+    isLoading: boolean;
+    setIsLoading: Dispatch<SetStateAction<boolean>>;
+    reset: () => void;
+    setPageInfo: Dispatch<SetStateAction<RelayPageInfo | null | undefined>>;
+}
+export interface RelayPaginationSupport {
+    variables: RelayPaginationQueryVariables;
+    table: RelayTableSupport;
+}
+export declare 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.
+ */
+export declare const useRelayPagination: ({ onReset, pageSize }?: RelayPaginationProps) => RelayPaginationSupport;