@ringcentral/juno 2.40.0 → 2.41.0

package/components/Virtuoso/react-virtuoso/interfaces.d.ts

@@ -1,51 +1,55 @@
-import { ComponentPropsWithRef, ComponentType, Key, ReactNode } from 'react';
+import React from 'react';
 export interface ListRange {
     startIndex: number;
     endIndex: number;
 }
 export interface ItemContent<D, C> {
-    (index: number, data: D, context: C): ReactNode;
+    (index: number, data: D, context: C): React.ReactNode;
 }
 export declare type FixedHeaderContent = (() => React.ReactNode) | null;
+export declare type FixedFooterContent = (() => React.ReactNode) | null;
 export interface GroupItemContent<D, C> {
-    (index: number, groupIndex: number, data: D, context: C): ReactNode;
+    (index: number, groupIndex: number, data: D, context: C): React.ReactNode;
 }
-export interface GroupContent {
-    (index: number): ReactNode;
+export interface GroupContent<C> {
+    (index: number, context: C): React.ReactNode;
 }
-export declare type ItemProps = Pick<ComponentPropsWithRef<'div'>, 'style' | 'children'> & {
+export declare type ItemProps<D> = Pick<React.ComponentPropsWithRef<'div'>, 'style' | 'children'> & {
     'data-index': number;
     'data-item-index': number;
     'data-item-group-index'?: number;
     'data-known-size': number;
+    item: D;
 };
-export declare type GroupProps = Pick<ComponentPropsWithRef<'div'>, 'style' | 'children'> & {
+export declare type GroupProps = Pick<React.ComponentPropsWithRef<'div'>, 'style' | 'children'> & {
     'data-index': number;
     'data-item-index': number;
     'data-known-size': number;
 };
-export declare type TopItemListProps = Pick<ComponentPropsWithRef<'div'>, 'style' | 'children'>;
-export declare type TableProps = Pick<ComponentPropsWithRef<'table'>, 'style'>;
+export declare type TopItemListProps = Pick<React.ComponentPropsWithRef<'div'>, 'style' | 'children'>;
+export declare type TableProps = Pick<React.ComponentPropsWithRef<'table'>, 'style' | 'children'>;
 /**
  * Passed to the Components.TableBody custom component
  */
-export declare type TableBodyProps = Pick<ComponentPropsWithRef<'tbody'>, 'style' | 'children' | 'ref' | 'className'> & {
+export declare type TableBodyProps = Pick<React.ComponentPropsWithRef<'tbody'>, 'style' | 'children' | 'ref' | 'className'> & {
     'data-test-id': string;
 };
 /**
  * Passed to the Components.List custom component
  */
-export declare type ListProps = Pick<ComponentPropsWithRef<'div'>, 'style' | 'children' | 'ref'> & {
+export declare type ListProps = Pick<React.ComponentPropsWithRef<'div'>, 'style' | 'children' | 'ref'> & {
     'data-test-id': string;
 };
 /**
  * Passed to the Components.List custom component
  */
-export declare type GridListProps = Pick<ComponentPropsWithRef<'div'>, 'style' | 'children' | 'ref' | 'className'>;
+export declare type GridListProps = Pick<React.ComponentPropsWithRef<'div'>, 'style' | 'children' | 'ref' | 'className'> & {
+    'data-test-id': string;
+};
 /**
  * Passed to the Components.Scroller custom component
  */
-export declare type ScrollerProps = Pick<ComponentPropsWithRef<'div'>, 'style' | 'children' | 'tabIndex' | 'ref'> & {
+export declare type ScrollerProps = Pick<React.ComponentPropsWithRef<'div'>, 'style' | 'children' | 'tabIndex' | 'ref'> & {
     'data-test-id'?: string;
     'data-virtuoso-scroller'?: boolean;
 };
@@ -75,124 +79,130 @@ export interface GridScrollSeekPlaceholderProps {
 /**
  * Customize the Virtuoso rendering by passing a set of custom components.
  */
-export interface Components<Context = unknown> {
+export interface Components<Data = unknown, Context = unknown> {
     /**
      * Set to render a component at the top of the list.
      *
      * The header remains above the top items and does not remain sticky.
      */
-    Header?: ComponentType<{
+    Header?: React.ComponentType<{
         context?: Context;
     }>;
     /**
      * Set to render a component at the bottom of the list.
      */
-    Footer?: ComponentType<{
+    Footer?: React.ComponentType<{
         context?: Context;
     }>;
     /**
      * Set to customize the item wrapping element. Use only if you would like to render list from elements different than a `div`.
      */
-    Item?: ComponentType<ItemProps & {
+    Item?: React.ComponentType<ItemProps<Data> & {
         context?: Context;
     }>;
     /**
      * Set to customize the group item wrapping element. Use only if you would like to render list from elements different than a `div`.
      */
-    Group?: ComponentType<GroupProps & {
+    Group?: React.ComponentType<GroupProps & {
         context?: Context;
     }>;
     /**
      * Set to customize the top list item wrapping element. Use if you would like to render list from elements different than a `div`
      * or you want to set a custom z-index for the sticky position.
      */
-    TopItemList?: ComponentType<TopItemListProps & {
+    TopItemList?: React.ComponentType<TopItemListProps & {
         context?: Context;
     }>;
     /**
      * Set to customize the outermost scrollable element. This should not be necessary in general,
      * as the component passes its HTML attribute props to it.
      */
-    Scroller?: ComponentType<ScrollerProps & {
+    Scroller?: React.ComponentType<ScrollerProps & {
         context?: Context;
     }>;
     /**
      * Set to customize the items wrapper. Use only if you would like to render list from elements different than a `div`.
      */
-    List?: ComponentType<ListProps & {
+    List?: React.ComponentType<ListProps & {
         context?: Context;
     }>;
     /**
      * Set to render a custom UI when the list is empty.
      */
-    EmptyPlaceholder?: ComponentType<{
+    EmptyPlaceholder?: React.ComponentType<{
         context?: Context;
     }>;
     /**
      * Set to render an item placeholder when the user scrolls fast.  See the `scrollSeek` property for more details.
      */
-    ScrollSeekPlaceholder?: ComponentType<ScrollSeekPlaceholderProps & {
+    ScrollSeekPlaceholder?: React.ComponentType<ScrollSeekPlaceholderProps & {
         context?: Context;
     }>;
 }
 /**
  * Customize the TableVirtuoso rendering by passing a set of custom components.
  */
-export interface TableComponents<Context = unknown> {
+export interface TableComponents<Data = unknown, Context = unknown> {
     /**
      * Set to customize the wrapping `table` element.
      *
      */
-    Table?: ComponentType<TableProps & {
+    Table?: React.ComponentType<TableProps & {
         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?: ComponentType<{
+    TableHead?: React.ComponentType<Pick<React.ComponentPropsWithRef<'thead'>, 'style' | 'children' | 'ref'> & {
+        context?: Context;
+    }>;
+    /**
+     * Set to render a fixed footer at the bottom of the table (`tfoot`). use [[fixedFooterContent]] to set the contents
+     */
+    TableFoot?: React.ComponentType<Pick<React.ComponentPropsWithRef<'tfoot'>, 'style' | 'children' | 'ref'> & {
         context?: Context;
     }>;
     /**
      * Set to customize the item wrapping element. Default is `tr`.
      */
-    TableRow?: ComponentType<ItemProps & {
+    TableRow?: React.ComponentType<ItemProps<Data> & {
         context?: Context;
     }>;
     /**
      * Set to customize the outermost scrollable element. This should not be necessary in general,
      * as the component passes its HTML attribute props to it.
      */
-    Scroller?: ComponentType<ScrollerProps & {
+    Scroller?: React.ComponentType<ScrollerProps & {
         context?: Context;
     }>;
     /**
      * Set to customize the items wrapper. Default is `tbody`.
      */
-    TableBody?: ComponentType<TableBodyProps & {
+    TableBody?: React.ComponentType<TableBodyProps & {
         context?: Context;
     }>;
     /**
      * Set to render a custom UI when the list is empty.
      */
-    EmptyPlaceholder?: ComponentType<{
+    EmptyPlaceholder?: React.ComponentType<{
         context?: Context;
     }>;
     /**
      * Set to render an item placeholder when the user scrolls fast.  See the `scrollSeek` property for more details.
      */
-    ScrollSeekPlaceholder?: ComponentType<ScrollSeekPlaceholderProps & {
+    ScrollSeekPlaceholder?: React.ComponentType<ScrollSeekPlaceholderProps & {
         context?: Context;
     }>;
     /**
      * Set to render an empty item placeholder.
      */
-    FillerRow?: ComponentType<FillerRowProps & {
+    FillerRow?: React.ComponentType<FillerRowProps & {
         context?: Context;
     }>;
 }
 export interface ComputeItemKey<D, C> {
-    (index: number, item: D, context: C): Key;
+    (index: number, item: D, context: C): React.Key;
 }
 export interface ScrollSeekToggle {
     (velocity: number, range: ListRange): boolean;
@@ -207,7 +217,7 @@ export 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;
 }
@@ -231,11 +241,7 @@ export interface GroupItem<D> extends Item<D> {
     originalIndex?: number;
 }
 export declare type ListItem<D> = RecordItem<D> | GroupItem<D>;
-export interface IndexLocationWithAlign {
-    /**
-     * The index of the item to scroll to.
-     */
-    index: number | 'LAST';
+export interface LocationOptions {
     /**
      * How to position the item in the viewport.
      */
@@ -249,10 +255,28 @@ export interface IndexLocationWithAlign {
      */
     offset?: number;
 }
+export interface FlatIndexLocationWithAlign extends LocationOptions {
+    /**
+     * The index of the item to scroll to.
+     */
+    index: number | 'LAST';
+}
+export interface GroupIndexLocationWithAlign extends LocationOptions {
+    /**
+     * The group index of the item to scroll to.
+     */
+    groupIndex: number;
+}
+export declare type IndexLocationWithAlign = FlatIndexLocationWithAlign | GroupIndexLocationWithAlign;
+export declare type GridIndexLocation = FlatIndexLocationWithAlign | number;
 export declare type ListRootProps = Omit<React.HTMLProps<HTMLDivElement>, 'ref' | 'data'>;
 export declare type TableRootProps = Omit<React.HTMLProps<HTMLTableElement>, 'ref' | 'data'>;
 export declare type GridRootProps = Omit<React.HTMLProps<HTMLDivElement>, 'ref' | 'data'>;
-export interface GridItem {
+export interface GridItem<D> {
+    index: number;
+    data?: D;
+}
+export interface GridItemProps {
     'data-index': number;
     className?: string;
 }
@@ -260,48 +284,123 @@ export 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`.
      */
-    Item?: ComponentType<GridItem & {
+    Item?: React.ComponentType<GridItemProps & {
         context?: Context;
     }>;
     /**
      * Set to customize the outermost scrollable element. This should not be necessary in general,
      * as the component passes its HTML attribute props to it.
      */
-    Scroller?: ComponentType<ScrollerProps & {
+    Scroller?: React.ComponentType<ScrollerProps & {
         context?: Context;
     }>;
     /**
      * Set to customize the items wrapper. Use only if you would like to render list from elements different than a `div`.
      */
-    List?: ComponentType<GridListProps & {
+    List?: React.ComponentType<GridListProps & {
+        context?: Context;
+    }>;
+    /**
+     * Set to render a component at the top of the list.
+     *
+     * The header remains above the top items and does not remain sticky.
+     */
+    Header?: React.ComponentType<{
+        context?: Context;
+    }>;
+    /**
+     * Set to render a component at the bottom of the list.
+     */
+    Footer?: React.ComponentType<{
         context?: Context;
     }>;
     /**
      * Set to render an item placeholder when the user scrolls fast.
      * See the `scrollSeekConfiguration` property for more details.
      */
-    ScrollSeekPlaceholder?: ComponentType<GridScrollSeekPlaceholderProps & {
+    ScrollSeekPlaceholder?: React.ComponentType<GridScrollSeekPlaceholderProps & {
         context?: Context;
     }>;
 }
-export interface GridComputeItemKey {
-    (index: number): Key;
+export interface GridComputeItemKey<D, C> {
+    (index: number, item: D, context: C): React.Key;
 }
-export interface GridItemContent<C> {
-    (index: number, context: C): ReactNode;
+export interface GridItemContent<D, C> {
+    (index: number, data: D, context: C): React.ReactNode;
 }
 export interface WindowViewportInfo {
     offsetTop: number;
     visibleHeight: number;
     visibleWidth: number;
 }
-export interface ScrollIntoViewLocation {
-    index: number;
+export interface CalculateViewLocationParams {
+    itemTop: number;
+    itemBottom: number;
+    viewportTop: number;
+    viewportBottom: number;
+    locationParams: {
+        align?: 'start' | 'center' | 'end';
+        behavior?: 'auto' | 'smooth';
+    } & ({
+        index: number;
+    } | {
+        groupIndex: number;
+    });
+}
+export declare type CalculateViewLocation = (params: CalculateViewLocationParams) => IndexLocationWithAlign | number | null;
+export 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 interface FlatScrollIntoViewLocation extends ScrollIntoViewLocationOptions {
+    index: number;
+}
+export interface GroupedScrollIntoViewLocation extends ScrollIntoViewLocationOptions {
+    groupIndex: number;
 }
+export declare type ScrollIntoViewLocation = FlatScrollIntoViewLocation | GroupedScrollIntoViewLocation;
 export interface ScrollContainerState {
     scrollHeight: number;
     scrollTop: number;
     viewportHeight: number;
 }
+/** 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 interface SizeRange {
+    startIndex: number;
+    endIndex: number;
+    size: number;
+}
+export interface StateSnapshot {
+    ranges: SizeRange[];
+    scrollTop: number;
+}
+export declare type StateCallback = (state: StateSnapshot) => void;