@react-native/virtualized-lists 0.73.0 → 0.73.1

package/Lists/FillRateHelper.js

@@ -10,7 +10,8 @@
 
 'use strict';
 
-import type {FrameMetricProps} from './VirtualizedListProps';
+import type {CellMetricProps} from './ListMetricsAggregator';
+import ListMetricsAggregator from './ListMetricsAggregator';
 
 export type FillRateInfo = Info;
 
@@ -27,13 +28,6 @@ class Info {
   sample_count: number = 0;
 }
 
-type FrameMetrics = {
-  inLayout?: boolean,
-  length: number,
-  offset: number,
-  ...
-};
-
 const DEBUG = false;
 
 let _listeners: Array<(Info) => void> = [];
@@ -51,7 +45,7 @@ let _sampleRate = DEBUG ? 1 : null;
 class FillRateHelper {
   _anyBlankStartTime: ?number = null;
   _enabled = false;
-  _getFrameMetrics: (index: number, props: FrameMetricProps) => ?FrameMetrics;
+  _listMetrics: ListMetricsAggregator;
   _info: Info = new Info();
   _mostlyBlankStartTime: ?number = null;
   _samplesStartTime: ?number = null;
@@ -79,10 +73,8 @@ class FillRateHelper {
     _minSampleCount = minSampleCount;
   }
 
-  constructor(
-    getFrameMetrics: (index: number, props: FrameMetricProps) => ?FrameMetrics,
-  ) {
-    this._getFrameMetrics = getFrameMetrics;
+  constructor(listMetrics: ListMetricsAggregator) {
+    this._listMetrics = listMetrics;
     this._enabled = (_sampleRate || 0) > Math.random();
     this._resetData();
   }
@@ -139,7 +131,7 @@ class FillRateHelper {
 
   computeBlankness(
     props: {
-      ...FrameMetricProps,
+      ...CellMetricProps,
       initialNumToRender?: ?number,
       ...
     },
@@ -186,12 +178,12 @@ class FillRateHelper {
 
     let blankTop = 0;
     let first = cellsAroundViewport.first;
-    let firstFrame = this._getFrameMetrics(first, props);
+    let firstFrame = this._listMetrics.getCellMetrics(first, props);
     while (
       first <= cellsAroundViewport.last &&
-      (!firstFrame || !firstFrame.inLayout)
+      (!firstFrame || !firstFrame.isMounted)
     ) {
-      firstFrame = this._getFrameMetrics(first, props);
+      firstFrame = this._listMetrics.getCellMetrics(first, props);
       first++;
     }
     // Only count blankTop if we aren't rendering the first item, otherwise we will count the header
@@ -204,12 +196,12 @@ class FillRateHelper {
     }
     let blankBottom = 0;
     let last = cellsAroundViewport.last;
-    let lastFrame = this._getFrameMetrics(last, props);
+    let lastFrame = this._listMetrics.getCellMetrics(last, props);
     while (
       last >= cellsAroundViewport.first &&
-      (!lastFrame || !lastFrame.inLayout)
+      (!lastFrame || !lastFrame.isMounted)
     ) {
-      lastFrame = this._getFrameMetrics(last, props);
+      lastFrame = this._listMetrics.getCellMetrics(last, props);
       last--;
     }
     // Only count blankBottom if we aren't rendering the last item, otherwise we will count the

package/Lists/ListMetricsAggregator.js

@@ -0,0 +1,385 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import type {Layout} from 'react-native/Libraries/Types/CoreEventTypes';
+import type {Props as VirtualizedListProps} from './VirtualizedListProps';
+import {keyExtractor as defaultKeyExtractor} from './VirtualizeUtils';
+
+import invariant from 'invariant';
+
+type LayoutEventDirection = 'top-down' | 'bottom-up';
+
+export type CellMetrics = {
+  /**
+   * Index of the item in the list
+   */
+  index: number,
+  /**
+   * Length of the cell along the scrolling axis
+   */
+  length: number,
+  /**
+   * Distance between this cell and the start of the list along the scrolling
+   * axis
+   */
+  offset: number,
+  /**
+   * Whether the cell is last known to be mounted
+   */
+  isMounted: boolean,
+};
+
+// TODO: `inverted` can be incorporated here if it is moved to an order
+// based implementation instead of transform.
+export type ListOrientation = {
+  horizontal: boolean,
+  rtl: boolean,
+};
+
+/**
+ * Subset of VirtualizedList props needed to calculate cell metrics
+ */
+export type CellMetricProps = {
+  data: VirtualizedListProps['data'],
+  getItemCount: VirtualizedListProps['getItemCount'],
+  getItem: VirtualizedListProps['getItem'],
+  getItemLayout?: VirtualizedListProps['getItemLayout'],
+  keyExtractor?: VirtualizedListProps['keyExtractor'],
+  ...
+};
+
+type UnresolvedCellMetrics = {
+  index: number,
+  layout: Layout,
+  isMounted: boolean,
+
+  // The length of list content at the time of layout is needed to correctly
+  // resolve flow relative offset in RTL. We are lazily notified of this after
+  // the layout of the cell, unless the cell relayout does not cause a length
+  // change. To keep stability, we use content length at time of query, or
+  // unmount if never queried.
+  listContentLength?: ?number,
+};
+
+/**
+ * Provides an interface to query information about the metrics of a list and its cells.
+ */
+export default class ListMetricsAggregator {
+  _averageCellLength = 0;
+  _cellMetrics: Map<string, UnresolvedCellMetrics> = new Map();
+  _contentLength: ?number;
+  _highestMeasuredCellIndex = 0;
+  _measuredCellsLength = 0;
+  _measuredCellsCount = 0;
+  _orientation: ListOrientation = {
+    horizontal: false,
+    rtl: false,
+  };
+
+  // Fabric and Paper may call onLayout in different orders. We can tell which
+  // direction layout events happen on the first layout.
+  _onLayoutDirection: LayoutEventDirection = 'top-down';
+
+  /**
+   * Notify the ListMetricsAggregator that a cell has been laid out.
+   *
+   * @returns whether the cell layout has changed since last notification
+   */
+  notifyCellLayout({
+    cellIndex,
+    cellKey,
+    orientation,
+    layout,
+  }: {
+    cellIndex: number,
+    cellKey: string,
+    orientation: ListOrientation,
+    layout: Layout,
+  }): boolean {
+    if (this._contentLength == null) {
+      this._onLayoutDirection = 'bottom-up';
+    }
+
+    this._invalidateIfOrientationChanged(orientation);
+
+    // If layout is top-down, our most recently cached content length
+    // corresponds to this cell. Otherwise, we need to resolve when events fire
+    // up the tree to the new length.
+    const listContentLength =
+      this._onLayoutDirection === 'top-down' ? this._contentLength : null;
+
+    const next: UnresolvedCellMetrics = {
+      index: cellIndex,
+      layout: layout,
+      isMounted: true,
+      listContentLength,
+    };
+    const curr = this._cellMetrics.get(cellKey);
+
+    if (
+      !curr ||
+      this._selectOffset(next.layout) !== this._selectOffset(curr.layout) ||
+      this._selectLength(next.layout) !== this._selectLength(curr.layout) ||
+      (curr.listContentLength != null &&
+        curr.listContentLength !== this._contentLength)
+    ) {
+      if (curr) {
+        const dLength =
+          this._selectLength(next.layout) - this._selectLength(curr.layout);
+        this._measuredCellsLength += dLength;
+      } else {
+        this._measuredCellsLength += this._selectLength(next.layout);
+        this._measuredCellsCount += 1;
+      }
+
+      this._averageCellLength =
+        this._measuredCellsLength / this._measuredCellsCount;
+      this._cellMetrics.set(cellKey, next);
+      this._highestMeasuredCellIndex = Math.max(
+        this._highestMeasuredCellIndex,
+        cellIndex,
+      );
+      return true;
+    } else {
+      curr.isMounted = true;
+      return false;
+    }
+  }
+
+  /**
+   * Notify ListMetricsAggregator that a cell has been unmounted.
+   */
+  notifyCellUnmounted(cellKey: string): void {
+    const curr = this._cellMetrics.get(cellKey);
+    if (curr) {
+      curr.isMounted = false;
+    }
+  }
+
+  /**
+   * Notify ListMetricsAggregator that the lists content container has been laid out.
+   */
+  notifyListContentLayout({
+    orientation,
+    layout,
+  }: {
+    orientation: ListOrientation,
+    layout: $ReadOnly<{width: number, height: number}>,
+  }): void {
+    this._invalidateIfOrientationChanged(orientation);
+    const newLength = this._selectLength(layout);
+
+    // Fill in any just-measured cells which did not have this length available.
+    // This logic assumes that cell relayout will always change list content
+    // size, which isn't strictly correct, but issues should be rare and only
+    // on Paper.
+    if (this._onLayoutDirection === 'bottom-up') {
+      for (const cellMetric of this._cellMetrics.values()) {
+        if (cellMetric.listContentLength == null) {
+          cellMetric.listContentLength = newLength;
+        }
+      }
+    }
+
+    this._contentLength = newLength;
+  }
+
+  /**
+   * Return the average length of the cells which have been measured
+   */
+  getAverageCellLength(): number {
+    return this._averageCellLength;
+  }
+
+  /**
+   * Return the highest measured cell index (or 0 if nothing has been measured
+   * yet)
+   */
+  getHighestMeasuredCellIndex(): number {
+    return this._highestMeasuredCellIndex;
+  }
+
+  /**
+   * Returns the exact metrics of a cell if it has already been laid out,
+   * otherwise an estimate based on the average length of previously measured
+   * cells
+   */
+  getCellMetricsApprox(index: number, props: CellMetricProps): CellMetrics {
+    const frame = this.getCellMetrics(index, props);
+    if (frame && frame.index === index) {
+      // check for invalid frames due to row re-ordering
+      return frame;
+    } else {
+      const {data, getItemCount} = props;
+      invariant(
+        index >= 0 && index < getItemCount(data),
+        'Tried to get frame for out of range index ' + index,
+      );
+      return {
+        length: this._averageCellLength,
+        offset: this._averageCellLength * index,
+        index,
+        isMounted: false,
+      };
+    }
+  }
+
+  /**
+   * Returns the exact metrics of a cell if it has already been laid out
+   */
+  getCellMetrics(index: number, props: CellMetricProps): ?CellMetrics {
+    const {data, getItem, getItemCount, getItemLayout} = props;
+    invariant(
+      index >= 0 && index < getItemCount(data),
+      'Tried to get metrics for out of range cell index ' + index,
+    );
+    const keyExtractor = props.keyExtractor ?? defaultKeyExtractor;
+    const frame = this._cellMetrics.get(
+      keyExtractor(getItem(data, index), index),
+    );
+    if (frame && frame.index === index) {
+      return this._resolveCellMetrics(frame);
+    }
+
+    if (getItemLayout) {
+      const {length, offset} = getItemLayout(data, index);
+      // TODO: `isMounted` is used for both "is exact layout" and "has been
+      // unmounted". Should be refactored.
+      return {index, length, offset, isMounted: true};
+    }
+
+    return null;
+  }
+
+  /**
+   * Gets an approximate offset to an item at a given index. Supports
+   * fractional indices.
+   */
+  getCellOffsetApprox(index: number, props: CellMetricProps): number {
+    if (Number.isInteger(index)) {
+      return this.getCellMetricsApprox(index, props).offset;
+    } else {
+      const frameMetrics = this.getCellMetricsApprox(Math.floor(index), props);
+      const remainder = index - Math.floor(index);
+      return frameMetrics.offset + remainder * frameMetrics.length;
+    }
+  }
+
+  /**
+   * Returns the length of all ScrollView content along the scrolling axis.
+   */
+  getContentLength(): number {
+    return this._contentLength ?? 0;
+  }
+
+  /**
+   * Whether a content length has been observed
+   */
+  hasContentLength(): boolean {
+    return this._contentLength != null;
+  }
+
+  /**
+   * Whether the ListMetricsAggregator is notified of cell metrics before
+   * ScrollView metrics (bottom-up) or ScrollView metrics before cell metrics
+   * (top-down).
+   *
+   * Must be queried after cell layout
+   */
+  getLayoutEventDirection(): LayoutEventDirection {
+    return this._onLayoutDirection;
+  }
+
+  /**
+   * Whether the ListMetricsAggregator must be aware of the current length of
+   * ScrollView content to be able to correctly resolve the (flow-relative)
+   * metrics of a cell.
+   */
+  needsContentLengthForCellMetrics(): boolean {
+    return this._orientation.horizontal && this._orientation.rtl;
+  }
+
+  /**
+   * Finds the flow-relative offset (e.g. starting from the left in LTR, but
+   * right in RTL) from a layout box.
+   */
+  flowRelativeOffset(layout: Layout, referenceContentLength?: ?number): number {
+    const {horizontal, rtl} = this._orientation;
+
+    if (horizontal && rtl) {
+      const contentLength = referenceContentLength ?? this._contentLength;
+      invariant(
+        contentLength != null,
+        'ListMetricsAggregator must be notified of list content layout before resolving offsets',
+      );
+      return (
+        contentLength -
+        (this._selectOffset(layout) + this._selectLength(layout))
+      );
+    } else {
+      return this._selectOffset(layout);
+    }
+  }
+
+  /**
+   * Converts a flow-relative offset to a cartesian offset
+   */
+  cartesianOffset(flowRelativeOffset: number): number {
+    const {horizontal, rtl} = this._orientation;
+
+    if (horizontal && rtl) {
+      invariant(
+        this._contentLength != null,
+        'ListMetricsAggregator must be notified of list content layout before resolving offsets',
+      );
+      return this._contentLength - flowRelativeOffset;
+    } else {
+      return flowRelativeOffset;
+    }
+  }
+
+  _invalidateIfOrientationChanged(orientation: ListOrientation): void {
+    if (orientation.rtl !== this._orientation.rtl) {
+      this._cellMetrics.clear();
+    }
+
+    if (orientation.horizontal !== this._orientation.horizontal) {
+      this._averageCellLength = 0;
+      this._contentLength = null;
+      this._highestMeasuredCellIndex = 0;
+      this._measuredCellsLength = 0;
+      this._measuredCellsCount = 0;
+    }
+
+    this._orientation = orientation;
+  }
+
+  _selectLength({
+    width,
+    height,
+  }: $ReadOnly<{width: number, height: number, ...}>): number {
+    return this._orientation.horizontal ? width : height;
+  }
+
+  _selectOffset({x, y}: $ReadOnly<{x: number, y: number, ...}>): number {
+    return this._orientation.horizontal ? x : y;
+  }
+
+  _resolveCellMetrics(metrics: UnresolvedCellMetrics): CellMetrics {
+    const {index, layout, isMounted, listContentLength} = metrics;
+
+    return {
+      index,
+      length: this._selectLength(layout),
+      isMounted,
+      offset: this.flowRelativeOffset(layout, listContentLength),
+    };
+  }
+}

package/Lists/StateSafePureComponent.js

@@ -14,7 +14,7 @@ import * as React from 'react';
 /**
  * `setState` is called asynchronously, and should not rely on the value of
  * `this.props` or `this.state`:
- * https://reactjs.org/docs/state-and-lifecycle.html#state-updates-may-be-asynchronous
+ * https://react.dev/docs/state-and-lifecycle.html#state-updates-may-be-asynchronous
  *
  * SafePureComponent adds runtime enforcement, to catch cases where these
  * variables are read in a state updater function, instead of the ones passed
@@ -32,7 +32,7 @@ export default class StateSafePureComponent<
   }
 
   setState(
-    partialState: ?($Shape<State> | ((State, Props) => ?$Shape<State>)),
+    partialState: ?(Partial<State> | ((State, Props) => ?Partial<State>)),
     callback?: () => mixed,
   ): void {
     if (typeof partialState === 'function') {

package/Lists/ViewabilityHelper.js

@@ -10,7 +10,8 @@
 
 'use strict';
 
-import type {FrameMetricProps} from './VirtualizedListProps';
+import type {CellMetricProps} from './ListMetricsAggregator';
+import ListMetricsAggregator from './ListMetricsAggregator';
 
 const invariant = require('invariant');
 
@@ -101,17 +102,10 @@ class ViewabilityHelper {
    * Determines which items are viewable based on the current metrics and config.
    */
   computeViewableItems(
-    props: FrameMetricProps,
+    props: CellMetricProps,
     scrollOffset: number,
     viewportHeight: number,
-    getFrameMetrics: (
-      index: number,
-      props: FrameMetricProps,
-    ) => ?{
-      length: number,
-      offset: number,
-      ...
-    },
+    listMetrics: ListMetricsAggregator,
     // Optional optimization to reduce the scan size
     renderRange?: {
       first: number,
@@ -146,12 +140,13 @@ class ViewabilityHelper {
       return [];
     }
     for (let idx = first; idx <= last; idx++) {
-      const metrics = getFrameMetrics(idx, props);
+      const metrics = listMetrics.getCellMetrics(idx, props);
       if (!metrics) {
         continue;
       }
-      const top = metrics.offset - scrollOffset;
-      const bottom = top + metrics.length;
+      const top = Math.floor(metrics.offset - scrollOffset);
+      const bottom = Math.floor(top + metrics.length);
+
       if (top < viewportHeight && bottom > 0) {
         firstVisible = idx;
         if (
@@ -178,21 +173,14 @@ class ViewabilityHelper {
    * `onViewableItemsChanged` as appropriate.
    */
   onUpdate(
-    props: FrameMetricProps,
+    props: CellMetricProps,
     scrollOffset: number,
     viewportHeight: number,
-    getFrameMetrics: (
-      index: number,
-      props: FrameMetricProps,
-    ) => ?{
-      length: number,
-      offset: number,
-      ...
-    },
+    listMetrics: ListMetricsAggregator,
     createViewToken: (
       index: number,
       isViewable: boolean,
-      props: FrameMetricProps,
+      props: CellMetricProps,
     ) => ViewToken,
     onViewableItemsChanged: ({
       viewableItems: Array<ViewToken>,
@@ -210,7 +198,7 @@ class ViewabilityHelper {
     if (
       (this._config.waitForInteraction && !this._hasInteracted) ||
       itemCount === 0 ||
-      !getFrameMetrics(0, props)
+      !listMetrics.getCellMetrics(0, props)
     ) {
       return;
     }
@@ -220,7 +208,7 @@ class ViewabilityHelper {
         props,
         scrollOffset,
         viewportHeight,
-        getFrameMetrics,
+        listMetrics,
         renderRange,
       );
     }
@@ -275,7 +263,7 @@ class ViewabilityHelper {
   }
 
   _onUpdateSync(
-    props: FrameMetricProps,
+    props: CellMetricProps,
     viewableIndicesToCheck: Array<number>,
     onViewableItemsChanged: ({
       changed: Array<ViewToken>,
@@ -285,7 +273,7 @@ class ViewabilityHelper {
     createViewToken: (
       index: number,
       isViewable: boolean,
-      props: FrameMetricProps,
+      props: CellMetricProps,
     ) => ViewToken,
   ) {
     // Filter out indices that have gone out of view since this call was scheduled.

package/Lists/VirtualizeUtils.js

@@ -10,7 +10,9 @@
 
 'use strict';
 
-import type {FrameMetricProps} from './VirtualizedListProps';
+import type ListMetricsAggregator, {
+  CellMetricProps,
+} from './ListMetricsAggregator';
 
 /**
  * Used to find the indices of the frames that overlap the given offsets. Useful for finding the
@@ -19,15 +21,8 @@ import type {FrameMetricProps} from './VirtualizedListProps';
  */
 export function elementsThatOverlapOffsets(
   offsets: Array<number>,
-  props: FrameMetricProps,
-  getFrameMetrics: (
-    index: number,
-    props: FrameMetricProps,
-  ) => {
-    length: number,
-    offset: number,
-    ...
-  },
+  props: CellMetricProps,
+  listMetrics: ListMetricsAggregator,
   zoomScale: number = 1,
 ): Array<number> {
   const itemCount = props.getItemCount(props.data);
@@ -38,9 +33,8 @@ export function elementsThatOverlapOffsets(
     let right = itemCount - 1;
 
     while (left <= right) {
-      // eslint-disable-next-line no-bitwise
-      const mid = left + ((right - left) >>> 1);
-      const frame = getFrameMetrics(mid, props);
+      const mid = left + Math.floor((right - left) / 2);
+      const frame = listMetrics.getCellMetricsApprox(mid, props);
       const scaledOffsetStart = frame.offset * zoomScale;
       const scaledOffsetEnd = (frame.offset + frame.length) * zoomScale;
 
@@ -99,21 +93,14 @@ export function newRangeCount(
  * biased in the direction of scroll.
  */
 export function computeWindowedRenderLimits(
-  props: FrameMetricProps,
+  props: CellMetricProps,
   maxToRenderPerBatch: number,
   windowSize: number,
   prev: {
     first: number,
     last: number,
   },
-  getFrameMetricsApprox: (
-    index: number,
-    props: FrameMetricProps,
-  ) => {
-    length: number,
-    offset: number,
-    ...
-  },
+  listMetrics: ListMetricsAggregator,
   scrollMetrics: {
     dt: number,
     offset: number,
@@ -152,7 +139,7 @@ export function computeWindowedRenderLimits(
   const overscanEnd = Math.max(0, visibleEnd + leadFactor * overscanLength);
 
   const lastItemOffset =
-    getFrameMetricsApprox(itemCount - 1, props).offset * zoomScale;
+    listMetrics.getCellMetricsApprox(itemCount - 1, props).offset * zoomScale;
   if (lastItemOffset < overscanBegin) {
     // Entire list is before our overscan window
     return {
@@ -165,7 +152,7 @@ export function computeWindowedRenderLimits(
   let [overscanFirst, first, last, overscanLast] = elementsThatOverlapOffsets(
     [overscanBegin, visibleBegin, visibleEnd, overscanEnd],
     props,
-    getFrameMetricsApprox,
+    listMetrics,
     zoomScale,
   );
   overscanFirst = overscanFirst == null ? 0 : overscanFirst;

package/Lists/VirtualizedList.d.ts

@@ -267,7 +267,7 @@ export interface VirtualizedListWithoutRenderItemProps<ItemT>
 
   /**
    * The maximum number of items to render in each incremental render batch. The more rendered at
-   * once, the better the fill rate, but responsiveness my suffer because rendering content may
+   * once, the better the fill rate, but responsiveness may suffer because rendering content may
    * interfere with responding to button taps or other interactions.
    */
   maxToRenderPerBatch?: number | undefined;