feat(iOS, Tabs): Add proper support for moreNavigationController on iOS (#3785)

## Description

Adds first-class support for UIKit's `moreNavigationController` — the
overflow tab that UIKit automatically creates when a
`UITabBarController` has more than 5 tabs. Previously the library had no
awareness of this controller, which led to crashes and broken state when
the user tapped the "More" tab or when JS attempted to navigate to it.

This PR follows the RFC-1028 state model introduced in #3781, extending
it to cover the `moreNavigationController` case.

Important thing to note from this PR is that it introduces a special
`rnscreens_moreNavigationController` *screenKey*. It is a reserved key,
that can not be used by the user.

## Changes

### Native (iOS)

- Introduced `kMoreNavigationControllerScreenKey`
(`"moreNavigationController"`) as the reserved key identifying the more
navigation controller across native and JS state.
- Updated `updateSelectedViewController` to detect when the pending
operation targets `moreNavigationController` and handle it separately
from regular tabs. If the controller is not present in the tab bar at
the time of the request (e.g. iPad sidebar/top bar mode), the operation
is silently dropped — a rejection event will be added in a follow-up.
- Fixed a crash in `tabBarController:shouldSelectViewController:` and
`tabBarController:didSelectViewController:` — previously these methods
unsafely cast `UINavigationController` (the more controller) to
`RNSTabsScreenViewController`.
- Removed the buggy `shouldAllowMoreControllerSelection` method, which
always returned `YES` due to a logic error (`!expr ?: YES`).
- Updated `updateSelectedViewControllerTo:` to accept an explicit
`screenKey` parameter instead of deriving it from the view controller,
eliminating a potential nil-key crash.
- When JS programmatically navigates to `moreNavigationController`, the
controller's stack is popped to root (animated only if the more tab is
already selected), so the user always sees the full list of overflow
tabs rather than whatever was previously on the navigation stack.
User-driven taps leave the stack untouched.
- `RNSTabBarController` now conforms to `UINavigationControllerDelegate`
and sets itself as delegate of `moreNavigationController` when it
becomes active. This allows tracking push/pop navigation within the more
list — when the user drills into a screen from the more list, the state
is updated accordingly.
- Aligned navigation bar suppression between user-driven and JS-driven
flows (the reason for suppression is still under investigation — likely
to hide the Edit button — tracked with a `TODO`).
- Added utility helpers guarded by
`RNS_MORE_NAVIGATION_CONTROLLER_AVAILABLE`:
`screenKeyForSelectedViewController`, `canHaveMoreNavigationController`,
`isSelectedViewControllerTheMoreNavigationController`,
`isMoreNavigationControllerPresentInTabBar`,
`isMoreNavigationControllerTabBarItemSelected`,
`isMoreNavigationControllerRequestedByOperation:`,
`popToRootInMoreNavigationControllerIfNeededAnimated:`,
`setupMoreNavigationControllerDelegateIfNeeded`,
`disableNavigationBarInMoreNavigationController`.

### JS / TypeScript

- `TabsContainer`: Added a guard that throws if any route config uses
`"moreNavigationController"` as its name, as that key is now reserved.
- `reducer`: The `"not found"` error is bypassed for
`moreNavigationController` key, allowing it to flow through the state
machine as a valid route.
- `reducer`: Fixed provenance calculation for `change-tab` action: next
provenance is now `max(suggestedState.provenance,
confirmedState.provenance) + 1` instead of `confirmedState.provenance +
1`. This prevents a rejected update (e.g. more controller not in tab
bar) from producing an identical provenance on retry, which would
silently block re-navigation.

## Visual documentation 

> [!note]
> When watching this video, please pay attention to the fact that
*programmatic* navigation to the `moreNavigationController` always
navigates to the ROOT (more selection list) of that view controller.
While user-driven navigation preserves what's already on the stack of
the `moreNavigationController`. This is intended. Programmer can always
navigate to any given screen by requesting it by the key.



https://github.com/user-attachments/assets/5bf979ba-92a1-4e18-af4c-5f2aeef809ad



## Test plan

- Added `TestTabsMoreNavigationController` scenario in
`apps/src/tests/single-feature-tests/tabs/`.
- The scenario renders more than 5 tabs to trigger the "More" tab and
covers JS-driven navigation to `moreNavigationController` as well as
user-driven selection.

## Checklist

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

---------

Co-authored-by: Copilot <[email protected]>

