@react-native/virtualized-lists 0.72.1 → 0.72.3

package/Lists/VirtualizedList.d.ts

@@ -23,7 +23,7 @@ export interface ViewToken {
   key: string;
   index: number | null;
   isViewable: boolean;
-  section?: any;
+  section?: any | undefined;
 }
 
 export interface ViewabilityConfig {
@@ -87,6 +87,16 @@ export type ListRenderItem<ItemT> = (
   info: ListRenderItemInfo<ItemT>,
 ) => React.ReactElement | null;
 
+export interface CellRendererProps<ItemT> {
+  cellKey: string;
+  children: React.ReactNode;
+  index: number;
+  item: ItemT;
+  onFocusCapture?: ((event: FocusEvent) => void) | undefined;
+  onLayout?: ((event: LayoutChangeEvent) => void) | undefined;
+  style: StyleProp<ViewStyle> | undefined;
+}
+
 /**
  * @see https://reactnative.dev/docs/virtualizedlist
  */
@@ -188,7 +198,7 @@ export interface VirtualizedListWithoutRenderItemProps<ItemT>
    * The default accessor functions assume this is an Array<{key: string}> but you can override
    * getItem, getItemCount, and keyExtractor to handle any type of index-based data.
    */
-  data?: any;
+  data?: any | undefined;
 
   /**
    * `debug` will turn on extra logging and visual overlays to aid with debugging both usage and
@@ -208,7 +218,7 @@ export interface VirtualizedListWithoutRenderItemProps<ItemT>
    * any of your `renderItem`, Header, Footer, etc. functions depend on anything outside of the
    * `data` prop, stick it here and treat it immutably.
    */
-  extraData?: any;
+  extraData?: any | undefined;
 
   /**
    * A generic accessor for extracting an item from any sort of data blob.
@@ -370,5 +380,14 @@ export interface VirtualizedListWithoutRenderItemProps<ItemT>
    */
   windowSize?: number | undefined;
 
-  CellRendererComponent?: React.ComponentType<any> | undefined;
+  /**
+   * CellRendererComponent allows customizing how cells rendered by
+   * `renderItem`/`ListItemComponent` are wrapped when placed into the
+   * underlying ScrollView. This component must accept event handlers which
+   * notify VirtualizedList of changes within the cell.
+   */
+  CellRendererComponent?:
+    | React.ComponentType<CellRendererProps<ItemT>>
+    | null
+    | undefined;
 }

package/Lists/VirtualizedList.js

@@ -50,6 +50,7 @@ import {
   keyExtractor as defaultKeyExtractor,
 } from './VirtualizeUtils';
 import invariant from 'invariant';
+import nullthrows from 'nullthrows';
 import * as React from 'react';
 
 export type {RenderItemProps, RenderItemType, Separators};
@@ -420,21 +421,7 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
 
   constructor(props: Props) {
     super(props);
-    invariant(
-      // $FlowFixMe[prop-missing]
-      !props.onScroll || !props.onScroll.__isNative,
-      'Components based on VirtualizedList must be wrapped with Animated.createAnimatedComponent ' +
-        'to support native onScroll events with useNativeDriver',
-    );
-    invariant(
-      windowSizeOrDefault(props.windowSize) > 0,
-      'VirtualizedList: The windowSize prop must be present and set to a value greater than 0.',
-    );
-
-    invariant(
-      props.getItemCount,
-      'VirtualizedList: The "getItemCount" prop must be provided',
-    );
+    this._checkProps(props);
 
     this._fillRateHelper = new FillRateHelper(this._getFrameMetrics);
     this._updateCellsToRenderBatcher = new Batchinator(
@@ -459,11 +446,6 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
       }
     }
 
-    invariant(
-      !this.context,
-      'Unexpectedly saw VirtualizedListContext available in ctor',
-    );
-
     const initialRenderRegion = VirtualizedList._initialRenderRegion(props);
 
     this.state = {
@@ -472,6 +454,54 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
     };
   }
 
