feat(Tabs): add preventNativeSelection support (#3838)

## Description

Adds the ability to prevent native tab selection on a per-screen basis.
When `preventNativeSelection` is set to `true` on a `TabsScreen`,
tapping that tab in the tab bar (or selecting it from the "More" list on
iOS) will be blocked. The `TabsHost` receives an
`onTabSelectionPrevented` callback with the key of the prevented screen
and the current navigation state, allowing JS to decide how to handle
the attempt (e.g. show a confirmation dialog, redirect elsewhere).

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

## Changes

- **`TabsScreen`**: New `preventNativeSelection` boolean prop plumbed
from JS → codegen specs → native on both Android and iOS.
- **`TabsHost`**: New `onTabSelectionPrevented` event (type + codegen
spec + native emitter) fired when selection is blocked.
- **iOS (`RNSTabBarController`)**:
- `tabBarController:shouldSelectViewController:` now checks per-screen
`preventNativeSelection` and emits the prevented event.
- ISA-swizzles `UIMoreNavigationController` to intercept
`pushViewController:animated:` so screens behind the "More" list are
also subject to prevention. Includes table-view deselection cleanup when
a push is blocked.
- Dynamic subclass name is derived from the actual runtime class (e.g.
`RNS_UIMoreNavigationController`), so each distinct original class gets
its own correct subclass — safe even if another library ISA-swizzles
first.
- Clears the `OBJC_ASSOCIATION_ASSIGN` back-reference in `dealloc` as a
safety measure against potential dangling pointers.
- Refactored `screenKeyForSelectedViewController` →
`screenKeyForViewController:` and
`isSelectedViewControllerTheMoreNavigationController` →
`isViewControllerTheMoreNavigationController:` to support querying
arbitrary view controllers (not just the selected one).
- **iOS (`RNSTabsScreenViewController`)**: Added `ScreenPropsForwarding`
category exposing `isPreventNativeSelectionEnabled`.
- **Android**: Prevention logic in `TabsContainer.onMenuItemSelected` —
checks `isPreventNativeSelectionEnabled` before progressing state,
delegates to `TabsContainerDelegate.onNavStateUpdatePrevented` which
emits the event via `TabsHost`.
- **Example app**: New test scenario (`TestTabsPreventNativeSelection`)
with 6 tabs, per-tab toggle, and toast on prevention.

## Known issues

- **`experimental_controlNavigationStateInJS` is not respected in the
"More" navigation controller flow on iOS.** When the experimental
controlled-mode flag is enabled and the user is already on the "More"
tab, tapping items in the More list will not be blocked by the
controlled-mode gate (only by `preventNativeSelection`). This is
acceptable since the controlled-mode feature is planned for removal
before release.

## Visual documentation

### Rudimentary scenarios

We navigate to a "third" tab natively, toggle `preventNativeSelection`,
go back, and navigate again. That attempt is blocked (prevented) and an
event is emitted, as it can be observed by appearance of toast. We
navigate to the "third" tab via JS - this is allowed, as we only prevent
native selection - toggle the option and repeat the experiment. This
time navigation to "third" tab is allowed.

| iOS | Android | 
| -- | -- |
| <video
src="https://github.com/user-attachments/assets/fed8b101-265e-469a-8e18-ad4cc6148618"
alt="s-1-ios" /> | <video
src="https://github.com/user-attachments/assets/523b0fbd-9366-4943-95bc-c4f7059a62e3"
alt="s-1-android" /> |

### More navigation controller scenarios

In the video on the left I showcase that the navigation from "more list"
is correctly prevented.

In the video on the right I cover a edge case, where a user / programmer
navigates first the the "fifth" tab, then navigates away, e.g. to
"third" and then comes back. W/o prevention mechanism, the "fifth" tab
would be shown, as it is pushed onto *more navigation controller stack*.
I've implemented logic to cover this case. Now, the "more list" will be
displayed. *I've decided that in such case we will emit the
`OnTabSelectionPrevented` event*, as we effectively prevent s user from
navigating to that tab, even if this is not fully intentional. See [more
details
here](610a4df).

| Block from more list | Forced pop on navigation | 
| -- | -- |
| <video
src="https://github.com/user-attachments/assets/67fb3e0e-b3bf-4ad8-8834-67e9cf8b439e"
alt="block-from-more-list" /> | <video
src="https://github.com/user-attachments/assets/d7302f29-dc27-4d9e-a335-6af5dcdbf2fc"
alt="forced-pop-on-navigation" /> |



## Test plan

- Run `TestTabsPreventNativeSelection` scenario from the example app.
- Tap a tab → verify it switches normally.
- Toggle `preventNativeSelection` on a tab → tap it → verify it does
**not** switch and the `onTabSelectionPrevented` toast appears.
- On iOS with 6 tabs: verify prevention also works for tabs listed under
the "More" navigation controller.
- Toggle the flag back off → verify the tab becomes selectable again.

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

---------

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

Author: kkafar

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/container/TabsContainer.kt

@@ -361,6 +361,12 @@ internal class TabsContainer(
 
         val isRepeated = nextSelectedFragment === currSelectedFragment
 
+        // If this is user action we test whether it should be prevented before we progress the state.
+        if (!isRepeated && !isInExternalOperationContext && nextSelectedFragment.isPreventNativeSelectionEnabled) {
+            delegate.onNavStateUpdatePrevented(navState, nextSelectedFragment.requireScreenKey)
+            return false
+        }
+
         val stateChanged = updateSelectedFragment(nextSelectedFragment)
 
         val hasTriggeredSpecialEffect =

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/container/TabsContainerDelegate.kt

@@ -32,4 +32,17 @@ internal interface TabsContainerDelegate {
         rejectedNavState: TabsNavState,
         reason: TabsNavStateUpdateRejectionReason,
     )
+
+    /**
+     * Called when a native user action (tap) attempts to select a tab that has
+     * [com.swmansion.rnscreens.gamma.tabs.screen.TabsScreen.preventNativeSelection] enabled.
+     * The navigation state remains unchanged.
+     *
+     * @param currentNavState The currently active navigation state that was kept.
+     * @param preventedScreenKey The screen key of the tab whose selection was prevented.
+     */
+    fun onNavStateUpdatePrevented(
+        currentNavState: TabsNavState,
+        preventedScreenKey: String,
+    )
 }

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/TabsHost.kt

@@ -182,6 +182,13 @@ class TabsHost(
         )
     }
 
