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

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

@@ -36,10 +36,17 @@ import com.swmansion.rnscreens.safearea.SafeAreaView
 import com.swmansion.rnscreens.utils.RNSLog
 import kotlin.properties.Delegates
 
+/**
+ * View that hosts the bottom navigation bar and the currently selected tab's content.
+ *
+ * Public API surface (the only contract third-party native consumers should rely on) is
+ * grouped under the `Public API` region below. Members in `Host-internal API` and other
+ * regions are implementation detail — the host (`TabsHost`) is the only intended caller
+ * and these can change without notice.
+ */
 @SuppressLint("ViewConstructor") // Created only by us. Should never be restored.
-internal class TabsContainer(
+class TabsContainer internal constructor(
     private val context: Context,
-    private val delegate: TabsContainerDelegate,
 ) : FrameLayout(context),
     ColorSchemeProviding,
     TabsScreenDelegate,
@@ -70,23 +77,25 @@ internal class TabsContainer(
         }
     }
 
-    private var navState: TabsNavState = TabsNavState.EMPTY
-    private var lastUINavState: TabsNavState = TabsNavState.EMPTY
+    private var navState: TabsNavigationState = TabsNavigationState.EMPTY
+    private var lastUINavState: TabsNavigationState = TabsNavigationState.EMPTY
     private val tabsModel: MutableList<TabsScreenFragment> = arrayListOf()
-    internal var rejectOpsWithStaleNavState: Boolean = false
+
+    internal var rejectStaleNavigationStateUpdates: Boolean = false
 
     internal val selectedTab: TabsScreenFragment
         get() =
-            checkNotNull(getFragmentForScreenKey(navState.selectedKey)) { "[RNScreens] No selected tab present" }
+            checkNotNull(getFragmentForScreenKey(navState.selectedScreenKey)) { "[RNScreens] No selected tab present" }
 
     internal val invalidationFlags = TabsContainerInvalidationFlags()
 
-    private var pendingOperation: TabsContainerOp? = null
-    internal val hasPendingOperation
-        get() = pendingOperation != null
+    private var pendingStateUpdateRequest: TabsNavigationStateUpdateRequest? = null
+
+    private fun requirePendingStateUpdateRequest(): TabsNavigationStateUpdateRequest =
+        checkNotNull(pendingStateUpdateRequest) { "[RNScreens] Attempt to require nullish pendingStateUpdateRequest" }
 
     /**
-     * Denotes whether container is currently performing update triggered by the `pendingOperation`.
+     * Denotes whether container is currently performing update triggered by the `pendingStateUpdateRequest`.
      */
     private var isInExternalOperationContext: Boolean = false
 
@@ -113,6 +122,8 @@ internal class TabsContainer(
     private val specialEffectsHandler = SpecialEffectsHandler()
     private val colorSchemeCoordinator = ColorSchemeCoordinator()
 
+    private val observerRegistry = TabsNavigationStateObserverRegistry()
+
     internal var colorScheme: ColorScheme by colorSchemeCoordinator::colorScheme
     internal var tabBarRespectsIMEInsets: Boolean = false
 
@@ -138,9 +149,8 @@ internal class TabsContainer(
             updateInterfaceInsets()
             invalidationFlags.isNavigationMenuAppearanceInvalidated = true
             post {
-                performContainerUpdateIfNeeded()
+                flushPendingUpdates()
             }
-//            updateNavigationMenuIfNeeded(oldValue, newValue)
         }
     }
 
@@ -152,12 +162,110 @@ internal class TabsContainer(
         invalidationFlags.invalidateAll()
     }
 