Author: kkafar

apps/src/shared/gamma/containers/tabs/TabsContainer.tsx

@@ -1,12 +1,12 @@
 import React from 'react';
 import { I18nManager, Platform, type NativeSyntheticEvent } from 'react-native';
 import {
+  SCREEN_KEY_MORE_NAV_CTRL,
   type TabChangeEvent,
   Tabs,
   type TabsHostNavState,
 } from 'react-native-screens';
-import SafeAreaView from '../../../../../../src/components/safe-area/SafeAreaView';
-import type { SafeAreaViewProps } from '../../../../../../src/components/safe-area/SafeAreaView.types';
+import { SafeAreaView, type SafeAreaViewProps } from 'react-native-screens/experimental'
 import type {
   ChangeTabMethod,
   TabRoute,
@@ -106,8 +106,7 @@ export function TabsContainer(props: TabsContainerProps) {
           route.routeKey === tabsNavState.suggestedState.selectedRouteKey;
 
         RNSLog.info(
-          `TabsContainer map to component -> ${route.routeKey} ${
-            isSelected ? '(selected)' : ''
+          `TabsContainer map to component -> ${route.routeKey} ${isSelected ? '(selected)' : ''
           }`,
         );
 
@@ -200,7 +199,15 @@ function useSanitizeRouteConfigs(routeConfigs: TabRouteConfig[]) {
     return names.length === new Set(names).size;
   }, [routeConfigs]);
 
+  const noNameUsesReservedRouteKey = React.useMemo(() => {
+    return routeConfigs.every(c => c.name !== SCREEN_KEY_MORE_NAV_CTRL);
+  }, [routeConfigs]);
+
   if (!areNamesUnique) {
     throw new Error('[Tabs] All tabs must have unique names');
   }
+
+  if (!noNameUsesReservedRouteKey) {
+    throw new Error(`[Tabs] Tab name "${SCREEN_KEY_MORE_NAV_CTRL}" is reserved and can not be used`);
+  }
 }

apps/src/shared/gamma/containers/tabs/reducer.tsx

@@ -1,3 +1,4 @@
+import { Platform } from 'react-native';
 import type {
   TabRoute,
   TabRouteConfig,
@@ -8,6 +9,7 @@ import type {
   TabsNavigationActionNativeChangeTab,
   TabsNavigationActionSetOptions,
 } from './TabsContainer.types';
+import { SCREEN_KEY_MORE_NAV_CTRL } from 'react-native-screens';
 
 const NOT_FOUND_INDEX = -1;
 
@@ -58,7 +60,7 @@ function tabsActionChangeTabHandler(
     r => r.routeKey === action.routeKey,
   );
 
-  if (routeIndex === NOT_FOUND_INDEX) {
+  if (routeIndex === NOT_FOUND_INDEX && !doesRouteKeyPointToMoreNavigationController(action.routeKey)) {
     console.error(
       `[Tabs] change-tab: route with key "${action.routeKey}" not found in state. Ignoring.`,
     );
@@ -71,7 +73,7 @@ function tabsActionChangeTabHandler(
 
   return navStateWithSuggestedState(state, {
     selectedRouteKey: action.routeKey,
-    provenance: state.confirmedState.provenance + 1, // suggested? What about update stacking before we receive confirmation?
+    provenance: Math.max(state.suggestedState.provenance, state.confirmedState.provenance) + 1,
   });
 }
 
@@ -83,7 +85,7 @@ function tabsActionNativeChangeTabHandler(
     r => r.routeKey === action.routeKey,
   );
 
-  if (routeIndex === NOT_FOUND_INDEX) {
+  if (routeIndex === NOT_FOUND_INDEX && !doesRouteKeyPointToMoreNavigationController(action.routeKey)) {
     console.error(
       `[Tabs] change-tab: route with key "${action.routeKey}" not found in state. Ignoring.`,
     );
@@ -102,7 +104,6 @@ function tabsActionNativeChangeTabHandler(
     return state;
   }
 
-  // What about aligning suggestedState here?
   return navStateWithConfirmedState(state, {
     selectedRouteKey: action.routeKey,
     provenance: action.nativeEvent.provenance,
@@ -206,3 +207,8 @@ function navStateWithConfirmedState(
     suggestedState: state.suggestedState,
   };
 }
+
+function doesRouteKeyPointToMoreNavigationController(routeKey: string): boolean {
+  return Platform.OS === 'ios' && routeKey === SCREEN_KEY_MORE_NAV_CTRL;
+}
+

apps/src/tests/single-feature-tests/tabs/index.ts

@@ -9,6 +9,7 @@ import TestTabsColorScheme from './test-tabs-color-scheme';
 import TestTabsLayoutDirection from './test-tabs-layout-direction';
 import TestTabsIMEInsets from './test-tabs-ime-insets';
 import TestTabsSimpleNav from './test-tabs-simple-nav';
+import TestTabsMoreNavigationController from './test-tabs-more-navigation-controller';
 
 const scenarios = {
   BottomAccessoryScenario,
@@ -20,6 +21,7 @@ const scenarios = {
   TestTabsLayoutDirection,
   TestTabsIMEInsets,
   TestTabsSimpleNav,
+  TestTabsMoreNavigationController,
 };
 
 const TabsScenarioGroup: ScenarioGroup<keyof typeof scenarios> = {

apps/src/tests/single-feature-tests/tabs/test-tabs-more-navigation-controller.tsx

@@ -0,0 +1,86 @@
+import React from 'react';
+import type { Scenario } from '../../shared/helpers';
+import { Button, Text, View } from 'react-native';
+import {
+  TabsContainer,
+  type TabRouteConfig,
+  DEFAULT_TAB_ROUTE_OPTIONS,
+  useTabsNavigationContext,
+} from '../../../shared/gamma/containers/tabs';
+import { CenteredLayoutView } from '../../../shared/CenteredLayoutView';
+import { SCREEN_KEY_MORE_NAV_CTRL } from 'react-native-screens';
+
+const SCENARIO: Scenario = {
+  name: 'More navigation controller',
+  key: 'test-tabs-more-navigation-controller',
+  details: 'Test navigation and interactions with "More Naviagation Controller"',
+  platforms: ['ios'],
+  AppComponent: App,
+};
+
+export default SCENARIO;
+
+function ContentView() {
+  const { routeKey } = useTabsNavigationContext();
+  return (
+    <CenteredLayoutView>
+      <Text style={{ fontWeight: 'bold', textAlign: 'center' }}>
+        {routeKey}
+      </Text>
+      <TabsNavigationButtons />
+    </CenteredLayoutView>
+  );
+}
+
+function TabsNavigationButtons() {
+  const nav = useTabsNavigationContext();
+
+  return (
+    <View>
+      <Button title="Select First" onPress={() => nav.changeTabTo('First')} />
+      <Button title="Select Second" onPress={() => nav.changeTabTo('Second')} />
+      <Button title="Select Third" onPress={() => nav.changeTabTo('Third')} />
+      <Button title="Select Fourth" onPress={() => nav.changeTabTo('Fourth')} />
+      <Button title="Select Fifth" onPress={() => nav.changeTabTo('Fifth')} />
+      <Button title="Select Sixth" onPress={() => nav.changeTabTo('Sixth')} />
+      <Button title="Select MoreTab" onPress={() => nav.changeTabTo(SCREEN_KEY_MORE_NAV_CTRL)} />
+    </View>
+  );
+}
+
+const ROUTE_CONFIGS: TabRouteConfig[] = [
+  {
+    name: 'First',
+    Component: ContentView,
+    options: { ...DEFAULT_TAB_ROUTE_OPTIONS, title: 'First' },
+  },
+  {
+    name: 'Second',
+    Component: ContentView,
+    options: { ...DEFAULT_TAB_ROUTE_OPTIONS, title: 'Second' },
+  },
+  {
+    name: 'Third',
+    Component: ContentView,
+    options: { ...DEFAULT_TAB_ROUTE_OPTIONS, title: 'Third' },
+  },
+  {
+    name: 'Fourth',
+    Component: ContentView,
+    options: { ...DEFAULT_TAB_ROUTE_OPTIONS, title: 'Fourth' },
+  },
+  {
+    name: 'Fifth',
+    Component: ContentView,
+    options: { ...DEFAULT_TAB_ROUTE_OPTIONS, title: 'Fifth' },
+  },
+  {
+    name: 'Sixth',
+    Component: ContentView,
+    options: { ...DEFAULT_TAB_ROUTE_OPTIONS, title: 'Sixth' },
+  },
+];
+
+export function App() {
+  return <TabsContainer routeConfigs={ROUTE_CONFIGS} />;
+}