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

package/ios/tabs/host/RNSTabsHostComponentView.mm

@@ -53,7 +53,7 @@ namespace react = facebook::react;
   BOOL _hasModifiedBottomAccessoryInCurrentTransation;
   BOOL _needsTabBarAppearanceUpdate;
 
-  RNSTabsNavigationState *_Nullable _jsNavState;
+  RNSTabsNavigationStateUpdateRequest *_Nullable _navStateRequest;
 }
 
 - (instancetype)initWithFrame:(CGRect)frame
@@ -85,6 +85,8 @@ namespace react = facebook::react;
   [self resetProps];
 
   _controller = [[RNSTabBarController alloc] initWithTabsHostComponentView:self];
+  RCTAssert([_controller addNavigationStateObserver:self],
+            @"[RNScreens] Failed to register RNSTabsHostComponentView as navigation state observer");
 
   _reactSubviews = [NSMutableArray new];
   _reactEventEmitter = [RNSTabsHostEventEmitter new];
@@ -119,6 +121,7 @@ namespace react = facebook::react;
   dispatch_async(dispatch_get_main_queue(), ^{
     auto strongSelf = weakSelf;
     if (strongSelf) {
+      [strongSelf->_controller tearDown];
       strongSelf->_controller = nil;
     }
   });
@@ -268,14 +271,16 @@ namespace react = facebook::react;
   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);
+  if (newComponentProps.navStateRequest.selectedScreenKey != oldComponentProps.navStateRequest.selectedScreenKey ||
+      newComponentProps.navStateRequest.baseProvenance != oldComponentProps.navStateRequest.baseProvenance) {
+    NSString *selectedScreenKey = RCTNSStringFromStringNilIfEmpty(newComponentProps.navStateRequest.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]];
+    RCTAssert(newComponentProps.navStateRequest.baseProvenance >= 0, @"[RNScreens] baseProvenance MUST BE >= 0");
+    _navStateRequest = [RNSTabsNavigationStateUpdateRequest
+        requestWithSelectedScreenKey:selectedScreenKey
+                      baseProvenance:newComponentProps.navStateRequest.baseProvenance
+                        actionOrigin:RNSTabsActionOriginProgrammaticJs];
+    [_controller setPendingNavigationStateUpdate:[_navStateRequest cloneRequest]];
   }
 
   if (newComponentProps.rejectStaleNavStateUpdates != oldComponentProps.rejectStaleNavStateUpdates) {
@@ -596,11 +601,11 @@ RNS_IGNORE_SUPER_CALL_END
   return _imageLoader;
 }
 
-#pragma mark - RNSTabBarControllerDelegate
+#pragma mark - RNSTabsNavigationStateObserver
 
-- (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
-        didUpdateStateTo:(nonnull RNSTabsNavigationState *)navState
-             withContext:(nonnull RNSTabsNavigationStateUpdateContext *)context
+- (void)tabsContainer:(nonnull RNSTabBarController *)tabsContainer
+     didUpdateStateTo:(nonnull RNSTabsNavigationState *)navState
+          withContext:(nonnull RNSTabsNavigationStateUpdateContext *)context
 {
   RCTAssert(navState.selectedScreenKey != nil, @"[RNScreens] screenKey MUST NOT be nil");
 
@@ -608,45 +613,44 @@ RNS_IGNORE_SUPER_CALL_END
                                              .provenance = navState.provenance,
                                              .isRepeated = context.isRepeated,
                                              .hasTriggeredSpecialEffect = context.hasTriggeredSpecialEffect,
-                                             .isNativeAction = context.isNativeAction}];
+                                             .actionOrigin = context.actionOrigin}];
 }
 
-- (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
-    rejectedStateUpdateTo:(nonnull RNSTabsNavigationState *)rejectedNavState
-             currentState:(nonnull RNSTabsNavigationState *)currentNavState
-               withReason:(RNSTabsNavigationStateRejectionReason)reasonCode
+- (void)tabsContainer:(nonnull RNSTabBarController *)tabsContainer
+    rejectedStateUpdate:(nonnull RNSTabsNavigationStateUpdateRequest *)rejectedRequest
+           currentState:(nonnull RNSTabsNavigationState *)currentNavState
+             withReason:(RNSTabsNavigationStateRejectionReason)reason
 {
   RCTAssert(currentNavState.selectedScreenKey != nil, @"[RNScreens] Current state screenKey MUST NOT be nil");
-  RCTAssert(rejectedNavState.selectedScreenKey != nil, @"[RNScreens] Rejected state screenKey MUST NOT be nil");
+  RCTAssert(rejectedRequest.selectedScreenKey != nil,
+            @"[RNScreens] Rejected request selectedScreenKey MUST NOT be nil");
 
   [self.reactEventEmitter emitOnTabSelectionRejected:{.currentNavState = currentNavState,
-                                                      .rejectedNavState = rejectedNavState,
-                                                      .rejectionReason = reasonCode}];
+                                                      .rejectedRequest = rejectedRequest,
+                                                      .rejectionReason = reason}];
 }
 
