@candidstartup/react-virtual-scroll 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,108 +1,637 @@
-import React from 'react';
+import React$1 from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
-interface VirtualBaseItemProps {
-    data: any;
+/**
+ * Props that an implementation of {@link VirtualContainerRender} must accept.
+ *
+ * Includes all the props that a {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement | HTMLDivElement} would accept.
+ */
+type VirtualContainerRenderProps = React$1.ComponentPropsWithoutRef<'div'>;
+/**
+ * Render prop for a {@link VirtualContainer}
+ *
+ * Can be passed to {@link VirtualContainer} to replace default implementation.
+ * Function must render a div and forward {@link VirtualContainerRenderProps}
+ * and any `ref` to it.
+ *
+ * @example Minimal compliant implementation
+ * ```
+ * const containerRender: VirtualContainerRender = ({...rest}, ref) => (
+ *   <div ref={ref} {...rest} />
+ * )
+ * ```
+ */
+type VirtualContainerRender = (props: VirtualContainerRenderProps, ref?: React$1.ForwardedRef<HTMLDivElement>) => JSX.Element;
+/**
+ * Props that {@link VirtualContainer} accepts.
+ */
+interface VirtualContainerComponentProps extends VirtualContainerRenderProps {
+    /** Render prop implementing {@link VirtualContainerRender}. Used to customize {@link VirtualContainer}. */
+    render?: VirtualContainerRender;
+}
+/**
+ * Wrapper around a div used by other components in {@link @candidstartup/react-virtual-scroll!}. Most props are passed through to the div. Use the
+ * {@link VirtualContainerComponentProps.render} prop to override the default behavior.
+ *
+ * @group Components
+ */
+declare const VirtualContainer: React$1.ForwardRefExoticComponent<VirtualContainerComponentProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Props that an implementation of {@link AutoSizerRender} must accept.
+ */
+interface AutoSizerRenderProps {
+    /** Computed height */
+    height: number;
+    /** Computed width */
+    width: number;
+}
+/**
+ * Render prop for content in an {@link AutoSizer}
+ *
+ * Function renders content and forwards `width` and `height`
+ * to whatever needs it.
+ *
+ * @example Simple implementation
+ * ```
+ * const autoSizeRender: AutoSizeRender = ({width, height}) => (
+ *   <VirtualList width={width} height={height} {...props} />
+ * )
+ * ```
+ */
+type AutoSizerRender = (props: AutoSizerRenderProps) => JSX.Element;
+/**
+ * Props accepted by {@link AutoSizer}
+ */
+interface AutoSizerProps {
+    /** Function implementing {@link AutoSizerRender} that renders the content that needs explicit sizing */
+    children: AutoSizerRender;
+    /** The `className` applied to the container element */
+    className?: string;
+    /** Inline style to apply to the container element */
+    style?: React$1.CSSProperties;
+}
+/**
+ * HOC that calculates the size available to it and makes the computed size available to children.
+ * The size available depends on DOM layout and style applied wherever the AutoSizer finds itself.
+ * You will probably want to pass something appropriate via the `className` or `style` props.
+ *
+ * Accepts props defined by {@link AutoSizerProps}.
+ * You must pass a single instance of {@link AutoSizerRender} as a child.
+ * @group Components
+ */
+declare function AutoSizer(props: AutoSizerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Common props for {@link DisplayListItem} and {@link DisplayGridItem}
+ */
+interface DisplayBaseItemProps {
+    /** Value of {@link DisplayBaseProps.itemData} from owning component */
+    data: unknown;
+    /**
+     * Is the owning component being actively scrolled? Used to change how the item is rendered depending on scroll state.
+     *
+     * Value passed through from {@link DisplayBaseProps.isScrolling}.
+     * */
     isScrolling?: boolean;
-    style: React.CSSProperties;
+    /** Style that should be applied to each item rendered. Positions the item within the inner container. */
+    style: React$1.CSSProperties;
 }
-interface VirtualBaseProps {
+/**
+ * Common props for all components
+ */
+interface ComponentProps {
+    /** The `className` applied to the outer container element. Use when styling the entire component. */
     className?: string;
+    /** The `className` applied to the inner container element. Use for special cases when styling only the inner container and items. */
     innerClassName?: string;
+    /** Component height */
     height: number;
+    /** Component width */
     width: number;
-    itemData?: any;
+}
+/**
+ * Common props for {@link DisplayList} and {@link DisplayGrid}
+ */
+interface DisplayBaseProps extends ComponentProps {
+    /** Passed as {@link DisplayBaseItemProps.data} to each child item */
+    itemData?: unknown;
+    /** Passed as {@link DisplayBaseItemProps.isScrolling} to each child item
+     *
+     * Provided as a convenience when combining display components with {@link VirtualScroll}
+     * Not interpreted by the display component itself
+     */
+    isScrolling?: boolean;
+    /**
+     * Renders the outer viewport div which provides a window onto the inner grid div
+     *
+     * Render prop implementing {@link VirtualContainerRender}. Used to customize display component outer container.
+     */
+    outerRender?: VirtualContainerRender;
+    /**
+     * Renders the inner grid div containing all the list items
+     *
+     * Render prop implementing {@link VirtualContainerRender}. Used to customize display component inner container.
+     */
+    innerRender?: VirtualContainerRender;
+}
+/**
+ * Common props for all virtual scrollable components
+ */
+interface VirtualScrollableProps extends ComponentProps {
+    /**
+     * Determines whether the component should track whether it's being actively scrolled
+     * and pass through when rendering its content.
+     *
+     * @defaultValue false
+     * */
     useIsScrolling?: boolean;
+    /**
+     * Maximum size for CSS element beyond which layout breaks. You should never normally need to change this.
+     * The default value is compatible with all major browsers.
+     *
+     * @defaultValue 6000000
+     * */
     maxCssSize?: number;
+    /**
+     * The minimum number of virtual pages to use when inner container would otherwise be more than {@link VirtualScrollableProps.maxCssSize} big.
+     * You should never normally need to change this.
+     *
+     * @defaultValue 100
+     */
     minNumPages?: number;
 }
-interface VirtualInnerProps {
-    className: string | undefined;
-    children: React.ReactNode;
-    style: React.CSSProperties;
-}
-type VirtualInnerComponent = React.ComponentType<VirtualInnerProps>;
-interface VirtualOuterProps {
-    className: string | undefined;
-    children: React.ReactNode;
-    style: React.CSSProperties;
-    onScroll: (event: ScrollEvent) => void;
+/**
+ * Common props for {@link VirtualList} and {@link VirtualGrid}
+ */
+interface VirtualBaseProps extends VirtualScrollableProps {
+    /** Passed as {@link DisplayBaseItemProps.data} to each child item */
+    itemData?: unknown;
 }
-type VirtualOuterComponent = React.ComponentType<VirtualOuterProps>;
+/**
+ * Interface that {@link VirtualList} and {@link VirtualGrid} use to determine size and
+ * positioning offset for items in a single dimension.
+ */
 interface ItemOffsetMapping {
+    /** Size of item with given index */
     itemSize(itemIndex: number): number;
+    /** Offset from start of container to specified item
+     *
+     * `itemOffset(n)` should be equal to `Sum{i:0->n-1}(itemSize(i))`
+     *
+     * To efficiently support large containers, cost should be `O(logn)` or better.
+     */
     itemOffset(itemIndex: number): number;
+    /** Given an offset, return the index of the item that intersects that offset, together with the start offset of that item */
     offsetToItem(offset: number): [itemIndex: number, startOffset: number];
 }
-type ScrollEvent = React.SyntheticEvent<HTMLDivElement>;
+/**  Alias for type of event that React passes to a `div` element's `OnScroll` handler. */
+type ScrollEvent = React$1.SyntheticEvent<HTMLDivElement>;
+/**
+ * Option for {@link VirtualGridProxy.scrollToItem} and {@link VirtualListProxy.scrollToItem}
+ *
+ * * `topleft` scrolls the item as far to the top and left as possible
+ * * `visible` scrolls the item the minimum amount needed to ensure that it's visible
+ *
+ *  @defaultValue `topleft`
+ */
+type ScrollToOption = 'topleft' | 'visible';
+/** Specifies the direction over which lists should implement virtual scrolling */
+type ScrollLayout = "horizontal" | "vertical";
 
+/** Direction of scrolling */
 type ScrollDirection = "forward" | "backward";
+/**
+ * Overall scroll state for a single dimension.
+ */
 interface ScrollState {
+    /** Scroll bar offset. Equal to outer container's `scrollTop` or `scrollLeft` depending on dimension.  */
     scrollOffset: number;
+    /** Offset used to position current page of items in virtual space. Overall offset is `scrollOffset+renderOffset`. */
     renderOffset: number;
+    /** Index of current page. */
     page: number;
+    /** Current scrolling direction. Calculated by comparing current overall offset to that when last rendered. */
     scrollDirection: ScrollDirection;
 }
 
-interface VirtualGridItemProps extends VirtualBaseItemProps {
+/**
+ * Custom ref handle returned by {@link VirtualScroll} that exposes imperative methods
+ *
+ * Use `React.useRef<VirtualScrollProxy>(null)` to create a ref.
+ */
+interface VirtualScrollProxy {
+    /**
+     * Scrolls to the specified vertical and horizontal offset in pixels
+     * Either offset can be left undefined to scroll in one dimension only
+     * @param verticalOffset - Offset to scroll to vertically
+     * @param horizontalOffset - Offset to scroll to horizontally
+     */
+    scrollTo(verticalOffset?: number, horizontalOffset?: number): void;
+    /**
+   * Scrolls to the specified area
+   * Either offset/size pair can be left undefined to scroll in one dimension only
+   * @param verticalOffset - Offset to scroll to vertically
+   * @param verticalSize - Size of target area vertically
+   * @param horizontalOffset - Offset to scroll to horizontally
+   * @param horizontalSize - Size of target area horizontally
+   * @param option - Where to {@link ScrollToOption | position} the area within the viewport
+   */
+    scrollToArea(verticalOffset?: number, verticalSize?: number, horizontalOffset?: number, horizontalSize?: number, option?: ScrollToOption): void;
+    /** Exposes DOM clientWidth property */
+    get clientWidth(): number;
+    /** Exposes DOM clientHeight property */
+    get clientHeight(): number;
+}
+/**
+ * Returns the offset needed to scroll in one dimension for a specified range
+ *
+ * Used internally to implement {@link VirtualScrollProxy.scrollToArea}. Can be used directly for
+ * advanced customization scenarios.
+ */
+declare function getOffsetToScrollRange(offset: number | undefined, size: number | undefined, clientExtent: number, scrollOffset: number, option?: ScrollToOption): number | undefined;
+
+/**
+ * Props that an implementation of {@link VirtualContentRender} must accept.
+ */
+interface VirtualContentProps {
+    /**
+     * Is the owning component being actively scrolled? Used to change how the content is rendered depending on scroll state.
+     *
+     * Only defined if {@link VirtualScrollableProps.useIsScrolling} is true.
+     * */
+    isScrolling?: boolean;
+}
+/**
+ * Render prop for content container in {@link VirtualScroll}
+ *
+ * Pass to {@link VirtualScroll} to render content into the viewport
+ * implementation. Function must render a div and forward {@link VirtualContentProps}
+ * and any `ref` to it.
+ *
+ * @example Minimal compliant implementation
+ * ```
+ * const contentRender: VirtualContentRender = ({isScrolling, ...rest}, ref) => (
+ *   <div ref={ref} {...rest} />
+ * )
+ * ```
+ */
+type VirtualContentRender = (props: VirtualContentProps, ref?: React$1.ForwardedRef<HTMLDivElement>) => JSX.Element;
+/**
+ * Props accepted by {@link VirtualScroll}
+ */
+interface VirtualScrollProps extends VirtualScrollableProps {
+    /** Function implementing {@link VirtualContentRender} that renders the content that needs to respond to scrolling */
+    children: VirtualContentRender;
+    /**
+     * Height of area to scroll over
+     *
+     * @defaultValue 0
+     */
+    scrollHeight?: number;
+    /**
+     * Width of area to scroll over
+     *
+     * @defaultValue 0
+     */
+    scrollWidth?: number;
+    /**
+     * Callback after a scroll event has been processed and state updated but before rendering
+     * @param verticalOffset - Resulting overall vertical offset.
+     * @param horizontalOffset - Resulting overall horizontal offset.
+     * @param newVerticalScrollState - New vertical {@link ScrollState} that will be used for rendering.
+     * @param newHorizontalScrollState - New horizontal {@link ScrollState} that will be used for rendering.
+     */
+    onScroll?: (verticalOffset: number, horizontalOffset: number, newVerticalScrollState: ScrollState, newHorizontalScrollState: ScrollState) => void;
+    /** Render prop implementing {@link VirtualContainerRender}. Used to customize {@link VirtualScroll} outer container. */
+    outerRender?: VirtualContainerRender;
+    /** Render prop implementing {@link VirtualContainerRender}. Used to customize {@link VirtualScroll} inner container. */
+    innerRender?: VirtualContainerRender;
+}
+/**
+ * Customizable Virtual Scrolling Component
+ *
+ * Allows user to scroll over a virtual area `scrollHeight` x `scrollWidth` pixels.
+ * Use `onScroll` to track scroll state and `innerRender` to render scroll state specific content into the viewport
+ *
+ * Accepts props defined by {@link VirtualScrollProps}.
+ * Refs are forwarded to {@link VirtualScrollProxy}.
+ * @group Components
+ */
+declare const VirtualScroll: React$1.ForwardRefExoticComponent<VirtualScrollProps & React$1.RefAttributes<VirtualScrollProxy>>;
+
+/**
+ * Props accepted by {@link DisplayListItem}
+ */
+interface DisplayListItemProps extends DisplayBaseItemProps {
+    /** Index of item in the list being rendered */
+    index: number;
+}
+/**
+ * Type of item in a {@link DisplayList}
+ *
+ * Must be passed as a child to {@link DisplayList}.
+ * Accepts props defined by {@link DisplayListItemProps}.
+ * Component must pass {@link DisplayBaseItemProps.style} to whatever it renders.
+ *
+ * @example Basic implementation
+ * ```
+ * const Row = ({ index, style }: { index: number, style: React.CSSProperties }) => (
+ *   <div className="row" style={style}>
+ *     { index }
+ *   </div>
+ * );
+ * ```
+ */
+type DisplayListItem = React$1.ComponentType<DisplayListItemProps>;
+/**
+ * Props accepted by {@link DisplayList}
+ */
+interface DisplayListProps extends DisplayBaseProps {
+    /** Component used as a template to render items in the list. Must implement {@link DisplayListItem} interface. */
+    children: DisplayListItem;
+    /** Number of items in the list */
+    itemCount: number;
+    /** Offset to start of displayed content */
+    offset: number;
+    /**
+     * Implementation of {@link ItemOffsetMapping} interface that defines size and offset to each item in the list
+     *
+     * Use {@link useFixedSizeItemOffsetMapping} or {@link useVariableSizeItemOffsetMapping} to create implementations
+     * for common cases.
+     */
+    itemOffsetMapping: ItemOffsetMapping;
+    /**
+     * Function that defines the key to use for each item given item index and value of {@link DisplayBaseProps.itemData}.
+     * @defaultValue `(index, _data) => index`
+     */
+    itemKey?: (index: number, data: unknown) => React$1.Key;
+    /**
+     * Choice of 'vertical' or 'horizontal' layouts
+     * @defaultValue 'vertical'
+     */
+    layout?: ScrollLayout;
+}
+/**
+ * Displays a window onto the contents of a virtualized list starting from `offset`.
+ *
+ * Accepts props defined by {@link DisplayListProps}.
+ * You must pass a single instance of {@link DisplayListItem} as a child.
+ * @group Components
+ */
+declare function DisplayList(props: DisplayListProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Props accepted by {@link DisplayGridItem}
+ */
+interface DisplayGridItemProps extends DisplayBaseItemProps {
+    /** Row index of item in the grid being rendered */
     rowIndex: number;
+    /** Column index of item in the grid being rendered */
     columnIndex: number;
 }
-type VirtualGridItem = React.ComponentType<VirtualGridItemProps>;
-interface VirtualGridProps extends VirtualBaseProps {
-    children: VirtualGridItem;
+/**
+ * Type of item in a {@link DisplayGrid}
+ *
+ * Must be passed as a child to {@link DisplayGrid}.
+ * Accepts props defined by {@link DisplayGridItemProps}.
+ * Component must pass {@link DisplayBaseItemProps.style} to whatever it renders.
+ *
+ * @example Basic implementation
+ * ```
+ * const Row = ({ index, style }: { index: number, style: React.CSSProperties }) => (
+ *   <div className="row" style={style}>
+ *     { index }
+ *   </div>
+ * );
+ * ```
+ */
+type DisplayGridItem = React$1.ComponentType<DisplayGridItemProps>;
+/**
+ * Props accepted by {@link DisplayGrid}
+ */
+interface DisplayGridProps extends DisplayBaseProps {
+    /** Component used as a template to render items in the list. Must implement {@link DisplayGridItem} interface. */
+    children: DisplayGridItem;
+    /** Number of rows in the grid */
     rowCount: number;
+    /**
+     * Implementation of {@link ItemOffsetMapping} interface that defines size and offset to each row in the grid
+     *
+     * Use {@link useFixedSizeItemOffsetMapping} or {@link useVariableSizeItemOffsetMapping} to create implementations
+     * for common cases.
+     */
     rowOffsetMapping: ItemOffsetMapping;
+    /** Number of columns in the grid */
     columnCount: number;
+    /**
+     * Implementation of {@link ItemOffsetMapping} interface that defines size and offset to each column in the grid
+     *
+     * Use {@link useFixedSizeItemOffsetMapping} or {@link useVariableSizeItemOffsetMapping} to create implementations
+     * for common cases.
+     */
     columnOffsetMapping: ItemOffsetMapping;
-    itemKey?: (rowIndex: number, columnIndex: number, data: any) => any;
-    onScroll?: (rowOffset: number, columnOffset: number, newRowScrollState: ScrollState, newColumnScrollState: ScrollState) => void;
-    outerComponent?: VirtualOuterComponent;
-    innerComponent?: VirtualInnerComponent;
+    /** Vertical offset to start of displayed content */
+    rowOffset: number;
+    /** Horizontal offset to start of displayed content */
+    columnOffset: number;
+    /**
+     * Function that defines the key to use for each item given row and column index and value of {@link DisplayBaseProps.itemData}.
+     * @defaultValue
+     * ```ts
+     * (rowIndex, columnIndex, _data) => `${rowIndex}:${columnIndex}`
+     * ```
+     */
+    itemKey?: (rowIndex: number, columnIndex: number, data: unknown) => React$1.Key;
 }
+/**
+ * Displays a window onto the contents of a virtualized grid starting from `rowOffset`, `columnOffset`.
+ *
+ * Accepts props defined by {@link DisplayGridProps}.
+ * You must pass a single instance of {@link DisplayGridItem} as a child.
+ * @group Components
+ */
+declare function DisplayGrid(props: DisplayGridProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Custom ref handle returned by {@link VirtualGrid} that exposes imperative methods
+ *
+ * Use `React.useRef<VirtualGridProxy>(null)` to create a ref.
+ */
 interface VirtualGridProxy {
-    scrollTo(rowOffset: number, columnOffset: number): void;
-    scrollToItem(rowIndex: number, columnIndex: number): void;
+    /**
+     * Scrolls the list to the specified row and column in pixels
+     */
+    scrollTo(rowOffset?: number, columnOffset?: number): void;
+    /**
+     * Scrolls the list so that the specified item is visible
+     * @param rowIndex - Row of item to scroll to
+     * @param columnIndex - Column of item to scroll to
+     * @param option - Where to {@link ScrollToOption | position} the item within the viewport
+     */
+    scrollToItem(rowIndex?: number, columnIndex?: number, option?: ScrollToOption): void;
+    /** Exposes DOM clientWidth property */
+    get clientWidth(): number;
+    /** Exposes DOM clientHeight property */
+    get clientHeight(): number;
 }
-declare const VirtualGrid: React.ForwardRefExoticComponent<VirtualGridProps & React.RefAttributes<VirtualGridProxy>>;
+/** Range to scroll to in one dimension specified as (offset,size). May be undefined if no need to scroll. */
+type ScrollRange = [offset: number | undefined, size: number | undefined];
+/**
+ * Returns the {@link ScrollRange} corresponding to a specified item.
+ *
+ * Used internally to implement {@link VirtualGridProxy.scrollToItem}. Can be used directly for
+ * advanced customization scenarios.
+ */
+declare function getRangeToScroll(index: number | undefined, mapping: ItemOffsetMapping): ScrollRange;
+/**
+ * Same logic as {@link VirtualGridProxy.scrollToItem} usable with your own {@link VirtualScroll}
+ *
+ * You're encouraged to put together your own combination of {@link VirtualScroll} and {@link DisplayGrid} for
+ * advanced customization scenarios. This function provides `ScrollToItem` functionality for use with your own {@link VirtualScroll}.
+ */
+declare function virtualGridScrollToItem(scrollRef: React.RefObject<VirtualScrollProxy>, rowOffsetMapping: ItemOffsetMapping, columnOffsetMapping: ItemOffsetMapping, rowIndex?: number, columnIndex?: number, option?: ScrollToOption): void;
 
-type ScrollLayout = "horizontal" | "vertical";
-interface VirtualListItemProps extends VirtualBaseItemProps {
-    index: number;
+/**
+ * Props accepted by {@link VirtualGrid}
+ */
+interface VirtualGridProps extends VirtualBaseProps {
+    /** Component used as a template to render items in the grid. Must implement {@link DisplayGridItem} interface. */
+    children: DisplayGridItem;
+    /** Number of rows in the grid */
+    rowCount: number;
+    /**
+     * Implementation of {@link ItemOffsetMapping} interface that defines size and offset to each row in the grid
+     *
+     * Use {@link useFixedSizeItemOffsetMapping} or {@link useVariableSizeItemOffsetMapping} to create implementations
+     * for common cases.
+     */
+    rowOffsetMapping: ItemOffsetMapping;
+    /** Number of columns in the grid */
+    columnCount: number;
+    /**
+     * Implementation of {@link ItemOffsetMapping} interface that defines size and offset to each column in the grid
+     *
+     * Use {@link useFixedSizeItemOffsetMapping} or {@link useVariableSizeItemOffsetMapping} to create implementations
+     * for common cases.
+     */
+    columnOffsetMapping: ItemOffsetMapping;
+    /**
+     * Function that defines the key to use for each item given row and column index and value of {@link VirtualBaseProps.itemData}.
+     * @defaultValue
+     * ```ts
+     * (rowIndex, columnIndex, _data) => `${rowIndex}:${columnIndex}`
+     * ```
+     */
+    itemKey?: (rowIndex: number, columnIndex: number, data: unknown) => React$1.Key;
+    /**
+     * Callback after a scroll event has been processed and state updated but before rendering
+     * @param rowOffset - Resulting overall row offset. Can be passed to {@link ItemOffsetMapping} to determine first row.
+     * @param columnOffset - Resulting overall column offset. Can be passed to {@link ItemOffsetMapping} to determine first column.
+     * @param newRowScrollState - New {@link ScrollState} for rows that will be used for rendering.
+     * @param newColumnScrollState - New {@link ScrollState} for columns that will be used for rendering.
+     */
+    onScroll?: (rowOffset: number, columnOffset: number, newRowScrollState: ScrollState, newColumnScrollState: ScrollState) => void;
+    /** Render prop implementing {@link VirtualContainerRender}. Used to customize {@link VirtualGrid} outer container. */
+    outerRender?: VirtualContainerRender;
+    /** Render prop implementing {@link VirtualContainerRender}. Used to customize {@link DisplayGrid} within {@link VirtualGrid} inner container. */
+    innerRender?: VirtualContainerRender;
+}
+/**
+ * Virtual Scrolling Grid
+ *
+ * Accepts props defined by {@link VirtualGridProps}.
+ * Refs are forwarded to {@link VirtualGridProxy}.
+ * You must pass a single instance of {@link DisplayGridItem} as a child.
+ * @group Components
+ */
+declare const VirtualGrid: React$1.ForwardRefExoticComponent<VirtualGridProps & React$1.RefAttributes<VirtualGridProxy>>;
+
+/**
+ * Custom ref handle returned by {@link VirtualList} that exposes imperative methods
+ *
+ * Use `React.useRef<VirtualListProxy>(null)` to create a ref.
+ */
+interface VirtualListProxy {
+    /**
+     * Scrolls the list to the specified offset in pixels
+     * @param offset - Offset to scroll to
+     */
+    scrollTo(offset: number): void;
+    /**
+     * Scrolls the list so that the specified item is visible
+     * @param index - Index of item to scroll to
+     * @param option - Where to {@link ScrollToOption | position} the item within the viewport
+     */
+    scrollToItem(index: number, option?: ScrollToOption): void;
 }
-type VirtualListItem = React.ComponentType<VirtualListItemProps>;
+/**
+ * Same logic as {@link VirtualListProxy.scrollToItem} usable with your own {@link VirtualScroll}
+ *
+ * You're encouraged to put together your own combination of {@link VirtualScroll} and {@link DisplayList} for
+ * advanced customization scenarios. This function provides `ScrollToItem` functionality for use with your own {@link VirtualScroll}.
+ */
+declare function virtualListScrollToItem(scrollRef: React.RefObject<VirtualScrollProxy>, itemOffsetMapping: ItemOffsetMapping, isVertical: boolean, index: number, option?: ScrollToOption): void;
+
+/**
+ * Props accepted by {@link VirtualList}
+ */
 interface VirtualListProps extends VirtualBaseProps {
-    children: VirtualListItem;
+    /** Component used as a template to render items in the list. Must implement {@link DisplayListItem} interface. */
+    children: DisplayListItem;
+    /** Number of items in the list */
     itemCount: number;
+    /**
+     * Implementation of {@link ItemOffsetMapping} interface that defines size and offset to each item in the list
+     *
+     * Use {@link useFixedSizeItemOffsetMapping} or {@link useVariableSizeItemOffsetMapping} to create implementations
+     * for common cases.
+     */
     itemOffsetMapping: ItemOffsetMapping;
-    itemKey?: (index: number, data: any) => any;
+    /**
+     * Function that defines the key to use for each item given item index and value of {@link VirtualBaseProps.itemData}.
+     * @defaultValue `(index, _data) => index`
+     */
+    itemKey?: (index: number, data: unknown) => React$1.Key;
+    /**
+     * Choice of 'vertical' or 'horizontal' layouts
+     * @defaultValue 'vertical'
+     */
     layout?: ScrollLayout;
+    /**
+     * Callback after a scroll event has been processed and state updated but before rendering
+     * @param offset - Resulting overall offset. Can be passed to {@link ItemOffsetMapping} to determine top item.
+     * @param newScrollState - New {@link ScrollState} that will be used for rendering.
+     */
     onScroll?: (offset: number, newScrollState: ScrollState) => void;
-    outerComponent?: VirtualOuterComponent;
-    innerComponent?: VirtualInnerComponent;
+    /** Render prop implementing {@link VirtualContainerRender}. Used to customize {@link VirtualList} outer container. */
+    outerRender?: VirtualContainerRender;
+    /** Render prop implementing {@link VirtualContainerRender}. Used to customize {@link DisplayList} within {@link VirtualList} inner container. */
+    innerRender?: VirtualContainerRender;
 }
-interface VirtualListProxy {
-    scrollTo(offset: number): void;
-    scrollToItem(index: number): void;
-}
-declare const VirtualList: React.ForwardRefExoticComponent<VirtualListProps & React.RefAttributes<VirtualListProxy>>;
+/**
+ * Virtual Scrolling List
+ *
+ * Accepts props defined by {@link VirtualListProps}.
+ * Refs are forwarded to {@link VirtualListProxy}.
+ * You must pass a single instance of {@link DisplayListItem} as a child.
+ * @group Components
+ */
+declare const VirtualList: React$1.ForwardRefExoticComponent<VirtualListProps & React$1.RefAttributes<VirtualListProxy>>;
 
-declare class FixedSizeItemOffsetMapping implements ItemOffsetMapping {
-    constructor(itemSize: number);
-    itemSize(_itemIndex: number): number;
-    itemOffset(itemIndex: number): number;
-    offsetToItem(offset: number): [itemIndex: number, startOffset: number];
-    fixedItemSize: number;
-}
-declare function useFixedSizeItemOffsetMapping(itemSize: number): FixedSizeItemOffsetMapping;
+/**
+ * Returns an instance of {@link ItemOffsetMapping} suitable for use when all items have a fixed size.
+ *
+ * @param itemSize - Size to use for all items
+ */
+declare function useFixedSizeItemOffsetMapping(itemSize: number): ItemOffsetMapping;
 
-declare class VariableSizeItemOffsetMapping implements ItemOffsetMapping {
-    constructor(defaultItemSize: number, sizes: number[]);
-    itemSize(itemIndex: number): number;
-    itemOffset(itemIndex: number): number;
-    offsetToItem(offset: number): [itemIndex: number, startOffset: number];
-    defaultItemSize: number;
-    sizes: number[];
-}
-declare function useVariableSizeItemOffsetMapping(defaultItemSize: number, sizes?: number[]): VariableSizeItemOffsetMapping;
+/**
+ * Returns an instance of {@link ItemOffsetMapping} suitable for use when initial items have variable sizes.
+ *
+ * @param defaultItemSize - Size to use for all other items
+ * @param sizes - Array of sizes to use for the initial items, one size per item
+ */
+declare function useVariableSizeItemOffsetMapping(defaultItemSize: number, sizes?: number[]): ItemOffsetMapping;
 
-export { type ScrollLayout, type ScrollState, VirtualGrid, type VirtualGridItemProps, type VirtualGridProps, type VirtualGridProxy, type VirtualInnerProps, VirtualList, type VirtualListItemProps, type VirtualListProps, type VirtualListProxy, type VirtualOuterProps, useFixedSizeItemOffsetMapping, useVariableSizeItemOffsetMapping };
+export { AutoSizer, type AutoSizerProps, type AutoSizerRender, type AutoSizerRenderProps, type ComponentProps, type DisplayBaseItemProps, type DisplayBaseProps, DisplayGrid, type DisplayGridItem, type DisplayGridItemProps, type DisplayGridProps, DisplayList, type DisplayListItem, type DisplayListItemProps, type DisplayListProps, type ItemOffsetMapping, type ScrollDirection, type ScrollEvent, type ScrollLayout, type ScrollRange, type ScrollState, type ScrollToOption, type VirtualBaseProps, VirtualContainer, type VirtualContainerComponentProps, type VirtualContainerRender, type VirtualContainerRenderProps, type VirtualContentProps, type VirtualContentRender, VirtualGrid, type VirtualGridProps, type VirtualGridProxy, VirtualList, type VirtualListProps, type VirtualListProxy, VirtualScroll, type VirtualScrollProps, type VirtualScrollProxy, type VirtualScrollableProps, getOffsetToScrollRange, getRangeToScroll, useFixedSizeItemOffsetMapping, useVariableSizeItemOffsetMapping, virtualGridScrollToItem, virtualListScrollToItem };