react-native-screens 4.24.0 → 4.25.0-beta.1

package/ios/tabs/host/RNSTabsHostComponentView.h

@@ -6,17 +6,16 @@
 #import "RNSScreenContainer.h"
 #import "RNSTabsHostComponentViewManager.h"
 #import "RNSTabsHostEventEmitter.h"
+#import "RNSTabsNavigationState.h"
 
-#ifdef RCT_NEW_ARCH_ENABLED
-#import "RNSViewControllerInvalidating.h"
-#else
+#if !RCT_NEW_ARCH_ENABLED
 #import <React/RCTInvalidating.h>
 #endif
 
+#import "RNSTabBarController.h"
+
 NS_ASSUME_NONNULL_BEGIN
 
-@class RNSTabsScreenComponentView;
-@class RNSTabBarController;
 @class RCTImageLoader;
 
 /**
@@ -29,9 +28,9 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @interface RNSTabsHostComponentView : RNSReactBaseView <
                                           RNSScreenContainerDelegate,
-#ifdef RCT_NEW_ARCH_ENABLED
-                                          RNSViewControllerInvalidating
-#else
+                                          RNSTabBarControllerDelegate
+#if !RCT_NEW_ARCH_ENABLED
+                                          ,
                                           RCTInvalidating
 #endif
                                           >
@@ -48,13 +47,22 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface RNSTabsHostComponentView ()
 
+/**
+ * Last navigation state requested by JS. Will be nonnull after first prop update.
+ */
+@property (nonatomic, strong, readonly, nullable) RNSTabsNavigationState *navState;
+
+@property (nonatomic, readonly) BOOL rejectStaleNavStateUpdates;
+
 @property (nonatomic, strong, readonly, nullable) UIColor *tabBarTintColor;
 
 @property (nonatomic, readonly) BOOL tabBarHidden;
 
 @property (nonatomic, strong, readonly, nullable) UIColor *nativeContainerBackgroundColor;
 
-@property (nonatomic, readonly) BOOL experimental_controlNavigationStateInJS;
+@property (nonatomic, readonly) UIUserInterfaceStyle colorScheme;
+
+@property (nonatomic, readonly) UITraitEnvironmentLayoutDirection layoutDirection;
 
 #if RNS_IPHONE_OS_VERSION_AVAILABLE(26_0)
 @property (nonatomic, readonly) UITabBarMinimizeBehavior tabBarMinimizeBehavior API_AVAILABLE(ios(26.0));
@@ -74,9 +82,6 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (nonnull RNSTabsHostEventEmitter *)reactEventEmitter;
 
-- (BOOL)emitOnNativeFocusChangeRequestSelectedTabScreen:(nonnull RNSTabsScreenComponentView *)tabScreen
-                repeatedSelectionHandledBySpecialEffect:(BOOL)repeatedSelectionHandledBySpecialEffect;
-
 #if !RCT_NEW_ARCH_ENABLED
 #pragma mark - LEGACY Event blocks
 

package/ios/tabs/host/RNSTabsHostComponentView.mm

@@ -9,9 +9,7 @@
 #import <react/renderer/components/rnscreens/Props.h>
 #import <react/renderer/components/rnscreens/RCTComponentViewHelpers.h>
 #import <rnscreens/RNSTabsHostComponentDescriptor.h>
-#import "RNSInvalidatedComponentsRegistry.h"
 #import "RNSTabsHostComponentView+RNSImageLoader.h"
-#import "RNSViewControllerInvalidator.h"
 #endif // RCT_NEW_ARCH_ENABLED
 
 #import "RNSConversions.h"
@@ -19,7 +17,6 @@
 #import "RNSDefines.h"
 #import "RNSLog.h"
 #import "RNSTabBarController.h"
-#import "RNSTabBarControllerDelegate.h"
 #import "RNSTabsBottomAccessoryComponentView.h"
 #import "RNSTabsBottomAccessoryHelper.h"
 #import "RNSTabsScreenComponentView.h"
