feat(iOS, Stack, Tabs): improve nested container integration -> introduce Container & ContainerItem (#4227)

## Description

Port the container-nesting protocol from Android to iOS so nesting
information
propagates between containers, and use it to resolve the content scroll
view for
special effects (e.g. scroll-to-top) across a nesting boundary.

On iOS the protocol is expressed at the view-controller level, mirroring
the
Android side. Shared state/logic lives in two composition holders:
`RNSContainerItemSupport` (item side) and
`RNSParentContainerItemRegistry`
(container side).

Closes
software-mansion/react-native-screens-labs#1573
Closes
software-mansion/react-native-screens-labs#1424

## Changes

- Introduce the `RNSContainer` and `RNSContainerItem` protocols and the
two
composition holders (`RNSContainerItemSupport`,
`RNSParentContainerItemRegistry`)
  mirroring the Android implementation.
- `RNSStackNavigationController` and `RNSTabBarController` adopt
`RNSContainer`
and self-register / unregister with the nearest parent
`RNSContainerItem` from
their own `didMoveToParentViewController:` lifecycle (i.e. as the
container is
added to / removed from the view-controller hierarchy). The host views
only
  mount the controller.
- `RNSStackScreenController` and `RNSTabsScreenViewController` adopt
  `RNSContainerItem`. Content-scroll-view resolution now follows
  cached -> nested container -> descendant-chain heuristic.
- The parent walk follows the view-controller containment chain
  (`parentViewController`) upwards to the nearest `RNSContainerItem`.
- `RNSTabsScreenViewController.resolveContentScrollView` delegates to
`findContentScrollView`, removing the duplicated edge / heuristic
lookup.
- Wire the stack screen's content scroll view via
`setContentScrollView:forEdge:`
(native `UINavigationBar` scroll edge appearance, top-screen-tap
scroll-to-top
  on iPad), matching the tabs screen.

## Before & after - visual documentation

There is no change in behaviour. It should work correctly right now,
just not "by accident".

## Test plan

Use the `test-stack-svm-tabs-special-effects` to confirm that indeed,
special effects now do work in nested container scenario, even when the
"standard UIKit heuristic" is broken.

## Checklist

- [x] Included code example that can be used to test this change.
- [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [ ] For API changes, updated relevant public types.
- [ ] Ensured that CI passes

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kkafar

apps/src/tests/component-integration-tests/scroll-view-marker/index.ts

@@ -2,6 +2,9 @@ import type { ScenarioGroup } from '@apps/tests/shared/helpers';
 import TestSvmTabsScrollEdgeEffects from './test-svm-tabs-scroll-edge-effects';
 import TestStackSvmTabsSpecialEffects from './test-stack-svm-tabs-special-effects';
 
+export { default as TestSvmTabsScrollEdgeEffects } from './test-svm-tabs-scroll-edge-effects';
+export { default as TestStackSvmTabsSpecialEffects } from './test-stack-svm-tabs-special-effects';
+
 const scenarios = {
   TestSvmTabsScrollEdgeEffects,
   TestStackSvmTabsSpecialEffects,

ios/gamma/stack/host/RNSStackNavigationController.h

@@ -1,11 +1,12 @@
 #pragma once
 
+#import "RNSContainer.h"
 #include "RNSStackNavigationBarCoordinator.h"
 #include "RNSStackScreenComponentView.h"
 
 @protocol RNSViewFrameChangeDelegate;
 
-@interface RNSStackNavigationController : UINavigationController
+@interface RNSStackNavigationController : UINavigationController <RNSContainer>
 
 @property (nonatomic, weak, nullable) id<RNSViewFrameChangeDelegate> navigationBarFrameChangeDelegate;
 

ios/gamma/stack/host/RNSStackNavigationController.mm

@@ -1,5 +1,7 @@
 #import "RNSStackNavigationController.h"
+#import "RNSContainer.h"
 #import "RNSLog.h"
+#import "RNSParentContainerItemRegistry.h"
 #import "RNSStackOperation.h"
 #import "RNSStackScreenController.h"
 #import "RNSViewFrameChangeDelegate.h"
@@ -8,6 +10,7 @@
 @implementation RNSStackNavigationController {
   NSMutableArray<RNSPushOperation *> *_Nonnull _pendingPushOperations;
   NSMutableArray<RNSPopOperation *> *_Nonnull _pendingPopOperations;
+  RNSParentContainerItemRegistry *_Nonnull _parentContainerRegistry;
 }
 
 - (instancetype)init
@@ -24,6 +27,50 @@ - (void)initState
 {
   _pendingPushOperations = [NSMutableArray array];
   _pendingPopOperations = [NSMutableArray array];
+  _parentContainerRegistry = [RNSParentContainerItemRegistry new];
+}
+
+#pragma mark-- Layout
+
+- (void)viewDidLayoutSubviews
+{
+  [super viewDidLayoutSubviews];
+  [_navigationBarFrameChangeDelegate viewFrameDidChange:self.navigationBar];
+}
+
+#pragma mark - RNSContainer
+
+- (nullable UIScrollView *)resolveCurrentContentScrollView
+{
+  // We assume `topViewController` corresponds to the currently presented screen.
+  UIViewController *topController = self.topViewController;
+  if (![topController isKindOfClass:RNSStackScreenController.class]) {
+    return nil;
+  }
+  return [static_cast<RNSStackScreenController *>(topController) findContentScrollView];
+}
+
+- (void)attachToParentContainerItem
+{
+  [_parentContainerRegistry attachContainer:self];
+}
+
+- (void)detachFromParentContainerItem
+{
+  [_parentContainerRegistry detachContainer:self];
+}
+
+#pragma mark - View controller containment
+
+- (void)didMoveToParentViewController:(UIViewController *)parent
+{
+  [super didMoveToParentViewController:parent];
+
+  if (parent != nil) {
+    [self attachToParentContainerItem];
+  } else {
+    [self detachFromParentContainerItem];
+  }
 }
 
 - (BOOL)hasPendingOperations
@@ -75,14 +122,6 @@ - (void)performContainerUpdateIfNeeded
   [_pendingPushOperations removeAllObjects];
 }
 
-#pragma mark - Layout
-
-- (void)viewDidLayoutSubviews
-{
-  [super viewDidLayoutSubviews];
-  [_navigationBarFrameChangeDelegate viewFrameDidChange:self.navigationBar];
-}
-
 #pragma mark - Debug
 
 - (void)dumpStackModel

ios/gamma/stack/screen/RNSStackScreenComponentView.h

@@ -43,4 +43,16 @@ typedef NS_ENUM(int, RNSStackScreenActivityMode) {
 
 @end
 
+#pragma mark - Content scroll view
+
+@interface RNSStackScreenComponentView ()
+
+/**
+ * Content scroll view registered by a descendant `RNSScrollViewMarkerComponentView`, or nil if
+ * none has been registered. Queried by the owning controller (`RNSContainerItem`).
+ */
+- (nullable UIScrollView *)cachedContentScrollView;
+
+@end
+
 NS_ASSUME_NONNULL_END

ios/gamma/stack/screen/RNSStackScreenComponentView.mm

@@ -8,6 +8,8 @@
 #import <rnscreens/RNSStackScreenComponentDescriptor.h>
 
 #import "RNSConversions-Stack.h"
+#import "RNSScrollViewMarkerComponentView.h"
+#import "RNSScrollViewSeeking.h"
 #import "RNSStackHeaderConfigComponentView.h"
 #import "RNSStackHostComponentView.h"
 #import "RNSStackNavigationController.h"
@@ -18,7 +20,7 @@
 
 namespace react = facebook::react;
 
-@interface RNSStackScreenComponentView () <RCTMountingTransactionObserving>
+@interface RNSStackScreenComponentView () <RCTMountingTransactionObserving, RNSScrollViewSeeking>
 @end
 
 #pragma mark - View implementation
@@ -27,6 +29,11 @@ @implementation RNSStackScreenComponentView {
   RNSStackScreenController *_Nonnull _controller;
   RNSStackScreenComponentEventEmitter *_Nonnull _reactEventEmitter;
 
+  // Content scroll view registered by a descendant `RNSScrollViewMarkerComponentView`. Queried by
+  // the owning `RNSStackScreenController` (as `RNSContainerItem`) when resolving the content
+  // scroll view for special effects.
+  __weak UIScrollView *_Nullable _contentScrollView;
+
   // Flags
   BOOL _hasUpdatedActivityMode;
 }
@@ -79,6 +86,21 @@ - (void)invalidateImpl
   });
 }
 
