refactor(tabs): replace isNativeAction with actionOrigin enum (#3949)

## Description

Replaces the boolean `isNativeAction` field on the `onTabSelected` event
with a three-valued `actionOrigin` discriminator (`'user' |
'programmatic-js' | 'implicit'`).

Important thing to note here is that this change also enables us to add
more action origins in the future, such as native-programmatic actions.

One thing I'm not proud of is that the React model details are leaked
into the `TabsContainer` (`TabsContainer` / `RNSTabBarController` on
Android & iOS respectively). It now recognizes different sources
including the `programmatic-js`.
This is not great, but it shouldn't hinder us later when attempting to
test it natively.

The boolean was lossy: it conflated JS-driven updates with implicit
UIKit-driven selection changes (e.g. iPad horizontal size-class
transitions where UIKit reshuffles the selected tab as a side effect).
Consumers that needed to react to JS-originated transitions specifically
had no way to distinguish them. Promoting the field to an enum makes the
actor explicit at the API boundary; on iOS it also lets us collapse the
previous internal `RNSTabsNavigationStateUpdateSource` taxonomy into a
single shared enum (`RNSTabsActionOrigin`).

## Changes

- Public TS API: `isNativeAction: boolean` → `actionOrigin: 'user' |
'programmatic-js' | 'implicit'` on `TabSelectedEvent` (and the matching
codegen specs for iOS / Android native components).
- iOS:
- New `RNSTabsActionOrigin` enum (`User`, `ProgrammaticJs`, `Implicit`)
declared in `RNSTabsNavigationState.h`.
- Removed the now-redundant `RNSTabsNavigationStateUpdateSource` enum;
`progressNavigationState:withSource:` becomes
`progressNavigationState:withOrigin:`.
- `RNSTabsNavigationStateUpdateContext.isNativeAction` → `actionOrigin`;
propagated through `OnTabSelectedPayload` and the event emitter, with an
Obj-C → codegen-enum conversion in `RNSConversions-Tabs.mm`.
- The implicit reconciliation path (More-controller size-class
transition) now reports `Implicit` instead of being lumped into
`isNativeAction = YES`.
- Android:
- New `TabsActionOrigin` enum (`USER`, `PROGRAMMATIC_JS`) under
`gamma.tabs.container`. `'implicit'` is iOS-only at the moment and not
currently produced on Android — documented in the enum's KDoc.
- Threaded through `TabsContainerDelegate.onNavStateUpdate`,
`TabsHostEventEmitter`, and `TabsHostTabSelectedEvent` (event payload
key `actionOrigin`, serialized via `enum.toString()`).

## Test plan

No new automated tests; this is a rename/refactor of an existing public
field with no behavioral change on the user/JS paths. The implicit path
on iOS now reports a distinct origin where it previously reported
`isNativeAction = YES`, so manual verification on the affected
platforms:

- iOS — tab bar tap → `actionOrigin === 'user'`.
- iOS — JS-driven `navStateRequest` update → `actionOrigin ===
'programmatic-js'`.
- iOS — iPad horizontal size-class transition that collapses/expands the
More controller → `actionOrigin === 'implicit'` (previously
`isNativeAction: true`, now distinguishable).
- Android — tab bar tap → `actionOrigin === 'user'`; JS-driven update →
`actionOrigin === 'programmatic-js'`.

Reproduction lives in `FabricExample` Tabs test screens; log
`e.nativeEvent.actionOrigin` from `onTabSelected`.

## Checklist

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

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

@@ -0,0 +1,22 @@
+package com.swmansion.rnscreens.gamma.tabs.container
+
+/**
+ * Origin (actor) that requested a tab transition. Mirrors the public `actionOrigin` event field.
+ *
+ * - [USER] — direct native UI interaction (tab bar tap).
+ * - [PROGRAMMATIC_JS] — JS-initiated request delivered via the `navStateRequest` prop.
+ *
+ * The `implicit` origin defined on the public TS API is iOS-only at the moment;
+ * Android does not currently produce it.
+ */
+enum class TabsActionOrigin {
+    USER,
+    PROGRAMMATIC_JS,
+    ;
+
+    override fun toString(): String =
+        when (this) {
+            USER -> "user"
+            PROGRAMMATIC_JS -> "programmatic-js"
+        }
+}

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

@@ -377,7 +377,7 @@ internal class TabsContainer(
                 navState,
                 isRepeated = isRepeated,
                 hasTriggeredSpecialEffect = hasTriggeredSpecialEffect,
-                isNativeAction = !isInExternalOperationContext,
+                actionOrigin = if (isInExternalOperationContext) TabsActionOrigin.PROGRAMMATIC_JS else TabsActionOrigin.USER,
             )
         }
 

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