@@ -44,22 +41,19 @@ namespace react = facebook::react;
 
 @implementation RNSTabsHostComponentView {
   RNSTabBarController *_Nonnull _controller;
-  RNSTabBarControllerDelegate *_controllerDelegate;
 
   RNSTabsHostEventEmitter *_Nonnull _reactEventEmitter;
 
   RCTImageLoader *_Nullable _imageLoader;
 
-#if RCT_NEW_ARCH_ENABLED
-  RNSInvalidatedComponentsRegistry *_Nonnull _invalidatedComponentsRegistry;
-#endif // RCT_NEW_ARCH_ENABLED
-
   // RCTViewComponentView does not expose this field, therefore we maintain
   // it on our side.
   NSMutableArray<UIView *> *_reactSubviews;
   BOOL _hasModifiedTabsScreensInCurrentTransaction;
   BOOL _hasModifiedBottomAccessoryInCurrentTransation;
   BOOL _needsTabBarAppearanceUpdate;
+
+  RNSTabsNavigationState *_Nullable _jsNavState;
 }
 
 - (instancetype)initWithFrame:(CGRect)frame
@@ -91,16 +85,10 @@ namespace react = facebook::react;
   [self resetProps];
 
   _controller = [[RNSTabBarController alloc] initWithTabsHostComponentView:self];
-  _controllerDelegate = [RNSTabBarControllerDelegate new];
-  _controller.delegate = _controllerDelegate;
 
   _reactSubviews = [NSMutableArray new];
   _reactEventEmitter = [RNSTabsHostEventEmitter new];
 
-#if RCT_NEW_ARCH_ENABLED
-  _invalidatedComponentsRegistry = [RNSInvalidatedComponentsRegistry new];
-#endif // RCT_NEW_ARCH_ENABLED
-
   _hasModifiedTabsScreensInCurrentTransaction = NO;
   _hasModifiedBottomAccessoryInCurrentTransation = NO;
   _needsTabBarAppearanceUpdate = NO;
@@ -109,10 +97,13 @@ namespace react = facebook::react;
 - (void)resetProps
 {
 #if RCT_NEW_ARCH_ENABLED
-  static const auto defaultProps = std::make_shared<const react::RNSTabsHostProps>();
+  static const auto defaultProps = std::make_shared<const react::RNSTabsHostIOSProps>();
   _props = defaultProps;
 #endif
   _tabBarTintColor = nil;
+  _layoutDirection = UITraitEnvironmentLayoutDirectionUnspecified;
+  _colorScheme = UIUserInterfaceStyleUnspecified;
+  _rejectStaleNavStateUpdates = NO;
 #if !TARGET_OS_TV
   _nativeContainerBackgroundColor = [UIColor systemBackgroundColor];
 #else // !TARGET_OS_TV
@@ -120,17 +111,21 @@ namespace react = facebook::react;
 #endif // !TARGET_OS_TV
 }
 
-#pragma mark - UIView methods
-
-- (void)willMoveToWindow:(UIWindow *)newWindow
+- (void)invalidateImpl
 {
-#if RCT_NEW_ARCH_ENABLED
-  if (newWindow == nil) {
-    [_invalidatedComponentsRegistry flushInvalidViews];
-  }
-#endif // RCT_NEW_ARCH_ENABLED
+  // We want to run after container updates are performed (transitions etc.)
+  __weak auto weakSelf = self;
+
+  dispatch_async(dispatch_get_main_queue(), ^{
+    auto strongSelf = weakSelf;
+    if (strongSelf) {
+      strongSelf->_controller = nil;
+    }
+  });
 }
 
+#pragma mark - UIView methods
+
 - (void)didMoveToWindow
 {
   if ([self window] != nil) {
@@ -227,20 +222,7 @@ namespace react = facebook::react;
   [self updateContainer];
 }
 
-#if RCT_NEW_ARCH_ENABLED
-
-#pragma mark - RNSViewControllerInvalidating
-
-- (void)invalidateController
-{
-  _controller = nil;
-}
-
-- (BOOL)shouldInvalidateOnMutation:(const facebook::react::ShadowViewMutation &)mutation
-{
-  return (mutation.oldChildShadowView.tag == self.tag && mutation.type == facebook::react::ShadowViewMutation::Delete);
-}
-#else
+#if !RCT_NEW_ARCH_ENABLED
 
 #pragma mark - RCTInvalidating
 
@@ -253,7 +235,7 @@ namespace react = facebook::react;
   for (UIView<RCTInvalidating> *subview in _reactSubviews) {
     [subview invalidate];
   }
-  _controller = nil;
+  [self invalidateImpl];
 }
 
 #endif