+#pragma mark - RNSScrollViewSeeking
+
+- (void)registerDescendantScrollView:(UIScrollView *)scrollView fromMarker:(RNSScrollViewMarkerComponentView *)marker
+{
+  // Native scroll-edge behavior (UINavigationBar scroll edge appearance, top-screen-tap scroll-to-top on iPad).
+  [_controller setContentScrollView:scrollView forEdge:NSDirectionalRectEdgeAll];
+  // Cache used by the container-nesting content-scroll-view resolution.
+  _contentScrollView = scrollView;
+}
+
+- (nullable UIScrollView *)cachedContentScrollView
+{
+  return _contentScrollView;
+}
+
 #pragma mark - Events
 
 - (nonnull RNSStackScreenComponentEventEmitter *)reactEventEmitter

ios/gamma/stack/screen/RNSStackScreenController.h

@@ -1,14 +1,15 @@
 #pragma once
 
 #import <UIKit/UIKit.h>
+#import "RNSContainerItem.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
 @class RNSStackScreenComponentView;
 @class RNSStackController;
 @class RNSStackScreenHeaderCoordinator;
 
-@interface RNSStackScreenController : UIViewController
+@interface RNSStackScreenController : UIViewController <RNSContainerItem>
 
 @property (nonatomic, strong, readonly, nonnull) RNSStackScreenHeaderCoordinator *headerCoordinator;
 

ios/gamma/stack/screen/RNSStackScreenController.mm

@@ -1,4 +1,6 @@
 #import "RNSStackScreenController.h"
