Virtualizer: ScrollTo hooks & callbacks

change/@fluentui-react-components-bdaf87d0-783b-403a-a2fe-d4d1f43890c4.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "[FEATURE] Imperative scrolling functionality for react-virtualizer",
+  "packageName": "@fluentui/react-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-virtualizer-132ffdc3-4c38-49e6-a75e-a019828a0ec8.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feature: Add scrollTo index hook and callbacks, isScrolling flag",
+  "packageName": "@fluentui/react-virtualizer",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-components/etc/react-components.unstable.api.md

@@ -80,6 +80,11 @@ import { renderVirtualizer_unstable } from '@fluentui/react-virtualizer';
 import { renderVirtualizerScrollView_unstable } from '@fluentui/react-virtualizer';
 import { renderVirtualizerScrollViewDynamic_unstable } from '@fluentui/react-virtualizer';
 import { ResizeCallbackWithRef } from '@fluentui/react-virtualizer';
+import { ScrollToInterface } from '@fluentui/react-virtualizer';
+import { scrollToItemDynamic } from '@fluentui/react-virtualizer';
+import { ScrollToItemDynamicParams } from '@fluentui/react-virtualizer';
+import { scrollToItemStatic } from '@fluentui/react-virtualizer';
+import { ScrollToItemStaticParams } from '@fluentui/react-virtualizer';
 import { Tree } from '@fluentui/react-tree';
 import { treeClassNames } from '@fluentui/react-tree';
 import { TreeContextValue } from '@fluentui/react-tree';
@@ -331,6 +336,16 @@ export { renderVirtualizerScrollViewDynamic_unstable }
 
 export { ResizeCallbackWithRef }
 
+export { ScrollToInterface }
+
+export { scrollToItemDynamic }
+
+export { ScrollToItemDynamicParams }
+
+export { scrollToItemStatic }
+
+export { ScrollToItemStaticParams }
+
 export { Tree }
 
 export { treeClassNames }

packages/react-components/react-components/src/unstable/index.ts

@@ -52,7 +52,10 @@ export {
   useVirtualizerScrollViewDynamic_unstable,
   renderVirtualizerScrollViewDynamic_unstable,
   useVirtualizerScrollViewDynamicStyles_unstable,
+  scrollToItemDynamic,
+  scrollToItemStatic,
 } from '@fluentui/react-virtualizer';