@@ -266,16 +248,8 @@ namespace react = facebook::react;
   return _reactEventEmitter;
 }
 
-- (BOOL)emitOnNativeFocusChangeRequestSelectedTabScreen:(nonnull RNSTabsScreenComponentView *)tabScreen
-                repeatedSelectionHandledBySpecialEffect:(BOOL)repeatedSelectionHandledBySpecialEffect
-{
-  return [_reactEventEmitter
-      emitOnNativeFocusChange:OnNativeFocusChangePayload{
-                                  .tabKey = tabScreen.tabKey,
-                                  .repeatedSelectionHandledBySpecialEffect = repeatedSelectionHandledBySpecialEffect}];
-}
-
 #pragma mark - RCTComponentViewProtocol
+
 #if RCT_NEW_ARCH_ENABLED
 
 - (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView index:(NSInteger)index
@@ -291,11 +265,22 @@ namespace react = facebook::react;
 - (void)updateProps:(const facebook::react::Props::Shared &)props
            oldProps:(const facebook::react::Props::Shared &)oldProps
 {
-  const auto &oldComponentProps = *std::static_pointer_cast<const react::RNSTabsHostProps>(_props);
-  const auto &newComponentProps = *std::static_pointer_cast<const react::RNSTabsHostProps>(props);
+  const auto &oldComponentProps = *std::static_pointer_cast<const react::RNSTabsHostIOSProps>(_props);
+  const auto &newComponentProps = *std::static_pointer_cast<const react::RNSTabsHostIOSProps>(props);
+
+  if (newComponentProps.navState.selectedScreenKey != oldComponentProps.navState.selectedScreenKey ||
+      newComponentProps.navState.provenance != oldComponentProps.navState.provenance) {
+    NSString *selectedScreenKey = RCTNSStringFromStringNilIfEmpty(newComponentProps.navState.selectedScreenKey);
+    RCTAssert(selectedScreenKey != nil, @"[RNScreens] selectedScreenKey MUST NOT be nil");
+    RCTAssert(newComponentProps.navState.provenance >= 0, @"[RNScreens] provenance MUST BE >= 0]");
+    _jsNavState = [RNSTabsNavigationState stateWithSelectedScreenKey:selectedScreenKey
+                                                          provenance:newComponentProps.navState.provenance];
+    [_controller setPendingNavigationStateUpdate:[_jsNavState cloneState]];
+  }
 
-  if (newComponentProps.controlNavigationStateInJS != oldComponentProps.controlNavigationStateInJS) {
-    _experimental_controlNavigationStateInJS = newComponentProps.controlNavigationStateInJS;
+  if (newComponentProps.rejectStaleNavStateUpdates != oldComponentProps.rejectStaleNavStateUpdates) {
+    _rejectStaleNavStateUpdates = static_cast<BOOL>(newComponentProps.rejectStaleNavStateUpdates);
+    [_controller setRejectStaleNavigationStateUpdates:_rejectStaleNavStateUpdates];
   }
 
   if (newComponentProps.tabBarTintColor != oldComponentProps.tabBarTintColor) {
@@ -334,7 +319,7 @@ namespace react = facebook::react;
       _controller.tabBarMinimizeBehavior = _tabBarMinimizeBehavior;
     } else
 #endif // Check for iOS >= 26
-      if (newComponentProps.tabBarMinimizeBehavior != react::RNSTabsHostTabBarMinimizeBehavior::Automatic) {
+      if (newComponentProps.tabBarMinimizeBehavior != react::RNSTabsHostIOSTabBarMinimizeBehavior::Automatic) {
         RCTLogWarn(@"[RNScreens] tabBarMinimizeBehavior is supported for iOS >= 26");
       }
   }
@@ -347,11 +332,21 @@ namespace react = facebook::react;
       _controller.mode = _tabBarControllerMode;
     } else
 #endif // Check for iOS >= 18
-      if (newComponentProps.tabBarControllerMode != react::RNSTabsHostTabBarControllerMode::Automatic) {
+      if (newComponentProps.tabBarControllerMode != react::RNSTabsHostIOSTabBarControllerMode::Automatic) {
         RCTLogWarn(@"[RNScreens] tabBarControllerMode is supported for iOS >= 18");
       }
   }
 
+  if (newComponentProps.layoutDirection != oldComponentProps.layoutDirection) {
+    [self setLayoutDirection:rnscreens::conversion::UITraitEnvironmentLayoutDirectionFromTabsHostCppEquivalent(
+                                 newComponentProps.layoutDirection)];
+  }
+
+  if (newComponentProps.colorScheme != oldComponentProps.colorScheme) {
+    _colorScheme = rnscreens::conversion::UIUserInterfaceStyleFromHostProp(newComponentProps.colorScheme);
+    _controller.overrideUserInterfaceStyle = _colorScheme;
+  }
+
   // Super call updates _props pointer. We should NOT update it before calling super.
   [super updateProps:props oldProps:oldProps];
 }
@@ -369,7 +364,7 @@ namespace react = facebook::react;
 {
   [super updateEventEmitter:eventEmitter];
 
-  const auto &castedEventEmitter = std::static_pointer_cast<const react::RNSTabsHostEventEmitter>(eventEmitter);
+  const auto &castedEventEmitter = std::static_pointer_cast<const react::RNSTabsHostIOSEventEmitter>(eventEmitter);
   [_reactEventEmitter updateEventEmitter:castedEventEmitter];
 }
 
@@ -396,24 +391,17 @@ namespace react = facebook::react;
 
 #pragma mark - RCTMountingTransactionObserving
 
+- (void)invalidate
+{
+  [self invalidateImpl];
+}
+
 - (void)mountingTransactionWillMount:(const facebook::react::MountingTransaction &)transaction
                 withSurfaceTelemetry:(const facebook::react::SurfaceTelemetry &)surfaceTelemetry
 {
   _hasModifiedTabsScreensInCurrentTransaction = NO;
   _hasModifiedBottomAccessoryInCurrentTransation = NO;
   [_controller reactMountingTransactionWillMount];
-
-#if RCT_NEW_ARCH_ENABLED
-  for (const auto &mutation : transaction.getMutations()) {
-    if ([self shouldInvalidateOnMutation:mutation]) {
-      for (UIView<RNSViewControllerInvalidating> *childView in _reactSubviews) {
-        [RNSViewControllerInvalidator invalidateViewIfDetached:childView forRegistry:_invalidatedComponentsRegistry];
-      }
-
-      [RNSViewControllerInvalidator invalidateViewIfDetached:self forRegistry:_invalidatedComponentsRegistry];
-    }
-  }
-#endif // RCT_NEW_ARCH_ENABLED
 }
 
 - (void)mountingTransactionDidMount:(const facebook::react::MountingTransaction &)transaction
@@ -582,6 +570,25 @@ RNS_IGNORE_SUPER_CALL_END
   }
 }
 