+  _checkProps(props: Props) {
+    const {onScroll, windowSize, getItemCount, data, initialScrollIndex} =
+      props;
+
+    invariant(
+      // $FlowFixMe[prop-missing]
+      !onScroll || !onScroll.__isNative,
+      'Components based on VirtualizedList must be wrapped with Animated.createAnimatedComponent ' +
+        'to support native onScroll events with useNativeDriver',
+    );
+    invariant(
+      windowSizeOrDefault(windowSize) > 0,
+      'VirtualizedList: The windowSize prop must be present and set to a value greater than 0.',
+    );
+
+    invariant(
+      getItemCount,
+      'VirtualizedList: The "getItemCount" prop must be provided',
+    );
+
+    const itemCount = getItemCount(data);
+
+    if (
+      initialScrollIndex != null &&
+      !this._hasTriggeredInitialScrollToIndex &&
+      (initialScrollIndex < 0 ||
+        (itemCount > 0 && initialScrollIndex >= itemCount)) &&
+      !this._hasWarned.initialScrollIndex
+    ) {
+      console.warn(
+        `initialScrollIndex "${initialScrollIndex}" is not valid (list has ${itemCount} items)`,
+      );
+      this._hasWarned.initialScrollIndex = true;
+    }
+
+    if (__DEV__ && !this._hasWarned.flexWrap) {
+      // $FlowFixMe[underconstrained-implicit-instantiation]
+      const flatStyles = StyleSheet.flatten(this.props.contentContainerStyle);
+      if (flatStyles != null && flatStyles.flexWrap === 'wrap') {
+        console.warn(
+          '`flexWrap: `wrap`` is not supported with the `VirtualizedList` components.' +
+            'Consider using `numColumns` with `FlatList` instead.',
+        );
+        this._hasWarned.flexWrap = true;
+      }
+    }
+  }
+
   static _createRenderMask(
     props: Props,
     cellsAroundViewport: {first: number, last: number},
@@ -518,15 +548,21 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
 
   static _initialRenderRegion(props: Props): {first: number, last: number} {
     const itemCount = props.getItemCount(props.data);
-    const scrollIndex = Math.floor(Math.max(0, props.initialScrollIndex ?? 0));
+
+    const firstCellIndex = Math.max(
+      0,
+      Math.min(itemCount - 1, Math.floor(props.initialScrollIndex ?? 0)),
+    );
+
+    const lastCellIndex =
+      Math.min(
+        itemCount,
+        firstCellIndex + initialNumToRenderOrDefault(props.initialNumToRender),
+      ) - 1;
 
     return {
-      first: scrollIndex,
-      last:
-        Math.min(
-          itemCount,
-          scrollIndex + initialNumToRenderOrDefault(props.initialNumToRender),
-        ) - 1,
+      first: firstCellIndex,
+      last: lastCellIndex,
     };
   }
 
@@ -554,8 +590,6 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
     const onEndReachedThreshold = onEndReachedThresholdOrDefault(
       props.onEndReachedThreshold,
     );
-    this._updateViewableItems(props, cellsAroundViewport);
-
     const {contentLength, offset, visibleLength} = this._scrollMetrics;
     const distanceFromEnd = contentLength - visibleLength - offset;
 
@@ -714,29 +748,31 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
     const end = getItemCount(data) - 1;
     let prevCellKey;
     last = Math.min(end, last);
+
     for (let ii = first; ii <= last; ii++) {
       const item = getItem(data, ii);
       const key = this._keyExtractor(item, ii, this.props);
+
       this._indicesToKeys.set(ii, key);
       if (stickyIndicesFromProps.has(ii + stickyOffset)) {
         stickyHeaderIndices.push(cells.length);
       }
+
+      const shouldListenForLayout =
+        getItemLayout == null || debug || this._fillRateHelper.enabled();
+
       cells.push(
         <CellRenderer
           CellRendererComponent={CellRendererComponent}
           ItemSeparatorComponent={ii < end ? ItemSeparatorComponent : undefined}
           ListItemComponent={ListItemComponent}
           cellKey={key}
-          debug={debug}
-          fillRateHelper={this._fillRateHelper}
-          getItemLayout={getItemLayout}
           horizontal={horizontal}
           index={ii}
           inversionStyle={inversionStyle}
           item={item}
           key={key}
           prevCellKey={prevCellKey}
-          onCellLayout={this._onCellLayout}
           onUpdateSeparators={this._onUpdateSeparators}
           onCellFocusCapture={e => this._onCellFocusCapture(key)}
           onUnmount={this._onCellUnmount}
@@ -744,6 +780,9 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
             this._cellRefs[key] = ref;
           }}
           renderItem={renderItem}
+          {...(shouldListenForLayout && {
+            onCellLayout: this._onCellLayout,
+          })}
         />,
       );
       prevCellKey = key;
