import { default as default_2 } from 'react'; import { JSX as JSX_2 } from 'react/jsx-runtime'; /** * Specifies whether append-like data changes or rendered-item size changes should scroll to the bottom. * * Passing `false` or `undefined` preserves the current viewport. Passing `true` is equivalent to `'auto'`. Passing a `ScrollBehavior` directly applies only when the list is already at the bottom. * * Use the callback form when the policy needs access to `scrollLocation`, `atBottom`, `scrollInProgress`, `context`, or the operation data. In callback form, return `false` to preserve position, a `ScrollBehavior` to scroll the last item into view, or an {@link ItemLocation} for custom alignment. * * @typeParam Data - The type of the data items in the list. * @typeParam Context - The type of the context passed to the list. * * @group Scroll Location */ export declare type AutoscrollToBottom = ItemLocationCallback | NonNullable | boolean; /** * A function that describes the easing curve for the scroll animation. * See {@link https://easings.net/ | easings.net} for examples of easing functions. * * @group Scroll Animation */ export declare type BezierFunction = (x: number) => number; /* Excluded from this release type: ComputeItemKey */ /** * Used for the custom components that accept the message list context prop. * @typeParam Context - The type of the context passed to the list. * * @group Customization */ export declare type ContextAwareComponent = React.ComponentType<{ /** * The value currently passed to the `context` prop of the `VirtuosoMessageList` component. */ context: Context; }>; /* Excluded from this release type: Data */ /* Excluded from this release type: DataAppendParams */ /** * Parameters passed to callbacks when data changes in the list. * @typeParam Data - The type of the data items in the list. * * @group State */ export declare interface DataChangeParams { newData: Data; autoscrollToBottomBehavior?: ScrollBehavior_2 | { location: () => ItemLocation | null | undefined; }; } /* Excluded from this release type: DataInsertParams */ /* Excluded from this release type: DataMapParams */ /** * Methods for manipulating the data in the list. * @typeParam Data - The type of the data items in the list. * @typeParam Context - The type of the context passed to the list. * * @group Imperative API */ export declare interface DataMethods { /** * Prepends additional items to the existing data in the list, while preserving the scroll position. * @param data - The data to prepend. */ prepend: (data: Data[]) => void; /** * Appends additional items to the existing data in the list, while optionally updating the scroll position. See the {@link AutoscrollToBottom} type for more information. * @param data - The data to append. * @param scrollToBottom - Specifies the behavior when the list is scrolled to the bottom. You can pass a boolean, a `ScrollBehavior`, or a function that returns a `ScrollBehavior`. */ append: (data: Data[], scrollToBottom?: AutoscrollToBottom) => void; /** * Updates the data in the list by applying a mapping function to each item. Optionally, you can specify a scroll behavior if the state change displaces the list (for example, if the item size increases). * @param callbackfn - A function that maps the data items. * @param autoscrollToBottomBehavior - Specifies the behavior to use to scroll to the bottom if necessary. */ map: (callbackfn: (data: Data, index: number) => Data, autoscrollToBottomBehavior?: ScrollBehavior_2 | { location: () => ItemLocation | null | undefined; }) => void; /** * Updates the data in the list by applying a mapping function to each item, while keeping the specified item anchored in the viewport. This is useful when the size of some items change, and you want to avoid displacing the scroll position. * @param callbackfn - A function that maps the data items. * @param anchorItemIndex - the index of the item to keep anchored in the viewport. */ mapWithAnchor: (callbackfn: (data: Data, index: number) => Data, anchorItemIndex: number) => void; /** * Deletes items from the list data that match the predicate. * @param predicate - A function that returns `true` for items that should be deleted. */ findAndDelete: (predicate: (item: Data, index: number) => boolean) => void; /** * Finds the index of the first item that matches the predicate. If no elements satisfy the testing function, -1 is returned. * @param predicate - A function that returns `true` for the item being searched for. */ findIndex: (predicate: (item: Data, index: number, data: Data[]) => boolean) => number; /** * Finds the first item that matches the predicate. If no elements satisfy the testing function, `undefined` is returned. * @param predicate - A function that returns `true` for the item being searched for. */ find: (predicate: (item: Data, index: number, data: Data[]) => boolean) => Data | undefined; /** * Completely replaces the data in the list with the new data. * Optionally, you can specify an initial scroll location after the data has been replaced. * See the {@link ItemLocation} type for more information. * Setting the `purgeItemSizes` flag to `true` will clear the item size cache and force the list to remeasure the items. * The `suppressItemMeasure` flag will prevent the list from measuring the items after the data has been replaced. * * @param data - The data to replace. * @param options - The location to scroll to after the data has been replaced and whether to purge the item sizes. * */ replace: (data: Data[], options?: { initialLocation?: ItemLocation; purgeItemSizes?: boolean; suppressItemMeasure?: boolean; }) => void; /** * Inserts the provided data at the specified offset, optionally updating the scroll position. * @param data - The data to insert. * @param offset - The index that the first item in the data will be inserted at. e.g. [1,2,3] with offset 10 will insert the data at index 10, 11, and 12 and shift the rest of the existing data. * @param scrollToBottom - Specifies the behavior when the list is scrolled to the bottom. You can pass a boolean, a `ScrollBehavior`, or a function that returns a `ScrollBehavior`. */ insert: (data: Data[], offset: number, scrollToBottom?: AutoscrollToBottom) => void; /** * Deletes a range of items from the list data. * @param offset - The index of the first item to delete. * @param count - The number of items to delete. */ deleteRange: (offset: number, count: number) => void; /** * Batches the data operations in the provided callback in a single render cycle. * @param callback - The callback that performs the data operations. * @param scrollToBottom - Specifies the behavior when the list is scrolled to the bottom. You can pass a boolean, a `ScrollBehavior`, or a function that returns a `ScrollBehavior`. */ batch: (callback: () => void, scrollToBottom?: AutoscrollToBottom) => void; /** * Gets a shallow copy of the current data in the list. */ get: () => Data[]; /** * Gets the currently rendered data items. */ getCurrentlyRendered: () => Data[]; /** * Removes the specified amount of items from the start of the list. * @param count - The number of items to remove. */ removeFromStart: (count: number) => void; } /* Excluded from this release type: DataRemoveRangeParams */ /* Excluded from this release type: DataReplaceParams */ /** * The shape of the message list `data` prop. It includes the data to render and any extra scroll position modification that should be applied when the data changes. * @typeParam Data - The type of the data items in the list. * * @group State */ export declare interface DataWithScrollModifier { data: Data[] | null | undefined; scrollModifier?: ScrollModifier; } /** * The type of the component used to wrap the `Footer` custom component. * * @group Customization */ export declare type FooterWrapperComponent = React.ComponentType<{ style: React.CSSProperties; children: React.ReactNode; } & React.RefAttributes>; /** * The type of the component used to wrap the `Header` custom component. * * @group Customization */ export declare type HeaderWrapperComponent = React.ComponentType<{ style: React.CSSProperties; children: React.ReactNode; } & React.RefAttributes>; /* Excluded from this release type: Item */ /** * A React component that's used to render the individual item. * @typeParam Data - The type of the data items in the list. * @typeParam Context - The type of the context passed to the list. * * @group Customization */ export declare type ItemContent = React.ComponentType<{ /** * The index of the item in the list data array. */ index: number; /** * The data item to render. */ data: Data; /** * The previous data item (if available). */ prevData: Data | null; /** * The next data item (if available). */ nextData: Data | null; /** * The value of the `context` prop passed to the list. */ context: Context; }>; /** * A location in the list to scroll to. Passing a number scrolls instantly to the item at the specified index aligned to the top. See {@link ItemLocationWithAlign} for more advanced options. * * @group Scroll Location */ export declare type ItemLocation = number | ItemLocationWithAlign; /** * A callback function that determines whether a data or rendered-item size change should scroll. * * Return `false` to preserve the current viewport. Return `true` or a `ScrollBehavior` to scroll to the bottom. Return an {@link ItemLocation} to scroll to a specific item. * * The callback receives the scroll location from before the change is applied. In callback form, returning a `ScrollBehavior` or {@link ItemLocation} scrolls even when `atBottom` is `false`; return `false` when a scrolled-up user should stay where they are. * * @typeParam Data - The type of the data items in the list. * @typeParam Context - The type of the context passed to the list. * * @group Scroll Location */ export declare type ItemLocationCallback = (params: ItemLocationCallbackParams) => ScrollBehavior_2 | boolean | ItemLocation; /** * The parameters passed to the {@link ItemLocationCallback} function. * @typeParam Data - The type of the data items in the list. * @typeParam Context - The type of the context passed to the list. * * @group Scroll Location */ export declare interface ItemLocationCallbackParams { /** * The location of the list before the data or rendered-item size change. See {@link ListScrollLocation} for the details of the parameter received. */ scrollLocation: ListScrollLocation; /** * Indicates whether the list is currently scrolling. If you receive fast updates and use `'smooth'` scrolling, there's a chance that the list will be in the middle of a scroll when new data arrives. */ scrollInProgress: boolean; /** * Whether the list is at the bottom before the data change. */ atBottom: boolean; /** * The data supplied by the operation that triggered the policy. * For append and insert operations, this is the added data. For declarative data updates, this is the next data array. For `notifyItemsChanged`, this is the current list data. */ data: Data[]; /** * The context passed to the list. */ context: Context; } /** * Specifies a location in the list to scroll to. * * @group Scroll Location */ export declare interface ItemLocationWithAlign { /** * The index of the item to scroll to. Use `'LAST'` to scroll to the last item. */ index: number | 'LAST'; /** * How to align the item in the viewport. */ align?: 'start' | 'center' | 'end' | 'start-no-overflow'; /** * Set `'smooth'` to have an animated transition to the specified location. */ behavior?: ScrollBehavior_2; /** * Use the offset for additional adjustment of the position - can be a positive or negative number. */ offset?: number; /** * A callback that's invoked when the scroll is complete. */ done?: () => void; } /** * Describes the location of the list relative to the viewport and the scroll element. * * @group State */ export declare interface ListScrollLocation { /** * The distance between the list top edge and the viewport top edge. * When the list is above the viewport (when scrolling down), this value is a negative number. When the list is scrolled to the top, this value is `0`. */ listOffset: number; /** * The height of the visible portion of the list without any headers and footers. */ visibleListHeight: number; /** * The scroll height of the scroller wrapper. */ scrollHeight: number; /** * The distance between the scroller element bottom edge and the viewport bottom edge. * If `0`, the list is at the bottom. */ bottomOffset: number; /** * A convenience flag that indicates whether the list is at the bottom. The flag is also true when the list is currently scrolling to the bottom. */ isAtBottom: boolean; /** * The index of the bottom-most item visible in the viewport. */ lastVisibleItemIndex: number; /** * The pixel distance from the bottom edge of the last visible item to the viewport bottom edge. `0` means the item's bottom is flush with the viewport bottom. */ lastItemBottomOffset: number; } /** * Options for notifying the list that rendered item content may have changed size without changing the data array. * * @group Scroll Location */ export declare interface NotifyItemsChangedOptions { /** * Specifies whether the list should scroll to the bottom if rendered items grow. * * Use the callback form to inspect the pre-change `scrollLocation`, `atBottom`, `scrollInProgress`, `context`, and current `data`. Return `false` to keep a scrolled-up user at the same location. */ scrollToBottom: AutoscrollToBottom; } /* Excluded from this release type: OffsetPoint */ /** * The scroll behavior to use when scrolling to a location. * You can also pass a custom scroll behavior function that returns an object with the number of animation frames and the easing function based on the current scroll top and the targetTop. * * @group Scroll Animation */ declare type ScrollBehavior_2 = 'smooth' | 'auto' | 'instant' | ((currentTop: number, targetTop: number) => { animationFrameCount: number; easing: BezierFunction; }); export { ScrollBehavior_2 as ScrollBehavior } /** * The type of the component that can be used for the scroll element. * @typeParam Context - The type of the context passed to the list. * * @group Customization */ export declare type ScrollElementComponent = React.ComponentType & { context?: Context; } & React.RefAttributes>; /** * The DOM attributes that you can pass to the `VirtuosoMessageList` component to customize the scroll element. * * @group Components * @noInheritDoc */ export declare type ScrollerProps = Omit, 'ref' | 'data' | 'onScroll'>; /** * Describes the scroll modification to perform when the data of the list is updated. * See [the scroll modifier](https://virtuoso.dev/virtuoso-message-list/scroll-modifier/) documentation section for examples of how to use this type. * * @group Scroll Location */ export declare type ScrollModifier = null | undefined | { type: 'item-location'; location: ItemLocation; purgeItemSizes?: boolean; } | { type: 'auto-scroll-to-bottom'; autoScroll: AutoscrollToBottom; } | { type: 'items-change'; behavior: ScrollBehavior_2 | { location: () => ItemLocation | null | undefined; }; } | ScrollModifierOptionValue; /** * Predefined scroll modifier options for common data operations. * * @group Scroll Location */ export declare const ScrollModifierOption: { readonly prepend: "prepend"; readonly removeFromStart: "remove-from-start"; readonly removeFromEnd: "remove-from-end"; }; /** * The type of the {@link ScrollModifierOption} constant. * * @group Scroll Location */ export declare type ScrollModifierOptionType = typeof ScrollModifierOption; /** * The possible values of the {@link ScrollModifierOption} constant. * * @group Scroll Location */ export declare type ScrollModifierOptionValue = ScrollModifierOptionType[keyof ScrollModifierOptionType]; /** * Always scrolls the last item into view. * * The helper uses a smooth scroll while the list is already at the bottom or scrolling to the bottom, and an instant scroll otherwise. * Use this for local actions, such as sending the current user's message, where the new item should become visible even if the user was scrolled up. * * @group Scroll Location */ export declare function scrollToBottomAlways({ atBottom, scrollInProgress, }: ItemLocationCallbackParams): ItemLocation; /** * Scrolls to the bottom only if the list was already at the bottom or is already scrolling to the bottom. * * Use this for incoming messages or row growth where a scrolled-up user should stay at their current location. * * @group Scroll Location */ export declare function scrollToBottomIfAtBottom({ atBottom, scrollInProgress, }: ItemLocationCallbackParams): ScrollBehavior_2 | false; /** * Specifies the alignment of the items when the content of the list is smaller than the viewport height. * - `'top'` (default), the items will be aligned to the top * - `'bottom'`, the items will be aligned to the bottom. * - `'bottom-smooth'`, the items will be aligned to the bottom and the scroll will be animated. * * @group Scroll Location */ export declare type ShortSizeAlign = 'top' | 'bottom' | 'bottom-smooth'; /* Excluded from this release type: SizeRange */ /** * The type of the component used to wrap the `StickyFooter` custom component. * * @group Customization */ export declare type StickyFooterWrapperComponent = React.ComponentType<{ style: React.CSSProperties; children: React.ReactNode; } & React.RefAttributes>; /** * The type of the component used to wrap the `StickyHeader` custom component. * * @group Customization */ export declare type StickyHeaderWrapperComponent = React.ComponentType<{ style: React.CSSProperties; children: React.ReactNode; } & React.RefAttributes>; /** * Lets you access the currently rendered data items. * @typeParam Data - The type of the data items in the list. * * @group Hooks */ export declare function useCurrentlyRenderedData(): Data[]; /** * Lets you access the current scroll location of the message list component from its child components. See {@link ListScrollLocation} for the available properties. * * @group Hooks */ export declare function useVirtuosoLocation(): ListScrollLocation; /** * Lets you access the message list methods from its child components. See {@link VirtuosoMessageListMethods} for the available methods. * @typeParam Data - The type of the data items in the list. * @typeParam Context - The type of the context passed to the list. * * @group Hooks */ export declare function useVirtuosoMethods(): VirtuosoMessageListMethods; /** * * The React component that renders the message list. Refer to {@link VirtuosoMessageListProps} for the accepted props. * The component accepts a ref that can be used to call methods on the message list. See {@link VirtuosoMessageListMethods} for the available methods. * * You should wrap your message lists (either individually or at a higher level) in a {@link VirtuosoMessageListLicense} to provide the license key. * * @function * @group Components */ export declare const VirtuosoMessageList: (props: VirtuosoMessageListProps & { ref?: NoInfer>>; }) => default_2.ReactElement; /** * A component that provides a license key to the VirtuosoMessageList component. * This component must wrap all VirtuosoMessageList components in your application - either individually or at a common parent. * @param props {@link VirtuosoMessageListLicenseProps} * * @group Components */ export declare function VirtuosoMessageListLicense({ licenseKey, children }: VirtuosoMessageListLicenseProps): JSX_2.Element; /** * @inline */ declare interface VirtuosoMessageListLicenseProps { /** * The license key to use for the VirtuosoMessageList component. * Buy a license at https://virtuoso.dev/pricing. Leave empty for trial mode. */ licenseKey: string; /** * The child components that will have access to the license context. The message list components must be descendants of this component. */ children: default_2.ReactNode; } /** * The imperative API of the message list component. You can access it with a `ref`, or by using the {@link useVirtuosoMethods | `useVirtuosoMethods()`} hook from a child component. * @typeParam Data - The type of the data items in the list. Specifying this type gives you correct typing in the `data` methods. * @typeParam Context - The type of the context passed to the list. Specifying this type gives you correct typing in the `data` methods. * * @group Imperative API */ export declare interface VirtuosoMessageListMethods { /** * A set of methods to manipulate the data in the list. */ data: DataMethods; /** * Scrolls the list to the specified item. See {@link ItemLocation} for possible location details. Passing a number scrolls to the item at the specified index aligned to the top. */ scrollToItem: (location: ItemLocation) => void; /** * Scrolls the specified item into view if necessary. See {@link ItemLocation} for possible location details. Passing a number scrolls to the item at the specified index. */ scrollIntoView: (location: ItemLocation) => void; /** * Lets you obtain a reference to the component's scroller DOM element. */ scrollerElement: () => HTMLDivElement | null; /** * Retrieves the current scroll location */ getScrollLocation: () => ListScrollLocation; /** * Cancels the current smooth scroll operation, if any. */ cancelSmoothScroll: () => void; /** * Notifies the list that rendered item content may have changed size without a data change. * * Use this after changing external state that affects item rendering, such as `context` or side maps, when that state can resize rows without changing the data array. ResizeObserver performs the measurement; this method supplies the scroll policy for preserving bottom stickiness. */ notifyItemsChanged: (options: NotifyItemsChangedOptions) => void; /** * Gets the known height of the item. */ height: (item: Data) => number; } /** * The properties accepted by the `VirtuosoMessageList` component. * In addition to the properties listed here, you can pass any other props that are accepted by a `div` element. They will be passed to the root div element used for the scroll. * @typeParam Data - The type of the data items in the list. * @typeParam Context - The type of the context passed to the list. * * @noInheritDoc * @group Components */ export declare interface VirtuosoMessageListProps extends ScrollerProps { /** * The initial data to display in the list. * * :::note * This property does not accept updates after the initial mount of the component. * If you need to update the data, use the `data` property. * ::: */ initialData?: Data[]; /** * Any additional state that you need to use in the `ItemContent`, `Header`, `Footer`, etc. */ context?: Context; /** * The initial location to scroll to. It will be applied the first time the list is rendered with data. * Using this property allows you to skip rendering of the items at the top of the list. * * :::note * If you're using the `data` prop, you should be using the `scrollModifier` field for the positioning of the list after the data has been updated. * ::: */ initialLocation?: ItemLocation; /** * Computes the value for the React `key` prop for the item at the specified index. * * Use stable, unique keys for rendered items to avoid React reconciliation issues. This controls React rendering identity only; controlled data updates use {@link VirtuosoMessageListProps.itemIdentity} to match old and new data items. * * @param params - The parameters to compute the key. */ computeItemKey?: NoInfer<(params: { data: Data; index: number; context: Context; }) => React.Key>; /** * A React component that's used to render the individual item. See {@link ItemContent} for further details on the accepted props. */ ItemContent?: NoInfer>; /** * An optional React component to render above the list items. */ Header?: NoInfer>; /** * An optional React component to render above the list items that remains visible at the top of the viewport when scrolling. */ StickyHeader?: NoInfer>; /** * An optional React component to render below the list items. */ Footer?: NoInfer>; /** * An optional React component to render below the list items that remains visible at the bottom of the viewport when scrolling. */ StickyFooter?: NoInfer>; /** * An optional React component to render when the list has zero data items. */ EmptyPlaceholder?: NoInfer>; /** * An optional React component to replace the default scroller element. The default value is a `div` element. */ ScrollElement?: NoInfer>; /** * A callback that's invoked when the list is scrolled. See {@link ListScrollLocation} for the details of the parameter received. */ onScroll?: (location: ListScrollLocation) => void; /** * A callback that's invoked when the currently visible items change */ onRenderedDataChange?: (range: Data[]) => void; /** * Pass a custom component here if you need to adjust the z-index of the header container. The default value is `div` with `zIndex: 1`. */ HeaderWrapper?: HeaderWrapperComponent; /** * Pass a custom component here if you need to adjust the z-index of the sticky header container. The default value is `div` with `zIndex: 1`. */ StickyHeaderWrapper?: StickyHeaderWrapperComponent; /** * Pass a custom component here if you need to adjust the footer container. The default value is `div` element. */ FooterWrapper?: FooterWrapperComponent; /** * Pass a custom component here if you need to adjust the z-index of the sticky footer container. The default value is `div` element with `zIndex: 1`. */ StickyFooterWrapper?: StickyHeaderWrapperComponent; /** * Specifies the alignment of the items when the content of the list is smaller than the viewport height. * - `'top'` (default), the items will be aligned to the top * - `'bottom'`, the items will be aligned to the bottom. * - `'bottom-smooth'`, the items will be aligned to the bottom and the scroll will be animated. */ shortSizeAlign?: ShortSizeAlign; /** * Set to true to make the list use the document scroller rather than wrapping in its own. */ useWindowScroll?: boolean; /** * Pass an HTML element to use as the scroll element. This is useful when you want to include additional content in the scrollable area, or if you want to use a complex custom scroll component. */ customScrollParent?: HTMLElement | undefined | null; /** * Artificially extends the viewport size in both directions, causing more items to be rendered. * Useful if you have relatively heavy items or want images to be loaded before the user scrolls to them. * For example, setting the value to `100` would increase the viewport in both directions by `100` pixels, causing the list to render more items. */ increaseViewportBy?: number; /** * The data to display, and the scroll action to perform when the data changes. */ data?: DataWithScrollModifier | null | undefined; /** * Returns the identity used by controlled `data` prop updates to match existing items in a new data array. * * By default, the item object itself is used. Provide this when your app recreates item objects across updates and uses scroll modifiers that need to find the old items in the new array, such as `'prepend'` or `'remove-from-start'`. * * This is separate from {@link VirtuosoMessageListProps.computeItemKey}, which only controls the React `key` prop. */ itemIdentity?: (item: Data) => unknown; /** * Set to true to force the sticky footer to be always at the bottom, even if the item list is short. */ enforceStickyFooterAtBottom?: boolean; } /** * A React context that provides a controlled testing environment for VirtuosoMessageList. * When this context is provided, the component skips the ResizeObserver measurements and uses the values from the context instead. * * @group Testing */ export declare const VirtuosoMessageListTestingContext: default_2.Context; /** * The value expected by the {@link VirtuosoMessageListTestingContext}. Useful for testing components that use VirtuosoMessageList. * * @group Testing */ export declare interface VirtuosoMessageListTestingContextValue { /** * The simulated viewport height in pixels. */ viewportHeight: number; /** * The simulated item height in pixels. */ itemHeight: number; } export { }