+
 export type {
   VirtualizerProps,
   VirtualizerState,
@@ -68,6 +71,9 @@ export type {
   VirtualizerMeasureDynamicProps,
   VirtualizerMeasureProps,
   ResizeCallbackWithRef,
+  ScrollToInterface,
+  ScrollToItemDynamicParams,
+  ScrollToItemStaticParams,
 } from '@fluentui/react-virtualizer';
 
 export {

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

@@ -4,14 +4,15 @@
 
 ```ts
 
-import { ComponentProps } from '@fluentui/react-utilities';
-import { ComponentState } from '@fluentui/react-utilities';
+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 { Slot } from '@fluentui/react-utilities';
+import type { Slot } from '@fluentui/react-utilities';
 import type { SlotClassNames } from '@fluentui/react-utilities';
 
 // @public (undocumented)
@@ -29,6 +30,39 @@ export interface ResizeCallbackWithRef {
     (entries: ResizeObserverEntry[], observer: ResizeObserver, scrollRef?: MutableRefObject<HTMLElement | null>): void;
 }
 
+// @public (undocumented)
+export type ScrollToInterface = {
+    scrollTo: (index: number, behavior?: ScrollBehavior, callback?: (index: number) => void) => void;
+};
+
+// @public (undocumented)
+export const scrollToItemDynamic: (params: ScrollToItemDynamicParams) => void;
+
+// @public (undocumented)
+export type ScrollToItemDynamicParams = {
+    index: number;
+    itemSizes: RefObject<number[]>;
+    totalSize: number;
+    scrollViewRef: RefObject<HTMLDivElement>;
+    axis?: 'horizontal' | 'vertical';
+    reversed?: boolean;
+    behavior?: ScrollBehavior;
+};
+
+// @public (undocumented)
+export const scrollToItemStatic: (params: ScrollToItemStaticParams) => void;
+
+// @public (undocumented)
+export type ScrollToItemStaticParams = {
+    index: number;
+    itemSize: number;
+    totalItems: number;
+    scrollViewRef: RefObject<HTMLDivElement>;
+    axis?: 'horizontal' | 'vertical';
+    reversed?: boolean;
+    behavior?: ScrollBehavior;
+};
+
 // @public
 export const useDynamicVirtualizerMeasure: <TElement extends HTMLElement>(virtualizerProps: VirtualizerMeasureDynamicProps) => {
     virtualizerLength: number;
@@ -80,7 +114,7 @@ export const useVirtualizerStyles_unstable: (state: VirtualizerState) => Virtual
 export const Virtualizer: FC<VirtualizerProps>;
 
 // @public (undocumented)
-export type VirtualizerChildRenderFunction = (index: number) => React_2.ReactNode;
+export type VirtualizerChildRenderFunction = (index: number, isScrolling: boolean) => React_2.ReactNode;
 
 // @public (undocumented)
 export const virtualizerClassNames: SlotClassNames<VirtualizerSlots>;
@@ -94,6 +128,13 @@ export type VirtualizerContextProps = {
 // @public (undocumented)
 export const VirtualizerContextProvider: React_2.Provider<VirtualizerContextProps>;
 
+// @public (undocumented)
+export type VirtualizerDataRef = {
+    progressiveSizes: RefObject<number[]>;
+    nodeSizes: RefObject<number[]>;
+    setFlaggedIndex: (index: number | null) => void;
+};
+
 // @public (undocumented)
 export type VirtualizerMeasureDynamicProps = {
     defaultItemSize: number;
@@ -125,11 +166,12 @@ 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'>> & {
+export type VirtualizerScrollViewDynamicProps = ComponentProps<Partial<VirtualizerScrollViewDynamicSlots>> & Partial<Omit<VirtualizerConfigProps, 'itemSize' | 'numItems' | 'getItemSize' | 'children' | 'flagIndex'>> & {
     itemSize: number;
     getItemSize: (index: number) => number;
     numItems: number;
     children: VirtualizerChildRenderFunction;
+    imperativeRef?: RefObject<ScrollToInterface>;
 };
 
 // @public (undocumented)
@@ -139,10 +181,11 @@ export type VirtualizerScrollViewDynamicSlots = VirtualizerScrollViewSlots;
 export type VirtualizerScrollViewDynamicState = ComponentState<VirtualizerScrollViewDynamicSlots> & VirtualizerConfigState;
 
 // @public (undocumented)
-export type VirtualizerScrollViewProps = ComponentProps<Partial<VirtualizerScrollViewSlots>> & Partial<Omit<VirtualizerConfigProps, 'itemSize' | 'numItems' | 'getItemSize' | 'children'>> & {
+export type VirtualizerScrollViewProps = ComponentProps<Partial<VirtualizerScrollViewSlots>> & Partial<Omit<VirtualizerConfigProps, 'itemSize' | 'numItems' | 'getItemSize' | 'children' | 'flagIndex' | 'imperativeVirtualizerRef'>> & {
     itemSize: number;
     numItems: number;
     children: VirtualizerChildRenderFunction;
+    imperativeRef?: RefObject<ScrollToInterface>;
 };
 
 // @public (undocumented)

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

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import type { ComponentProps, ComponentState, Slot } from '@fluentui/react-utilities';
-import { VirtualizerContextProps } from '../../Utilities';
+import type { VirtualizerContextProps } from '../../Utilities';
+import type { RefObject, MutableRefObject } from 'react';
 
 export type VirtualizerSlots = {
   /**
@@ -62,7 +63,13 @@ export type VirtualizerState = ComponentState<VirtualizerSlots> & VirtualizerCon
 
 // 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?
-export type VirtualizerChildRenderFunction = (index: number) => React.ReactNode;
+export type VirtualizerChildRenderFunction = (index: number, isScrolling: boolean) => React.ReactNode;
+
+export type VirtualizerDataRef = {
+  progressiveSizes: RefObject<number[]>;
+  nodeSizes: RefObject<number[]>;
+  setFlaggedIndex: (index: number | null) => void;
+};
 
 export type VirtualizerConfigProps = {
   /**
@@ -139,6 +146,21 @@ export type VirtualizerConfigProps = {
    * 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;
+
+  /*
+   * Callback for notifying when a flagged index has been rendered
+   */
+  flaggedIndex?: MutableRefObject<number | null>;
+
+  /**
+   * Imperative ref contains our scrollTo index functionality for user control.
+   */
+  imperativeVirtualizerRef?: RefObject<VirtualizerDataRef>;
 };
 
 export type VirtualizerProps = ComponentProps<Partial<VirtualizerSlots>> & VirtualizerConfigProps;

packages/react-components/react-virtualizer/src/components/Virtualizer/renderVirtualizer.tsx

@@ -2,10 +2,11 @@
 /** @jsx createElement */
 
 import * as React from 'react';
+import type { VirtualizerSlots, VirtualizerState } from './Virtualizer.types';
+import type { ReactNode } from 'react';
+
 import { createElement } from '@fluentui/react-jsx-runtime';
 import { getSlotsNext } from '@fluentui/react-utilities';
-import { VirtualizerSlots, VirtualizerState } from './Virtualizer.types';
-import { ReactNode } from 'react';
 
 export const renderVirtualizer_unstable = (state: VirtualizerState) => {
   const { slots, slotProps } = getSlotsNext<VirtualizerSlots>(state);