feat(Android, Tabs): partially implement RFC-1028 for Tabs on Android (#3776)

## Description

> [!note]
> I'll wait with landing this PR until I get approvals on
#3781.
These two should be landed in tandem.

Partially implements
[RFC-1028](#3702)
for the Tabs component on Android. This PR changes the communication
model between the native and JS sides of the Tabs implementation,
switching from *controlled mode* to *managed mode*, and introduces a
richer event payload for tab change events.

This is part of a broader refactor series for the Tabs component. State
conflict resolution algorithm (as described in RFC-1028) is deferred to
a follow-up PR.

Related to #3702.

Closes
software-mansion/react-native-screens-labs#990

## Changes

### Android (native)

- **Switched from *controlled* to *managed* mode**: The container now
first updates its model and then sends events to the Element realm,
rather than waiting for JS to confirm state.
- **Replaced `TabsHostNativeFocusChangeEvent` with
`TabsHostTabChangeEvent`**: The new event carries an extended payload
(`selectedScreenKey` + `provenance`) aligned with RFC-1028 model.
- **Moved menu model construction out of appearance update**:
Previously, `BottomNavigationMenuView` model was built inside
`updateBottomNavigationViewAppearance`. It's now a separate step that
happens before any container update is triggered, which is
architecturally cleaner and required by the new update flow.
- **Streamlined container update logic**: Native update now begins with
`TabsContainer::onMenuItemSelected` (triggered by `OnMenuItemClicked`
listener). JS-initiated update begins with `TabsHost` setting an
operation on `TabsContainer` and flushing it, which in turn triggers
`onMenuItemSelected` via `bottomNavigationView.menu.selectedItemId`
assignment.
- **Removed `ContainerUpdateCoordinator`**: Replaced with the stack
model — operations are flushed on `UIManagerListener.didMountItems`
callback, aligning with how Stack works on Android and iOS.
- **`TabsScreen` no longer tracks its own selection state**: `isFocused`
prop has been removed. Selection state is now passed to the native side
via the new `navState` prop on `TabsHost`.
- **Added `TabsContainerDelegate`** and **`MenuHelpers`** as supporting
infrastructure.

### JS / TypeScript

- **`onNativeFocusChange` replaced with `onTabChange`**: New event name
follows RFC-1028. The payload is richer, providing more context. This is
a **breaking change** — downstream code will need to adapt.
- **`navState` prop added to `TabsHost`**: Carries `selectedScreenKey`
and `provenance`, enabling the managed mode operation flow.
- **`isFocused` removed from `TabsScreen`**: Screen no longer manages
its own focus awareness.
- **Updated JS `TabsContainer` example implementation**:
- Distinguishes between `native-tab-change` and `js-tab-change` dispatch
actions.
- Introduces `confirmedState` (state confirmed as displayed by native
side) and `suggestedState` (state sent to native but not yet confirmed).
- Prevents user-defined `onTabChange` callback from overriding
`TabsContainer`'s internal handler.

## Test plan

- Tested manually using
`apps/src/tests/single-feature-tests/tabs/test-tabs-simple-nav.tsx` on
Android.
- Verified basic tab navigation works in managed mode (native-initiated
and JS-initiated tab changes).

## Checklist

- [x] 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

Author: kkafar

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/appearance/TabsAppearanceApplicator.kt

@@ -15,12 +15,11 @@ import com.facebook.react.uimanager.PixelUtil
 import com.google.android.material.R
 import com.google.android.material.bottomnavigation.BottomNavigationView
 import com.google.android.material.navigation.NavigationBarView
-import com.swmansion.rnscreens.gamma.tabs.host.TabsHost
 import com.swmansion.rnscreens.gamma.tabs.screen.TabsScreen
 import com.swmansion.rnscreens.utils.resolveColorAttr
 
 @SuppressLint("PrivateResource") // We want to use variables from material design for default values
-class TabsAppearanceApplicator(
+internal class TabsAppearanceApplicator(
     private val bottomNavigationView: BottomNavigationView,
 ) {
     private val states =
@@ -33,11 +32,10 @@ class TabsAppearanceApplicator(
 
     fun updateSharedAppearance(
         context: Context,
-        tabsHost: TabsHost,
+        tabBarAppearance: TabsAppearance?,
+        isTabBarHidden: Boolean,
     ) {
-        val tabBarAppearance = tabsHost.currentFocusedTab.tabsScreen.appearance
-
-        bottomNavigationView.isVisible = !tabsHost.tabBarHidden
+        bottomNavigationView.isVisible = !isTabBarHidden
         bottomNavigationView.setBackgroundColor(
             tabBarAppearance?.tabBarBackgroundColor
                 ?: resolveColorAttr(context, R.attr.colorSurfaceContainer),
@@ -115,9 +113,8 @@ class TabsAppearanceApplicator(
 
     fun updateFontStyles(
         context: Context,
-        tabsHost: TabsHost,
+        tabBarAppearance: TabsAppearance?,
     ) {
-        val tabBarAppearance = tabsHost.currentFocusedTab.tabsScreen.appearance
         val bottomNavigationMenuView = bottomNavigationView.getChildAt(0) as ViewGroup
 
         for (menuItem in bottomNavigationMenuView.children) {

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/appearance/TabsAppearanceCoordinator.kt

@@ -1,42 +1,41 @@
 package com.swmansion.rnscreens.gamma.tabs.appearance
 
 import android.content.Context
-import android.view.Menu
 import android.view.MenuItem
-import androidx.core.view.size
 import com.google.android.material.bottomnavigation.BottomNavigationView
-import com.swmansion.rnscreens.gamma.tabs.host.TabsHost
+import com.swmansion.rnscreens.gamma.tabs.container.TabsContainer
+import com.swmansion.rnscreens.gamma.tabs.container.menuItemIdForFragmentAtIndex
 import com.swmansion.rnscreens.gamma.tabs.screen.TabsScreen
 import com.swmansion.rnscreens.gamma.tabs.screen.TabsScreenFragment
 
-class TabsAppearanceCoordinator(
+internal class TabsAppearanceCoordinator(
     private val bottomNavigationView: BottomNavigationView,
     private val tabsScreenFragments: MutableList<TabsScreenFragment>,
 ) {
     private val appearanceApplicator = TabsAppearanceApplicator(bottomNavigationView)
 
     fun updateTabAppearance(
         context: Context,
-        tabsHost: TabsHost,
+        tabsContainer: TabsContainer,
     ) {
-        appearanceApplicator.updateSharedAppearance(context, tabsHost)
-        updateMenuItems(context, tabsHost)
-        appearanceApplicator.updateFontStyles(context, tabsHost) // It needs to be updated after updateMenuItems
+        val selectedTabAppearance = tabsContainer.selectedTab.tabsScreen.appearance
+        appearanceApplicator.updateSharedAppearance(context, selectedTabAppearance, tabsContainer.tabBarHidden)
+        updateMenuItems(context, selectedTabAppearance)
+        appearanceApplicator.updateFontStyles(context, selectedTabAppearance) // It needs to be updated after updateMenuItems
     }
 
     private fun updateMenuItems(
         context: Context,
-        tabsHost: TabsHost,
+        tabsAppearance: TabsAppearance?,
     ) {
-        if (bottomNavigationView.menu.size != tabsScreenFragments.size) {
-            // Most likely first render or some tab has been removed. Let's nuke the menu (easiest option).
-            bottomNavigationView.menu.clear()
-        }
-        val appearance = tabsHost.currentFocusedTab.tabsScreen.appearance
         tabsScreenFragments.forEachIndexed { index, fragment ->
-            val menuItem = bottomNavigationView.menu.getOrCreateMenuItem(index, fragment.tabsScreen)
-            check(menuItem.itemId == index) { "[RNScreens] Illegal state: menu items are shuffled" }
-            updateMenuItemAppearance(context, menuItem, fragment.tabsScreen, appearance)
+            val menuItemId = menuItemIdForFragmentAtIndex(index)
+            val menuItem =
+                checkNotNull(bottomNavigationView.menu.findItem(menuItemId)) {
+                    "[RNScreens] Missing MenuItem for id: $menuItemId"
+                }
+            check(menuItem.itemId == menuItemIdForFragmentAtIndex(index)) { "[RNScreens] Illegal state: menu items are shuffled" }
+            updateMenuItemAppearance(context, menuItem, fragment.tabsScreen, tabsAppearance)
         }
     }
 
@@ -50,8 +49,3 @@ class TabsAppearanceCoordinator(
         appearanceApplicator.updateBadgeAppearance(context, menuItem, tabsScreen, appearance)
     }
 }
-
-private fun Menu.getOrCreateMenuItem(
-    index: Int,
-    tabsScreen: TabsScreen,
-): MenuItem = this.findItem(index) ?: this.add(Menu.NONE, index, Menu.NONE, tabsScreen.tabTitle)

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

@@ -0,0 +1,31 @@
+package com.swmansion.rnscreens.gamma.tabs.container
+
+import android.view.Menu
+import android.view.MenuItem
+import com.swmansion.rnscreens.gamma.tabs.screen.TabsScreen
+
+// MenuItem ids are offset by one, because 0 has special meaning in the BottomNavigationMenuView API.
+
+/**
+ * Compute MenuItem id for a fragment at given index in "tabsModel" of TabsContainer
+ */
+internal fun menuItemIdForFragmentAtIndex(fragmentIndex: Int): Int = fragmentIndex + 1
+
+/**
+ * Compute fragment index in "tabsModel" of TabsContainer for a MenuItem with given id.
+ */
+internal fun fragmentIndexForMenuItemId(menuItemId: Int): Int {
+    check(menuItemId >= 1) { "[RNScreens] MenuItem id must not be less than 1" }
+    return menuItemId - 1
+}
+
+internal fun Menu.getOrCreateMenuItemForFragmentAt(
+    index: Int,
+    tabsScreen: TabsScreen,
+): MenuItem =
+    this.findItem(menuItemIdForFragmentAtIndex(index)) ?: this.add(
+        Menu.NONE,
+        menuItemIdForFragmentAtIndex(index),
+        Menu.NONE,
+        tabsScreen.tabTitle,
+    )