+- (void)setLayoutDirection:(UITraitEnvironmentLayoutDirection)layoutDirection
+{
+  _layoutDirection = layoutDirection;
+#if RNS_IPHONE_OS_VERSION_AVAILABLE(17_0)
+  if (@available(iOS 17.0, *)) {
+    _controller.traitOverrides.layoutDirection = _layoutDirection;
+  } else
+#endif // RNS_IPHONE_OS_VERSION_AVAILABLE(17_0)
+  {
+    _controller.needsLayoutDirectionUpdateBelowIOS17 = YES;
+
+    // If controller is already attached to parent VC, we should update layout direction
+    // immediately as controller updates layoutDirection only on `didMoveToParentViewController`.
+    if (_controller.parentViewController != nil) {
+      [_controller updateLayoutDirectionBelowIOS17IfNeeded];
+    }
+  }
+}
+
 #pragma mark - React Image Loader
 
 - (nullable RCTImageLoader *)reactImageLoader
@@ -589,6 +596,73 @@ RNS_IGNORE_SUPER_CALL_END
   return _imageLoader;
 }
 
+#pragma mark - RNSTabBarControllerDelegate
+
+- (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
+        didUpdateStateTo:(nonnull RNSTabsNavigationState *)navState
+             withContext:(nonnull RNSTabsNavigationStateUpdateContext *)context
+{
+  RCTAssert(navState.selectedScreenKey != nil, @"[RNScreens] screenKey MUST NOT be nil");
+
+  [self.reactEventEmitter emitOnTabSelected:{.selectedScreenKey = navState.selectedScreenKey,
+                                             .provenance = navState.provenance,
+                                             .isRepeated = context.isRepeated,
+                                             .hasTriggeredSpecialEffect = context.hasTriggeredSpecialEffect,
+                                             .isNativeAction = context.isNativeAction}];
+}
+
+- (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
+    rejectedStateUpdateTo:(nonnull RNSTabsNavigationState *)rejectedNavState
+             currentState:(nonnull RNSTabsNavigationState *)currentNavState
+               withReason:(RNSTabsNavigationStateRejectionReason)reasonCode
+{
+  RCTAssert(currentNavState.selectedScreenKey != nil, @"[RNScreens] Current state screenKey MUST NOT be nil");
+  RCTAssert(rejectedNavState.selectedScreenKey != nil, @"[RNScreens] Rejected state screenKey MUST NOT be nil");
+
+  [self.reactEventEmitter emitOnTabSelectionRejected:{.currentNavState = currentNavState,
+                                                      .rejectedNavState = rejectedNavState,
+                                                      .rejectionReason = reasonCode}];
+}
+
+- (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
+    preventedSelectionOf:(nonnull NSString *)screenKey
+            currentState:(nonnull RNSTabsNavigationState *)currentNavState
+{
+  RCTAssert(tabBarController != nil, @"[RNScreens] Expected NON NIL tabBarController");
+  RCTAssert(screenKey != nil, @"[RNScreens] Expected NON NIL screenKey");
+  RCTAssert(
+      currentNavState != nil && currentNavState.selectedScreenKey != nil,
+      @"[RNScreens] Expected NON NIL nav state & selectedScreenKey");
+
+  [self.reactEventEmitter emitOnTabSelectionPrevented:{
+                                                          .currentNavState = currentNavState,
+                                                          .preventedScreenKey = screenKey,
+  }];
+}
+
+- (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
+    didSelectMoreTabWithCurrentState:(nonnull RNSTabsNavigationState *)currentNavState
+{
+  RCTAssert(tabBarController != nil, @"[RNScreens] Expected NON NIL tabBarController");
+  RCTAssert(
+      currentNavState != nil && currentNavState.selectedScreenKey != nil,
+      @"[RNScreens] Expected NON NIL nav state & selectedScreenKey");
+
+  [self.reactEventEmitter emitOnMoreTabSelected:{
+                                                    .currentNavState = currentNavState,
+  }];
+}
+
+#pragma mark - Dynamic frameworks support
+
+// Needed because of this: https://github.com/facebook/react-native/pull/37274
+#ifdef RCT_DYNAMIC_FRAMEWORKS
++ (void)load
+{
+  [super load];
+}
+#endif // RCT_DYNAMIC_FRAMEWORKS
+
 @end
 
 #pragma mark - Modified React Subviews implementation

package/ios/tabs/host/RNSTabsHostComponentViewManager.mm

@@ -35,9 +35,6 @@ RCT_REMAP_VIEW_PROPERTY(
 // from JS.
 RCT_REMAP_VIEW_PROPERTY(tabBarControllerMode, tabBarControllerModeFromRNSTabBarControllerMode, RNSTabBarControllerMode);
 
-// TODO: Missing prop
-//@property (nonatomic, readonly) BOOL experimental_controlNavigationStateInJS;
-
 #pragma mark - LEGACY Events
 
 RCT_EXPORT_VIEW_PROPERTY(onNativeFocusChange, RCTDirectEventBlock);

package/ios/tabs/host/RNSTabsHostEventEmitter.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #import <Foundation/Foundation.h>
+#import "RNSTabsNavigationState.h"
 
 // Hide C++ symbols from C compiler used when building Swift module
 #if defined(__cplusplus) && RCT_NEW_ARCH_ENABLED
@@ -15,21 +16,57 @@ namespace react = facebook::react;
 
 NS_ASSUME_NONNULL_BEGIN
 
-#if defined(__cplusplus)
-struct OnNativeFocusChangePayload {
-  NSString *_Nonnull tabKey;
-  BOOL repeatedSelectionHandledBySpecialEffect;
-};
-#else
+/** Payload for the `onTabSelected` event emitted when a tab selection is accepted. */
+typedef struct {
+  /** Screen key of the newly selected tab. */
+  NSString *_Nonnull selectedScreenKey;
+  /** Provenance of the navigation state after the selection. */
+  int provenance;
+  /** Whether the same tab that was already selected has been selected again. */
+  BOOL isRepeated;
+  /** Whether a special effect (e.g. scroll-to-top) was triggered. */
+  BOOL hasTriggeredSpecialEffect;
+  /** Whether the selection was initiated by a native user action (tap). */
+  BOOL isNativeAction;
+} OnTabSelectedPayload;
+
+/** Payload for the `onTabSelectionRejected` event emitted when a tab selection request is rejected. */
 typedef struct {
-  NSString *_Nonnull tabKey;
-  BOOL repeatedSelectionHandledBySpecialEffect;
-} OnNativeFocusChangePayload;
-#endif
+  /** The currently active navigation state that was kept. */
+  RNSTabsNavigationState *_Nonnull currentNavState;
+  /** The navigation state update that was rejected. */
+  RNSTabsNavigationState *_Nonnull rejectedNavState;
+  /** Reason the update was rejected. */
+  RNSTabsNavigationStateRejectionReason rejectionReason;
+} OnTabSelectionRejectedPayload;
+
+/** Payload for the `onTabSelectionPrevented` event emitted when a tab selection is prevented. */
+typedef struct {
+  /** The currently active navigation state that was kept. */
+  RNSTabsNavigationState *_Nonnull currentNavState;
+  /** Screen key of the tab whose selection was prevented. */
+  NSString *_Nonnull preventedScreenKey;
+} OnTabSelectionPreventedPayload;
+
+/** Payload for the `onMoreTabSelected` event emitted when the user taps the "More" tab bar item. */
+typedef struct {
+  /** The currently active navigation state when the "More" tab was tapped. */
+  RNSTabsNavigationState *_Nonnull currentNavState;
+} OnMoreTabSelectedPayload;
 
 @interface RNSTabsHostEventEmitter : NSObject
 
-- (BOOL)emitOnNativeFocusChange:(OnNativeFocusChangePayload)payload;
+/** Emits `onTabSelected` event to JS. Returns YES if the event was dispatched successfully. */
+- (BOOL)emitOnTabSelected:(OnTabSelectedPayload)payload;
+
+/** Emits `onTabSelectionRejected` event to JS. Returns YES if the event was dispatched successfully. */
+- (BOOL)emitOnTabSelectionRejected:(OnTabSelectionRejectedPayload)payload;
+
+/** Emits `onTabSelectionPrevented` event to JS. Returns YES if the event was dispatched successfully. */
+- (BOOL)emitOnTabSelectionPrevented:(OnTabSelectionPreventedPayload)payload;
+
+/** Emits `onMoreTabSelected` event to JS. Returns YES if the event was dispatched successfully. */
+- (BOOL)emitOnMoreTabSelected:(OnMoreTabSelectedPayload)payload;
 
 @end
 
@@ -41,7 +78,7 @@ typedef struct {
 
 #if RCT_NEW_ARCH_ENABLED
 
-- (void)updateEventEmitter:(const std::shared_ptr<const react::RNSTabsHostEventEmitter> &)emitter;
+- (void)updateEventEmitter:(const std::shared_ptr<const react::RNSTabsHostIOSEventEmitter> &)emitter;
 
 #else
 #pragma mark - LEGACY Event emitter blocks

package/ios/tabs/host/RNSTabsHostEventEmitter.mm

@@ -4,6 +4,7 @@
 #if RCT_NEW_ARCH_ENABLED
 #import <React/RCTConversions.h>
 #import <react/renderer/components/rnscreens/EventEmitters.h>
+#import "RNSConversions.h"
 #endif // RCT_NEW_ARCH_ENABLED
 
 #if RCT_NEW_ARCH_ENABLED
@@ -12,7 +13,7 @@ namespace react = facebook::react;
 
 @implementation RNSTabsHostEventEmitter {
 #if RCT_NEW_ARCH_ENABLED
-  std::shared_ptr<const react::RNSTabsHostEventEmitter> _reactEventEmitter;
+  std::shared_ptr<const react::RNSTabsHostIOSEventEmitter> _reactEventEmitter;
 #endif // RCT_NEW_ARCH_ENABLED
 }
 
@@ -27,37 +28,72 @@ namespace react = facebook::react;
 }
 
 #if RCT_NEW_ARCH_ENABLED
-- (void)updateEventEmitter:(const std::shared_ptr<const react::RNSTabsHostEventEmitter> &)emitter
+- (void)updateEventEmitter:(const std::shared_ptr<const react::RNSTabsHostIOSEventEmitter> &)emitter
 {
   _reactEventEmitter = emitter;
 }
 #endif // RCT_NEW_ARCH_ENABLED
 
-- (BOOL)emitOnNativeFocusChange:(OnNativeFocusChangePayload)payload
+- (BOOL)emitOnTabSelected:(OnTabSelectedPayload)payload
 {
-#if RCT_NEW_ARCH_ENABLED
   if (_reactEventEmitter != nullptr) {
-    _reactEventEmitter->onNativeFocusChange(
-        {.tabKey = RCTStringFromNSString(payload.tabKey),
-         .repeatedSelectionHandledBySpecialEffect =
-             static_cast<bool>(payload.repeatedSelectionHandledBySpecialEffect)});
+    _reactEventEmitter->onTabSelected(
+        {.selectedScreenKey = RCTStringFromNSString(payload.selectedScreenKey),
+         .provenance = payload.provenance,
+         .isRepeated = static_cast<bool>(payload.isRepeated),
+         .hasTriggeredSpecialEffect = static_cast<bool>(payload.hasTriggeredSpecialEffect),
+         .isNativeAction = static_cast<bool>(payload.isNativeAction)});
     return YES;
   } else {
-    RCTLogWarn(@"[RNScreens] Skipped OnNativeFocusChange event emission due to nullish emitter");
+    RCTLogWarn(@"[RNScreens] Skipped OnTabSelected event emission due to nullish emitter");
     return NO;
   }
-#else
-  if (self.onNativeFocusChange) {
-    self.onNativeFocusChange(@{
-      @"tabKey" : payload.tabKey,
-      @"repeatedSelectionHandledBySpecialEffect" : @(payload.repeatedSelectionHandledBySpecialEffect)
-    });
+}
+
+- (BOOL)emitOnTabSelectionRejected:(OnTabSelectionRejectedPayload)payload
+{
+  if (_reactEventEmitter != nullptr) {
+    auto convertedReason =
+        rnscreens::conversion::RNSOnTabSelectionRejectedRejectionReasonFromRNSTabsNavigationStateRejectionReason(
+            payload.rejectionReason);
+    _reactEventEmitter->onTabSelectionRejected(
+        {.selectedScreenKey = RCTStringFromNSString(payload.currentNavState.selectedScreenKey),
+         .provenance = payload.currentNavState.provenance,
+         .rejectedScreenKey = RCTStringFromNSString(payload.rejectedNavState.selectedScreenKey),
+         .rejectedProvenance = payload.rejectedNavState.provenance,
+         .rejectionReason = convertedReason});
     return YES;
   } else {
-    RCTLogWarn(@"[RNScreens] Skipped OnNativeFocusChange event emission due to nullish emitter");
+    RCTLogWarn(@"[RNScreens] Skipped OnTabSelectionRejected event emission due to nullish emitter");
+    return NO;
+  }
+}
+
+- (BOOL)emitOnTabSelectionPrevented:(OnTabSelectionPreventedPayload)payload
+{
+  if (_reactEventEmitter != nullptr) {
+    _reactEventEmitter->onTabSelectionPrevented(
+        {.selectedScreenKey = RCTStringFromNSString(payload.currentNavState.selectedScreenKey),
+         .provenance = payload.currentNavState.provenance,
+         .preventedScreenKey = RCTStringFromNSString(payload.preventedScreenKey)});
+    return YES;
+  } else {
+    RCTLogWarn(@"[RNScreens] Skipped OnTabSelectionPrevented event emission due to nullish emitter");
+    return NO;
+  }
+}
+
+- (BOOL)emitOnMoreTabSelected:(OnMoreTabSelectedPayload)payload
+{
+  if (_reactEventEmitter != nullptr) {
+    _reactEventEmitter->onMoreTabSelected(
+        {.selectedScreenKey = RCTStringFromNSString(payload.currentNavState.selectedScreenKey),
+         .provenance = payload.currentNavState.provenance});
+    return YES;
+  } else {
+    RCTLogWarn(@"[RNScreens] Skipped OnMoreTabSelected event emission due to nullish emitter");
     return NO;
   }
-#endif // RCT_NEW_ARCH_ENABLED
 }
 
 @end

package/ios/tabs/host/RNSTabsNavigationState.h

@@ -0,0 +1,69 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Describes navigation state of a tabs container.
+ *
+ * It holds information about key of a selected screen AND state provenance.
+ * The provenance describes *a history of the state*. Conceptually, the state with provenance `N + 1`
+ * MUST BE derived from state with provenance `N`.
+ */
+@interface RNSTabsNavigationState : NSObject
+
+/** Screen key of the currently selected tab. */
+@property (nonatomic, strong, readonly, nonnull) NSString *selectedScreenKey;
+
+/** Monotonically increasing number describing the generation of this state instance.
+ *  Used for stale update detection: state A is stale iff A.provenance <= B.provenance. */
+@property (nonatomic, readonly) int provenance;
+
+- (instancetype)initWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey provenance:(int)provenance;
+
+- (instancetype)cloneState;
+
++ (instancetype)stateWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey provenance:(int)provenance;
+
+@end
+
+/** Bundles a navigation state change together with metadata about the selection context. */
+@interface RNSTabsNavigationStateUpdateContext : NSObject
+
+/** The navigation state after the change. */
+@property (nonatomic, readonly, strong, nonnull) RNSTabsNavigationState *navState;
+/** Whether the same tab that was already selected has been selected again. */
+@property (nonatomic, readonly) BOOL isRepeated;
+/** Whether a special effect (e.g. scroll-to-top) was triggered by the selection. */
+@property (nonatomic, readonly) BOOL hasTriggeredSpecialEffect;
+/** Whether the selection was initiated by a native user action (tap) as opposed to a JS-driven update. */
+@property (nonatomic, readonly) BOOL isNativeAction;
+
+- (instancetype)initWithNavState:(nonnull RNSTabsNavigationState *)navState
+                      isRepeated:(BOOL)isRepeated
+       hasTriggeredSpecialEffect:(BOOL)hasTriggeredSpecialEffect
+                  isNativeAction:(BOOL)isNativeAction;
+
+@end
+
+/** Source of a navigation state update. */
+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,
+  /** 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. */
+typedef NS_ENUM(NSInteger, RNSTabsNavigationStateRejectionReason) {
+  /** The update's provenance is based on a stale state. */
+  RNSTabsNavigationStateRejectionReasonStale = 0,
+  /** The requested tab is already selected. */
+  RNSTabsNavigationStateRejectionReasonRepeated,
+};
+
+NS_ASSUME_NONNULL_END