+    override fun onNavStateUpdatePrevented(
+        currentNavState: TabsNavState,
+        preventedScreenKey: String,
+    ) {
+        eventEmitter.emitOnTabSelectionPreventedEvent(currentNavState, preventedScreenKey)
+    }
+
     override fun didMountItems(uiManager: UIManager) {
         container.performContainerUpdateIfNeeded()
     }

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/TabsHostEventEmitter.kt

@@ -5,6 +5,7 @@ import com.swmansion.rnscreens.gamma.common.event.BaseEventEmitter
 import com.swmansion.rnscreens.gamma.tabs.container.TabsNavState
 import com.swmansion.rnscreens.gamma.tabs.container.TabsNavStateUpdateRejectionReason
 import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabSelectedEvent
+import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabSelectionPreventedEvent
 import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabSelectionRejectedEvent
 
 internal class TabsHostEventEmitter(
@@ -53,4 +54,22 @@ internal class TabsHostEventEmitter(
             ),
         )
     }
+
+    /**
+     * Emits `onTabSelectionPrevented` event to JS when a tab selection is prevented
+     * because the target screen has `preventNativeSelection` enabled.
+     */
+    fun emitOnTabSelectionPreventedEvent(
+        currentNavState: TabsNavState,
+        preventedScreenKey: String,
+    ) {
+        reactEventDispatcher.dispatchEvent(
+            TabsHostTabSelectionPreventedEvent(
+                surfaceId,
+                viewTag,
+                currentNavState,
+                preventedScreenKey,
+            ),
+        )
+    }
 }

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/TabsHostViewManager.kt

@@ -13,6 +13,7 @@ import com.swmansion.rnscreens.gamma.common.colorscheme.ColorScheme
 import com.swmansion.rnscreens.gamma.helpers.makeEventRegistrationInfo
 import com.swmansion.rnscreens.gamma.tabs.container.TabsNavState
 import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabSelectedEvent
+import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabSelectionPreventedEvent
 import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabSelectionRejectedEvent
 import com.swmansion.rnscreens.gamma.tabs.screen.TabsScreen
 
@@ -59,6 +60,7 @@ class TabsHostViewManager :
     override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any> =
         mutableMapOf(
             makeEventRegistrationInfo(TabsHostTabSelectedEvent),
+            makeEventRegistrationInfo(TabsHostTabSelectionPreventedEvent),
             makeEventRegistrationInfo(TabsHostTabSelectionRejectedEvent),
         )
 

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/event/TabsHostTabSelectionPreventedEvent.kt

