feat(Tabs): special effects refactor (#3440)

kligarski · web-flow · commit 257a53c17ee8 · 2025-12-03T10:09:45.000+01:00
## Description Refactors special effects on both platforms: - fixes disabling `popToRoot` on iOS 26, - fixes special effects running on regular (not repeated) tab change on Android, - adds `repeatedSelectionHandledBySpecialEffect` to `NativeFocusChangeEvent` on both platforms (now the event is sent on every tab press with appropriate flag value), - adds support for `specialEffects` on Paper+iOS. Closes software-mansion/react-native-screens-labs#579. Closes software-mansion/react-native-screens-labs#574. ### Recordings Pay attention to logs. #### Android https://github.com/user-attachments/assets/54887d06-f6fa-4bb9-a9bd-2642a8af31b2 #### iOS https://github.com/user-attachments/assets/c06505dc-e4e6-44b9-90f3-5d18c3345c01 ### Native pop to root on iOS 26 UIKit natively has "pop to root" effect in `UITabBarController` but prior to iOS 26, it worked only when `UINavigationController` was direct child of `UITabBarController`. In `screens`, `RNSTabBarController` has `RNSTabsScreenViewController` children view controllers and `RNSScreenStack` can be a child VC of `RNSTabsScreenViewController`. This prevents native effect from working on iOS versions prior to 26. Starting from iOS 26, `UITabBarController` also detects nested `UINavigationController`s. This interaction happens when we return `true` from `tabBarController:shouldSelectViewController:` delegate method. This would work for natively-driven tabs but for controlled tabs, we need to return `false` to prevent tab change on the native side -> that's why we decided to use only our own implementation and disable native effect by always returning `false` from `tabBarController:shouldSelectViewController:` on repeated tab selection. ## Changes - handle `specialEffects` prop on iOS, Paper, - add `repeatedSelectionHandledBySpecialEffect` to `NativeFocusChangeEvent` - update docs (move special effects and freeze to general section, clean up) - return `false` from `tabBarController:(UITabBarController *)tabBarController shouldSelectViewController:(UIViewController *)viewController` on repeated tab selection on iOS (disables native pop to root interaction which is available starting from iOS 26) - prevent running `onItemSelectedListener` after menu selection on Android (it runs on click for the first time and it would run for the second time after update from JS which would activate special effect erroneously) ## Test code and steps to reproduce Run `TestBottomTabs`. Test repeated selection with different special effects enabled on `Tab4`. Make sure that special effects don't run when changing from other tab to `Tab4`. ## Checklist - [x] Included code example that can be used to test this change - [x] Updated TS types - [x] Updated documentation - [x] Ensured that CI passes
diff --git a/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/TabsHost.kt b/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/TabsHost.kt
@@ -252,10 +252,14 @@ class TabsHost(
         bottomNavigationView.setOnItemSelectedListener { item ->
             RNSLog.d(TAG, "Item selected $item")
             val fragment = getFragmentForMenuItemId(item.itemId)
-            if (fragment != currentFocusedTab || !specialEffectsHandler.handleRepeatedTabSelection()) {
-                val tabKey = fragment?.tabScreen?.tabKey ?: "undefined"
-                eventEmitter.emitOnNativeFocusChange(tabKey)
-            }
+            val repeatedSelectionHandledBySpecialEffect =
+                if (fragment == currentFocusedTab) specialEffectsHandler.handleRepeatedTabSelection() else false
+            val tabKey = fragment?.tabScreen?.tabKey ?: "undefined"
+            eventEmitter.emitOnNativeFocusChange(
+                tabKey,
+                item.itemId,
+                repeatedSelectionHandledBySpecialEffect,
+            )
             true
         }
     }
@@ -352,8 +356,11 @@ class TabsHost(
 
         appearanceCoordinator.updateTabAppearance(this)
 
-        bottomNavigationView.selectedItemId =
+        val selectedTabScreenFragmentId =
             checkNotNull(getSelectedTabScreenFragmentId()) { "[RNScreens] A single selected tab must be present" }
+        if (bottomNavigationView.selectedItemId != selectedTabScreenFragmentId) {
+            bottomNavigationView.selectedItemId = selectedTabScreenFragmentId
+        }
 
         post {
             refreshLayout()
diff --git a/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/TabsHostEventEmitter.kt b/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/TabsHostEventEmitter.kt
@@ -8,7 +8,19 @@ internal class TabsHostEventEmitter(
     reactContext: ReactContext,
     viewTag: Int,
 ) : BaseEventEmitter(reactContext, viewTag) {
-    fun emitOnNativeFocusChange(tabKey: String) {
-        reactEventDispatcher.dispatchEvent(TabsHostNativeFocusChangeEvent(surfaceId, viewTag, tabKey))
+    fun emitOnNativeFocusChange(
+        tabKey: String,
+        tabNumber: Int,
+        repeatedSelectionHandledBySpecialEffect: Boolean,
+    ) {
+        reactEventDispatcher.dispatchEvent(
+            TabsHostNativeFocusChangeEvent(
+                surfaceId,
+                viewTag,
+                tabKey,
+                tabNumber,
+                repeatedSelectionHandledBySpecialEffect,
+            ),
+        )
     }
 }
diff --git a/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/event/TabsHostNativeFocusChangeEvent.kt b/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/event/TabsHostNativeFocusChangeEvent.kt
@@ -9,25 +9,36 @@ class TabsHostNativeFocusChangeEvent(
     surfaceId: Int,
     viewId: Int,
     val tabKey: String,
+    val tabNumber: Int,
+    val repeatedSelectionHandledBySpecialEffect: Boolean,
 ) : Event<TabScreenDidAppearEvent>(surfaceId, viewId),
     NamingAwareEventType {
     override fun getEventName() = EVENT_NAME
 
     override fun getEventRegistrationName() = EVENT_REGISTRATION_NAME
 
-    // All events for a given view can be coalesced.
-    override fun getCoalescingKey(): Short = 0
+    // If the user taps currently selected tab 2 times and e.g. scroll to top effect can run,
+    // we should send 2 events [(tabKey, true), (tabKey, false)]. We don't want them to be coalesced
+    // as we would lose information about activation of special effect. That's why we take into
+    // account `repeatedSelectionHandledBySpecialEffect` for coalescingKey.
+    override fun getCoalescingKey(): Short = (tabNumber * 10 + if (repeatedSelectionHandledBySpecialEffect) 1 else 0).toShort()
 
     override fun getEventData(): WritableMap? =
         Arguments.createMap().apply {
             putString(EVENT_KEY_TAB_KEY, tabKey)
+            putBoolean(
+                EVENT_KEY_REPEATED_SELECTION_HANDLED_BY_SPECIAL_EFFECT,
+                repeatedSelectionHandledBySpecialEffect,
+            )
         }
 
     companion object : NamingAwareEventType {
         const val EVENT_NAME = "topNativeFocusChange"
         const val EVENT_REGISTRATION_NAME = "onNativeFocusChange"
 
         private const val EVENT_KEY_TAB_KEY = "tabKey"
+        private const val EVENT_KEY_REPEATED_SELECTION_HANDLED_BY_SPECIAL_EFFECT =
+            "repeatedSelectionHandledBySpecialEffect"
 
         override fun getEventName() = EVENT_NAME
 
diff --git a/ios/bottom-tabs/host/RNSBottomTabsHostComponentView.h b/ios/bottom-tabs/host/RNSBottomTabsHostComponentView.h
@@ -72,7 +72,8 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (nonnull RNSBottomTabsHostEventEmitter *)reactEventEmitter;
 
-- (BOOL)emitOnNativeFocusChangeRequestSelectedTabScreen:(nonnull RNSBottomTabsScreenComponentView *)tabScreen;
+- (BOOL)emitOnNativeFocusChangeRequestSelectedTabScreen:(nonnull RNSBottomTabsScreenComponentView *)tabScreen
+                repeatedSelectionHandledBySpecialEffect:(BOOL)repeatedSelectionHandledBySpecialEffect;
 
 #if !RCT_NEW_ARCH_ENABLED
 #pragma mark - LEGACY Event blocks
diff --git a/ios/bottom-tabs/host/RNSBottomTabsHostComponentView.mm b/ios/bottom-tabs/host/RNSBottomTabsHostComponentView.mm
@@ -261,9 +261,13 @@ - (nonnull RNSBottomTabsHostEventEmitter *)reactEventEmitter
   return _reactEventEmitter;
 }
 
-- (BOOL)emitOnNativeFocusChangeRequestSelectedTabScreen:(RNSBottomTabsScreenComponentView *)tabScreen
+- (BOOL)emitOnNativeFocusChangeRequestSelectedTabScreen:(nonnull RNSBottomTabsScreenComponentView *)tabScreen
+                repeatedSelectionHandledBySpecialEffect:(BOOL)repeatedSelectionHandledBySpecialEffect
 {
-  return [_reactEventEmitter emitOnNativeFocusChange:OnNativeFocusChangePayload{.tabKey = tabScreen.tabKey}];
+  return [_reactEventEmitter
+      emitOnNativeFocusChange:OnNativeFocusChangePayload{
+                                  .tabKey = tabScreen.tabKey,
+                                  .repeatedSelectionHandledBySpecialEffect = repeatedSelectionHandledBySpecialEffect}];
 }
 
 #pragma mark - RCTComponentViewProtocol
diff --git a/ios/bottom-tabs/host/RNSBottomTabsHostEventEmitter.h b/ios/bottom-tabs/host/RNSBottomTabsHostEventEmitter.h
@@ -18,10 +18,12 @@ NS_ASSUME_NONNULL_BEGIN
 #if defined(__cplusplus)
 struct OnNativeFocusChangePayload {
   NSString *_Nonnull tabKey;
+  BOOL repeatedSelectionHandledBySpecialEffect;
 };
 #else
 typedef struct {
   NSString *_Nonnull tabKey;
+  BOOL repeatedSelectionHandledBySpecialEffect;
 } OnNativeFocusChangePayload;
 #endif
 
diff --git a/ios/bottom-tabs/host/RNSBottomTabsHostEventEmitter.mm b/ios/bottom-tabs/host/RNSBottomTabsHostEventEmitter.mm
@@ -37,15 +37,20 @@ - (BOOL)emitOnNativeFocusChange:(OnNativeFocusChangePayload)payload
 {
 #if RCT_NEW_ARCH_ENABLED
   if (_reactEventEmitter != nullptr) {
-    _reactEventEmitter->onNativeFocusChange({.tabKey = RCTStringFromNSString(payload.tabKey)});
+    _reactEventEmitter->onNativeFocusChange(
+        {.tabKey = RCTStringFromNSString(payload.tabKey),
+         .repeatedSelectionHandledBySpecialEffect = payload.repeatedSelectionHandledBySpecialEffect});
     return YES;
   } else {
     RCTLogWarn(@"[RNScreens] Skipped OnNativeFocusChange event emission due to nullish emitter");
     return NO;
   }
 #else
   if (self.onNativeFocusChange) {
-    self.onNativeFocusChange(@{@"tabKey" : payload.tabKey});
+    self.onNativeFocusChange(@{
+      @"tabKey" : payload.tabKey,
+      @"repeatedSelectionHandledBySpecialEffect" : @(payload.repeatedSelectionHandledBySpecialEffect)
+    });
     return YES;
   } else {
     RCTLogWarn(@"[RNScreens] Skipped OnNativeFocusChange event emission due to nullish emitter");
diff --git a/ios/bottom-tabs/host/RNSTabBarControllerDelegate.mm b/ios/bottom-tabs/host/RNSTabBarControllerDelegate.mm
@@ -32,26 +32,20 @@ - (BOOL)tabBarController:(UITabBarController *)tabBarController
   }
 #endif // !TARGET_OS_TV
 
-  bool repeatedSelectionHandledNatively = false;
+  // TODO: handle enforcing orientation with natively-driven tabs
 
   // Detect repeated selection and inform tabScreenController
-  if ([tabBarCtrl selectedViewController] == tabScreenCtrl) {
-    repeatedSelectionHandledNatively = [tabScreenCtrl tabScreenSelectedRepeatedly];
-  }
-
-  // TODO: send an event with information about event being handled natively
-  if (!repeatedSelectionHandledNatively) {
-    [tabBarCtrl.tabsHostComponentView
-        emitOnNativeFocusChangeRequestSelectedTabScreen:tabScreenCtrl.tabScreenComponentView];
+  BOOL repeatedSelection = [tabBarCtrl selectedViewController] == tabScreenCtrl;
+  BOOL repeatedSelectionHandledBySpecialEffect =
+      repeatedSelection ? [tabScreenCtrl tabScreenSelectedRepeatedly] : false;
 
-    // TODO: handle overrideScrollViewBehaviorInFirstDescendantChainIfNeeded for natively-driven tabs
-    return ![self shouldPreventNativeTabChangeWithinTabBarController:tabBarCtrl];
-  }
-
-  // TODO: handle enforcing orientation with natively-driven tabs
+  [tabBarCtrl.tabsHostComponentView
+      emitOnNativeFocusChangeRequestSelectedTabScreen:tabScreenCtrl.tabScreenComponentView
+              repeatedSelectionHandledBySpecialEffect:repeatedSelectionHandledBySpecialEffect];
 
-  // As we're selecting the same controller, returning both true and false works here.
-  return true;
+  // On repeated selection we return false to prevent native *pop to root* effect that works only starting from iOS 26
+  // and interferes with our implementation (which is necessary for controlled tabs).
+  return repeatedSelection ? false : ![self shouldPreventNativeTabChangeWithinTabBarController:tabBarCtrl];
 }
 
 - (void)tabBarController:(UITabBarController *)tabBarController
diff --git a/ios/bottom-tabs/screen/RNSBottomTabsScreenComponentView.mm b/ios/bottom-tabs/screen/RNSBottomTabsScreenComponentView.mm
@@ -649,6 +649,30 @@ - (void)setSystemItem:(RNSBottomTabsScreenSystemItem)systemItem
   _tabBarItemNeedsRecreation = YES;
 }
 
+- (void)setSpecialEffects:(NSDictionary *)specialEffects
+{
+  if (specialEffects == nil || specialEffects[@"repeatedTabSelection"] == nil ||
+      ![specialEffects[@"repeatedTabSelection"] isKindOfClass:[NSDictionary class]]) {
+    _shouldUseRepeatedTabSelectionPopToRootSpecialEffect = YES;
+    _shouldUseRepeatedTabSelectionScrollToTopSpecialEffect = YES;
+    return;
+  }
+
+  NSDictionary *repeatedTabSelection = specialEffects[@"repeatedTabSelection"];
+
+  if (repeatedTabSelection[@"popToRoot"] != nil) {
+    _shouldUseRepeatedTabSelectionPopToRootSpecialEffect = [RCTConvert BOOL:repeatedTabSelection[@"popToRoot"]];
+  } else {
+    _shouldUseRepeatedTabSelectionPopToRootSpecialEffect = YES;
+  }
+
+  if (repeatedTabSelection[@"scrollToTop"] != nil) {
+    _shouldUseRepeatedTabSelectionScrollToTopSpecialEffect = [RCTConvert BOOL:repeatedTabSelection[@"scrollToTop"]];
+  } else {
+    _shouldUseRepeatedTabSelectionScrollToTopSpecialEffect = YES;
+  }
+}
+
 - (void)setOrientation:(RNSOrientation)orientation
 {
   _orientation = orientation;
diff --git a/ios/bottom-tabs/screen/RNSBottomTabsScreenComponentViewManager.mm b/ios/bottom-tabs/screen/RNSBottomTabsScreenComponentViewManager.mm
@@ -33,9 +33,6 @@ - (UIView *)view
 RCT_EXPORT_VIEW_PROPERTY(selectedIconImageSource, RCTImageSource);
 RCT_EXPORT_VIEW_PROPERTY(selectedIconSfSymbolName, NSString);
 
-RCT_EXPORT_VIEW_PROPERTY(shouldUseRepeatedTabSelectionPopToRootSpecialEffect, BOOL);
-RCT_EXPORT_VIEW_PROPERTY(shouldUseRepeatedTabSelectionScrollToTopSpecialEffect, BOOL);
-
 RCT_EXPORT_VIEW_PROPERTY(overrideScrollViewContentInsetAdjustmentBehavior, BOOL);
 
 RCT_EXPORT_VIEW_PROPERTY(bottomScrollEdgeEffect, RNSScrollEdgeEffect);
@@ -47,6 +44,8 @@ - (UIView *)view
 
 RCT_EXPORT_VIEW_PROPERTY(systemItem, RNSBottomTabsScreenSystemItem);
 
+RCT_EXPORT_VIEW_PROPERTY(specialEffects, NSDictionary);
+
 RCT_EXPORT_VIEW_PROPERTY(onWillAppear, RCTDirectEventBlock);
 RCT_EXPORT_VIEW_PROPERTY(onWillDisappear, RCTDirectEventBlock);
 RCT_EXPORT_VIEW_PROPERTY(onDidAppear, RCTDirectEventBlock);
diff --git a/src/components/bottom-tabs/BottomTabs.types.ts b/src/components/bottom-tabs/BottomTabs.types.ts
@@ -13,6 +13,7 @@ export type BottomAccessoryFn = (
 
 export type NativeFocusChangeEvent = {
   tabKey: string;
+  repeatedSelectionHandledBySpecialEffect: boolean;
 };
 
 // Android-specific
@@ -49,11 +50,13 @@ export interface BottomTabsProps extends ViewProps {
    * @summary Hides the tab bar.
    *
    * @default false
+   *
+   * @platform android, ios
    */
   tabBarHidden?: boolean;
   // #endregion General
 
-  // #region Android-only appearance
+  // #region Android-only
   /**
    * @summary Specifies the background color for the entire tab bar.
    *
@@ -157,12 +160,13 @@ export interface BottomTabsProps extends ViewProps {
    * @see {@link https://github.com/material-components/material-components-android/blob/master/docs/components/BottomNavigation.md#making-navigation-bar-accessible|Material Components documentation}
    *
    * @default auto
+   *
    * @platform android
    */
   tabBarItemLabelVisibilityMode?: TabBarItemLabelVisibilityMode;
-  // #endregion Android-only appearance
+  // #endregion Android-only
 
-  // #region iOS-only appearance
+  // #region iOS-only
   /**
    * @summary Specifies the color used for selected tab's text and icon color.
    *
@@ -249,7 +253,7 @@ export interface BottomTabsProps extends ViewProps {
    * @supported iOS 18 or higher
    */
   tabBarControllerMode?: TabBarControllerMode;
-  // #endregion iOS-only appearance
+  // #endregion iOS-only
 
   // #region Experimental support
   /**
diff --git a/src/components/bottom-tabs/BottomTabsScreen.types.ts b/src/components/bottom-tabs/BottomTabsScreen.types.ts
diff --git a/src/fabric/bottom-tabs/BottomTabsNativeComponent.ts b/src/fabric/bottom-tabs/BottomTabsNativeComponent.ts

Original file line number	Diff line number	Diff line change
`@@ -261,9 +261,13 @@ - (nonnull RNSBottomTabsHostEventEmitter *)reactEventEmitter`
`261`	`261`	`return _reactEventEmitter;`
`262`	`262`	`}`
`263`	`263`
`264`		`-- (BOOL)emitOnNativeFocusChangeRequestSelectedTabScreen:(RNSBottomTabsScreenComponentView *)tabScreen`
	`264`	`+- (BOOL)emitOnNativeFocusChangeRequestSelectedTabScreen:(nonnull RNSBottomTabsScreenComponentView *)tabScreen`
	`265`	`+ repeatedSelectionHandledBySpecialEffect:(BOOL)repeatedSelectionHandledBySpecialEffect`
`265`	`266`	`{`
`266`		`- return [_reactEventEmitter emitOnNativeFocusChange:OnNativeFocusChangePayload{.tabKey = tabScreen.tabKey}];`
	`267`	`+ return [_reactEventEmitter`
	`268`	`+ emitOnNativeFocusChange:OnNativeFocusChangePayload{`
	`269`	`+ .tabKey = tabScreen.tabKey,`
	`270`	`+ .repeatedSelectionHandledBySpecialEffect = repeatedSelectionHandledBySpecialEffect}];`
`267`	`271`	`}`
`268`	`272`
`269`	`273`	`#pragma mark - RCTComponentViewProtocol`