Fire VirtualizedList edge callbacks after programmatic scrolling

Summary:
Programmatic list scrolling can move to an edge before asynchronously scheduled cells finish rendering. The scroll handler then skips the edge callback because the terminal cell is not yet in the render window, and no later scroll or layout event is guaranteed.

Recheck edge callbacks after post-scroll render updates. Track the item count when an edge callback is sent so internal measurement changes cannot emit duplicates while the list remains at the same edge; appending data or scrolling away re-arms the callback.

Changelog:
[General][Fixed] - Fire `VirtualizedList` edge callbacks after programmatic scrolling

Differential Revision: D100870075

Author: Abbondanzo

packages/rn-tester/js/examples/FlatList/BaseFlatListExample.js

@@ -60,6 +60,7 @@ const Item = ({item, separators}: ListRenderItemInfo<string>) => {
 };
 
 type Props = Readonly<{
+  data?: ReadonlyArray<string>,
   exampleProps: Partial<React.ElementConfig<typeof FlatList>>,
   exampleTestID?: ?string,
   onTest?: ?() => void,
@@ -95,7 +96,7 @@ const BaseFlatListExample: component(
         ref={ref}
         testID="flat_list"
         // $FlowFixMe[incompatible-type]
-        data={DATA}
+        data={props.data ?? DATA}
         keyExtractor={(item, index) => item + index}
         style={styles.list}
         // $FlowFixMe[incompatible-type]

packages/rn-tester/js/examples/FlatList/FlatList-onEndReached.js

@@ -12,41 +12,137 @@
 
 import type {RNTesterModuleExample} from '../../types/RNTesterTypes';
 
-import BaseFlatListExample from './BaseFlatListExample';
+import BaseFlatListExample, {ITEM_HEIGHT} from './BaseFlatListExample';
 import * as React from 'react';
 import {useRef, useState} from 'react';
+import {Button, FlatList} from 'react-native';
+
+const DATA = Array.from({length: 20}, (_, index) => `Item ${index}`);
+const SCROLL_TO_ITEM = DATA[18];
+
+type EventCounts = {
+  dragEvents: number,
+  onEndReached: number,
+  onMomentumScrollEnd: number,
+  onStartReached: number,
+};
 
 export component FlatList_onEndReached() {
-  const [output, setOutput] = useState('');
-  const exampleProps = {
-    onEndReached: (info: {distanceFromEnd: number, ...}) =>
-      setOutput('onEndReached'),
-    onEndReachedThreshold: 0,
+  const [output, setOutput] = useState('ready');
+  const listRef = useRef<?FlatList<string>>(null);
+  const actionRef = useRef<'end' | 'start'>('end');
+  const attemptsRef = useRef(0);
+  const eventCountsRef = useRef<EventCounts>({
+    dragEvents: 0,
+    onEndReached: 0,
+    onMomentumScrollEnd: 0,
+    onStartReached: 0,
+  });
+  const recordEventsRef = useRef(false);
+  const momentumEndedRef = useRef(false);
+
+  const report = () => {
+    const {dragEvents, onEndReached, onMomentumScrollEnd, onStartReached} =
+      eventCountsRef.current;
+    setOutput(
+      `${actionRef.current}: attempts=${attemptsRef.current}, ` +
+        `onEndReached=${onEndReached}, onStartReached=${onStartReached}, ` +
+        `onMomentumScrollEnd=${onMomentumScrollEnd}, dragEvents=${dragEvents}`,
+    );
+  };
+
+  const onEndReached = () => {
+    if (recordEventsRef.current) {
+      eventCountsRef.current.onEndReached++;
+      if (momentumEndedRef.current) {
+        report();
+      }
+    }
+  };
+
+  const onStartReached = () => {
+    if (recordEventsRef.current) {
+      eventCountsRef.current.onStartReached++;
+      if (momentumEndedRef.current) {
+        report();
+      }
+    }
   };
-  const ref = useRef<any>(null);
 
-  const onTest = () => {
-    const scrollResponder = ref?.current?.getScrollResponder();
-    if (scrollResponder != null) {
-      scrollResponder.scrollToEnd();
+  const onMomentumScrollEnd = () => {
+    if (recordEventsRef.current) {
+      eventCountsRef.current.onMomentumScrollEnd++;
+      momentumEndedRef.current = true;
+      report();
     }
   };
 
+  const onDragEvent = () => {
+    if (recordEventsRef.current) {
+      eventCountsRef.current.dragEvents++;
+    }
+  };
+
+  const scrollToEnd = () => {
+    recordEventsRef.current = true;
+    momentumEndedRef.current = false;
+    actionRef.current = 'end';
+    attemptsRef.current++;
+    setOutput('running');
+    listRef.current?.scrollToItem({
+      animated: true,
+      item: SCROLL_TO_ITEM,
+      viewOffset: -ITEM_HEIGHT,
+    });
+  };
+
+  const scrollToStart = () => {
+    momentumEndedRef.current = false;
+    actionRef.current = 'start';
+    attemptsRef.current++;
+    setOutput('running');
+    listRef.current?.scrollToOffset({animated: true, offset: 0});
+  };
+
+  const exampleProps = {
+    initialNumToRender: 19,
+    onEndReached,
+    onEndReachedThreshold: 0.2,
+    onMomentumScrollEnd,
+    onScrollBeginDrag: onDragEvent,
+    onScrollEndDrag: onDragEvent,
+    onStartReached,
+    onStartReachedThreshold: 0.1,
+    windowSize: 2,
+  };
+
   return (
     <BaseFlatListExample
-      ref={ref}
+      ref={listRef}
+      data={DATA}
       exampleProps={exampleProps}
       testOutput={output}
-      onTest={onTest}
-    />
+      onTest={scrollToEnd}
+      testLabel="Scroll to item">
+      <Button
+        testID="scroll_to_start"
+        onPress={scrollToStart}
+        title="Scroll to start"
+      />
+      <Button
+        testID="scroll_to_end"
+        onPress={scrollToEnd}
+        title="Scroll to item"
+      />
+    </BaseFlatListExample>
   );
 }
 
 export default {
   title: 'onEndReached',
   name: 'onEndReached',
   description:
-    'Scroll to end of list or tap Test button to see `onEndReached` triggered.',
+    'Programmatic scrolling calls edge callbacks once and does not emit drag callbacks.',
   render: function () {
     return <FlatList_onEndReached />;
   },

packages/virtualized-lists/Lists/VirtualizedList.js

@@ -1195,7 +1195,7 @@ class VirtualizedList extends StateSafePureComponent<
   }
 
   componentDidUpdate(prevProps: VirtualizedListProps) {
-    const {data, extraData, getItemLayout} = this.props;
+    const {data, extraData} = this.props;
     if (data !== prevProps.data || extraData !== prevProps.extraData) {
       // clear the viewableIndices cache to also trigger
       // the onViewableItemsChanged callback with the new data
@@ -1217,11 +1217,14 @@ class VirtualizedList extends StateSafePureComponent<
       this._hiPriInProgress = false;
     }
 
-    // We only call `onEndReached` after we render the last cell, but when
-    // getItemLayout is present, we can scroll past the last rendered cell, and
-    // never trigger a new layout or bounds change, so we need to check again
-    // after rendering more cells.
-    if (getItemLayout != null) {
+    // We only call `onEndReached` after we render the last cell, but
+    // programmatic scrolling (e.g. scrollToItem, scrollToIndex) or using
+    // getItemLayout can scroll past the last rendered cell, and never
+    // trigger a new layout or bounds change, so we need to check again
+    // after rendering more cells. We gate on having received at least one
+    // scroll event (timestamp > 0) to avoid false onEndReached calls
+    // during initial render.
+    if (this.props.getItemLayout != null || this._scrollMetrics.timestamp > 0) {
       this._maybeCallOnEdgeReached();
     }
   }
@@ -1264,8 +1267,8 @@ class VirtualizedList extends StateSafePureComponent<
     zoomScale: 1,
   };
   _scrollRef: ?React.ElementRef<typeof ScrollView> = null;
-  _sentStartForContentLength = 0;
-  _sentEndForContentLength = 0;
+  _sentStartForItemCount: ?number = null;
+  _sentEndForItemCount: ?number = null;
   _updateCellsToRenderTimeoutID: ?ReturnType<typeof setTimeout> = null;
   _viewabilityTuples: Array<ViewabilityHelperCallbackTuple> = [];
 
@@ -1610,39 +1613,41 @@ class VirtualizedList extends StateSafePureComponent<
     const isWithinStartThreshold = distanceFromStart <= startThreshold;
     const isWithinEndThreshold = distanceFromEnd <= endThreshold;
 
+    const itemCount = getItemCount(data);
+
     // First check if the user just scrolled within the end threshold
-    // and call onEndReached only once for a given content length,
+    // and call onEndReached only once for a given item count,
     // and only if onStartReached is not being executed
     if (
       onEndReached &&
-      this.state.cellsAroundViewport.last === getItemCount(data) - 1 &&
+      this.state.cellsAroundViewport.last === itemCount - 1 &&
       isWithinEndThreshold &&
-      this._listMetrics.getContentLength() !== this._sentEndForContentLength
+      itemCount !== this._sentEndForItemCount
     ) {
-      this._sentEndForContentLength = this._listMetrics.getContentLength();
+      this._sentEndForItemCount = itemCount;
       onEndReached({distanceFromEnd});
     }
 
     // Next check if the user just scrolled within the start threshold
-    // and call onStartReached only once for a given content length,
+    // and call onStartReached only once for a given item count,
     // and only if onEndReached is not being executed
     if (
       onStartReached != null &&
       this.state.cellsAroundViewport.first === 0 &&
       isWithinStartThreshold &&
-      this._listMetrics.getContentLength() !== this._sentStartForContentLength
+      itemCount !== this._sentStartForItemCount
     ) {
-      this._sentStartForContentLength = this._listMetrics.getContentLength();
+      this._sentStartForItemCount = itemCount;
       onStartReached({distanceFromStart});
     }
 
     // If the user scrolls away from the start or end and back again,
     // cause onStartReached or onEndReached to be triggered again
     if (!isWithinStartThreshold) {
-      this._sentStartForContentLength = 0;
+      this._sentStartForItemCount = null;
     }
     if (!isWithinEndThreshold) {
-      this._sentEndForContentLength = 0;
+      this._sentEndForItemCount = null;
     }
   }
 

packages/virtualized-lists/Lists/__tests__/VirtualizedList-test.js

@@ -799,6 +799,113 @@ describe('VirtualizedList', () => {
     expect(onEndReached).toHaveBeenCalled();
   });
 
+  it('calls onEndReached once after a programmatic scroll and re-arms for appended data', async () => {
+    const ITEM_HEIGHT = 40;
+    const layout = {width: 300, height: 600};
+    let data = Array(40)
+      .fill()
+      .map((_, index) => ({key: `key-${index}`}));
+    const onEndReached = jest.fn();
+    const props = {
+      data,
+      initialNumToRender: 10,
+      onEndReachedThreshold: 1,
+      windowSize: 2,
+      renderItem: ({item}) => <item value={item.key} />,
+      getItem: (items, index) => items[index],
+      getItemCount: items => items.length,
+      onEndReached,
+    };
+
+    let component;
+    await act(() => {
+      component = create(<VirtualizedList {...props} />);
+    });
+    const instance = component.getInstance();
+
+    await act(() => {
+      instance._onLayout({nativeEvent: {layout, zoomScale: 1}});
+      instance._onContentSizeChange(300, data.length * ITEM_HEIGHT);
+      for (let i = 0; i < props.initialNumToRender; i++) {
+        simulateCellLayout(component, data, i, {
+          width: layout.width,
+          height: ITEM_HEIGHT,
+          x: 0,
+          y: i * ITEM_HEIGHT,
+        });
+      }
+      performAllBatches();
+    });
+    expect(onEndReached).not.toHaveBeenCalled();
+
+    const scrollToEnd = async (timeStamp: number) => {
+      await act(() => {
+        instance._onScroll({
+          timeStamp,
+          nativeEvent: {
+            contentOffset: {
+              y: data.length * ITEM_HEIGHT - layout.height,
+              x: 0,
+            },
+            layoutMeasurement: layout,
+            contentSize: {...layout, height: data.length * ITEM_HEIGHT},
+            zoomScale: 1,
+            contentInset: {right: 0, top: 0, left: 0, bottom: 0},
+          },
+        });
+        performAllBatches();
+      });
+    };
+
+    await scrollToEnd(1000);
+    expect(onEndReached).toHaveBeenCalledTimes(1);
+    expect(onEndReached).toHaveBeenLastCalledWith({distanceFromEnd: 0});
+
+    await act(() => {
+      instance._onContentSizeChange(300, data.length * ITEM_HEIGHT + 1);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(1);
+
+    await act(() => {
+      instance._onContentSizeChange(300, data.length * ITEM_HEIGHT);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(1);
+
+    data = [...data, {key: `key-${data.length}`}];
+    await act(() => {
+      component.update(<VirtualizedList {...props} data={data} />);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    await act(() => {
+      instance._onContentSizeChange(300, data.length * ITEM_HEIGHT);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    await scrollToEnd(2000);
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    await act(() => {
+      instance._onScroll({
+        timeStamp: 3000,
+        nativeEvent: {
+          contentOffset: {y: 0, x: 0},
+          layoutMeasurement: layout,
+          contentSize: {...layout, height: data.length * ITEM_HEIGHT},
+          zoomScale: 1,
+          contentInset: {right: 0, top: 0, left: 0, bottom: 0},
+        },
+      });
+      performAllBatches();
+    });
+    await scrollToEnd(4000);
+    expect(onEndReached).toHaveBeenCalledTimes(3);
+  });
+
   it('does not call onEndReached when onContentSizeChange happens after onLayout', async () => {
     const ITEM_HEIGHT = 40;
     const layout = {width: 300, height: 600};