fix(Tabs, iOS): reconcile navigation state on implicit UIKit selection changes (#3877)

## Description

On iPad, when the app transitions from compact to regular horizontal
size class (e.g. user resizes the window), the More navigation
controller disappears. UIKit restores the previously selected tab by
calling `setSelectedIndex:` internally, but no
`UITabBarControllerDelegate` methods fire — leaving `_navigationState`
out of sync with UIKit's actual selection.

This PR ensures `_navigationState` stays consistent with UIKit
regardless of how the selection changes.

Closes
software-mansion/react-native-screens-labs#1107

## Changes

- Override `setSelectedIndex:` and `setSelectedViewController:` on
`RNSTabBarController` to detect untracked selection changes
- Add a guard flag (`_isHandlingExplicitSelectionUpdate`) set during all
known selection flows (container updates, delegate handling) to prevent
double state progression
- Add `reconcileNavigationStateWithUIKitState` — when the overrides fire
without the flag, this method detects the mismatch and updates
`_navigationState` + notifies the delegate
- Add `RNSTabsNavigationStateUpdateSourceImplicit` enum value to
distinguish UIKit-initiated side-effect changes from explicit user taps
and JS prop updates
- Update `progressNavigationState:withSource:` condition from `== User`
to `!= External` so that both `User` and `Implicit` sources update
`_lastUINavigationState` (needed for correct stale update rejection)

## Test plan

Using `test-tabs-more-navigation-controller.tsx` on iPad simulator:

1. Navigate to "Second" tab
2. Tap "More" tab bar item → select "Sixth" from the More list
3. Tap "More" tab bar item again to see the More list
4. Resize the app window to regular width (More controller disappears)
5. Verify `onTabSelected` event fires with `selectedScreenKey: "Second"`
6. Verify normal tab switching (tap, JS-driven) still works — no double
events, no provenance skips
7. Verify repeated selection still triggers special effects

Also another scenario: if we skip steps 2 & 3, no state update should be
sent!

## Checklist

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

Author: kkafar

ios/tabs/host/RNSTabBarController.mm

@@ -63,12 +63,18 @@ @implementation RNSTabBarController {
   RNSTabsNavigationState *_Nullable _navigationState;
 
   /// Holds last state that has been a result of UI-side navigation (user request).
+  /// This one is also updated in cases where UIKit modifies the selected tab implicitly,
+  /// e.g. when user resizes the app and more tab disappears.
   ///
   /// This property is nullable until first container update. Later it MUST NOT be nil.
   RNSTabsNavigationState *_Nullable _lastUINavigationState;
 
   RNSTabsNavigationState *_Nullable _pendingOperation;
 
+  /// When YES, the controller is inside an explicit selection-changing code path (container update,
+  /// delegate handling). Setter overrides skip reconciliation while this flag is set.
+  BOOL _isHandlingExplicitSelectionUpdate;
+
 #if !RCT_NEW_ARCH_ENABLED
   BOOL _isControllerFlushBlockScheduled;
 #endif // !RCT_NEW_ARCH_ENABLED
@@ -117,6 +123,22 @@ - (void)tabBar:(UITabBar *)tabBar didSelectItem:(UITabBarItem *)item
   RNSLog(@"TabBar: %@ didSelectItem: %@", tabBar, item);
 }
 
+- (void)setSelectedIndex:(NSUInteger)selectedIndex
+{
+  [super setSelectedIndex:selectedIndex];
+  if (!_isHandlingExplicitSelectionUpdate) {
+    [self reconcileNavigationStateWithUIKitState];
+  }
+}
+
+- (void)setSelectedViewController:(__kindof UIViewController *)selectedViewController
+{
+  [super setSelectedViewController:selectedViewController];
+  if (!_isHandlingExplicitSelectionUpdate) {
+    [self reconcileNavigationStateWithUIKitState];
+  }
+}
+
 #pragma mark - Signals
 
 - (void)setPendingNavigationStateUpdate:(nullable RNSTabsNavigationState *)navState
@@ -176,8 +198,11 @@ - (void)reactMountingTransactionDidMount
 
 - (void)performContainerUpdate
 {
+  _isHandlingExplicitSelectionUpdate = YES;
   [self updateChildViewControllersIfNeeded];
   [self updateSelectedViewControllerIfNeeded];
+  _isHandlingExplicitSelectionUpdate = NO;
+
   [self updateTabBarAppearanceIfNeeded];
   [self updateTabBarA11yIfNeeded];
   [self updateOrientationIfNeeded];
@@ -351,6 +376,7 @@ - (BOOL)tabBarController:(UITabBarController *)tabBarController
     }
   }
 
+  _isHandlingExplicitSelectionUpdate = YES;
   return YES;
 }
 
@@ -367,6 +393,7 @@ - (void)tabBarController:(UITabBarController *)tabBarController
       viewController.class);
 
   [self userDidSelectViewController:viewController];