+#import "RNSContainer.h"
+#import "RNSContainerItemSupport.h"
 #import "RNSLog.h"
 #import "RNSStackHostComponentView.h"
 #import "RNSStackNavigationController.h"
@@ -8,17 +10,42 @@
 
 @implementation RNSStackScreenController {
   RNSStackScreenComponentView *_Nonnull _screenView;
+  RNSContainerItemSupport *_Nonnull _containerItemSupport;
 }
 
 - (instancetype)initWithComponentView:(RNSStackScreenComponentView *)componentView
 {
   if (self = [super initWithNibName:nil bundle:nil]) {
     _screenView = componentView;
     _headerCoordinator = [[RNSStackScreenHeaderCoordinator alloc] initWithScreenController:self];
+    _containerItemSupport = [RNSContainerItemSupport new];
   }
   return self;
 }
 
+#pragma mark - RNSContainerItem
+
+- (void)registerNestedContainer:(id<RNSContainer>)container
+{
+  [_containerItemSupport registerNestedContainer:container];
+}
+
+- (void)unregisterNestedContainer:(id<RNSContainer>)container
+{
+  [_containerItemSupport unregisterNestedContainer:container];
+}
+
+- (nullable id<RNSContainer>)resolveNestedContainer
+{
+  return [_containerItemSupport resolveNestedContainer];
+}
+
+- (nullable UIScrollView *)findContentScrollView
+{
+  return [_containerItemSupport findContentScrollViewWithCachedScrollView:[_screenView cachedContentScrollView]
+                                                            heuristicRoot:_screenView];
+}
+
 - (RNSStackScreenComponentEventEmitter *)reactEventEmitter
 {
   return [_screenView reactEventEmitter];

ios/helpers/container/RNSContainer.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * A navigation container (e.g. stack, tabs) that hosts items and can resolve the content scroll
+ * view of whichever item is currently presented.
+ *
+ * On iOS the concept is implemented at the view-controller level: `RNSStackNavigationController`
+ * and `RNSTabBarController` conform to this protocol.
+ */
+@protocol RNSContainer <NSObject>
+
+/**
+ * A container can host multiple items, each with its own content scroll view. It is up to the
+ * implementer to decide which scroll view to return here (if any) for the item that is currently
+ * presented.
+ */
+- (nullable UIScrollView *)resolveCurrentContentScrollView;
+
+@end
+
+NS_ASSUME_NONNULL_END

ios/helpers/container/RNSContainerItem.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+#import "RNSContentScrollViewProviding.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol RNSContainer;
+
+/**
+ * A single item hosted by an `RNSContainer` (e.g. a stack screen, a tab). An item may itself host
+ * a single nested `RNSContainer` and exposes the content scroll view of its subtree via
+ * `findContentScrollView` (inherited from `RNSContentScrollViewProviding`).
+ *
+ * On iOS the concept is implemented at the view-controller level: `RNSStackScreenController` and
+ * `RNSTabsScreenViewController` conform to this protocol.
+ */
+@protocol RNSContainerItem <RNSContentScrollViewProviding>
+
+#pragma mark - Nested Container handling
+
+/**
+ * A `RNSContainerItem` supports at most a single nested `RNSContainer`. Registering a second
+ * container while one is already registered overwrites the previous one. This is an intentional
+ * design invariant: a single item is expected to host at most one nested container.
+ */
+- (void)registerNestedContainer:(id<RNSContainer>)container;
+
+- (void)unregisterNestedContainer:(id<RNSContainer>)container;
+
+- (nullable id<RNSContainer>)resolveNestedContainer;
+
+#pragma mark - Content Scroll View support
+
+// `findContentScrollView` is inherited from `RNSContentScrollViewProviding`.
+
+@end
+
+NS_ASSUME_NONNULL_END

ios/helpers/container/RNSContainerItemSupport.h

@@ -0,0 +1,35 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol RNSContainer;
+
+/**
+ * Composition holder for the `RNSContainerItem` side of the container-nesting mechanism.
+ *
+ * It owns the (weak) reference to the nested container and implements the content-scroll-view
+ * resolution order shared by all container items. The cached content scroll view itself is NOT
+ * owned here - it lives on the item's component view and is passed in by the owner.
+ */
+@interface RNSContainerItemSupport : NSObject
+
+- (void)registerNestedContainer:(id<RNSContainer>)container;
+
+- (void)unregisterNestedContainer:(id<RNSContainer>)container;
+
+- (nullable id<RNSContainer>)resolveNestedContainer;
+
+/**
+ * Resolves the content scroll view using the shared order:
+ *   1. the provided `cachedScrollView` (registered on the owner's view by the scroll view marker),
+ *   2. the nested container's current content scroll view,
+ *   3. a first-descendant-chain heuristic rooted at `rootView`.
+ */
+- (nullable UIScrollView *)findContentScrollViewWithCachedScrollView:(nullable UIScrollView *)cachedScrollView
+                                                       heuristicRoot:(nullable UIView *)rootView;
+
+@end
+
+NS_ASSUME_NONNULL_END