@@ -11,13 +11,13 @@ internal interface TabsContainerDelegate {
      * @param navState The new navigation state after the change.
      * @param isRepeated Whether the same tab that was already selected has been selected again.
      * @param hasTriggeredSpecialEffect Whether a special effect (e.g. scroll-to-top) was triggered.
-     * @param isNativeAction Whether the change was initiated by a native user action (tap).
+     * @param actionOrigin Origin (actor) that requested this transition.
      */
     fun onNavStateUpdate(
         navState: TabsNavState,
         isRepeated: Boolean,
         hasTriggeredSpecialEffect: Boolean,
-        isNativeAction: Boolean,
+        actionOrigin: TabsActionOrigin,
     )
 
     /**

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

@@ -13,6 +13,7 @@ import com.facebook.react.uimanager.UIManagerHelper
 import com.swmansion.rnscreens.gamma.common.colorscheme.ColorScheme
 import com.swmansion.rnscreens.gamma.helpers.getFabricUIManagerNotNull
 import com.swmansion.rnscreens.gamma.tabs.container.TabSelectOp
+import com.swmansion.rnscreens.gamma.tabs.container.TabsActionOrigin
 import com.swmansion.rnscreens.gamma.tabs.container.TabsContainer
 import com.swmansion.rnscreens.gamma.tabs.container.TabsContainerDelegate
 import com.swmansion.rnscreens.gamma.tabs.container.TabsNavState
@@ -159,14 +160,14 @@ class TabsHost(
         navState: TabsNavState,
         isRepeated: Boolean,
         hasTriggeredSpecialEffect: Boolean,
-        isNativeAction: Boolean,
+        actionOrigin: TabsActionOrigin,
     ) {
         eventEmitter.emitOnTabSelectedEvent(
             navState.selectedKey,
             navState.provenance,
             isRepeated,
             hasTriggeredSpecialEffect,
-            isNativeAction,
+            actionOrigin,
         )
     }
 

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

@@ -2,6 +2,7 @@ package com.swmansion.rnscreens.gamma.tabs.host
 
 import com.facebook.react.bridge.ReactContext
 import com.swmansion.rnscreens.gamma.common.event.BaseEventEmitter
+import com.swmansion.rnscreens.gamma.tabs.container.TabsActionOrigin
 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
@@ -20,7 +21,7 @@ internal class TabsHostEventEmitter(
         provenance: Int,
         isRepeated: Boolean,
         hasTriggeredSpecialEffect: Boolean,
-        isNativeAction: Boolean,
+        actionOrigin: TabsActionOrigin,
     ) {
         reactEventDispatcher.dispatchEvent(
             TabsHostTabSelectedEvent(
@@ -30,7 +31,7 @@ internal class TabsHostEventEmitter(
                 provenance,
                 isRepeated,
                 hasTriggeredSpecialEffect,
-                isNativeAction,
+                actionOrigin,
             ),
         )
     }

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

@@ -4,6 +4,7 @@ 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.TabsActionOrigin
 
 class TabsHostTabSelectedEvent(
     surfaceId: Int,
@@ -12,7 +13,7 @@ class TabsHostTabSelectedEvent(
     val provenance: Int,
     val isRepeated: Boolean,
     val hasTriggeredSpecialEffect: Boolean,
-    val isNativeAction: Boolean,
+    val actionOrigin: TabsActionOrigin,
 ) : Event<TabsHostTabSelectedEvent>(surfaceId, viewId),
     NamingAwareEventType {
     override fun getEventName() = EVENT_NAME
@@ -28,7 +29,7 @@ class TabsHostTabSelectedEvent(
             putInt(EK_PROVENANCE, provenance)
             putBoolean(EK_IS_REPEATED, isRepeated)
             putBoolean(EK_HAS_TRIGGERED_SPECIAL_EFFECT, hasTriggeredSpecialEffect)
-            putBoolean(EK_IS_NATIVE_ACTION, isNativeAction)
+            putString(EK_ACTION_ORIGIN, actionOrigin.toString())
         }
 
     companion object : NamingAwareEventType {
@@ -39,7 +40,7 @@ class TabsHostTabSelectedEvent(
         private const val EK_PROVENANCE = "provenance"
         private const val EK_IS_REPEATED = "isRepeated"
         private const val EK_HAS_TRIGGERED_SPECIAL_EFFECT = "hasTriggeredSpecialEffect"
-        private const val EK_IS_NATIVE_ACTION = "isNativeAction"
+        private const val EK_ACTION_ORIGIN = "actionOrigin"
 
         override fun getEventName() = EVENT_NAME
 

ios/conversion/RNSConversions-Tabs.mm

@@ -233,6 +233,23 @@ UITabBarControllerMode UITabBarControllerModeFromRNSTabBarControllerMode(RNSTabB
   }
 }
 
+react::RNSTabsHostIOSEventEmitter::OnTabSelectedActionOrigin RNSOnTabSelectedActionOriginFromRNSTabsActionOrigin(
+    RNSTabsActionOrigin actionOrigin)
+{
+  using enum facebook::react::RNSTabsHostIOSEventEmitter::OnTabSelectedActionOrigin;
+  switch (actionOrigin) {
+    case RNSTabsActionOriginUser:
+      return User;
+    case RNSTabsActionOriginProgrammaticJs:
+      return ProgrammaticJs;
+    case RNSTabsActionOriginImplicit:
+      return Implicit;
+    default:
+      RCTLogError(@"[RNScreens] Unexpected actionOrigin: %ld", actionOrigin);
+  }
+  return User;
+}
+
 RNSTabsIconType RNSTabsIconTypeFromIcon(react::RNSTabsScreenIOSIconType iconType)
 {
   using enum facebook::react::RNSTabsScreenIOSIconType;

ios/conversion/RNSConversions.h

@@ -63,6 +63,9 @@ react::RNSTabsHostIOSEventEmitter::OnTabSelectionRejectedRejectionReason
 RNSOnTabSelectionRejectedRejectionReasonFromRNSTabsNavigationStateRejectionReason(
     RNSTabsNavigationStateRejectionReason reason);
 
+react::RNSTabsHostIOSEventEmitter::OnTabSelectedActionOrigin RNSOnTabSelectedActionOriginFromRNSTabsActionOrigin(
+    RNSTabsActionOrigin actionOrigin);
+
 RNSTabsIconType RNSTabsIconTypeFromIcon(react::RNSTabsScreenIOSIconType iconType);
 
 RNSTabsScreenSystemItem RNSTabsScreenSystemItemFromReactRNSTabsScreenSystemItem(

ios/tabs/host/RNSTabBarController.mm

@@ -236,7 +236,7 @@ - (BOOL)updateSelectedViewControllerTo:(nullable UIViewController *)nextSelected
       ![NSString rnscreens_isBlankOrNull:screenKey],
       @"[RNScreens] The screenKey MUST NOT be null if the view controller is not null");
 
-  [self progressNavigationState:screenKey withSource:RNSTabsNavigationStateUpdateSourceExternal];
+  [self progressNavigationState:screenKey withOrigin:RNSTabsActionOriginProgrammaticJs];
 
   if (currSelectedViewController == nextSelectedViewController) {
     return YES;
@@ -254,8 +254,7 @@ - (BOOL)updateSelectedViewControllerTo:(nullable UIViewController *)nextSelected
  */
 - (void)updateNavigationStateOnModelUpdate
 {
-  [self progressNavigationState:[self screenKeyForSelectedViewController]
-                     withSource:RNSTabsNavigationStateUpdateSourceUser];
+  [self progressNavigationState:[self screenKeyForSelectedViewController] withOrigin:RNSTabsActionOriginUser];
 }
 
 - (void)userDidRepeatViewControllerSelection:(nonnull UIViewController *)viewController
@@ -277,7 +276,7 @@ - (void)userDidRepeatViewControllerSelection:(nonnull UIViewController *)viewCon
       [[RNSTabsNavigationStateUpdateContext alloc] initWithNavState:_navigationState
                                                          isRepeated:YES
                                           hasTriggeredSpecialEffect:repeatedSelectionHandledBySpecialEffect
-                                                     isNativeAction:YES];
+                                                       actionOrigin:RNSTabsActionOriginUser];
   [self.tabsHostComponentView tabBarController:self didUpdateStateTo:_navigationState withContext:updateContext];
 }
 