+  _isHandlingExplicitSelectionUpdate = NO;
 }
 
 #pragma mark - UINavigationControllerDelegate
@@ -560,7 +587,7 @@ - (void)progressNavigationState:(nonnull NSString *)newSelectedScreenKey
   _navigationState = [RNSTabsNavigationState stateWithSelectedScreenKey:newSelectedScreenKey
                                                              provenance:_navigationState.provenance + 1];
 
-  if (updateSource == RNSTabsNavigationStateUpdateSourceUser) {
+  if (updateSource != RNSTabsNavigationStateUpdateSourceExternal) {
     _lastUINavigationState = [_navigationState cloneState];
   }
 }
@@ -596,6 +623,58 @@ - (nonnull NSString *)screenKeyForSelectedViewController
   return [self screenKeyForViewController:self.selectedViewController];
 }
 
+/**
+ * Detect and fix any mismatch between `_navigationState` and UIKit's actual selected view controller.
+ *
+ * This is called from the `setSelectedIndex:` / `setSelectedViewController:` overrides when
+ * the change was NOT initiated by a known code path (container update, delegate handling).
+ * The primary case is UIKit restoring a tab when the More navigation controller disappears
+ * during a horizontal size class transition on iPad.
+ */
+- (void)reconcileNavigationStateWithUIKitState
+{
+  if (_navigationState == nil) {
+    // Before the first container update, _navigationState is nil — there is no established baseline
+    // to drift from. The normal initialization path (performContainerUpdate → progressNavigationState:)
+    // handles the nil → first state transition. Reconciling here would prematurely initialize state
+    // and emit a delegate notification before the controller is fully set up.
+    return;
+  }
+
+  if ([self isSelectedViewControllerTheMoreNavigationController]) {
+    // We don't want to progress the state in case of more navigation controller.
+    // If we're reconciling here, it means that it won't be handled correctly.
+    // I'm not aware of any flow where this could happen, hence assertion.
+    RCTAssert(NO, @"[RNScreens] Unexpected state reconciliation with More Navigation Controller");
+    return;
+  }
+
+  if (![self.selectedViewController isKindOfClass:RNSTabsScreenViewController.class]) {
+    RCTAssert(
+        NO,
+        @"[RNScreens] Unexpected controller type during state reconciliation: %@",
+        self.selectedViewController.class);
+    return;
+  }
+
+  NSString *selectedScreenKey = [self screenKeyForSelectedViewController];
+  if ([_navigationState.selectedScreenKey isEqualToString:selectedScreenKey]) {
+    return;
+  }
+
+  RNSLog(
+      @"TabBarCtrl reconcileNavigationStateWithUIKitState: %@ -> %@",
+      _navigationState.selectedScreenKey,
+      selectedScreenKey);
+  [self progressNavigationState:selectedScreenKey withSource:RNSTabsNavigationStateUpdateSourceImplicit];
+
+  auto *context = [[RNSTabsNavigationStateUpdateContext alloc] initWithNavState:_navigationState
+                                                                     isRepeated:NO
+                                                      hasTriggeredSpecialEffect:NO
+                                                                 isNativeAction:YES];
+  [self.tabsHostComponentView tabBarController:self didUpdateStateTo:_navigationState withContext:context];
+}
+
 /**
  * This function assumes that the source of the state is NOT user. In current model, user update is never stale.
  */

ios/tabs/host/RNSTabsNavigationState.h

@@ -52,7 +52,10 @@ typedef NS_ENUM(NSInteger, RNSTabsNavigationStateUpdateSource) {
   /** Update initiated by a native user interaction (e.g. tab tap). */
   RNSTabsNavigationStateUpdateSourceUser = 0,
   /** Update initiated externally (e.g. from JS via props). */
-  RNSTabsNavigationStateUpdateSourceExternal
+  RNSTabsNavigationStateUpdateSourceExternal,
+  /** Update detected implicitly — UIKit changed the selection as a side effect of another operation
+   *  (e.g. More navigation controller disappearing during a horizontal size class transition on iPad). */
+  RNSTabsNavigationStateUpdateSourceImplicit
 };
 
 /** Reason why a navigation state update was rejected by the container. */

src/components/tabs/host/TabsHost.types.ts

@@ -59,7 +59,10 @@ export type TabSelectedEvent = {
   isRepeated: boolean;
   /** Whether the selection triggered a special effect (e.g. scroll-to-top on repeated selection). */
   hasTriggeredSpecialEffect: boolean;
-  /** Whether the selection was initiated by a native user action (tap) as opposed to a JS-driven update. */
+  /**
+   * False in case the event is a result of JS-driven update. True otherwise, e.g. in case of user action (tap)
+   * or implicit UIKit action (app resize, orientation change, etc.).
+   */
   isNativeAction: boolean;
 };