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

package/ios/tabs/host/RNSTabsNavigationState.h

@@ -0,0 +1,184 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class RNSTabBarController;
+
+/**
+ * Origin (actor) that requested a tab transition. Mirrors the public `actionOrigin` event field.
+ */
+typedef NS_ENUM(NSInteger, RNSTabsActionOrigin) {
+  /**
+   * Direct native UI interaction (tab bar tap, drag-and-drop).
+   */
+  RNSTabsActionOriginUser = 0,
+  /**
+   * JS-initiated request delivered via the `navStateRequest` prop.
+   */
+  RNSTabsActionOriginProgrammaticJs,
+  /**
+   * Request initiated from the native side by some actor, e.g. a downstream
+   * library integrating directly against `RNSTabBarController`.
+   */
+  RNSTabsActionOriginProgrammaticNative,
+  /**
+   * Platform side effect not attributable to an explicit actor — 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).
+   */
+  RNSTabsActionOriginImplicit,
+};
+
+/**
+ * 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,
+};
+
+/**
+ * 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.
+ */
+@property (nonatomic, readonly) int provenance;
+
+- (instancetype)initWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey provenance:(int)provenance;
+
+- (instancetype)cloneState;
+
++ (instancetype)stateWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey provenance:(int)provenance;
+
+@end
+
+/**
+ * A request to change navigation state.
+ *
+ * Carries the target `selectedScreenKey`, the `baseProvenance` of the state the request was derived from,
+ * and the `actionOrigin` (actor) that initiated it. Mirrors the public
+ * `TabsHostNavStateRequest` TS type plus an `actionOrigin` carried internally.
+ */
+@interface RNSTabsNavigationStateUpdateRequest : NSObject
+
+@property (nonatomic, strong, readonly, nonnull) NSString *selectedScreenKey;
+@property (nonatomic, readonly) int baseProvenance;
+@property (nonatomic, readonly) RNSTabsActionOrigin actionOrigin;
+
+- (instancetype)initWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey
+                           baseProvenance:(int)baseProvenance
+                             actionOrigin:(RNSTabsActionOrigin)actionOrigin;
+
+- (instancetype)cloneRequest;
+
++ (instancetype)requestWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey
+                              baseProvenance:(int)baseProvenance
+                                actionOrigin:(RNSTabsActionOrigin)actionOrigin;
+
+@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;
+/**
+ * Origin (actor) that requested this transition.
+ */
+@property (nonatomic, readonly) RNSTabsActionOrigin actionOrigin;
+
+- (instancetype)initWithNavState:(nonnull RNSTabsNavigationState *)navState
+                      isRepeated:(BOOL)isRepeated
+       hasTriggeredSpecialEffect:(BOOL)hasTriggeredSpecialEffect
+                    actionOrigin:(RNSTabsActionOrigin)actionOrigin;
+
+@end
+
+/**
+ * Observer of navigation state changes on a tabs container (`RNSTabBarController`).
+ *
+ * Multiple observers may register against a single container via
+ * `RNSTabBarController addNavigationStateObserver:` / `removeNavigationStateObserver:`.
+ * The host (`RNSTabsHostComponentView`) registers itself as an observer to relay events
+ * to JS; downstream native libraries integrating directly against `RNSTabBarController`
+ * may register additional observers.
+ *
+ * Observers are held with strong references; callers must explicitly call
+ * `removeNavigationStateObserver:` before observer dealloc, or rely on the host
+ * invoking `tearDown` (which clears the registry) on container teardown.
+ */
+@protocol RNSTabsNavigationStateObserver <NSObject>
+
+@required
+
+/**
+ * Called when the container accepts a navigation state change.
+ */
+- (void)tabsContainer:(nonnull RNSTabBarController *)tabsContainer
+     didUpdateStateTo:(nonnull RNSTabsNavigationState *)navState
+          withContext:(nonnull RNSTabsNavigationStateUpdateContext *)context;
+
+/**
+ * Called when the container rejects a navigation state update.
+ */
+- (void)tabsContainer:(nonnull RNSTabBarController *)tabsContainer
+    rejectedStateUpdate:(nonnull RNSTabsNavigationStateUpdateRequest *)rejectedRequest
+           currentState:(nonnull RNSTabsNavigationState *)currentNavState
+             withReason:(RNSTabsNavigationStateRejectionReason)reason;
+
+/**
+ * Called when a native user action (tap) attempts to select a tab that has
+ * `preventNativeSelection` enabled. The navigation state remains unchanged.
+ */
+- (void)tabsContainer:(nonnull RNSTabBarController *)tabsContainer
+    preventedSelectionOf:(nonnull NSString *)preventedScreenKey
+            currentState:(nonnull RNSTabsNavigationState *)currentNavState;
+
+@optional
+
+/**
+ * iOS-only. Called when the user taps the More tab on iPhone or in iPad split view
+ * configurations where UIKit groups overflow tabs into a More navigation controller.
+ *
+ * This event is informational; the navigation state is not advanced as part of this callback.
+ * Android does not emit an analogue.
+ */
+- (void)tabsContainer:(nonnull RNSTabBarController *)tabsContainer
+    didSelectMoreTabWithCurrentState:(nonnull RNSTabsNavigationState *)currentNavState;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/tabs/host/RNSTabsNavigationState.mm

