refactor(tabs): rename onTabChange event to onTabSelected (#3789)

## Description

Renames the `onTabChange` event prop to `onTabSelected` across the
entire tabs stack, and aligns the imperative tab-switching API to use
"select" nomenclature as well. The previous name was ambiguous —
"change" describes the act of switching, while "selected" more precisely
communicates the semantics: a tab was chosen/selected by the user or
programmatically.

## Changes

- **Codegen specs** (`TabsHostIOSNativeComponent`,
`TabsHostAndroidNativeComponent`): `onTabChange` → `onTabSelected`,
`TabChangeEvent` → `TabSelectedEvent`
- **TypeScript public API** (`TabsHost.types`, `useTabsHost`,
`TabsHost.ios`, `TabsHost.android`): prop, callback variable, and type
renamed accordingly
- **Android**: `TabsHostTabChangeEvent` → `TabsHostTabSelectedEvent`
(file renamed), native event strings `topTabChange` → `topTabSelected` /
`onTabChange` → `onTabSelected`, `TabChangeOp` → `TabSelectOp`,
`emitOnTabChangeEvent` → `emitOnTabSelectedEvent`
- **iOS**: `OnTabChangePayload` → `OnTabSelectedPayload`,
`emitOnTabChange:` → `emitOnTabSelected:`,
`shouldPreventNativeTabChange` → `shouldPreventNativeTabSelection`
- **Example app — imperative API & types** (`TabsContainer`,
`TabsContainer.types`, `TabsNavigationContext`, reducer, index, test
files):
- `ChangeTabMethod` → `SelectTabMethod`, `changeTabTo` → `selectTab`,
`tabChangeActionMethod` → `selectTabMethod`
- `TabsNavigationActionChangeTab` → `TabsNavigationActionSelectTab`,
`TabsNavigationActionNativeChangeTab` →
`TabsNavigationActionNativeSelectTab`
- Action type literals `'tab-change'` → `'tab-select'`,
`'native-tab-change'` → `'native-tab-select'`
- Reducer handlers `tabsActionChangeTabHandler` →
`tabsActionSelectTabHandler`, `tabsActionNativeChangeTabHandler` →
`tabsActionNativeSelectTabHandler`
- Updated usages in test files (`test-tabs-more-navigation-controller`,
`test-tabs-simple-nav`)

## Test plan

Trigger tab selection in the example app and verify the `onTabSelected`
callback fires correctly on both iOS and Android.

## Checklist

- [ ] Included code example that can be used to test this change.
- [ ] Updated / created local changelog entries in relevant test files.
- [ ] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [x] For API changes, updated relevant public types.
- [ ] Ensured that CI passes

---------

Co-authored-by: Claude Sonnet 4.6 <[email protected]>

Author: kkafar

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

@@ -253,12 +253,12 @@ internal class TabsContainer(
         }
 
         check(hasPendingOperation) { "[RNScreens] Attempt to update container with empty state and no pending update" }
-        check(pendingOperation is TabChangeOp)
-        val tabChangeOp = pendingOperation as TabChangeOp
+        check(pendingOperation is TabSelectOp)
+        val tabSelectOp = pendingOperation as TabSelectOp
 
         val nextSelectedMenuItemId =
-            checkNotNull(getMenuItemIdForFragment(requireFragmentForScreenKey(tabChangeOp.navState.selectedKey))) {
-                "[RNScreens] Failed to find Menu Item for screenKey: ${tabChangeOp.navState.selectedKey}"
+            checkNotNull(getMenuItemIdForFragment(requireFragmentForScreenKey(tabSelectOp.navState.selectedKey))) {
+                "[RNScreens] Failed to find Menu Item for screenKey: ${tabSelectOp.navState.selectedKey}"
             }
 
         if (bottomNavigationView.selectedItemId != nextSelectedMenuItemId || navState.isEmpty()) {
@@ -373,8 +373,7 @@ internal class TabsContainer(
         appearanceCoordinator.updateTabAppearance(themedContext, this)
     }
 
-    private fun getFragmentForMenuItemId(itemId: Int): TabsScreenFragment? =
-        tabsModel.getOrNull(fragmentIndexForMenuItemId(itemId))
+    private fun getFragmentForMenuItemId(itemId: Int): TabsScreenFragment? = tabsModel.getOrNull(fragmentIndexForMenuItemId(itemId))
 
     private fun getMenuItemIdForFragment(tabsScreenFragment: TabsScreenFragment): Int? =
         tabsModel.indexOfFirst { it === tabsScreenFragment }.takeIf { it != -1 }?.let {
@@ -396,11 +395,9 @@ internal class TabsContainer(
 
     override fun getResolvedUiNightMode() = colorSchemeCoordinator.getResolvedUiNightMode()
 
-    override fun addColorSchemeListener(listener: ColorSchemeListener) =
-        colorSchemeCoordinator.addColorSchemeListener(listener)
+    override fun addColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.addColorSchemeListener(listener)
 
-    override fun removeColorSchemeListener(listener: ColorSchemeListener) =
-        colorSchemeCoordinator.removeColorSchemeListener(listener)
+    override fun removeColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.removeColorSchemeListener(listener)
 
     override fun onAppearanceChanged(tabsScreen: TabsScreen) {
         if (selectedTab.tabsScreen === tabsScreen) {
@@ -427,11 +424,10 @@ internal class TabsContainer(
     override fun getFragmentForTabsScreen(tabsScreen: TabsScreen): TabsScreenFragment? =
         tabsModel.find {
             it.tabsScreen ===
-                    tabsScreen
+                tabsScreen
         }
 
-    private fun getFragmentForScreenKey(screenKey: String): TabsScreenFragment? =
-        tabsModel.find { it.requireScreenKey == screenKey }
+    private fun getFragmentForScreenKey(screenKey: String): TabsScreenFragment? = tabsModel.find { it.requireScreenKey == screenKey }
 
     private fun requireFragmentForScreenKey(screenKey: String): TabsScreenFragment =
         checkNotNull(getFragmentForScreenKey(screenKey)) {
@@ -490,8 +486,7 @@ internal class TabsContainer(
         }
     }
 
-    override fun getInterfaceInsets(): EdgeInsets =
-        EdgeInsets(0.0f, 0.0f, 0.0f, bottomNavigationView.height.toFloat())
+    override fun getInterfaceInsets(): EdgeInsets = EdgeInsets(0.0f, 0.0f, 0.0f, bottomNavigationView.height.toFloat())
 
     private fun getInsetsForBottomNavigationView(insets: WindowInsets): WindowInsets? {
         if (tabBarRespectsIMEInsets) {
@@ -528,8 +523,7 @@ internal class TabsContainerInvalidationFlags(
     var isNavigationMenuAppearanceInvalidated: Boolean = false,
     var isNavigationMenuStructureInvalidated: Boolean = false,
 ) {
-    internal fun any(): Boolean =
-        isSelectedTabInvalidated || isNavigationMenuAppearanceInvalidated || isNavigationMenuStructureInvalidated
+    internal fun any(): Boolean = isSelectedTabInvalidated || isNavigationMenuAppearanceInvalidated || isNavigationMenuStructureInvalidated
 
     internal fun invalidateAll() {
         isSelectedTabInvalidated = true

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

@@ -2,6 +2,6 @@ package com.swmansion.rnscreens.gamma.tabs.container
 
 internal sealed class TabsContainerOp
 
-internal data class TabChangeOp(
+internal data class TabSelectOp(
     val navState: TabsNavState,
 ) : TabsContainerOp()

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

@@ -12,7 +12,7 @@ import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.UIManagerHelper
 import com.swmansion.rnscreens.gamma.common.colorscheme.ColorScheme
 import com.swmansion.rnscreens.gamma.helpers.getFabricUIManagerNotNull
-import com.swmansion.rnscreens.gamma.tabs.container.TabChangeOp
+import com.swmansion.rnscreens.gamma.tabs.container.TabSelectOp
 import com.swmansion.rnscreens.gamma.tabs.container.TabsContainer
 import com.swmansion.rnscreens.gamma.tabs.container.TabsContainerDelegate
 import com.swmansion.rnscreens.gamma.tabs.container.TabsNavState
@@ -108,7 +108,7 @@ class TabsHost(
 
     internal fun updateJSNavState(navState: TabsNavState) {
         jsNavState = navState
-        container.setContainerOperation(TabChangeOp(jsNavState.copy()))
+        container.setContainerOperation(TabSelectOp(jsNavState.copy()))
     }
 
     private val layoutCallback =
@@ -158,7 +158,7 @@ class TabsHost(
         hasTriggeredSpecialEffect: Boolean,
         isNativeAction: Boolean,
     ) {
-        eventEmitter.emitOnTabChangeEvent(
+        eventEmitter.emitOnTabSelectedEvent(
             navState.selectedKey,
             navState.provenance,
             isRepeated,

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

@@ -2,21 +2,21 @@ package com.swmansion.rnscreens.gamma.tabs.host
 
 import com.facebook.react.bridge.ReactContext
 import com.swmansion.rnscreens.gamma.common.event.BaseEventEmitter
-import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabChangeEvent
+import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabSelectedEvent
 
 internal class TabsHostEventEmitter(
     reactContext: ReactContext,
     viewTag: Int,
 ) : BaseEventEmitter(reactContext, viewTag) {
-    fun emitOnTabChangeEvent(
+    fun emitOnTabSelectedEvent(
         selectedScreenKey: String,
         provenance: Int,
         isRepeated: Boolean,
         hasTriggeredSpecialEffect: Boolean,
         isNativeAction: Boolean,
     ) {
         reactEventDispatcher.dispatchEvent(
-            TabsHostTabChangeEvent(
+            TabsHostTabSelectedEvent(
                 surfaceId,
                 viewTag,
                 selectedScreenKey,

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

@@ -12,7 +12,7 @@ import com.facebook.react.viewmanagers.RNSTabsHostAndroidManagerInterface
 import com.swmansion.rnscreens.gamma.common.colorscheme.ColorScheme
 import com.swmansion.rnscreens.gamma.helpers.makeEventRegistrationInfo
 import com.swmansion.rnscreens.gamma.tabs.container.TabsNavState
-import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabChangeEvent
+import com.swmansion.rnscreens.gamma.tabs.host.event.TabsHostTabSelectedEvent
 import com.swmansion.rnscreens.gamma.tabs.screen.TabsScreen
 
 @ReactModule(name = TabsHostViewManager.REACT_CLASS)
@@ -57,7 +57,7 @@ class TabsHostViewManager :
 
     override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any> =
         mutableMapOf(
-            makeEventRegistrationInfo(TabsHostTabChangeEvent),
+            makeEventRegistrationInfo(TabsHostTabSelectedEvent),
         )
 
     override fun addEventEmitters(

…abs/host/event/TabsHostTabChangeEvent.kt …s/host/event/TabsHostTabSelectedEvent.ktandroid/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/event/TabsHostTabChangeEvent.kt renamed to android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/event/TabsHostTabSelectedEvent.kt android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/event/TabsHostTabChangeEvent.kt renamed to android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/event/TabsHostTabSelectedEvent.kt

@@ -5,15 +5,15 @@ import com.facebook.react.bridge.WritableMap
 import com.facebook.react.uimanager.events.Event
 import com.swmansion.rnscreens.gamma.common.event.NamingAwareEventType
 
-class TabsHostTabChangeEvent(
+class TabsHostTabSelectedEvent(
     surfaceId: Int,
     viewId: Int,
     val selectedScreenKey: String,
     val provenance: Int,
     val isRepeated: Boolean,
     val hasTriggeredSpecialEffect: Boolean,
     val isNativeAction: Boolean,
-) : Event<TabsHostTabChangeEvent>(surfaceId, viewId),
+) : Event<TabsHostTabSelectedEvent>(surfaceId, viewId),
     NamingAwareEventType {
     override fun getEventName() = EVENT_NAME
 
@@ -32,8 +32,8 @@ class TabsHostTabChangeEvent(
         }
 
     companion object : NamingAwareEventType {
-        const val EVENT_NAME = "topTabChange"
-        const val EVENT_REGISTRATION_NAME = "onTabChange"
+        const val EVENT_NAME = "topTabSelected"
+        const val EVENT_REGISTRATION_NAME = "onTabSelected"
 
         private const val EK_SELECTED_KEY = "selectedScreenKey"
         private const val EK_PROVENANCE = "provenance"

apps/src/shared/gamma/containers/tabs/TabsContainer.tsx

@@ -2,13 +2,13 @@ import React from 'react';
 import { I18nManager, Platform, type NativeSyntheticEvent } from 'react-native';
 import {
   SCREEN_KEY_MORE_NAV_CTRL,
-  type TabChangeEvent,
+  type TabSelectedEvent,
   Tabs,
   type TabsHostNavState,
 } from 'react-native-screens';
 import { SafeAreaView, type SafeAreaViewProps } from 'react-native-screens/experimental'
 import type {
-  ChangeTabMethod,
+  SelectTabMethod,
   TabRoute,
   TabRouteConfig,
   TabRouteOptions,
@@ -33,7 +33,7 @@ export function TabsContainer(props: TabsContainerProps) {
     routeConfigs,
     initialFocusedName,
     experimentalControlNavigationStateInJS,
-    onTabChange,
+    onTabSelected,
     ...restProps
   } = props;
 
@@ -57,14 +57,14 @@ export function TabsContainer(props: TabsContainerProps) {
 
   const hostNavState = useTabsHostNavState(tabsNavState);
 
-  const onTabChangeCallback = React.useCallback(
-    (event: NativeSyntheticEvent<TabChangeEvent>) => {
+  const onTabSelectedCallback = React.useCallback(
+    (event: NativeSyntheticEvent<TabSelectedEvent>) => {
       // First call user provided callback
-      onTabChange?.(event);
+      onTabSelected?.(event);
 
       // Perform our logic
       const screenKey = event.nativeEvent.selectedScreenKey;
-      console.log(`[Tabs] onTabChangeCallback: ${screenKey}`);
+      console.log(`[Tabs] onTabSelectedCallback: ${screenKey}`);
 
       // Please note that the `useTransition` hook can not be used here,
       // because it intruduces additional renders, which lead
@@ -73,18 +73,18 @@ export function TabsContainer(props: TabsContainerProps) {
       React.startTransition(() => {
         RNSLog.info(`Starting transition to ${screenKey}`);
         dispatch({
-          type: 'native-tab-change',
+          type: 'native-tab-select',
           routeKey: screenKey,
           nativeEvent: event.nativeEvent,
         });
       });
     },
-    [onTabChange],
+    [onTabSelected],
   );
 
-  const tabChangeActionMethod: ChangeTabMethod = React.useCallback(
+  const selectTabMethod: SelectTabMethod = React.useCallback(
     (routeKey: string) => {
-      dispatch({ type: 'tab-change', routeKey });
+      dispatch({ type: 'tab-select', routeKey });
     },
     [],
   );
@@ -93,7 +93,7 @@ export function TabsContainer(props: TabsContainerProps) {
     <Tabs.Host
       // Use controlled tabs by default, but allow to overwrite if user wants to
       navState={hostNavState}
-      onTabChange={onTabChangeCallback}
+      onTabSelected={onTabSelectedCallback}
       experimentalControlNavigationStateInJS={
         experimentalControlNavigationStateInJS
       }
@@ -114,7 +114,7 @@ export function TabsContainer(props: TabsContainerProps) {
           routeKey: route.routeKey,
           routeOptions: { ...route.options },
           setRouteOptions,
-          changeTabTo: tabChangeActionMethod,
+          selectTab: selectTabMethod,
           isSelected: isSelected,
           shouldRenderContents: isSelected || pendingForUpdate,
         };

apps/src/shared/gamma/containers/tabs/TabsContainer.types.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import type {
-  TabChangeEvent,
+  TabSelectedEvent,
   TabsHostProps,
   TabsScreenProps,
 } from 'react-native-screens';
@@ -52,15 +52,15 @@ export type TabsContainerState = {
 
 /// Navigation actions
 
-export type TabsNavigationActionChangeTab = {
-  type: 'tab-change';
+export type TabsNavigationActionSelectTab = {
+  type: 'tab-select';
   routeKey: string;
 };
 
-export type TabsNavigationActionNativeChangeTab = {
-  type: 'native-tab-change';
+export type TabsNavigationActionNativeSelectTab = {
+  type: 'native-tab-select';
   routeKey: string;
-  nativeEvent: TabChangeEvent;
+  nativeEvent: TabSelectedEvent;
 };
 
 export type TabsNavigationActionSetOptions = {
@@ -70,9 +70,9 @@ export type TabsNavigationActionSetOptions = {
 };
 
 export type TabsNavigationAction =
-  | TabsNavigationActionChangeTab
+  | TabsNavigationActionSelectTab
   | TabsNavigationActionSetOptions
-  | TabsNavigationActionNativeChangeTab;
+  | TabsNavigationActionNativeSelectTab;
 
 /// TabsContainer props
 
@@ -103,4 +103,4 @@ export type SetTabOptionsMethod = (
   options: Partial<TabRouteOptions>,
 ) => void;
 
-export type ChangeTabMethod = (routeKey: string) => void;
+export type SelectTabMethod = (routeKey: string) => void;

apps/src/shared/gamma/containers/tabs/contexts/TabsNavigationContext.tsx

@@ -2,14 +2,14 @@ import React from 'react';
 import type {
   TabRouteOptions,
   SetTabOptionsMethod,
-  ChangeTabMethod,
+  SelectTabMethod,
 } from '../TabsContainer.types';
 
 export type TabsNavigationContextPayload = {
   routeKey: string;
   routeOptions: TabRouteOptions;
   setRouteOptions: SetTabOptionsMethod;
-  changeTabTo: ChangeTabMethod;
+  selectTab: SelectTabMethod;
   isSelected: boolean;
   shouldRenderContents: boolean;
 };

apps/src/shared/gamma/containers/tabs/index.ts

@@ -6,7 +6,7 @@ export type {
   TabsContainerProps,
   TabsHostConfig,
   TabsNavigationAction,
-  TabsNavigationActionChangeTab,
+  TabsNavigationActionSelectTab,
   TabsNavigationActionSetOptions,
   TabsContainerState,
 } from './TabsContainer.types';