-- (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
-    preventedSelectionOf:(nonnull NSString *)screenKey
+- (void)tabsContainer:(nonnull RNSTabBarController *)tabsContainer
+    preventedSelectionOf:(nonnull NSString *)preventedScreenKey
             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");
+  RCTAssert(tabsContainer != nil, @"[RNScreens] Expected NON NIL tabsContainer");
+  RCTAssert(preventedScreenKey != nil, @"[RNScreens] Expected NON NIL preventedScreenKey");
+  RCTAssert(currentNavState != nil && currentNavState.selectedScreenKey != nil,
+            @"[RNScreens] Expected NON NIL nav state & selectedScreenKey");
 
   [self.reactEventEmitter emitOnTabSelectionPrevented:{
                                                           .currentNavState = currentNavState,
-                                                          .preventedScreenKey = screenKey,
+                                                          .preventedScreenKey = preventedScreenKey,
   }];
 }
 
-- (void)tabBarController:(nonnull RNSTabBarController *)tabBarController
+- (void)tabsContainer:(nonnull RNSTabBarController *)tabsContainer
     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");
+  RCTAssert(tabsContainer != nil, @"[RNScreens] Expected NON NIL tabsContainer");
+  RCTAssert(currentNavState != nil && currentNavState.selectedScreenKey != nil,
+            @"[RNScreens] Expected NON NIL nav state & selectedScreenKey");
 
   [self.reactEventEmitter emitOnMoreTabSelected:{
                                                     .currentNavState = currentNavState,

package/ios/tabs/host/RNSTabsHostEventEmitter.h

@@ -26,16 +26,16 @@ typedef struct {
   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;
+  /** Origin (actor) that requested this transition. */
+  RNSTabsActionOrigin actionOrigin;
 } OnTabSelectedPayload;
 
 /** Payload for the `onTabSelectionRejected` event emitted when a tab selection request is rejected. */
 typedef struct {
   /** The currently active navigation state that was kept. */
   RNSTabsNavigationState *_Nonnull currentNavState;
-  /** The navigation state update that was rejected. */
-  RNSTabsNavigationState *_Nonnull rejectedNavState;
+  /** The navigation state update request that was rejected. */
+  RNSTabsNavigationStateUpdateRequest *_Nonnull rejectedRequest;
   /** Reason the update was rejected. */
   RNSTabsNavigationStateRejectionReason rejectionReason;
 } OnTabSelectionRejectedPayload;

package/ios/tabs/host/RNSTabsHostEventEmitter.mm

@@ -37,12 +37,14 @@ namespace react = facebook::react;
 - (BOOL)emitOnTabSelected:(OnTabSelectedPayload)payload
 {
   if (_reactEventEmitter != nullptr) {
+    auto convertedActionOrigin =
+        rnscreens::conversion::RNSOnTabSelectedActionOriginFromRNSTabsActionOrigin(payload.actionOrigin);
     _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)});
+         .actionOrigin = convertedActionOrigin});
     return YES;
   } else {
     RCTLogWarn(@"[RNScreens] Skipped OnTabSelected event emission due to nullish emitter");
@@ -59,8 +61,8 @@ namespace react = facebook::react;
     _reactEventEmitter->onTabSelectionRejected(
         {.selectedScreenKey = RCTStringFromNSString(payload.currentNavState.selectedScreenKey),
          .provenance = payload.currentNavState.provenance,
-         .rejectedScreenKey = RCTStringFromNSString(payload.rejectedNavState.selectedScreenKey),
-         .rejectedProvenance = payload.rejectedNavState.provenance,
+         .rejectedScreenKey = RCTStringFromNSString(payload.rejectedRequest.selectedScreenKey),
+         .rejectedBaseProvenance = payload.rejectedRequest.baseProvenance,
          .rejectionReason = convertedReason});
     return YES;
   } else {

package/ios/tabs/host/RNSTabsNavigationState.h

@@ -4,6 +4,47 @@
 
 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.
  *
@@ -13,11 +54,15 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @interface RNSTabsNavigationState : NSObject
 
-/** Screen key of the currently selected tab. */
+/**
+ * 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. */
+/**
+ * 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;
@@ -28,42 +73,112 @@ NS_ASSUME_NONNULL_BEGIN
 
 @end
 
-/** Bundles a navigation state change together with metadata about the selection context. */
+/**
+ * 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. */
+/**
+ * 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. */
+/**
+ * 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. */
+/**
+ * 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;
+/**
+ * Origin (actor) that requested this transition.
+ */
+@property (nonatomic, readonly) RNSTabsActionOrigin actionOrigin;
 
 - (instancetype)initWithNavState:(nonnull RNSTabsNavigationState *)navState
                       isRepeated:(BOOL)isRepeated
        hasTriggeredSpecialEffect:(BOOL)hasTriggeredSpecialEffect
-                  isNativeAction:(BOOL)isNativeAction;
+                    actionOrigin:(RNSTabsActionOrigin)actionOrigin;
 
 @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
-};
+/**
+ * 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>
 
-/** 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,
-};
+@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

@@ -26,18 +26,51 @@
 
 @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
-                  isNativeAction:(BOOL)isNativeAction
+                    actionOrigin:(RNSTabsActionOrigin)actionOrigin
 {
   if (self = [super init]) {
     _navState = navState;
     _isRepeated = isRepeated;
     _hasTriggeredSpecialEffect = hasTriggeredSpecialEffect;
-    _isNativeAction = isNativeAction;
+    _actionOrigin = actionOrigin;
   }
   return self;
 }

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/lib/commonjs/components/gamma/stack/header/StackHeaderConfig.android.js

@@ -27,13 +27,25 @@ function StackHeaderConfig(props) {
     centerSubview,
     trailingSubview,
     backButtonIcon,
+    scrollFlagScroll,
+    scrollFlagEnterAlways,
+    scrollFlagEnterAlwaysCollapsed,
+    scrollFlagExitUntilCollapsed,
+    scrollFlagSnap,
     ...filteredAndroidProps
   } = android ?? {};
   const backButtonIconProps = parseBackButtonIconToNativeProps(backButtonIcon);
+  const scrollFlagProps = resolveScrollFlags(filteredAndroidProps.type, {
+    scrollFlagScroll,
+    scrollFlagEnterAlways,
+    scrollFlagEnterAlwaysCollapsed,
+    scrollFlagExitUntilCollapsed,
+    scrollFlagSnap
+  });
   return /*#__PURE__*/_react.default.createElement(_StackHeaderConfigAndroidNativeComponent.default, _extends({
     collapsable: false,
     style: _reactNative.StyleSheet.absoluteFill
-  }, baseProps, filteredAndroidProps, backButtonIconProps), backgroundSubview && /*#__PURE__*/_react.default.createElement(_StackHeaderSubview.default, {
+  }, baseProps, filteredAndroidProps, backButtonIconProps, scrollFlagProps), backgroundSubview && /*#__PURE__*/_react.default.createElement(_StackHeaderSubview.default, {
     type: "background",
     collapseMode: backgroundSubview.collapseMode
   }, backgroundSubview.Component), leadingSubview && /*#__PURE__*/_react.default.createElement(_StackHeaderSubview.default, {
@@ -64,5 +76,38 @@ function parseBackButtonIconToNativeProps(icon) {
     throw new Error('[RNScreens] Incorrect icon format for Android. You must provide `imageSource` or `drawableResource`.');
   }
 }
+const SCROLL_FLAG_DEFAULTS_BY_TYPE = {
+  small: {
+    scrollFlagScroll: false,
+    scrollFlagEnterAlways: false,
+    scrollFlagEnterAlwaysCollapsed: false,
+    scrollFlagExitUntilCollapsed: false,
+    scrollFlagSnap: false
+  },
+  medium: {
+    scrollFlagScroll: true,
+    scrollFlagEnterAlways: false,
+    scrollFlagEnterAlwaysCollapsed: false,
+    scrollFlagExitUntilCollapsed: true,
+    scrollFlagSnap: true
+  },
+  large: {
+    scrollFlagScroll: true,
+    scrollFlagEnterAlways: false,
+    scrollFlagEnterAlwaysCollapsed: false,
+    scrollFlagExitUntilCollapsed: true,
+    scrollFlagSnap: true
+  }
+};
+function resolveScrollFlags(type, overrides) {
+  const defaults = SCROLL_FLAG_DEFAULTS_BY_TYPE[type ?? 'small'];
+  return {
+    scrollFlagScroll: overrides.scrollFlagScroll ?? defaults.scrollFlagScroll,
+    scrollFlagEnterAlways: overrides.scrollFlagEnterAlways ?? defaults.scrollFlagEnterAlways,
+    scrollFlagEnterAlwaysCollapsed: overrides.scrollFlagEnterAlwaysCollapsed ?? defaults.scrollFlagEnterAlwaysCollapsed,
+    scrollFlagExitUntilCollapsed: overrides.scrollFlagExitUntilCollapsed ?? defaults.scrollFlagExitUntilCollapsed,
+    scrollFlagSnap: overrides.scrollFlagSnap ?? defaults.scrollFlagSnap
+  };
+}
 var _default = exports.default = StackHeaderConfig;
 //# sourceMappingURL=StackHeaderConfig.android.js.map