@@ -0,0 +1,78 @@
+#import "RNSTabsNavigationState.h"
+
+@implementation RNSTabsNavigationState
+
+- (instancetype)initWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey provenance:(int)provenance
+{
+  if (self = [super init]) {
+    _selectedScreenKey = selectedScreenKey;
+    _provenance = provenance;
+  }
+  return self;
+}
+
+- (instancetype)cloneState
+{
+  auto *clonedValue =
+      [[RNSTabsNavigationState alloc] initWithSelectedScreenKey:[NSString stringWithString:self.selectedScreenKey]
+                                                     provenance:self.provenance];
+  return clonedValue;
+}
+
++ (instancetype)stateWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey provenance:(int)provenance
+{
+  return [[RNSTabsNavigationState alloc] initWithSelectedScreenKey:selectedScreenKey provenance:provenance];
+}
+
+@end
+
+@implementation RNSTabsNavigationStateUpdateRequest
+
+- (instancetype)initWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey
+                           baseProvenance:(int)baseProvenance
+                             actionOrigin:(RNSTabsActionOrigin)actionOrigin
+{
+  if (self = [super init]) {
+    _selectedScreenKey = selectedScreenKey;
+    _baseProvenance = baseProvenance;
+    _actionOrigin = actionOrigin;
+  }
+  return self;
+}
+
+- (instancetype)cloneRequest
+{
+  return [[RNSTabsNavigationStateUpdateRequest alloc]
+      initWithSelectedScreenKey:[NSString stringWithString:self.selectedScreenKey]
+                 baseProvenance:self.baseProvenance
+                   actionOrigin:self.actionOrigin];
+}
+
++ (instancetype)requestWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey
+                              baseProvenance:(int)baseProvenance
+                                actionOrigin:(RNSTabsActionOrigin)actionOrigin
+{
+  return [[RNSTabsNavigationStateUpdateRequest alloc] initWithSelectedScreenKey:selectedScreenKey
+                                                                 baseProvenance:baseProvenance
+                                                                   actionOrigin:actionOrigin];
+}
+
+@end
+
+@implementation RNSTabsNavigationStateUpdateContext
+
+- (instancetype)initWithNavState:(nonnull RNSTabsNavigationState *)navState
+                      isRepeated:(BOOL)isRepeated
+       hasTriggeredSpecialEffect:(BOOL)hasTriggeredSpecialEffect
+                    actionOrigin:(RNSTabsActionOrigin)actionOrigin
+{
+  if (self = [super init]) {
+    _navState = navState;
+    _isRepeated = isRepeated;
+    _hasTriggeredSpecialEffect = hasTriggeredSpecialEffect;
+    _actionOrigin = actionOrigin;
+  }
+  return self;
+}
+
+@end

package/ios/tabs/host/RNSTabsNavigationStateObserverRegistry.h

