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

Summary:
Pull Request resolved: #58412

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 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

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<<590f18ec6caea33fef591da5d56419f4>>
+ * @generated SignedSource<<0c9222928e2bb42a859e43ec4d9736c7>>
  *
  * This file was generated by scripts/js-api/build-types/index.js.
  */
@@ -1778,6 +1778,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: () => {
@@ -1792,6 +1793,7 @@ declare type Context = {
   }
   readonly registerAsNestedChild: ($$PARAM_0$$: {
     cellKey: string
+    horizontal?: boolean
     ref: VirtualizedList_default
   }) => void
   readonly unregisterAsNestedChild: ($$PARAM_0$$: {
@@ -5505,6 +5507,7 @@ declare class ViewabilityHelper_default {
       first: number
       last: number
     },
+    suppressViewableItems?: boolean,
   ): void
   recordInteraction(): void
   resetViewableIndices(): void

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<TimeoutID> = 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: TimeoutID = 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++;
   }
 
   /**