Fix viewability reporting for cross-orientation nested lists (#58412)

Summary:

A horizontal `VirtualizedList` nested inside a vertical list could report its items through `onViewableItemsChanged` while the parent row was off screen. The existing same-orientation nesting path translates parent scroll metrics, but cross-orientation children have independent scroll axes and therefore need the visibility of their containing row as a separate signal.

Expose a semantic cell-visibility query through `VirtualizedListContext` and register cross-orientation children with the key of their containing cell. Parents evaluate those cells after scroll and layout changes, but invoke children only when the ancestor suppression state transitions. Known data rows without layout metrics fail closed, eliminating transient mount reports, while unsupported structural cells preserve the previous behavior.

Explicit suppression now clears previously published viewability tokens even when current cell metrics are unavailable. It also invalidates stale `minimumViewTime` work. Suppression propagates through deeper cross-orientation nesting, and parent registration is reconciled when orientation or context changes so unmount always cleans up the exact collection that was registered.

The new behavior is gated behind the `fixCrossOrientationNestedListViewability` JS feature flag, which defaults to off. While it is off, parents do not expose the cell-visibility query, so cross-orientation children are never registered or suppressed and nested lists behave as before. Independently of the flag, `ViewabilityHelper` now invalidates a pending `minimumViewTime` callback when an update returns early.

The implementation is kept in sync across the main, Windows, and macOS variants. The generated public API snapshot is updated accordingly.

Fixes #57797
Fixes #57778

Changelog:
[General][Fixed] - Do not report viewable items for a cross-orientation nested list while its parent row is off screen

Reviewed By: Abbondanzo

Differential Revision: D117727511

Author: amroaltah

packages/react-native/ReactNativeApi.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<3ce9599aceb36dd1f09ded3db3332daa>>
+ * @generated SignedSource<<adc11a9d577530725c3bf23ed3806582>>
  *
  * This file was generated by scripts/js-api/build-types/index.js.
  */
@@ -1771,6 +1771,7 @@ declare function configureNext(
 declare type ContentAvailable = 1 | null | void
 declare type Context = {
   readonly cellKey: string | undefined
+  readonly getCellVisibilityByKey?: (cellKey: string) => boolean | undefined
   readonly horizontal: boolean | undefined
   readonly getOutermostParentListRef: () => VirtualizedList_default
   readonly getScrollMetrics: () => {
@@ -1785,6 +1786,7 @@ declare type Context = {
   }
   readonly registerAsNestedChild: ($$PARAM_0$$: {
     cellKey: string
+    horizontal?: boolean
     ref: VirtualizedList_default
   }) => void
   readonly unregisterAsNestedChild: ($$PARAM_0$$: {
@@ -5503,6 +5505,7 @@ declare class ViewabilityHelper_default {
       first: number
       last: number
     },
+    suppressViewableItems?: boolean,
   ): void
   recordInteraction(): void
   resetViewableIndices(): void

packages/react-native/scripts/featureflags/ReactNativeFeatureFlags.config.js

@@ -1091,6 +1091,17 @@ const definitions: FeatureFlagDefinitions = {
       },
       ossReleaseStage: 'none',
     },
+    fixCrossOrientationNestedListViewability: {
+      defaultValue: false,
+      metadata: {
+        dateAdded: '2026-09-29',
+        description:
+          'When enabled, a VirtualizedList nested inside a list of the opposite orientation does not report viewable items while its containing cell is outside the parent viewport.',
+        expectedReleaseValue: true,
+        purpose: 'experimentation',
+      },
+      ossReleaseStage: 'none',
+    },
     fixVirtualizeListCollapseWindowSize: {
       defaultValue: false,
       metadata: {

packages/react-native/src/private/featureflags/ReactNativeFeatureFlags.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<6e73a99aafb36218e1d679637bb80c82>>
+ * @generated SignedSource<<0c6ae0cc911ae8ee487183dca0b0015c>>
  * @flow strict
  * @noformat
  */
@@ -37,6 +37,7 @@ export type ReactNativeFeatureFlagsJsOnly = Readonly<{
   enableImperativeEvents_DEPRECATED: Getter<boolean>,
   enableNativeEventTargetEventDispatching: Getter<boolean>,
   externalElementInspectionEnabled: Getter<boolean>,
+  fixCrossOrientationNestedListViewability: Getter<boolean>,
   fixVirtualizeListCollapseWindowSize: Getter<boolean>,
   isLayoutAnimationEnabled: Getter<boolean>,
   shouldUseAnimatedObjectForTransform: Getter<boolean>,
@@ -185,6 +186,11 @@ export const enableNativeEventTargetEventDispatching: Getter<boolean> = createJa
  */
 export const externalElementInspectionEnabled: Getter<boolean> = createJavaScriptFlagGetter('externalElementInspectionEnabled', true);
 
+/**
+ * When enabled, a VirtualizedList nested inside a list of the opposite orientation does not report viewable items while its containing cell is outside the parent viewport.
+ */
+export const fixCrossOrientationNestedListViewability: Getter<boolean> = createJavaScriptFlagGetter('fixCrossOrientationNestedListViewability', false);
+
 /**
  * Fixing an edge case where the current window size is not properly calculated with fast scrolling. Window size collapsed to 1 element even if windowSize more than the current amount of elements
  */

packages/virtualized-lists/Lists/ViewabilityHelper.js

@@ -82,7 +82,9 @@ export type ViewabilityConfig = Readonly<{
 class ViewabilityHelper {
   _config: ViewabilityConfig;
   _hasInteracted: boolean = false;
-  _timers: Set<number> = new Set();
+  _pendingSuppressedUpdate: boolean = false;
+  _timers: Set<ReturnType<typeof setTimeout>> = new Set();
+  _updateGeneration: number = 0;
   _viewableIndices: Array<number> = [];
   _viewableItems: Map<string, ViewToken> = new Map();
 
@@ -96,9 +98,6 @@ class ViewabilityHelper {
    * Cleanup, e.g. on unmount. Clears any pending timers.
    */
   dispose() {
-    /* $FlowFixMe[incompatible-type] (>=0.63.0 site=react_native_fb) This
-     * comment suppresses an error found when Flow v0.63 was deployed. To see
-     * the error delete this comment and run Flow. */
     this._timers.forEach(clearTimeout);
   }
 
@@ -197,17 +196,33 @@ class ViewabilityHelper {
       last: number,
       ...
     },
+    // Suppression bypasses the normal early returns so an empty result clears
+    // items reported before an ancestor moved off screen.
+    suppressViewableItems?: boolean,
   ): void {
+    const updateGeneration = this._updateGeneration + 1;
     const itemCount = props.getItemCount(props.data);
     if (
-      (this._config.waitForInteraction && !this._hasInteracted) ||
-      itemCount === 0 ||
-      !listMetrics.getCellMetrics(0, props)
+      suppressViewableItems !== true &&
+      this._config.waitForInteraction &&
+      !this._hasInteracted
     ) {
+      this._updateGeneration = updateGeneration;
+      this._pendingSuppressedUpdate = false;
+      this._viewableIndices = [];
+      return;
+    }
+    if (
+      suppressViewableItems !== true &&
+      (itemCount === 0 || !listMetrics.getCellMetrics(0, props))
+    ) {
+      this._updateGeneration = updateGeneration;
+      this._pendingSuppressedUpdate = false;
+      this._viewableIndices = [];
       return;
     }
     let viewableIndices: Array<number> = [];
-    if (itemCount) {
+    if (itemCount && suppressViewableItems !== true) {
       viewableIndices = this.computeViewableItems(
         props,
         scrollOffset,
@@ -218,35 +233,35 @@ class ViewabilityHelper {
     }
     if (
       this._viewableIndices.length === viewableIndices.length &&
-      this._viewableIndices.every((v, ii) => v === viewableIndices[ii])
+      this._viewableIndices.every((v, ii) => v === viewableIndices[ii]) &&
+      (suppressViewableItems !== true ||
+        this._viewableItems.size === 0 ||
+        this._pendingSuppressedUpdate)
     ) {
       // We might get a lot of scroll events where visibility doesn't change and we don't want to do
       // extra work in those cases.
       return;
     }
     this._viewableIndices = viewableIndices;
+    this._updateGeneration = updateGeneration;
     if (this._config.minimumViewTime) {
+      this._pendingSuppressedUpdate = suppressViewableItems === true;
       const handle: ReturnType<typeof setTimeout> = setTimeout(() => {
-        /* $FlowFixMe[incompatible-type] (>=0.63.0 site=react_native_fb) This
-         * comment suppresses an error found when Flow v0.63 was deployed. To
-         * see the error delete this comment and run Flow. */
         this._timers.delete(handle);
-        // `onUpdate` replaces the array whenever the visible set changes.
-        if (this._viewableIndices !== viewableIndices) {
+        if (this._updateGeneration !== updateGeneration) {
           return;
         }
+        this._pendingSuppressedUpdate = false;
         this._onUpdateSync(
           props,
           viewableIndices,
           onViewableItemsChanged,
           createViewToken,
         );
       }, this._config.minimumViewTime);
-      /* $FlowFixMe[incompatible-type] (>=0.63.0 site=react_native_fb) This
-       * comment suppresses an error found when Flow v0.63 was deployed. To see
-       * the error delete this comment and run Flow. */
       this._timers.add(handle);
     } else {
+      this._pendingSuppressedUpdate = false;
       this._onUpdateSync(
         props,
         viewableIndices,
@@ -261,6 +276,8 @@ class ViewabilityHelper {
    */
   resetViewableIndices() {
     this._viewableIndices = [];
+    this._pendingSuppressedUpdate = false;
+    this._updateGeneration++;
   }
 
   /**