react-virtuoso 0.0.0-development → 0.0.0-semantic-release

package/dist/index.d.ts

@@ -1,5 +1,22 @@
 import { default as React_2 } from 'react';
 
+export declare type CalculateViewLocation = (params: CalculateViewLocationParams) => IndexLocationWithAlign | number | null;
+
+export declare interface CalculateViewLocationParams {
+    itemTop: number;
+    itemBottom: number;
+    viewportTop: number;
+    viewportBottom: number;
+    locationParams: {
+        align?: 'start' | 'center' | 'end';
+        behavior?: 'auto' | 'smooth';
+    } & ({
+        index: number;
+    } | {
+        groupIndex: number;
+    });
+}
+
 /**
  * Customize the Virtuoso rendering by passing a set of custom components.
  */
@@ -68,6 +85,11 @@ export declare interface ComputeItemKey<D, C> {
     (index: number, item: D, context: C): React_2.Key;
 }
 
+export declare interface ElementDimensions {
+    width: number;
+    height: number;
+}
+
 /**
  * Passed to the Components.FillerRow custom component
  */
@@ -96,6 +118,11 @@ export declare type FollowOutputCallback = (isAtBottom: boolean) => FollowOutput
 
 export declare type FollowOutputScalarType = boolean | 'smooth' | 'auto';
 
+export declare interface Gap {
+    row: number;
+    column: number;
+}
+
 export declare interface GridComponents<Context = any> {
     /**
      * Set to customize the item wrapping element. Use only if you would like to render list from elements different than a `div`.
@@ -143,6 +170,8 @@ export declare interface GridComputeItemKey<D, C> {
     (index: number, item: D, context: C): React_2.Key;
 }
 
+export declare type GridIndexLocation = FlatIndexLocationWithAlign | number;
+
 export declare interface GridItem<D> {
     index: number;
     data?: D;
@@ -152,17 +181,19 @@ export declare interface GridItemContent<D, C> {
     (index: number, data: D, context: C): React_2.ReactNode;
 }
 
-export declare interface GridItemProps {
+/**
+ * Passed to the Components.Item custom component
+ */
+export declare type GridItemProps = Pick<React_2.ComponentProps<'div'>, 'style' | 'children' | 'className'> & {
     'data-index': number;
-    className?: string;
-}
+} & React_2.RefAttributes<HTMLDivElement>;
 
 /**
  * Passed to the Components.List custom component
  */
-export declare type GridListProps = Pick<React_2.ComponentPropsWithRef<'div'>, 'style' | 'children' | 'ref' | 'className'> & {
-    'data-test-id': string;
-};
+export declare type GridListProps = Pick<React_2.ComponentProps<'div'>, 'style' | 'children' | 'className'> & {
+    'data-testid': string;
+} & React_2.RefAttributes<HTMLDivElement>;
 
 export declare type GridRootProps = Omit<React_2.HTMLProps<HTMLDivElement>, 'ref' | 'data'>;
 
@@ -175,8 +206,15 @@ export declare interface GridScrollSeekPlaceholderProps {
     width: number;
 }
 