+    // region Public API (third-party stable)
+
+    /**
+     * Current navigation state of the container.
+     * Returns [TabsNavigationState.EMPTY] before the first tab is selected.
+     */
+    val navigationState: TabsNavigationState
+        get() = navState
+
+    /**
+     * Queue a navigation state update. Apply via [flushPendingUpdates] or rely on the
+     * host's next render cycle to apply automatically.
+     */
+    fun submitSelectionOfTabsScreenWithKey(screenKey: String) {
+        setPendingNavigationStateUpdate(
+            TabsNavigationStateUpdateRequest(
+                screenKey,
+                navigationState.provenance,
+                TabsActionOrigin.PROGRAMMATIC_NATIVE,
+            ),
+        )
+    }
+
+    /**
+     * Apply any pending invalidations and state updates in a single coordinated pass.
+     * No-op when nothing is dirty or the view is detached.
+     */
+    fun flushPendingUpdates() {
+        if (invalidationFlags.any() && isAttachedToWindow) {
+            performContainerUpdate()
+        }
+    }
+
+    fun addNavigationStateObserver(observer: TabsNavigationStateObserver): Boolean = observerRegistry.add(observer)
+
+    fun removeNavigationStateObserver(observer: TabsNavigationStateObserver): Boolean = observerRegistry.remove(observer)
+
+    // endregion
+
+    // region Host-internal API
+
+    /**
+     * Queue a navigation state update. Apply via [flushPendingUpdates] or rely on the
+     * host's next render cycle to apply automatically.
+     */
+    internal fun setPendingNavigationStateUpdate(request: TabsNavigationStateUpdateRequest?) {
+        pendingStateUpdateRequest = request
+        invalidationFlags.isSelectedTabInvalidated = request != null
+    }
+
+    internal fun addTabsScreenAt(
+        index: Int,
+        tabsScreen: TabsScreen,
+    ) {
+        tabsModel.add(index, TabsScreenFragment(tabsScreen))
+        invalidationFlags.invalidateAll()
+    }
+
+    internal fun removeTabsScreenAt(index: Int): TabsScreen? =
+        tabsModel.removeAt(index).tabsScreen.also {
+            invalidationFlags.invalidateAll()
+        }
+
+    internal fun removeTabsScreen(tabsScreen: TabsScreen): Boolean =
+        tabsModel.removeIf { it.tabsScreen === tabsScreen }.also { isRemoved ->
+            if (isRemoved) invalidationFlags.invalidateAll()
+        }
+
+    internal fun removeAllTabsScreens() {
+        tabsModel.clear()
+        invalidationFlags.invalidateAll()
+    }
+
+    internal fun setupFragmentManager() {
+        fragmentManager =
+            checkNotNull(FragmentManagerHelper.findFragmentManagerForView(this)) {
+                "[RNScreens] Nullish fragment manager - can't run container operations"
+            }
+    }
+
+    internal fun teardownFragmentManager() {
+        fragmentManager = null
+    }
+
+    /**
+     * Idempotent teardown. Releases observer references and clears any pending operation.
+     * Called by the host on view lifecycle end. Note: named `tearDown` (not `invalidate`) to avoid
+     * shadowing [android.view.View.invalidate].
+     */
+    internal fun tearDown() {
+        observerRegistry.clear()
+        setPendingNavigationStateUpdate(null)
+    }
+
+    // endregion
+
+    // region View lifecycle / insets / appearance
+
     override fun onAttachedToWindow() {
         RNSLog.d(TAG, "TabsContainer [$id] attached to window")
 
         super.onAttachedToWindow()
         setupFragmentManager()
-        performContainerUpdateIfNeeded()
+        flushPendingUpdates()
 
         colorSchemeCoordinator.setup(this) { uiNightMode ->
             applyDayNightUiMode(uiNightMode)
@@ -196,40 +304,94 @@ internal class TabsContainer(
         return insets
     }
 
-    internal fun setContainerOperation(op: TabsContainerOp) {
-        pendingOperation = op
-        invalidationFlags.isSelectedTabInvalidated = true
+    override fun onLayoutChange(
+        view: View?,
+        left: Int,
+        top: Int,
+        right: Int,
+        bottom: Int,
+        oldLeft: Int,
+        oldTop: Int,
+        oldRight: Int,
+        oldBottom: Int,
+    ) {
+        require(view is BottomNavigationView) {
+            "[RNScreens] TabsContainer's onLayoutChange expects BottomNavigationView, received $view instead"
+        }
+
+        val oldHeight = oldBottom - oldTop
+        val newHeight = bottom - top
+
+        if (newHeight != oldHeight) {
+            updateInterfaceInsets(newHeight)
+        }
     }
 
-    internal fun addTabsScreenAt(
-        index: Int,
-        tabsScreen: TabsScreen,
-    ) {
-        tabsModel.add(index, TabsScreenFragment(tabsScreen))
-        invalidationFlags.invalidateAll()
+    override fun setOnInterfaceInsetsChangeListener(listener: SafeAreaView) {
+        if (interfaceInsetsChangeListener == null) {
+            bottomNavigationView.addOnLayoutChangeListener(this)
+        }
+        interfaceInsetsChangeListener = listener
     }
 
-    internal fun removeTabsScreenAt(index: Int): TabsScreen? =
-        tabsModel.removeAt(index).tabsScreen.also {
-            invalidationFlags.invalidateAll()
+    override fun removeOnInterfaceInsetsChangeListener(listener: SafeAreaView) {
+        if (interfaceInsetsChangeListener == listener) {
+            interfaceInsetsChangeListener = null
+            bottomNavigationView.removeOnLayoutChangeListener(this)
         }
+    }
 
-    internal fun removeTabsScreen(tabsScreen: TabsScreen): Boolean =
-        tabsModel.removeIf { it.tabsScreen === tabsScreen }.also { isRemoved ->
-            if (isRemoved) invalidationFlags.invalidateAll()
+    override fun getInterfaceInsets(): EdgeInsets = EdgeInsets(0.0f, 0.0f, 0.0f, bottomNavigationView.height.toFloat())
+
+    override fun getResolvedUiNightMode() = colorSchemeCoordinator.getResolvedUiNightMode()
+
+    override fun addColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.addColorSchemeListener(listener)
+
+    override fun removeColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.removeColorSchemeListener(listener)
+
+    // endregion
+
+    // region TabsScreenDelegate impl
+
+    override fun onAppearanceChanged(tabsScreen: TabsScreen) {
+        if (selectedTab.tabsScreen === tabsScreen) {
+            invalidationFlags.isNavigationMenuAppearanceInvalidated = true
+            post {
+                this.flushPendingUpdates()
+            }
         }
+    }
 
-    internal fun removeAllTabsScreens() {
-        tabsModel.clear()
-        invalidationFlags.invalidateAll()
+    override fun onMenuItemAttributesChange(tabsScreen: TabsScreen) {
+        getMenuItemForTabsScreen(tabsScreen)?.let { menuItem ->
+            val appearance = selectedTab.tabsScreen.appearance
+            appearanceCoordinator.updateMenuItemAppearance(
+                themedContext,
+                menuItem,
+                tabsScreen,
+                appearance,
+            )
+            a11yCoordinator.setA11yPropertiesToTabItem(menuItem, tabsScreen)
+        }
     }
 
-    internal fun performContainerUpdateIfNeeded() {
-        if (invalidationFlags.any() && isAttachedToWindow) {
-            performContainerUpdate()
+    override fun getFragmentForTabsScreen(tabsScreen: TabsScreen): TabsScreenFragment? =
+        tabsModel.find {
+            it.tabsScreen ===
+                tabsScreen
         }
+
+    override fun onFragmentConfigurationChange(
+        tabsScreen: TabsScreen,
+        config: Configuration,
+    ) {
+        this.onConfigurationChanged(config)
     }
 
+    // endregion
+
+    // region Private helpers
+
     private fun performContainerUpdate() {
         if (invalidationFlags.isNavigationMenuStructureInvalidated) {
             invalidationFlags.isNavigationMenuStructureInvalidated = false
@@ -249,27 +411,25 @@ internal class TabsContainer(
     }
 
     private fun performOperation() {
-        if (pendingOperation == null) {
+        if (pendingStateUpdateRequest == null) {
             RNSLog.w(TAG, "TabsContainer::performOperation called w/o pending operation; skipping update")
             return
         }
 
-        check(hasPendingOperation) { "[RNScreens] Attempt to update container with empty state and no pending update" }
-        check(pendingOperation is TabSelectOp)
-        val tabSelectOp = pendingOperation as TabSelectOp
+        val stateUpdateRequest = requirePendingStateUpdateRequest()
 
         val nextSelectedMenuItemId =
-            checkNotNull(getMenuItemIdForFragment(requireFragmentForScreenKey(tabSelectOp.navState.selectedKey))) {
-                "[RNScreens] Failed to find Menu Item for screenKey: ${tabSelectOp.navState.selectedKey}"
+            checkNotNull(getMenuItemIdForFragment(requireFragmentForScreenKey(stateUpdateRequest.selectedScreenKey))) {
+                "[RNScreens] Failed to find Menu Item for screenKey: ${stateUpdateRequest.selectedScreenKey}"
             }
 
-        if (rejectOpsWithStaleNavState && isNavStateStale(tabSelectOp.navState)) {
-            delegate.onNavStateUpdateRejected(
+        if (rejectStaleNavigationStateUpdates && isNavigationStateStale(stateUpdateRequest)) {
+            observerRegistry.emitOnNavigationStateUpdateRejected(
                 navState,
-                tabSelectOp.navState,
-                TabsNavStateUpdateRejectionReason.STALE,
+                stateUpdateRequest,
+                TabsNavigationStateRejectionReason.STALE,
             )
-            pendingOperation = null
+            pendingStateUpdateRequest = null
             return
         }
 
@@ -279,14 +439,14 @@ internal class TabsContainer(
             bottomNavigationView.selectedItemId = nextSelectedMenuItemId
             isInExternalOperationContext = false
         } else {
-            delegate.onNavStateUpdateRejected(
+            observerRegistry.emitOnNavigationStateUpdateRejected(
                 navState,
-                tabSelectOp.navState,
-                TabsNavStateUpdateRejectionReason.REPEATED,
+                stateUpdateRequest,
+                TabsNavigationStateRejectionReason.REPEATED,
             )
         }
 
-        pendingOperation = null
+        pendingStateUpdateRequest = null
     }
 
     private fun updateNavigationMenuStructure() {
@@ -316,8 +476,8 @@ internal class TabsContainer(
 
     private fun updateSelectedFragment(nextSelectedFragment: TabsScreenFragment): Boolean {
         if (navState.isEmpty()) {
-            check(isInExternalOperationContext && hasPendingOperation)
-            navState = TabsNavState(nextSelectedFragment.requireScreenKey, 0)
+            check(isInExternalOperationContext && pendingStateUpdateRequest != null)
+            navState = TabsNavigationState(nextSelectedFragment.requireScreenKey, 0)
             requireFragmentManager
                 .createTransactionWithReordering()
                 .add(contentView.id, nextSelectedFragment)
@@ -328,7 +488,7 @@ internal class TabsContainer(
         val currentSelectedFragment = selectedTab
 
         if (nextSelectedFragment === currentSelectedFragment) {
-            progressNavigationState(navState.selectedKey)
+            progressNavigationState(navState.selectedScreenKey)
             return true
         }
 
@@ -343,8 +503,8 @@ internal class TabsContainer(
         return true
     }
 
-    private fun progressNavigationState(selectedKey: String) {
-        navState = TabsNavState(selectedKey, navState.provenance + 1)
+    private fun progressNavigationState(selectedScreenKey: String) {
+        navState = TabsNavigationState(selectedScreenKey, navState.provenance + 1)
         if (!isInExternalOperationContext) {
             lastUINavState = navState
         }
@@ -363,7 +523,7 @@ internal class TabsContainer(
 
         // If this is user action we test whether it should be prevented before we progress the state.
         if (!isRepeated && !isInExternalOperationContext && nextSelectedFragment.isPreventNativeSelectionEnabled) {
-            delegate.onNavStateUpdatePrevented(navState, nextSelectedFragment.requireScreenKey)
+            observerRegistry.emitOnNavigationStateUpdatePrevented(navState, nextSelectedFragment.requireScreenKey)
             return false
         }
 
@@ -373,11 +533,16 @@ internal class TabsContainer(
             if (isRepeated) specialEffectsHandler.handleRepeatedTabSelection() else false
 
         if (stateChanged) {
-            delegate.onNavStateUpdate(
+            observerRegistry.emitOnNavigationStateUpdate(
                 navState,
                 isRepeated = isRepeated,
                 hasTriggeredSpecialEffect = hasTriggeredSpecialEffect,
-                isNativeAction = !isInExternalOperationContext,
+                actionOrigin =
+                    if (isInExternalOperationContext) {
+                        requirePendingStateUpdateRequest().actionOrigin
+                    } else {
+                        TabsActionOrigin.USER
+                    },
             )
         }
 
@@ -413,7 +578,7 @@ internal class TabsContainer(
 
     private fun getSelectedTabsScreenFragmentId(): Int? =
         tabsModel
-            .indexOfFirst { it.requireScreenKey == navState.selectedKey }
+            .indexOfFirst { it.requireScreenKey == navState.selectedScreenKey }
             .takeIf { it != -1 }
 
     private fun getMenuItemForTabsScreen(tabsScreen: TabsScreen): MenuItem? =
@@ -424,40 +589,6 @@ internal class TabsContainer(
                 bottomNavigationView.menu.findItem(menuItemIdForFragmentAtIndex(index))
             }
 
-    override fun getResolvedUiNightMode() = colorSchemeCoordinator.getResolvedUiNightMode()
-
-    override fun addColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.addColorSchemeListener(listener)
-
-    override fun removeColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.removeColorSchemeListener(listener)
-
-    override fun onAppearanceChanged(tabsScreen: TabsScreen) {
-        if (selectedTab.tabsScreen === tabsScreen) {
-            invalidationFlags.isNavigationMenuAppearanceInvalidated = true
-            post {
-                this.performContainerUpdateIfNeeded()
-            }
-        }
-    }
-
-    override fun onMenuItemAttributesChange(tabsScreen: TabsScreen) {
-        getMenuItemForTabsScreen(tabsScreen)?.let { menuItem ->
-            val appearance = selectedTab.tabsScreen.appearance
-            appearanceCoordinator.updateMenuItemAppearance(
-                themedContext,
-                menuItem,
-                tabsScreen,
-                appearance,
-            )
-            a11yCoordinator.setA11yPropertiesToTabItem(menuItem, tabsScreen)
-        }
-    }
-
-    override fun getFragmentForTabsScreen(tabsScreen: TabsScreen): TabsScreenFragment? =
-        tabsModel.find {
-            it.tabsScreen ===
-                tabsScreen
-        }
-
     private fun getFragmentForScreenKey(screenKey: String): TabsScreenFragment? = tabsModel.find { it.requireScreenKey == screenKey }
 
     private fun requireFragmentForScreenKey(screenKey: String): TabsScreenFragment =
@@ -465,50 +596,6 @@ internal class TabsContainer(
             "[RNScreens] Requested fragment for key: $screenKey does not exist"
         }
 
-    override fun onFragmentConfigurationChange(
-        tabsScreen: TabsScreen,
-        config: Configuration,
-    ) {
-        this.onConfigurationChanged(config)
-    }
-
-    override fun onLayoutChange(
-        view: View?,
-        left: Int,
-        top: Int,
-        right: Int,
-        bottom: Int,
-        oldLeft: Int,
-        oldTop: Int,
-        oldRight: Int,
-        oldBottom: Int,
-    ) {
-        require(view is BottomNavigationView) {
-            "[RNScreens] TabsContainer's onLayoutChange expects BottomNavigationView, received $view instead"
-        }
-
-        val oldHeight = oldBottom - oldTop
-        val newHeight = bottom - top
-
-        if (newHeight != oldHeight) {
-            updateInterfaceInsets(newHeight)
-        }
-    }
-
-    override fun setOnInterfaceInsetsChangeListener(listener: SafeAreaView) {
-        if (interfaceInsetsChangeListener == null) {
-            bottomNavigationView.addOnLayoutChangeListener(this)
-        }
-        interfaceInsetsChangeListener = listener
-    }
-
-    override fun removeOnInterfaceInsetsChangeListener(listener: SafeAreaView) {
-        if (interfaceInsetsChangeListener == listener) {
-            interfaceInsetsChangeListener = null
-            bottomNavigationView.removeOnLayoutChangeListener(this)
-        }
-    }
-
     private fun updateInterfaceInsets(newHeight: Int? = null) {
         val height = if (tabBarHidden) 0 else (newHeight ?: bottomNavigationView.height)
 
@@ -517,8 +604,6 @@ internal class TabsContainer(
         }
     }
 
-    override fun getInterfaceInsets(): EdgeInsets = EdgeInsets(0.0f, 0.0f, 0.0f, bottomNavigationView.height.toFloat())
-
     private fun getInsetsForBottomNavigationView(insets: WindowInsets): WindowInsets? {
         if (tabBarRespectsIMEInsets) {
             return insets
@@ -533,22 +618,13 @@ internal class TabsContainer(
             .toWindowInsets()
     }
 
-    internal fun setupFragmentManager() {
-        fragmentManager =
-            checkNotNull(FragmentManagerHelper.findFragmentManagerForView(this)) {
-                "[RNScreens] Nullish fragment manager - can't run container operations"
-            }
-    }
-
-    internal fun teardownFragmentManager() {
-        fragmentManager = null
-    }
-
-    private fun isNavStateStale(state: TabsNavState): Boolean {
+    private fun isNavigationStateStale(request: TabsNavigationStateUpdateRequest): Boolean {
         if (navState.isEmpty() || lastUINavState.isEmpty()) return false
-        return state.provenance < lastUINavState.provenance
+        return request.baseProvenance < lastUINavState.provenance
     }
 
+    // endregion
+
     companion object {
         const val TAG = "TabsContainer"
     }

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

@@ -0,0 +1,60 @@
+package com.swmansion.rnscreens.gamma.tabs.container
+
+import com.swmansion.rnscreens.gamma.tabs.container.TabsNavigationStateRejectionReason.REPEATED
+import com.swmansion.rnscreens.gamma.tabs.container.TabsNavigationStateRejectionReason.STALE
+
+/**
+ * Describes navigation state of a tabs container.
+ *
+ * @property selectedScreenKey Screen key of the currently selected tab.
+ * @property provenance Monotonically increasing number describing the history (generation) of the state.
+ *   State with provenance `N + 1` is derived from state with provenance `N`.
+ *   This allows detecting stale updates.
+ */
+data class TabsNavigationState(
+    val selectedScreenKey: String,
+    val provenance: Int,
+) {
+    internal fun isEmpty(): Boolean = this === EMPTY
+
+    internal fun isNotEmpty(): Boolean = !this.isEmpty()
+
+    companion object {
+        val EMPTY = TabsNavigationState("", Int.MIN_VALUE)
+    }
+}
+
+/**
+ * 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.
+ *
+ * @property selectedScreenKey Screen key of the requested tab.
+ * @property baseProvenance Provenance of the state this request was derived from. Used for staleness detection.
+ * @property actionOrigin Origin (actor) that initiated this request.
+ */
+data class TabsNavigationStateUpdateRequest(
+    val selectedScreenKey: String,
+    val baseProvenance: Int,
+    val actionOrigin: TabsActionOrigin,
+)
+
+/**
+ * Reason why a navigation state update was rejected by the container.
+ *
+ * - [STALE] — the update's provenance indicates that it is based on a stale state.
+ * - [REPEATED] — the requested tab is already selected.
+ */
+enum class TabsNavigationStateRejectionReason {
+    STALE,
+    REPEATED,
+    ;
+
+    override fun toString(): String =
+        when (this) {
+            STALE -> "stale"
+            REPEATED -> "repeated"
+        }
+}

package/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/container/{TabsContainerDelegate.kt → TabsNavigationStateObserver.kt}

@@ -1,36 +1,41 @@
 package com.swmansion.rnscreens.gamma.tabs.container
 
 /**
- * Callback interface for observing navigation state changes and rejections
- * in [TabsContainer]. Implemented by [com.swmansion.rnscreens.gamma.tabs.host.TabsHost] to relay events to JS.
+ * Observer of navigation state changes on a [TabsContainer].
+ *
+ * Multiple observers may register against a single container via
+ * [TabsContainer.addNavigationStateObserver] / [TabsContainer.removeNavigationStateObserver].
+ * The host (`TabsHost` on Android) registers itself as an observer to relay events to JS;
+ * downstream native libraries integrating directly against [TabsContainer] may register
+ * additional observers.
  */
-internal interface TabsContainerDelegate {
+interface TabsNavigationStateObserver {
     /**
      * Called when the container accepts a navigation state change.
      *
      * @param navState The new navigation state after the change.
      * @param isRepeated Whether the same tab that was already selected has been selected again.
      * @param hasTriggeredSpecialEffect Whether a special effect (e.g. scroll-to-top) was triggered.
-     * @param isNativeAction Whether the change was initiated by a native user action (tap).
+     * @param actionOrigin Origin (actor) that requested this transition.
      */
-    fun onNavStateUpdate(
-        navState: TabsNavState,
+    fun onNavigationStateUpdate(
+        navState: TabsNavigationState,
         isRepeated: Boolean,
         hasTriggeredSpecialEffect: Boolean,
-        isNativeAction: Boolean,
+        actionOrigin: TabsActionOrigin,
     )
 
     /**
      * Called when the container rejects a navigation state update.
      *
      * @param currentNavState The currently active navigation state that was kept.
-     * @param rejectedNavState The navigation state update that was rejected.
+     * @param rejectedRequest The navigation state update request that was rejected.
      * @param reason Why the update was rejected.
      */
-    fun onNavStateUpdateRejected(
-        currentNavState: TabsNavState,
-        rejectedNavState: TabsNavState,
-        reason: TabsNavStateUpdateRejectionReason,
+    fun onNavigationStateUpdateRejected(
+        currentNavState: TabsNavigationState,
+        rejectedRequest: TabsNavigationStateUpdateRequest,
+        reason: TabsNavigationStateRejectionReason,
     )
 
     /**
@@ -41,8 +46,8 @@ internal interface TabsContainerDelegate {
      * @param currentNavState The currently active navigation state that was kept.
      * @param preventedScreenKey The screen key of the tab whose selection was prevented.
      */
-    fun onNavStateUpdatePrevented(
-        currentNavState: TabsNavState,
+    fun onNavigationStateUpdatePrevented(
+        currentNavState: TabsNavigationState,
         preventedScreenKey: String,
     )
 }