Virtualizer: Optimize IO usage and export useMeasureList

change/@fluentui-react-virtualizer-bab73d05-7372-4052-8d22-ca75b5fadfe2.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "BREAKING CHANGE (useVirtualizerDynamicMeasure): optimized with scrollPos state and children height reference, updated algorithm to be more accurate, and exported measurement hook",
+  "packageName": "@fluentui/react-virtualizer",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-combobox/stories/src/Combobox/ComboboxVirtualizer.stories.tsx

@@ -17,10 +17,11 @@ const useStyles = makeStyles({
 export const ComboboxVirtualizer = (props: Partial<ComboboxProps>) => {
   const comboId = useId('combobox');
 
-  const itemHeight = 32; //This should match the height of each item in the listbox
+  //This should include the item height (32px) and account for rowGap (2px)
+  const itemHeight = 34;
   const numberOfItems = 10000;
 
-  const { virtualizerLength, bufferItems, bufferSize, scrollRef } = useStaticVirtualizerMeasure({
+  const { virtualizerLength, bufferItems, bufferSize, scrollRef, containerSizeRef } = useStaticVirtualizerMeasure({
     defaultItemSize: itemHeight,
     direction: 'vertical',
   });
@@ -43,6 +44,7 @@ export const ComboboxVirtualizer = (props: Partial<ComboboxProps>) => {
             bufferItems={bufferItems}
             bufferSize={bufferSize}
             itemSize={itemHeight}
+            containerSizeRef={containerSizeRef}
           >
             {index => {
               return (

packages/react-components/react-virtualizer/library/etc/react-virtualizer.api.md

@@ -15,6 +15,15 @@ import type { SetStateAction } from 'react';
 import type { Slot } from '@fluentui/react-utilities';
 import type { SlotClassNames } from '@fluentui/react-utilities';
 
+// @public
+export type DynamicVirtualizerContextProps = Required<VirtualizerContextProps>;
+
+// @public (undocumented)
+export interface IndexedResizeCallbackElement {
+    // (undocumented)
+    handleResize: () => void;
+}
+
 // @public (undocumented)
 export const renderVirtualizer_unstable: (state: VirtualizerState) => JSX.Element;
 
@@ -71,6 +80,7 @@ export const useDynamicVirtualizerMeasure: <TElement extends HTMLElement>(virtua
     bufferItems: number;
     bufferSize: number;
     scrollRef: (instance: TElement | null) => void;
+    containerSizeRef: React_2.RefObject<number>;
 };
 
 // @public
@@ -80,6 +90,15 @@ export const useIntersectionObserver: (callback: IntersectionObserverCallback, o
     observer: MutableRefObject<IntersectionObserver | undefined>;
 };
 
+// @public
+export function useMeasureList<TElement extends HTMLElement & IndexedResizeCallbackElement = HTMLElement & IndexedResizeCallbackElement>(currentIndex: number, refLength: number, totalLength: number, defaultItemSize: number): {
+    widthArray: React_2.MutableRefObject<any[]>;
+    heightArray: React_2.MutableRefObject<any[]>;
+    createIndexedRef: (index: number) => (el: TElement) => void;
+    refArray: React_2.MutableRefObject<(TElement | null | undefined)[]>;
+    sizeUpdateCount: number;
+};
+
 // @public
 export const useResizeObserverRef_unstable: (resizeCallback: ResizeCallbackWithRef) => (instance: HTMLElement | HTMLDivElement | null) => void;
 
@@ -89,6 +108,7 @@ export const useStaticVirtualizerMeasure: <TElement extends HTMLElement>(virtual
     bufferItems: number;
     bufferSize: number;
     scrollRef: (instance: TElement | null) => void;
+    containerSizeRef: React_2.MutableRefObject<number>;
 };
 
 // @public (undocumented)
@@ -115,7 +135,7 @@ export const useVirtualizerStyles_unstable: (state: VirtualizerState) => Virtual
 // @public
 export const Virtualizer: FC<VirtualizerProps>;
 
-// @public (undocumented)
+// @public
 export type VirtualizerChildRenderFunction = (index: number, isScrolling: boolean) => React_2.ReactNode;
 
 // @public (undocumented)
@@ -125,6 +145,9 @@ export const virtualizerClassNames: SlotClassNames<VirtualizerSlots>;
 export type VirtualizerContextProps = {
     contextIndex: number;
     setContextIndex: (index: number) => void;
+    contextPosition?: number;
+    setContextPosition?: (index: number) => void;
+    childProgressiveSizes?: React_2.MutableRefObject<number[]>;
 };
 
 // @public (undocumented)
@@ -141,16 +164,20 @@ export type VirtualizerDataRef = {
 // @public (undocumented)
 export type VirtualizerMeasureDynamicProps = {
     defaultItemSize: number;
-    currentIndex: number;
+    virtualizerContext: DynamicVirtualizerContextProps;
     numItems: number;
     getItemSize: (index: number) => number;
     direction?: 'vertical' | 'horizontal';
+    bufferItems?: number;
+    bufferSize?: number;
 };
 
 // @public (undocumented)
 export type VirtualizerMeasureProps = {
     defaultItemSize: number;
     direction?: 'vertical' | 'horizontal';
+    bufferItems?: number;
+    bufferSize?: number;
 };
 
 // @public (undocumented)
@@ -169,13 +196,14 @@ export const VirtualizerScrollViewDynamic: React_2.FC<VirtualizerScrollViewDynam
 export const virtualizerScrollViewDynamicClassNames: SlotClassNames<VirtualizerScrollViewDynamicSlots>;
 
 // @public (undocumented)
-export type VirtualizerScrollViewDynamicProps = ComponentProps<Partial<VirtualizerScrollViewDynamicSlots>> & Partial<Omit<VirtualizerConfigProps, 'itemSize' | 'numItems' | 'getItemSize' | 'children' | 'flagIndex'>> & {
+export type VirtualizerScrollViewDynamicProps = ComponentProps<Partial<VirtualizerScrollViewDynamicSlots>> & Partial<Omit<VirtualizerConfigProps, 'itemSize' | 'numItems' | 'getItemSize' | 'children' | 'flagIndex' | 'virtualizerContext'>> & {
     itemSize: number;
     getItemSize?: (index: number) => number;
     numItems: number;
     children: VirtualizerChildRenderFunction;
     imperativeRef?: RefObject<ScrollToInterface>;
     enablePagination?: boolean;
+    virtualizerContext?: DynamicVirtualizerContextProps;
 };
 
 // @public (undocumented)

packages/react-components/react-virtualizer/library/src/components/Virtualizer/Virtualizer.types.ts

@@ -52,6 +52,11 @@ export type VirtualizerConfigState = {
    * Tells the virtualizer to measure in the reverse direction (for column-reverse order etc.)
    */
   reversed?: boolean;
+  /**
+   * Enables the isScrolling property in the child render function
+   * Default: false - to prevent nessecary render function calls
+   */
+  enableScrollLoad?: boolean;
   /**
    * Pixel size of intersection observers and how much they 'cross over' into the bufferItems index.
    * Minimum 1px.
@@ -69,8 +74,10 @@ export type VirtualizerConfigState = {
 
 export type VirtualizerState = ComponentState<VirtualizerSlots> & VirtualizerConfigState;
 
-// Virtualizer render function to procedurally generate children elements as rows or columns via index.
-// Q: Use generic typing and passing through object data or a simple index system?
+/**
+ * The main child render method of Virtualization
+ * isScrolling will only be enabled when enableScrollLoad is set to true.
+ */
 export type VirtualizerChildRenderFunction = (index: number, isScrolling: boolean) => React.ReactNode;
 
 export type VirtualizerDataRef = {
@@ -109,16 +116,19 @@ export type VirtualizerConfigProps = {
   virtualizerLength: number;
 
   /**
-   * Defaults to 1/4th of virtualizerLength.
+   * Defaults to 1/4th (or 1/3rd for dynamic items) of virtualizerLength.
+   * RECOMMEND: Override this with a consistent value if using a dynamic virtualizer.
+   *
    * 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.
+   * - Small enough that the virtualizer only renders a few items outside of view.
    */
   bufferItems?: number;
 
   /**
-   * Defaults to half of bufferItems size (in pixels).
+   * Defaults to half of bufferItems * itemSize size (in pixels).
+   * RECOMMEND: Override this with a consistent minimum item size value if using a dynamic virtualizer.
    * 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.
@@ -130,6 +140,8 @@ export type VirtualizerConfigProps = {
 
   /**
    * Enables users to override the intersectionObserverRoot.
+   * RECOMMEND: DO NOT PASS THIS IN, as it can cause side effects
+   * when overlapping with other scroll views
    */
   scrollViewRef?: React.MutableRefObject<HTMLElement | null>;
 
@@ -145,6 +157,12 @@ export type VirtualizerConfigProps = {
    */
   reversed?: boolean;
 
+  /**
+   * Enables the isScrolling property in the child render function
+   * Default: false - to prevent nessecary render function calls
+   */
+  enableScrollLoad?: boolean;
+
   /**
    * Callback for acquiring size of individual items
    * @param index - the index of the requested size's child
@@ -171,6 +189,12 @@ export type VirtualizerConfigProps = {
    * Imperative ref contains our scrollTo index functionality for user control.
    */
   imperativeVirtualizerRef?: RefObject<VirtualizerDataRef>;
+
+  /**
+   * A ref that provides the size of container (vertical - height, horizontal - width), set by a resize observer.
+   * Virtualizer Measure hooks provide a suitable reference.
+   */
+  containerSizeRef: RefObject<number>;
 };
 
 export type VirtualizerProps = ComponentProps<Partial<VirtualizerSlots>> & VirtualizerConfigProps;