@@ -809,16 +848,7 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
   }
 
   render(): React.Node {
-    if (__DEV__) {
-      // $FlowFixMe[underconstrained-implicit-instantiation]
-      const flatStyles = StyleSheet.flatten(this.props.contentContainerStyle);
-      if (flatStyles != null && flatStyles.flexWrap === 'wrap') {
-        console.warn(
-          '`flexWrap: `wrap`` is not supported with the `VirtualizedList` components.' +
-            'Consider using `numColumns` with `FlatList` instead.',
-        );
-      }
-    }
+    this._checkProps(this.props);
     const {ListEmptyComponent, ListFooterComponent, ListHeaderComponent} =
       this.props;
     const {data, horizontal} = this.props;
@@ -1233,6 +1263,7 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
   }
 
   _onCellUnmount = (cellKey: string) => {
+    delete this._cellRefs[cellKey];
     const curr = this._frames[cellKey];
     if (curr) {
       this._frames[cellKey] = {...curr, inLayout: false};
@@ -1509,10 +1540,17 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
       !this._hasTriggeredInitialScrollToIndex
     ) {
       if (this.props.contentOffset == null) {
-        this.scrollToIndex({
-          animated: false,
-          index: this.props.initialScrollIndex,
-        });
+        if (
+          this.props.initialScrollIndex <
+          this.props.getItemCount(this.props.data)
+        ) {
+          this.scrollToIndex({
+            animated: false,
+            index: nullthrows(this.props.initialScrollIndex),
+          });
+        } else {
+          this.scrollToEnd({animated: false});
+        }
       }
       this._hasTriggeredInitialScrollToIndex = true;
     }
@@ -1714,6 +1752,8 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
   };
 
   _updateCellsToRender = () => {
+    this._updateViewableItems(this.props, this.state.cellsAroundViewport);
+
     this.setState((state, props) => {
       const cellsAroundViewport = this._adjustCellsAroundViewport(
         props,
@@ -1846,14 +1886,6 @@ class VirtualizedList extends StateSafePureComponent<Props, State> {
     const focusedCellIndex = lastFocusedCellRenderer.props.index;
     const itemCount = props.getItemCount(props.data);
 
-    // The cell may have been unmounted and have a stale index
-    if (
-      focusedCellIndex >= itemCount ||
-      this._indicesToKeys.get(focusedCellIndex) !== this._lastFocusedCellKey
-    ) {
-      return [];
-    }
-
     let first = focusedCellIndex;
     let heightOfCellsBeforeFocused = 0;
     for (

package/Lists/VirtualizedListCellRenderer.js

@@ -13,8 +13,7 @@ import type {
   FocusEvent,
   LayoutEvent,
 } from 'react-native/Libraries/Types/CoreEventTypes';
-import type FillRateHelper from './FillRateHelper';
-import type {RenderItemType} from './VirtualizedListProps';
+import type {CellRendererProps, RenderItemType} from './VirtualizedListProps';
 
 import {View, StyleSheet} from 'react-native';
 import {VirtualizedListCellContextProvider} from './VirtualizedListContext.js';
@@ -22,28 +21,17 @@ import invariant from 'invariant';
 import * as React from 'react';
 
 export type Props<ItemT> = {
-  CellRendererComponent?: ?React.ComponentType<any>,
+  CellRendererComponent?: ?React.ComponentType<CellRendererProps<ItemT>>,
   ItemSeparatorComponent: ?React.ComponentType<
     any | {highlighted: boolean, leadingItem: ?ItemT},
   >,
   ListItemComponent?: ?(React.ComponentType<any> | React.Element<any>),
   cellKey: string,
-  debug?: ?boolean,
-  fillRateHelper: FillRateHelper,
-  getItemLayout?: (
-    data: any,
-    index: number,
-  ) => {
-    length: number,
-    offset: number,
-    index: number,
-    ...
-  },
   horizontal: ?boolean,
   index: number,
   inversionStyle: ViewStyleProp,
   item: ItemT,
-  onCellLayout: (event: LayoutEvent, cellKey: string, index: number) => void,
+  onCellLayout?: (event: LayoutEvent, cellKey: string, index: number) => void,
   onCellFocusCapture?: (event: FocusEvent) => void,
   onUnmount: (cellKey: string) => void,
   onUpdateSeparators: (
@@ -181,14 +169,13 @@ export default class CellRenderer<ItemT> extends React.Component<
       CellRendererComponent,
       ItemSeparatorComponent,
       ListItemComponent,
-      debug,
-      fillRateHelper,
-      getItemLayout,
+      cellKey,
       horizontal,
       item,
       index,
       inversionStyle,
       onCellFocusCapture,
+      onCellLayout,
       renderItem,
     } = this.props;
     const element = this._renderElement(
@@ -198,11 +185,6 @@ export default class CellRenderer<ItemT> extends React.Component<
       index,
     );
 
-    const onLayout =
-      (getItemLayout && !debug && !fillRateHelper.enabled()) ||
-      !this.props.onCellLayout
-        ? undefined
-        : this._onLayout;
     // NOTE: that when this is a sticky header, `onLayout` will get automatically extracted and
     // called explicitly by `ScrollViewStickyHeader`.
     const itemSeparator: React.Node = React.isValidElement(
@@ -224,21 +206,19 @@ export default class CellRenderer<ItemT> extends React.Component<
     const result = !CellRendererComponent ? (
       <View
         style={cellStyle}
-        onLayout={onLayout}
         onFocusCapture={onCellFocusCapture}
-        /* $FlowFixMe[incompatible-type-arg] (>=0.89.0 site=react_native_fb) *
-        This comment suppresses an error found when Flow v0.89 was deployed. *
-        To see the error, delete this comment and run Flow. */
-      >
+        {...(onCellLayout && {onLayout: this._onLayout})}>
         {element}
         {itemSeparator}
       </View>
     ) : (
       <CellRendererComponent
-        {...this.props}
+        cellKey={cellKey}
+        index={index}
+        item={item}
         style={cellStyle}
-        onLayout={onLayout}
-        onFocusCapture={onCellFocusCapture}>
+        onFocusCapture={onCellFocusCapture}
+        {...(onCellLayout && {onLayout: this._onLayout})}>
         {element}
         {itemSeparator}
       </CellRendererComponent>

package/Lists/VirtualizedListProps.js

@@ -9,6 +9,10 @@
  */
 
 import {typeof ScrollView} from 'react-native';
+import type {
+  FocusEvent,
+  LayoutEvent,
+} from 'react-native/Libraries/Types/CoreEventTypes';
 import type {ViewStyleProp} from 'react-native/Libraries/StyleSheet/StyleSheet';
 import type {
   ViewabilityConfig,
@@ -34,6 +38,16 @@ export type RenderItemProps<ItemT> = {
   ...
 };
 
+export type CellRendererProps<ItemT> = $ReadOnly<{
+  cellKey: string,
+  children: React.Node,
+  index: number,
+  item: ItemT,
+  onFocusCapture?: (event: FocusEvent) => void,
+  onLayout?: (event: LayoutEvent) => void,
+  style: ViewStyleProp,
+}>;
+
 export type RenderItemType<ItemT> = (
   info: RenderItemProps<ItemT>,
 ) => React.Node;
@@ -102,10 +116,12 @@ type OptionalProps = {|
   inverted?: ?boolean,
   keyExtractor?: ?(item: Item, index: number) => string,
   /**
-   * Each cell is rendered using this element. Can be a React Component Class,
-   * or a render function. Defaults to using View.
+   * CellRendererComponent allows customizing how cells rendered by
+   * `renderItem`/`ListItemComponent` are wrapped when placed into the
+   * underlying ScrollView. This component must accept event handlers which
+   * notify VirtualizedList of changes within the cell.
    */
-  CellRendererComponent?: ?React.ComponentType<any>,
+  CellRendererComponent?: ?React.ComponentType<CellRendererProps<Item>>,
   /**
    * Rendered in between each item, but not at the top or bottom. By default, `highlighted` and
    * `leadingItem` props are provided. `renderItem` provides `separators.highlight`/`unhighlight`

package/index.js

@@ -24,6 +24,7 @@ export type {
   ViewabilityConfigCallbackPair,
 } from './Lists/ViewabilityHelper';
 export type {
+  CellRendererProps,
   RenderItemProps,
   RenderItemType,
   Separators,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native/virtualized-lists",
-  "version": "0.72.1",
+  "version": "0.72.3",
   "description": "Virtualized lists for React Native.",
   "repository": {
     "type": "git",
@@ -9,7 +9,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "invariant": "^2.2.4"
+    "invariant": "^2.2.4",
+    "nullthrows": "^1.1.1"
   },
   "devDependencies": {
     "react-test-renderer": "18.2.0"