-export declare interface GroupContent {
-    (index: number): React_2.ReactNode;
+export declare interface GridStateSnapshot {
+    viewport: ElementDimensions;
+    item: ElementDimensions;
+    gap: Gap;
+    scrollTop: number;
+}
+
+export declare interface GroupContent<C> {
+    (index: number, context: C): React_2.ReactNode;
 }
 
 export declare interface GroupedScrollIntoViewLocation extends ScrollIntoViewLocationOptions {
@@ -193,6 +231,10 @@ export declare interface GroupedVirtuosoHandle {
     scrollTo(location: ScrollToOptions): void;
     scrollBy(location: ScrollToOptions): void;
     autoscrollToBottom(): void;
+    /**
+     * Obtains the internal size state of the component, so that it can be restored later. This does not include the data items.
+     */
+    getState(stateCb: StateCallback): void;
 }
 
 export declare interface GroupedVirtuosoProps<D, C> extends Omit<VirtuosoProps<D, C>, 'totalCount' | 'itemContent'> {
@@ -204,11 +246,25 @@ export declare interface GroupedVirtuosoProps<D, C> extends Omit<VirtuosoProps<D
     /**
      * Specifies how each each group header gets rendered. The callback receives the zero-based index of the group.
      */
-    groupContent?: GroupContent;
+    groupContent?: GroupContent<C>;
     /**
      * Specifies how each each item gets rendered.
      */
     itemContent?: GroupItemContent<D, C>;
+    /**
+     * Use when implementing inverse infinite scrolling, decrease the value this property
+     * in combination with a change in `groupCounts` to prepend groups items to the top of the list.
+     * Both new groups and extending the top group is supported.
+     *
+     * The delta of the firstItemIndex should equal the amount of new items introduced, without the group themselves.
+     * As an example, if you prepend 2 groups with 20 and 30 items each, the firstItemIndex should be decreased with 50.
+     *
+     * You can also prepend more items to the first group, for example:
+     * `{ groupCounts: [20, 30], firstItemIndex: 1000 }` can become `{ groupCounts: [10, 30, 30], firstItemIndex: 980 }`
+     *
+     * Warning: the firstItemIndex should **be a positive number**, based on the total amount of items to be displayed.
+     */
+    firstItemIndex?: number;
 }
 
 export declare interface GroupIndexLocationWithAlign extends LocationOptions {
@@ -227,7 +283,7 @@ export declare interface GroupItemContent<D, C> {
     (index: number, groupIndex: number, data: D, context: C): React_2.ReactNode;
 }
 
-export declare type GroupProps = Pick<React_2.ComponentPropsWithRef<'div'>, 'style' | 'children'> & {
+export declare type GroupProps = Pick<React_2.ComponentProps<'div'>, 'style' | 'children'> & {
     'data-index': number;
     'data-item-index': number;
     'data-known-size': number;
@@ -246,7 +302,7 @@ export declare interface ItemContent<D, C> {
     (index: number, data: D, context: C): React_2.ReactNode;
 }
 
-export declare type ItemProps<D> = Pick<React_2.ComponentPropsWithRef<'div'>, 'style' | 'children'> & {
+export declare type ItemProps<D> = Pick<React_2.ComponentProps<'div'>, 'style' | 'children'> & {
     'data-index': number;
     'data-item-index': number;
     'data-item-group-index'?: number;
@@ -259,9 +315,9 @@ export declare type ListItem<D> = RecordItem<D> | GroupItem<D>;
 /**
  * Passed to the Components.List custom component
  */
-export declare type ListProps = Pick<React_2.ComponentPropsWithRef<'div'>, 'style' | 'children' | 'ref'> & {
-    'data-test-id': string;
-};
+export declare type ListProps = Pick<React_2.ComponentProps<'div'>, 'style' | 'children'> & {
+    'data-testid': string;
+} & React_2.RefAttributes<HTMLDivElement>;
 
 export declare interface ListRange {
     startIndex: number;
@@ -308,17 +364,44 @@ export declare interface ScrollContainerState {
 /**
  * Passed to the Components.Scroller custom component
  */
-export declare type ScrollerProps = Pick<React_2.ComponentPropsWithRef<'div'>, 'style' | 'children' | 'tabIndex' | 'ref'> & {
-    'data-test-id'?: string;
+export declare type ScrollerProps = Pick<React_2.ComponentProps<'div'>, 'style' | 'children' | 'tabIndex'> & {
+    'data-testid'?: string;
     'data-virtuoso-scroller'?: boolean;
-};
+} & React_2.RefAttributes<HTMLDivElement>;
 
 export declare type ScrollIntoViewLocation = FlatScrollIntoViewLocation | GroupedScrollIntoViewLocation;
 
 export declare interface ScrollIntoViewLocationOptions {
     align?: 'start' | 'center' | 'end';
     behavior?: 'auto' | 'smooth';
+    /**
+     * Will be called when the scroll is done, or immediately if no scroll is needed.
+     */
     done?: () => void;
+    /**
+     * Use this function to fine-tune the scrollIntoView behavior.
+     * The function receives the item's top and bottom position in the viewport, and the viewport top/bottom.
+     * Return an location object to scroll, or null to prevent scrolling.
+     * Here's the default implementation:
+     * ```ts
+     const defaultCalculateViewLocation: CalculateViewLocation = ({
+     itemTop,
+     itemBottom,
+     viewportTop,
+     viewportBottom,
+     locationParams: { behavior, align, ...rest },
+     }) => {
+     if (itemTop < viewportTop) {
+     return { ...rest, behavior, align: align ?? 'start' }
+     }
+     if (itemBottom > viewportBottom) {
+     return { ...rest, behavior, align: align ?? 'end' }
+     }
+     return null
+     }
+     *```
+     */
+    calculateViewLocation?: CalculateViewLocation;
 }
 
 export declare interface ScrollSeekConfiguration {
@@ -331,7 +414,7 @@ export declare interface ScrollSeekConfiguration {
      */
     change?: (velocity: number, range: ListRange) => void;
     /**
-     * Callback to determine if the list should enter "scroll seek" mode.
+     * Callback to determine if the list should exit "scroll seek" mode.
      */
     exit: ScrollSeekToggle;
 }
@@ -353,12 +436,25 @@ export declare interface ScrollSeekToggle {
 /** Calculates the height of `el`, which will be the `Item` element in the DOM. */
 export declare type SizeFunction = (el: HTMLElement, field: 'offsetHeight' | 'offsetWidth') => number;
 
+export declare interface SizeRange {
+    startIndex: number;
+    endIndex: number;
+    size: number;
+}
+
+export declare type StateCallback = (state: StateSnapshot) => void;
+
+export declare interface StateSnapshot {
+    ranges: SizeRange[];
+    scrollTop: number;
+}
+
 /**
  * Passed to the Components.TableBody custom component
  */
-export declare type TableBodyProps = Pick<React_2.ComponentPropsWithRef<'tbody'>, 'style' | 'children' | 'ref' | 'className'> & {
-    'data-test-id': string;
-};
+export declare type TableBodyProps = Pick<React_2.ComponentProps<'tbody'>, 'style' | 'children' | 'className'> & {
+    'data-testid': string;
+} & React_2.RefAttributes<HTMLTableSectionElement>;
 
 /**
  * Customize the TableVirtuoso rendering by passing a set of custom components.
@@ -372,18 +468,18 @@ export declare interface TableComponents<Data = unknown, Context = unknown> {
         context?: Context;
     }>;
     /**
-     * Set to render a fixed header at the top of the table (`thead`). use [[fixedHeaderHeight]] to set the contents
+     * Set to render a fixed header at the top of the table (`thead`). use [[fixedHeaderContent]] to set the contents
      *
      */
-    TableHead?: React_2.ComponentType<Pick<React_2.ComponentPropsWithRef<'thead'>, 'style' | 'ref'> & {
+    TableHead?: React_2.ComponentType<Pick<React_2.ComponentProps<'thead'>, 'style' | 'children'> & {
         context?: Context;
-    }>;
+    } & React_2.RefAttributes<HTMLTableSectionElement>>;
     /**
      * Set to render a fixed footer at the bottom of the table (`tfoot`). use [[fixedFooterContent]] to set the contents
      */
-    TableFoot?: React_2.ComponentType<Pick<React_2.ComponentPropsWithRef<'tfoot'>, 'style' | 'ref'> & {
+    TableFoot?: React_2.ComponentType<Pick<React_2.ComponentProps<'tfoot'>, 'style' | 'children'> & {
         context?: Context;
-    }>;
+    } & React_2.RefAttributes<HTMLTableSectionElement>>;
     /**
      * Set to customize the item wrapping element. Default is `tr`.
      */
@@ -423,7 +519,7 @@ export declare interface TableComponents<Data = unknown, Context = unknown> {
     }>;
 }
 
-export declare type TableProps = Pick<React_2.ComponentPropsWithRef<'table'>, 'style' | 'children'>;
+export declare type TableProps = Pick<React_2.ComponentProps<'table'>, 'style' | 'children'>;
 
 export declare type TableRootProps = Omit<React_2.HTMLProps<HTMLTableElement>, 'ref' | 'data'>;
 
@@ -436,6 +532,10 @@ export declare interface TableVirtuosoHandle {
     scrollToIndex(location: number | FlatIndexLocationWithAlign): void;
     scrollTo(location: ScrollToOptions): void;
     scrollBy(location: ScrollToOptions): void;
+    /**
+     * Obtains the internal size state of the component, so that it can be restored later. This does not include the data items.
+     */
+    getState(stateCb: StateCallback): void;
 }
 
 export declare interface TableVirtuosoProps<D, C> extends Omit<VirtuosoProps<D, C>, 'components' | 'headerFooterTag' | 'topItemCount'> {
@@ -613,9 +713,15 @@ export declare interface TableVirtuosoProps<D, C> extends Omit<VirtuosoProps<D,
      * By default `4`. Redefine to change how much away from the bottom the scroller can be before the list is not considered not at bottom.
      */
     atBottomThreshold?: number;
+    /**
+     * pass a state obtained from the getState() method to restore the list state - this includes the previously measured item sizes and the scroll location.
+     * Notice that you should still pass the same data and totalCount properties as before, so that the list can match the data with the stored measurements.
+     * This is useful when you want to keep the list state when the component is unmounted and remounted, for example when navigating to a different page.
+     */
+    restoreStateFrom?: StateSnapshot;
 }
 
-export declare type TopItemListProps = Pick<React_2.ComponentPropsWithRef<'div'>, 'style' | 'children'>;
+export declare type TopItemListProps = Pick<React_2.ComponentProps<'div'>, 'style' | 'children'>;
 
 export declare const Virtuoso: <ItemData = any, Context = any>(props: VirtuosoProps<ItemData, Context> & {
     ref?: React_2.Ref<VirtuosoHandle> | undefined;
@@ -626,7 +732,7 @@ export declare const VirtuosoGrid: <ItemData = any, Context = any>(props: Virtuo
 }) => React_2.ReactElement;
 
 export declare interface VirtuosoGridHandle {
-    scrollToIndex(location: number | IndexLocationWithAlign): void;
+    scrollToIndex(location: GridIndexLocation): void;
     scrollTo(location: ScrollToOptions): void;
     scrollBy(location: ScrollToOptions): void;
 }
@@ -702,6 +808,11 @@ export declare interface VirtuosoGridProps<D, C = unknown> extends GridRootProps
      * Called with the new set of items each time the list items are rendered due to scrolling.
      */
     rangeChanged?: (range: ListRange) => void;
+    /**
+     * reports when the grid state changes. The reported value can be stored and passed back to `restoreStateFrom` to restore the grid to the same state.
+     */
+    stateChanged?: (state: GridStateSnapshot) => void;
+    restoreStateFrom?: GridStateSnapshot | undefined | null;
     /**
      * Called with true / false when the list has reached the bottom / gets scrolled up.
      * Can be used to load newer items, like `tail -f`.
@@ -731,6 +842,13 @@ export declare interface VirtuosoGridProps<D, C = unknown> extends GridRootProps
      * Pass a reference to a scrollable parent element, so that the grid won't wrap in its own.
      */
     customScrollParent?: HTMLElement;
+    /**
+     * set to LogLevel.DEBUG to enable various diagnostics in the console, the most useful being the item measurement reports.
+     *
+     * Ensure that you have "all levels" enabled in the browser console too see the messages.
+     */
+    logLevel?: LogLevel;
+    initialTopMostItemIndex?: GridIndexLocation;
 }
 
 export declare interface VirtuosoHandle {
@@ -754,6 +872,10 @@ export declare interface VirtuosoHandle {
      * Use this with combination with follow output if you have images loading in the list. Listen to the image loading and call the method.
      */
     autoscrollToBottom(): void;
+    /**
+     * Obtains the internal size state of the component, so that it can be restored later. This does not include the data items.
+     */
+    getState(stateCb: StateCallback): void;
 }
 
 export declare const VirtuosoMockContext: React_2.Context<VirtuosoMockContextValue | undefined>;
@@ -956,6 +1078,22 @@ export declare interface VirtuosoProps<D, C> extends ListRootProps {
      * By default `4`. Redefine to change how much away from the bottom the scroller can be before the list is not considered not at bottom.
      */
     atBottomThreshold?: number;
+    /**
+     * set to LogLevel.DEBUG to enable various diagnostics in the console, the most useful being the item measurement reports.
+     *
+     * Ensure that you have "all levels" enabled in the browser console too see the messages.
+     */
+    logLevel?: LogLevel;
+    /**
+     * pass a state obtained from the getState() method to restore the list state - this includes the previously measured item sizes and the scroll location.
+     * Notice that you should still pass the same data and totalCount properties as before, so that the list can match the data with the stored measurements.
+     * This is useful when you want to keep the list state when the component is unmounted and remounted, for example when navigating to a different page.
+     */
+    restoreStateFrom?: StateSnapshot;
+    /**
+     * when set, turns the scroller into a horizontal list.
+     */
+    horizontalDirection?: boolean;
 }
 
 export declare interface WindowViewportInfo {