@@ -0,0 +1,62 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import "RNSTabsNavigationState.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Holds the set of `RNSTabsNavigationStateObserver`s registered against an
+ * `RNSTabBarController` and fans out container events to all of them.
+ *
+ * Observers are held with strong references; callers must explicitly call
+ * `removeObserver:` before observer dealloc, or rely on the host invoking
+ * `clear` (via `RNSTabBarController.tearDown`) on container teardown.
+ *
+ * `emit*` methods invoke each observer in registration order. The `@optional`
+ * More-tab callback is dispatched only to observers that respond to the selector.
+ */
+@interface RNSTabsNavigationStateObserverRegistry : NSObject
+
+/**
+ * Register an observer.
+ *
+ * @returns NO if the observer is already registered or if called
+ * during an in-flight `emit*` (modifications during emission are rejected).
+ */
+- (BOOL)addObserver:(id<RNSTabsNavigationStateObserver>)observer;
+
+/**
+ * Unregister an observer.
+ *
+ * @returns NO if the observer was not registered or if called
+ * during an in-flight `emit*` (modifications during emission are rejected).
+ */
+- (BOOL)removeObserver:(id<RNSTabsNavigationStateObserver>)observer;
+
+/**
+ * Drop all registered observers.
+ *
+ * @returns NO if called during in-flight `emit*` (modifications during emission are rejected).
+ */
+- (BOOL)clear;
+
+- (void)emitDidUpdateStateTo:(nonnull RNSTabsNavigationState *)navState
+                 withContext:(nonnull RNSTabsNavigationStateUpdateContext *)context
+                      sender:(nonnull RNSTabBarController *)sender;
+
+- (void)emitRejectedStateUpdate:(nonnull RNSTabsNavigationStateUpdateRequest *)rejectedRequest
+                   currentState:(nonnull RNSTabsNavigationState *)currentNavState
+                     withReason:(RNSTabsNavigationStateRejectionReason)reason
+                         sender:(nonnull RNSTabBarController *)sender;
+
+- (void)emitPreventedSelectionOf:(nonnull NSString *)preventedScreenKey
+                    currentState:(nonnull RNSTabsNavigationState *)currentNavState
+                          sender:(nonnull RNSTabBarController *)sender;
+
+- (void)emitDidSelectMoreTabWithCurrentState:(nonnull RNSTabsNavigationState *)currentNavState
+                                      sender:(nonnull RNSTabBarController *)sender;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/tabs/host/RNSTabsNavigationStateObserverRegistry.mm

@@ -0,0 +1,104 @@
+#import "RNSTabsNavigationStateObserverRegistry.h"
+
+#import <React/RCTAssert.h>
+
+#import "RNSTabBarController.h"
+
+@implementation RNSTabsNavigationStateObserverRegistry {
+  NSMutableArray<id<RNSTabsNavigationStateObserver>> *_observers;
+  BOOL _isEmitting;
+}
+
+- (instancetype)init
+{
+  if (self = [super init]) {
+    _observers = [NSMutableArray new];
+    _isEmitting = NO;
+  }
+  return self;
+}
+
+- (BOOL)addObserver:(id<RNSTabsNavigationStateObserver>)observer
+{
+  if (_isEmitting || [_observers containsObject:observer]) {
+    return NO;
+  }
+  [_observers addObject:observer];
+  return YES;
+}
+
+- (BOOL)removeObserver:(id<RNSTabsNavigationStateObserver>)observer
+{
+  if (_isEmitting || ![_observers containsObject:observer]) {
+    return NO;
+  }
+  [_observers removeObject:observer];
+  return YES;
+}
+
+- (BOOL)clear
+{
+  if (_isEmitting) {
+    return NO;
+  }
+  [_observers removeAllObjects];
+  return YES;
+}
+
+- (void)emitDidUpdateStateTo:(nonnull RNSTabsNavigationState *)navState
+                 withContext:(nonnull RNSTabsNavigationStateUpdateContext *)context
+                      sender:(nonnull RNSTabBarController *)sender
+{
+  [self emitSignal:^(id<RNSTabsNavigationStateObserver> observer) {
+    [observer tabsContainer:sender didUpdateStateTo:navState withContext:context];
+  }];
+}
+
+- (void)emitRejectedStateUpdate:(nonnull RNSTabsNavigationStateUpdateRequest *)rejectedRequest
+                   currentState:(nonnull RNSTabsNavigationState *)currentNavState
+                     withReason:(RNSTabsNavigationStateRejectionReason)reason
+                         sender:(nonnull RNSTabBarController *)sender
+{
+  [self emitSignal:^(id<RNSTabsNavigationStateObserver> observer) {
+    [observer tabsContainer:sender rejectedStateUpdate:rejectedRequest currentState:currentNavState withReason:reason];
+  }];
+}
+
+- (void)emitPreventedSelectionOf:(nonnull NSString *)preventedScreenKey
+                    currentState:(nonnull RNSTabsNavigationState *)currentNavState
+                          sender:(nonnull RNSTabBarController *)sender
+{
+  [self emitSignal:^(id<RNSTabsNavigationStateObserver> observer) {
+    [observer tabsContainer:sender preventedSelectionOf:preventedScreenKey currentState:currentNavState];
+  }];
+}
+
+- (void)emitDidSelectMoreTabWithCurrentState:(nonnull RNSTabsNavigationState *)currentNavState
+                                      sender:(nonnull RNSTabBarController *)sender
+{
+  SEL observerSelector = @selector(tabsContainer:didSelectMoreTabWithCurrentState:);
+  [self emitSignal:^(id<RNSTabsNavigationStateObserver> observer) {
+    if ([observer respondsToSelector:observerSelector]) {
+      [observer tabsContainer:sender didSelectMoreTabWithCurrentState:currentNavState];
+    }
+  }];
+}
+
+- (void)emitSignal:(void (^)(id<RNSTabsNavigationStateObserver> observer))emitBlock
+{
+  RCTAssert(!_isEmitting, @"[RNScreens] Recursive emission on RNSTabsNavigationStateObserverRegistry");
+
+  // In release best we can do here is let it emit the event. Alternatives are to crash or not emit (certain wrong
+  // state).
+
+  _isEmitting = YES;
+  @try {
+    for (id<RNSTabsNavigationStateObserver> observer in _observers) {
+      emitBlock(observer);
+    }
+  } @finally {
+    _isEmitting = NO;
+  }
+}
+
+@end