@@ -299,7 +298,7 @@ - (void)userDidSelectViewController:(nonnull UIViewController *)viewController
     auto *updateContext = [[RNSTabsNavigationStateUpdateContext alloc] initWithNavState:_navigationState
                                                                              isRepeated:NO
                                                               hasTriggeredSpecialEffect:NO
-                                                                         isNativeAction:YES];
+                                                                           actionOrigin:RNSTabsActionOriginUser];
     [self.tabsHostComponentView tabBarController:self didUpdateStateTo:_navigationState withContext:updateContext];
   }
 }
@@ -517,7 +516,7 @@ - (void)updateSelectedViewControllerInner
         [[RNSTabsNavigationStateUpdateContext alloc] initWithNavState:_navigationState
                                                            isRepeated:NO
                                             hasTriggeredSpecialEffect:NO
-                                                       isNativeAction:NO];
+                                                         actionOrigin:RNSTabsActionOriginProgrammaticJs];
     [self.tabsHostComponentView tabBarController:self didUpdateStateTo:_navigationState withContext:context];
   }
 }
@@ -574,8 +573,7 @@ - (nullable RNSTabsScreenViewController *)findChildViewControllerForKey:(nullabl
   return nil;
 }
 
-- (void)progressNavigationState:(nonnull NSString *)newSelectedScreenKey
-                     withSource:(RNSTabsNavigationStateUpdateSource)updateSource
+- (void)progressNavigationState:(nonnull NSString *)newSelectedScreenKey withOrigin:(RNSTabsActionOrigin)origin
 {
   RCTAssert(newSelectedScreenKey != nil, @"[RNScreens] newSelectedScreenKey MUST NOT be nil");
 
@@ -587,7 +585,7 @@ - (void)progressNavigationState:(nonnull NSString *)newSelectedScreenKey
   _navigationState = [RNSTabsNavigationState stateWithSelectedScreenKey:newSelectedScreenKey
                                                              provenance:_navigationState.provenance + 1];
 
-  if (updateSource != RNSTabsNavigationStateUpdateSourceExternal) {
+  if (origin != RNSTabsActionOriginProgrammaticJs) {
     _lastUINavigationState = [_navigationState cloneState];
   }
 }
@@ -666,12 +664,12 @@ - (void)reconcileNavigationStateWithUIKitState
       @"TabBarCtrl reconcileNavigationStateWithUIKitState: %@ -> %@",
       _navigationState.selectedScreenKey,
       selectedScreenKey);
-  [self progressNavigationState:selectedScreenKey withSource:RNSTabsNavigationStateUpdateSourceImplicit];
+  [self progressNavigationState:selectedScreenKey withOrigin:RNSTabsActionOriginImplicit];
 
   auto *context = [[RNSTabsNavigationStateUpdateContext alloc] initWithNavState:_navigationState
                                                                      isRepeated:NO
                                                       hasTriggeredSpecialEffect:NO
-                                                                 isNativeAction:YES];
+                                                                   actionOrigin:RNSTabsActionOriginImplicit];
   [self.tabsHostComponentView tabBarController:self didUpdateStateTo:_navigationState withContext:context];
 }
 

ios/tabs/host/RNSTabsHostComponentView.mm

@@ -609,7 +609,7 @@ - (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
                                              .provenance = navState.provenance,
                                              .isRepeated = context.isRepeated,
                                              .hasTriggeredSpecialEffect = context.hasTriggeredSpecialEffect,
-                                             .isNativeAction = context.isNativeAction}];
+                                             .actionOrigin = context.actionOrigin}];
 }
 
 - (void)tabBarController:(nonnull RNSTabBarController *)tabBarController