@@ -0,0 +1,47 @@
+package com.swmansion.rnscreens.gamma.tabs.host.event
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.events.Event
+import com.swmansion.rnscreens.gamma.common.event.NamingAwareEventType
+import com.swmansion.rnscreens.gamma.tabs.container.TabsNavState
+
+/**
+ * React Native event dispatched to JS when a tab selection is prevented because the target
+ * screen has `preventNativeSelection` enabled.
+ *
+ * This event is never coalesced — every prevention is delivered individually.
+ */
+class TabsHostTabSelectionPreventedEvent(
+    surfaceId: Int,
+    viewId: Int,
+    val currentNavState: TabsNavState,
+    val preventedScreenKey: String,
+) : Event<TabsHostTabSelectionPreventedEvent>(surfaceId, viewId),
+    NamingAwareEventType {
+    override fun getEventName() = EVENT_NAME
+
+    override fun getEventRegistrationName() = EVENT_REGISTRATION_NAME
+
+    override fun canCoalesce(): Boolean = false
+
+    override fun getEventData(): WritableMap? =
+        Arguments.createMap().apply {
+            putString(EK_SELECTED_KEY, currentNavState.selectedKey)
+            putInt(EK_PROVENANCE, currentNavState.provenance)
+            putString(EK_PREVENTED_KEY, preventedScreenKey)
+        }
+
+    companion object : NamingAwareEventType {
+        const val EVENT_NAME = "topTabSelectionPrevented"
+        const val EVENT_REGISTRATION_NAME = "onTabSelectionPrevented"
+
+        private const val EK_SELECTED_KEY = "selectedScreenKey"
+        private const val EK_PROVENANCE = "provenance"
+        private const val EK_PREVENTED_KEY = "preventedScreenKey"
+
+        override fun getEventName() = EVENT_NAME
+
+        override fun getEventRegistrationName() = EVENT_REGISTRATION_NAME
+    }
+}

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/screen/TabsScreen.kt

@@ -94,6 +94,8 @@ class TabsScreen(
     var shouldUseRepeatedTabSelectionScrollToTopSpecialEffect: Boolean = true
     var shouldUseRepeatedTabSelectionPopToRootSpecialEffect: Boolean = true
 
+    var preventNativeSelection: Boolean = false
+
     private fun <T> updateMenuItemAttributesIfNeeded(
         oldValue: T,
         newValue: T,

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/screen/TabsScreenFragment.kt

@@ -11,6 +11,7 @@ class TabsScreenFragment(
     internal val tabsScreen: TabsScreen,
 ) : Fragment() {
     internal val requireScreenKey: String by tabsScreen::requireScreenKey
+    internal val isPreventNativeSelectionEnabled: Boolean by tabsScreen::preventNativeSelection
 
     override fun onCreateView(
         inflater: LayoutInflater,

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/screen/TabsScreenViewManager.kt

@@ -97,6 +97,13 @@ class TabsScreenViewManager :
         view.shouldUseRepeatedTabSelectionScrollToTopSpecialEffect = scrollToTop
     }
 
+    override fun setPreventNativeSelection(
+        view: TabsScreen,
+        value: Boolean,
+    ) {
+        view.preventNativeSelection = value
+    }
+
     override fun setTabBarItemTestID(
         view: TabsScreen,
         value: String?,

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

@@ -10,6 +10,7 @@ import TestTabsTabBarLayoutDirection from './test-tabs-tab-bar-layout-direction'
 import TestTabsIMEInsets from './test-tabs-ime-insets';
 import TestTabsSimpleNav from './test-tabs-simple-nav';
 import TestTabsMoreNavigationController from './test-tabs-more-navigation-controller';
+import TestTabsPreventNativeSelection from './test-tabs-prevent-native-selection';
 import TestTabsStaleStateUpdateRejection from './test-tabs-stale-update-rejection';
 import TestTabsTabBarMinimizeBehavior from './test-tabs-tab-bar-minimize-behavior-ios';
 import TestTabsTabBarControllerMode from './test-tabs-tab-bar-controller-mode-ios';
@@ -25,6 +26,7 @@ const scenarios = {
   TestTabsIMEInsets,
   TestTabsSimpleNav,
   TestTabsMoreNavigationController,
+  TestTabsPreventNativeSelection,
   TestTabsStaleStateUpdateRejection,
   TestTabsTabBarMinimizeBehavior,
   TestTabsTabBarControllerMode,