package/ios/tabs/screen/RNSTabsScreenComponentView.h

@@ -4,13 +4,10 @@
 #import "RNSEnums.h"
 #import "RNSReactBaseView.h"
 #import "RNSSafeAreaProviding.h"
-#import "RNSScrollEdgeEffectApplicator.h"
 #import "RNSScrollViewBehaviorOverriding.h"
 #import "RNSTabsScreenEventEmitter.h"
 
-#ifdef RCT_NEW_ARCH_ENABLED
-#import "RNSViewControllerInvalidating.h"
-#else
+#if !RCT_NEW_ARCH_ENABLED
 #import <React/RCTInvalidating.h>
 #endif
 
@@ -24,10 +21,9 @@ NS_ASSUME_NONNULL_BEGIN
  * of a particular tab.
  */
 @interface RNSTabsScreenComponentView : RNSReactBaseView <
-                                            RNSSafeAreaProviding,
-#ifdef RCT_NEW_ARCH_ENABLED
-                                            RNSViewControllerInvalidating
-#else
+                                            RNSSafeAreaProviding
+#if !RCT_NEW_ARCH_ENABLED
+                                            ,
                                             RCTInvalidating
 #endif
                                             >
@@ -42,12 +38,6 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (nonatomic, weak, nullable) RNSTabsHostComponentView *reactSuperview;
 
-/**
- * Updates [scroll edge effects](https://developer.apple.com/documentation/uikit/uiscrolledgeeffect)
- * on a content ScrollView inside the tab screen, if one exists. It uses ScrollViewFinder to find the ScrollView.
- */
-- (void)updateContentScrollViewEdgeEffectsIfExists;
-
 @end
 
 #pragma mark - Props
@@ -55,13 +45,12 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Properties set on component in JavaScript.
  */
-@interface RNSTabsScreenComponentView () <RNSScrollViewBehaviorOverriding, RNSScrollEdgeEffectProviding>
+@interface RNSTabsScreenComponentView () <RNSScrollViewBehaviorOverriding>
 
 // TODO: All of these properties should be `readonly`. Do this when support for legacy
 // architecture is dropped.
 
-@property (nonatomic) BOOL isSelectedScreen;
-@property (nonatomic, nullable) NSString *tabKey;
+@property (nonatomic, nullable) NSString *screenKey;
 @property (nonatomic, nullable) NSString *badgeValue;
 
 @property (nonatomic, nullable) NSString *tabBarItemTestID;
@@ -85,17 +74,14 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic) BOOL shouldUseRepeatedTabSelectionPopToRootSpecialEffect;
 @property (nonatomic) BOOL shouldUseRepeatedTabSelectionScrollToTopSpecialEffect;
 
+@property (nonatomic) BOOL preventNativeSelection;
+
 @property (nonatomic, readonly) BOOL overrideScrollViewContentInsetAdjustmentBehavior;
 
 @property (nonatomic, nullable) NSString *tabItemTestID;
 @property (nonatomic, nullable) NSString *tabItemAccessibilityLabel;
 @property (nonatomic) BOOL tabBarItemNeedsA11yUpdate;
 
-@property (nonatomic) RNSScrollEdgeEffect bottomScrollEdgeEffect;
-@property (nonatomic) RNSScrollEdgeEffect leftScrollEdgeEffect;
-@property (nonatomic) RNSScrollEdgeEffect rightScrollEdgeEffect;
-@property (nonatomic) RNSScrollEdgeEffect topScrollEdgeEffect;
-
 @property (nonatomic) RNSTabsScreenSystemItem systemItem;
 
 @end