392 lines
15 KiB
TypeScript
392 lines
15 KiB
TypeScript
|
import type { ComponentProps } from '@fluentui/react-utilities';
|
||
|
|
import type { ComponentState } from '@fluentui/react-utilities';
|
||
|
|
import type { Dispatch } from 'react';
|
||
|
|
import type { FC } from 'react';
|
||
|
|
import { MutableRefObject } from 'react';
|
||
|
|
import * as React_2 from 'react';
|
||
|
|
import type { RefObject } from 'react';
|
||
|
|
import type { SetStateAction } from 'react';
|
||
|
|
import type { Slot } from '@fluentui/react-utilities';
|
||
|
|
import type { SlotClassNames } from '@fluentui/react-utilities';
|
||
|
|
|
||
|
|
export declare const renderVirtualizer_unstable: (state: VirtualizerState) => JSX.Element;
|
||
|
|
|
||
|
|
export declare const renderVirtualizerScrollView_unstable: (state: VirtualizerScrollViewState) => JSX.Element;
|
||
|
|
|
||
|
|
export declare const renderVirtualizerScrollViewDynamic_unstable: (state: VirtualizerScrollViewDynamicState) => JSX.Element;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Additional direct Ref prevents reading old resize entry data
|
||
|
|
* Backwards compatible with ResizeObserverCallback if preferred
|
||
|
|
*/
|
||
|
|
export declare interface ResizeCallbackWithRef {
|
||
|
|
(entries: ResizeObserverEntry[], observer: ResizeObserver, scrollRef?: MutableRefObject<HTMLElement | null>): void;
|
||
|
|
}
|
||
|
|
|
||
|
|
export declare type ScrollToInterface = {
|
||
|
|
scrollTo: (index: number, behavior?: ScrollBehavior, callback?: (index: number) => void) => void;
|
||
|
|
virtualizerLength: RefObject<number>;
|
||
|
|
currentIndex: RefObject<number> | undefined;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare const scrollToItemDynamic: (params: ScrollToItemDynamicParams) => void;
|
||
|
|
|
||
|
|
export declare type ScrollToItemDynamicParams = {
|
||
|
|
index: number;
|
||
|
|
itemSizes: RefObject<number[]>;
|
||
|
|
totalSize: number;
|
||
|
|
scrollViewRef: RefObject<HTMLDivElement>;
|
||
|
|
axis?: 'horizontal' | 'vertical';
|
||
|
|
reversed?: boolean;
|
||
|
|
behavior?: ScrollBehavior;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare const scrollToItemStatic: (params: ScrollToItemStaticParams) => void;
|
||
|
|
|
||
|
|
export declare type ScrollToItemStaticParams = {
|
||
|
|
index: number;
|
||
|
|
itemSize: number;
|
||
|
|
totalItems: number;
|
||
|
|
scrollViewRef: RefObject<HTMLDivElement>;
|
||
|
|
axis?: 'horizontal' | 'vertical';
|
||
|
|
reversed?: boolean;
|
||
|
|
behavior?: ScrollBehavior;
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* React hook that measures virtualized space dynamically to ensure optimized virtualization length.
|
||
|
|
*/
|
||
|
|
export declare const useDynamicVirtualizerMeasure: <TElement extends HTMLElement>(virtualizerProps: VirtualizerMeasureDynamicProps) => {
|
||
|
|
virtualizerLength: number;
|
||
|
|
bufferItems: number;
|
||
|
|
bufferSize: number;
|
||
|
|
scrollRef: (instance: TElement | null) => void;
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* React hook that allows easy usage of the browser API IntersectionObserver within React
|
||
|
|
* @param callback - A function called when the percentage of the target element is visible crosses a threshold.
|
||
|
|
* @param options - An optional object which customizes the observer. If options isn't specified, the observer uses the
|
||
|
|
* document's viewport as the root, with no margin, and a 0% threshold (meaning that even a one-pixel change is
|
||
|
|
* enough to trigger a callback).
|
||
|
|
* @returns An array containing a callback to update the list of Elements the observer should listen to, a callback to
|
||
|
|
* update the init options of the IntersectionObserver and a ref to the IntersectionObserver instance itself.
|
||
|
|
*/
|
||
|
|
export declare const useIntersectionObserver: (callback: IntersectionObserverCallback, options?: IntersectionObserverInit) => {
|
||
|
|
setObserverList: Dispatch<SetStateAction<Element[] | undefined>>;
|
||
|
|
setObserverInit: (newInit: IntersectionObserverInit | undefined) => void;
|
||
|
|
observer: MutableRefObject<IntersectionObserver | undefined>;
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* useResizeObserverRef_unstable simplifies resize observer connection and ensures debounce/cleanup
|
||
|
|
*/
|
||
|
|
export declare const useResizeObserverRef_unstable: (resizeCallback: ResizeCallbackWithRef) => (instance: HTMLElement | HTMLDivElement | null) => void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* React hook that measures virtualized space based on a static size to ensure optimized virtualization length.
|
||
|
|
*/
|
||
|
|
export declare const useStaticVirtualizerMeasure: <TElement extends HTMLElement>(virtualizerProps: VirtualizerMeasureProps) => {
|
||
|
|
virtualizerLength: number;
|
||
|
|
bufferItems: number;
|
||
|
|
bufferSize: number;
|
||
|
|
scrollRef: (instance: TElement | null) => void;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare function useVirtualizer_unstable(props: VirtualizerProps): VirtualizerState;
|
||
|
|
|
||
|
|
export declare const useVirtualizerContext_unstable: () => VirtualizerContextProps;
|
||
|
|
|
||
|
|
export declare function useVirtualizerScrollView_unstable(props: VirtualizerScrollViewProps): VirtualizerScrollViewState;
|
||
|
|
|
||
|
|
export declare function useVirtualizerScrollViewDynamic_unstable(props: VirtualizerScrollViewDynamicProps): VirtualizerScrollViewDynamicState;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Apply styling to the Virtualizer states
|
||
|
|
*/
|
||
|
|
export declare const useVirtualizerScrollViewDynamicStyles_unstable: (state: VirtualizerScrollViewDynamicState) => VirtualizerScrollViewDynamicState;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Apply styling to the Virtualizer states
|
||
|
|
*/
|
||
|
|
export declare const useVirtualizerScrollViewStyles_unstable: (state: VirtualizerScrollViewState) => VirtualizerScrollViewState;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Apply styling to the Virtualizer states
|
||
|
|
*/
|
||
|
|
export declare const useVirtualizerStyles_unstable: (state: VirtualizerState) => VirtualizerState;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Virtualizer pseudo-component, this functional wrapper
|
||
|
|
* provides a simple interface for reducing the total number
|
||
|
|
* of elements rendered at one time in large lists.
|
||
|
|
*/
|
||
|
|
export declare const Virtualizer: FC<VirtualizerProps>;
|
||
|
|
|
||
|
|
export declare type VirtualizerChildRenderFunction = (index: number, isScrolling: boolean) => React_2.ReactNode;
|
||
|
|
|
||
|
|
export declare const virtualizerClassNames: SlotClassNames<VirtualizerSlots>;
|
||
|
|
|
||
|
|
declare type VirtualizerConfigProps = {
|
||
|
|
/**
|
||
|
|
* Child render function.
|
||
|
|
* Iteratively called to return current virtualizer DOM children.
|
||
|
|
* Will act as a row or column indexer depending on Virtualizer settings.
|
||
|
|
* Can be used dynamically.
|
||
|
|
*/
|
||
|
|
children: VirtualizerChildRenderFunction;
|
||
|
|
/**
|
||
|
|
* Default cell size to use if no custom callback provided.
|
||
|
|
* If implementing `getItemSize` this should be the initial and ideally minimum cell size.
|
||
|
|
*/
|
||
|
|
itemSize: number;
|
||
|
|
/**
|
||
|
|
* The total number of items to be virtualized.
|
||
|
|
*/
|
||
|
|
numItems: number;
|
||
|
|
/**
|
||
|
|
* Number of children to render in the DOM during virtualization.
|
||
|
|
* Constraints:
|
||
|
|
* - Large enough that the items rendered in DOM cover the viewport
|
||
|
|
* and intersection observer buffers (buffersize) at both ends.
|
||
|
|
*/
|
||
|
|
virtualizerLength: number;
|
||
|
|
/**
|
||
|
|
* Defaults to 1/4th of virtualizerLength.
|
||
|
|
* Controls the number of elements rendered before the current index entering the virtualized viewport.
|
||
|
|
* Constraints:
|
||
|
|
* - Large enough to cover bufferSize (prevents buffers intersecting into the viewport during rest state).
|
||
|
|
* - Small enough that the end buffer and end index (start index + virtualizerLength) is not within viewport at rest.
|
||
|
|
*/
|
||
|
|
bufferItems?: number;
|
||
|
|
/**
|
||
|
|
* Defaults to half of bufferItems size (in pixels).
|
||
|
|
* The length (in pixels) before the end/start DOM index where the virtualizer recalculation will be triggered.
|
||
|
|
* Increasing this reduces whitespace on ultra-fast scroll, as additional elements
|
||
|
|
* are buffered to appear while virtualization recalculates.
|
||
|
|
* Constraints:
|
||
|
|
* - At least 1px - although this will only trigger the recalculation after bookends (whitespace) enter viewport.
|
||
|
|
* - BufferSize must be smaller than bufferItems pixel size, as it prevents bookends entering viewport at rest.
|
||
|
|
*/
|
||
|
|
bufferSize?: number;
|
||
|
|
/**
|
||
|
|
* Enables users to override the intersectionObserverRoot.
|
||
|
|
*/
|
||
|
|
scrollViewRef?: React_2.MutableRefObject<HTMLElement | null>;
|
||
|
|
/**
|
||
|
|
* The scroll direction
|
||
|
|
* @default vertical
|
||
|
|
*/
|
||
|
|
axis?: 'vertical' | 'horizontal';
|
||
|
|
/**
|
||
|
|
* Tells the virtualizer to measure in the reverse direction (for column-reverse order etc.)
|
||
|
|
* This value should be flipped in RTL implementation (TBD whether automate RTL).
|
||
|
|
*/
|
||
|
|
reversed?: boolean;
|
||
|
|
/**
|
||
|
|
* Callback for acquiring size of individual items
|
||
|
|
* @param index - the index of the requested size's child
|
||
|
|
*/
|
||
|
|
getItemSize?: (index: number) => number;
|
||
|
|
/**
|
||
|
|
* Virtualizer context can be passed as a prop for extended class use
|
||
|
|
*/
|
||
|
|
virtualizerContext?: VirtualizerContextProps;
|
||
|
|
/**
|
||
|
|
* Callback for notifying when a flagged index has been rendered
|
||
|
|
*/
|
||
|
|
onRenderedFlaggedIndex?: (index: number) => void;
|
||
|
|
flaggedIndex?: MutableRefObject<number | null>;
|
||
|
|
/**
|
||
|
|
* Imperative ref contains our scrollTo index functionality for user control.
|
||
|
|
*/
|
||
|
|
imperativeVirtualizerRef?: RefObject<VirtualizerDataRef>;
|
||
|
|
};
|
||
|
|
|
||
|
|
declare type VirtualizerConfigState = {
|
||
|
|
/**
|
||
|
|
* The current virtualized array of children to show in the DOM.
|
||
|
|
*/
|
||
|
|
virtualizedChildren: React_2.ReactNode[];
|
||
|
|
/**
|
||
|
|
* The current start index for the virtualizer, all previous index's will be removed from DOM.
|
||
|
|
*/
|
||
|
|
virtualizerStartIndex: number;
|
||
|
|
/**
|
||
|
|
* Current buffer height required at beginning of array.
|
||
|
|
*/
|
||
|
|
afterBufferHeight: number;
|
||
|
|
/**
|
||
|
|
* Current buffer height required at end of array.
|
||
|
|
*/
|
||
|
|
beforeBufferHeight: number;
|
||
|
|
/**
|
||
|
|
* The total current height of the scrollView/child content.
|
||
|
|
*/
|
||
|
|
totalVirtualizerHeight: number;
|
||
|
|
/**
|
||
|
|
* The scroll direction
|
||
|
|
* @default vertical
|
||
|
|
*/
|
||
|
|
axis?: 'vertical' | 'horizontal';
|
||
|
|
/**
|
||
|
|
* Tells the virtualizer to measure in the reverse direction (for column-reverse order etc.)
|
||
|
|
*/
|
||
|
|
reversed?: boolean;
|
||
|
|
/**
|
||
|
|
* Pixel size of intersection observers and how much they 'cross over' into the bufferItems index.
|
||
|
|
* Minimum 1px.
|
||
|
|
*/
|
||
|
|
bufferSize: number;
|
||
|
|
/**
|
||
|
|
* Ref for access to internal size knowledge, can be used to measure updates
|
||
|
|
*/
|
||
|
|
childSizes: React_2.MutableRefObject<number[]>;
|
||
|
|
/**
|
||
|
|
* Ref for access to internal progressive size knowledge, can be used to measure updates
|
||
|
|
*/
|
||
|
|
childProgressiveSizes: React_2.MutableRefObject<number[]>;
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* {@docCategory Virtualizer}
|
||
|
|
*/
|
||
|
|
export declare type VirtualizerContextProps = {
|
||
|
|
contextIndex: number;
|
||
|
|
setContextIndex: (index: number) => void;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare const VirtualizerContextProvider: React_2.Provider<VirtualizerContextProps>;
|
||
|
|
|
||
|
|
export declare type VirtualizerDataRef = {
|
||
|
|
progressiveSizes: RefObject<number[]>;
|
||
|
|
nodeSizes: RefObject<number[]>;
|
||
|
|
setFlaggedIndex: (index: number | null) => void;
|
||
|
|
currentIndex: RefObject<number>;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare type VirtualizerMeasureDynamicProps = {
|
||
|
|
defaultItemSize: number;
|
||
|
|
currentIndex: number;
|
||
|
|
numItems: number;
|
||
|
|
getItemSize: (index: number) => number;
|
||
|
|
direction?: 'vertical' | 'horizontal';
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare type VirtualizerMeasureProps = {
|
||
|
|
defaultItemSize: number;
|
||
|
|
direction?: 'vertical' | 'horizontal';
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare type VirtualizerProps = ComponentProps<Partial<VirtualizerSlots>> & VirtualizerConfigProps;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Virtualizer ScrollView
|
||
|
|
*/
|
||
|
|
export declare const VirtualizerScrollView: React_2.FC<VirtualizerScrollViewProps>;
|
||
|
|
|
||
|
|
export declare const virtualizerScrollViewClassNames: SlotClassNames<VirtualizerScrollViewSlots>;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Virtualizer ScrollView
|
||
|
|
*/
|
||
|
|
export declare const VirtualizerScrollViewDynamic: React_2.FC<VirtualizerScrollViewDynamicProps>;
|
||
|
|
|
||
|
|
export declare const virtualizerScrollViewDynamicClassNames: SlotClassNames<VirtualizerScrollViewDynamicSlots>;
|
||
|
|
|
||
|
|
export declare type VirtualizerScrollViewDynamicProps = ComponentProps<Partial<VirtualizerScrollViewDynamicSlots>> & Partial<Omit<VirtualizerConfigProps, 'itemSize' | 'numItems' | 'getItemSize' | 'children' | 'flagIndex'>> & {
|
||
|
|
/**
|
||
|
|
* Set as the minimum item size.
|
||
|
|
* Axis: 'vertical' = Height
|
||
|
|
* Axis: 'horizontal' = Width
|
||
|
|
*/
|
||
|
|
itemSize: number;
|
||
|
|
/**
|
||
|
|
* Callback for acquiring size of individual items
|
||
|
|
* @param index - the index of the requested size's child
|
||
|
|
* If undefined, Virtualizer will auto-measure by default (performance tradeoff)
|
||
|
|
*/
|
||
|
|
getItemSize?: (index: number) => number;
|
||
|
|
/**
|
||
|
|
* The total number of items to be virtualized.
|
||
|
|
*/
|
||
|
|
numItems: number;
|
||
|
|
/**
|
||
|
|
* Child render function.
|
||
|
|
* Iteratively called to return current virtualizer DOM children.
|
||
|
|
* Will act as a row or column indexer depending on Virtualizer settings.
|
||
|
|
*/
|
||
|
|
children: VirtualizerChildRenderFunction;
|
||
|
|
/**
|
||
|
|
* Imperative ref contains our scrollTo index functionality for user control.
|
||
|
|
*/
|
||
|
|
imperativeRef?: RefObject<ScrollToInterface>;
|
||
|
|
/**
|
||
|
|
* Imperative ref contains our scrollTo index functionality for user control.
|
||
|
|
*/
|
||
|
|
enablePagination?: boolean;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare type VirtualizerScrollViewDynamicSlots = VirtualizerScrollViewSlots;
|
||
|
|
|
||
|
|
export declare type VirtualizerScrollViewDynamicState = ComponentState<VirtualizerScrollViewDynamicSlots> & VirtualizerConfigState;
|
||
|
|
|
||
|
|
export declare type VirtualizerScrollViewProps = ComponentProps<Partial<VirtualizerScrollViewSlots>> & Partial<Omit<VirtualizerConfigProps, 'itemSize' | 'numItems' | 'getItemSize' | 'children' | 'flagIndex' | 'imperativeVirtualizerRef'>> & {
|
||
|
|
/**
|
||
|
|
* Virtualizer item size in pixels - static.
|
||
|
|
* Axis: 'vertical' = Height
|
||
|
|
* Axis: 'horizontal' = Width
|
||
|
|
*/
|
||
|
|
itemSize: number;
|
||
|
|
/**
|
||
|
|
* The total number of items to be virtualized.
|
||
|
|
*/
|
||
|
|
numItems: number;
|
||
|
|
/**
|
||
|
|
* Child render function.
|
||
|
|
* Iteratively called to return current virtualizer DOM children.
|
||
|
|
* Will act as a row or column indexer depending on Virtualizer settings.
|
||
|
|
*/
|
||
|
|
children: VirtualizerChildRenderFunction;
|
||
|
|
/**
|
||
|
|
* Imperative ref contains our scrollTo index functionality for user control.
|
||
|
|
*/
|
||
|
|
imperativeRef?: RefObject<ScrollToInterface>;
|
||
|
|
/**
|
||
|
|
* Imperative ref contains our scrollTo index functionality for user control.
|
||
|
|
*/
|
||
|
|
enablePagination?: boolean;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare type VirtualizerScrollViewSlots = VirtualizerSlots & {
|
||
|
|
/**
|
||
|
|
* The root container that provides embedded scrolling.
|
||
|
|
*/
|
||
|
|
container: NonNullable<Slot<'div'>>;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare type VirtualizerScrollViewState = ComponentState<VirtualizerScrollViewSlots> & VirtualizerConfigState;
|
||
|
|
|
||
|
|
export declare type VirtualizerSlots = {
|
||
|
|
/**
|
||
|
|
* The intersection observed 'before' element will detect when scrolling towards the beginning.
|
||
|
|
*/
|
||
|
|
before: NonNullable<Slot<'div', 'td'>>;
|
||
|
|
/**
|
||
|
|
* A block place holding whitespace at the beginning of current DOM children.
|
||
|
|
*/
|
||
|
|
beforeContainer: NonNullable<Slot<'div', 'tr'>>;
|
||
|
|
/**
|
||
|
|
* The intersection observed 'after' element will detect when scrolling towards the end.
|
||
|
|
*/
|
||
|
|
after: NonNullable<Slot<'div', 'td'>>;
|
||
|
|
/**
|
||
|
|
* A block place holding whitespace after the end of current DOM children.
|
||
|
|
*/
|
||
|
|
afterContainer: NonNullable<Slot<'div', 'tr'>>;
|
||
|
|
};
|
||
|
|
|
||
|
|
export declare type VirtualizerState = ComponentState<VirtualizerSlots> & VirtualizerConfigState;
|
||
|
|
|
||
|
|
export { }
|