refactor(tabs): rename TabsHost navState prop to navStateRequest (#3943)

## Description

Aligns the `TabsHost` public API with
[RFC-1028](software-mansion/react-native-screens-labs#1174
request/state distinction.

The prop currently named `navState` carries a *request* for a state
change — not the state itself. The resulting state is delivered back to
JS through the `OnTabSelected` event. Today both sides expose a field
called `provenance`, but they refer to different things:

- on the request: provenance of the state the request was *derived from*
(i.e. the JS-side base),
- on the event payload: provenance of the *resulting* state after the
transition.

Renaming the prop and field makes this distinction explicit at the API
surface and prevents downstream consumers from conflating the two.

Most other RFC-1028 deliverables are already implemented
(`OnTabSelected`/`OnTabSelectionRejected`/`OnTabSelectionPrevented`,
`isNativeAction`, `rejectStaleNavStateUpdates`, the prevention event).
This PR is the remaining rename pass.

No behavior change.

## Changes

- Public TS:
  - type `TabsHostNavState` → `TabsHostNavStateRequest`
  - field `provenance` → `baseProvenance` on the request type
  - prop `navState` → `navStateRequest` on `TabsHostPropsBase`
  - re-export updated in ` src/components/tabs/index.ts`
- Codegen specs (Android + iOS): same prop/field rename. The C++ Props
struct regenerates automatically on next codegen run.
- Native binding boundary:
- Android: `setNavStateRequest` override on the ViewManager, parses
`selectedScreenKey` + `baseProvenance` from the `ReadableMap`.
  - iOS: prop access in `RNSTabsHostComponentView::updateProps`.
- Internal native state types are kept untouched — they model state, not
requests:
  - Kotlin `TabsNavState` (data class)
  - ObjC `RNSTabsNavigationState`
- `TabSelectOp.navState` payload (the op models a container-level state
update, not a JS request)
- Internal members holding the most recent JS request renamed for
clarity:
- Android: `jsNavState` → `jsNavStateRequest`, `updateJSNavState` →
`updateJSNavStateRequest`
- iOS: `_jsNavState` → `_jsNavStateRequest`, `@property navState` →
`@property navStateRequest`
- Apps consumer (`apps/.../TabsContainer.{tsx,types.tsx}`) updated in
lockstep so the workspace stays green; helper hook renamed
`useTabsHostNavState` → `useTabsHostNavStateRequest`.

## Test plan

This is a pure rename — no behavior change is introduced. Verification
focused on build/type integrity and a manual smoke test in
`FabricExample`:

- ` yarn check-types` (library) — passes.
- ` yarn check-types` in `apps/` — only pre-existing, unrelated errors
remain (no errors mention `navState`/`TabsHostNavState` after the
rename).
- Android: full rebuild of `FabricExample` — codegen regenerates
`RNSTabsHostAndroidManagerInterface.setNavStateRequest(...)` and the
`RNSTabsHostAndroidNavStateRequestStruct` C++ struct; the Kotlin
override compiles against the new signature.
- iOS: ` pod install` + build of `FabricExample` — codegen produces the
renamed C++ Props member; the ObjC++ side reads `
newComponentProps.navStateRequest.{selectedScreenKey,baseProvenance}`.
- Manual smoke test in `FabricExample` Tabs example: drive tab changes
from JS (programmatic, via the apps' `TabsContainer`) and from native
(tab bar tap). Confirm tab selection works on both platforms and `
OnTabSelected` events still fire as expected.

Reviewers may want to focus on:

- ` src/components/tabs/host/TabsHost.types.ts` — public type shape
- both codegen specs in ` src/fabric/tabs/`
- the boundary conversion in `
TabsHostViewManager.kt::setNavStateRequest` and `
RNSTabsHostComponentView.mm::updateProps` (request's `baseProvenance` is
fed in as the constructor's ` provenance:` arg on the internal state
types — by design)

## Checklist

- [ ] Included code example that can be used to test this change.
- [ ] 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/host/TabsHost.kt

@@ -29,7 +29,7 @@ class TabsHost(
     TabsContainerDelegate,
     UIManagerListener {
     private val renderedScreens: ArrayList<TabsScreen> = arrayListOf()
-    private var jsNavState: TabsNavState = TabsNavState.EMPTY
+    private var jsNavStateRequest: TabsNavState = TabsNavState.EMPTY
 
     private val container: TabsContainer =
         TabsContainer(reactContext, this).apply {
@@ -109,9 +109,9 @@ class TabsHost(
         container.removeAllTabsScreens()
     }
 
-    internal fun updateJSNavState(navState: TabsNavState) {
-        jsNavState = navState
-        container.setContainerOperation(TabSelectOp(jsNavState.copy()))
+    internal fun updateJSNavStateRequest(navStateRequest: TabsNavState) {
+        jsNavStateRequest = navStateRequest
+        container.setContainerOperation(TabSelectOp(jsNavStateRequest.copy()))
     }
 
     private val layoutCallback =

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

@@ -72,14 +72,14 @@ class TabsHostViewManager :
         view.onViewManagerAddEventEmitters()
     }
 
-    override fun setNavState(
+    override fun setNavStateRequest(
         view: TabsHost,
         value: ReadableMap?,
     ) {
-        val navStateMap = requireNotNull(value) { "[RNScreens] NavState must not be nullish" }
-        val selectedScreenKey = requireNotNull(navStateMap.getString("selectedScreenKey"))
-        val provenance = requireNotNull(navStateMap.getInt("provenance"))
-        view.updateJSNavState(TabsNavState(selectedScreenKey, provenance))
+        val navStateRequestMap = requireNotNull(value) { "[RNScreens] navStateRequest must not be nullish" }
+        val selectedScreenKey = requireNotNull(navStateRequestMap.getString("selectedScreenKey"))
+        val baseProvenance = requireNotNull(navStateRequestMap.getInt("baseProvenance"))
+        view.updateJSNavStateRequest(TabsNavState(selectedScreenKey, baseProvenance))
     }
 
     override fun setRejectStaleNavStateUpdates(

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

@@ -3,7 +3,7 @@ import { I18nManager, type NativeSyntheticEvent } from 'react-native';
 import {
   type TabSelectedEvent,
   Tabs,
-  type TabsHostNavState,
+  type TabsHostNavStateRequest,
 } from 'react-native-screens';
 import type {
   SelectTabMethod,
@@ -43,7 +43,7 @@ export function TabsContainer(props: TabsContainerProps) {
     determineInitialTabsContainerState,
   );
 
-  const hostNavState = useTabsHostNavState(tabsNavState);
+  const hostNavStateRequest = useTabsHostNavStateRequest(tabsNavState);
 
   const onTabSelectedCallback = React.useCallback(
     (event: NativeSyntheticEvent<TabSelectedEvent>) => {
@@ -74,7 +74,7 @@ export function TabsContainer(props: TabsContainerProps) {
 
   return (
     <Tabs.Host
-      navState={hostNavState}
+      navStateRequest={hostNavStateRequest}
       onTabSelected={onTabSelectedCallback}
       direction={I18nManager.isRTL ? 'rtl' : 'ltr'}
       {...restProps}>
@@ -90,17 +90,17 @@ export function TabsContainer(props: TabsContainerProps) {
   );
 }
 
-function useTabsHostNavState(
+function useTabsHostNavStateRequest(
   tabsNavState: TabsContainerState,
-): TabsHostNavState {
-  const hostNavState: TabsHostNavState = React.useMemo(() => {
+): TabsHostNavStateRequest {
+  const hostNavStateRequest: TabsHostNavStateRequest = React.useMemo(() => {
     return {
       selectedScreenKey: tabsNavState.suggestedState.selectedRouteKey,
-      provenance: tabsNavState.suggestedState.provenance,
+      baseProvenance: tabsNavState.suggestedState.provenance,
     };
   }, [tabsNavState.suggestedState]);
 
-  return hostNavState;
+  return hostNavStateRequest;
 }
 
 function useSanitizeRouteConfigs(routeConfigs: TabRouteConfig[]) {

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

@@ -80,12 +80,12 @@ export type TabsNavigationAction =
 export type TabsHostConfig = Omit<
   TabsHostProps,
   | 'children'
-  | 'navState'
+  | 'navStateRequest'
 >;
 
 export type TabsContainerProps = Omit<
   TabsHostProps,
-  'children' | 'navState'
+  'children' | 'navStateRequest'
 > & {
   routeConfigs: TabRouteConfig[];
   /**

ios/tabs/host/RNSTabsHostComponentView.h

@@ -50,7 +50,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Last navigation state requested by JS. Will be nonnull after first prop update.
  */
-@property (nonatomic, strong, readonly, nullable) RNSTabsNavigationState *navState;
+@property (nonatomic, strong, readonly, nullable) RNSTabsNavigationState *navStateRequest;
 
 @property (nonatomic, readonly) BOOL rejectStaleNavStateUpdates;
 

ios/tabs/host/RNSTabsHostComponentView.mm

@@ -53,7 +53,7 @@ @implementation RNSTabsHostComponentView {
   BOOL _hasModifiedBottomAccessoryInCurrentTransation;
   BOOL _needsTabBarAppearanceUpdate;
 
-  RNSTabsNavigationState *_Nullable _jsNavState;
+  RNSTabsNavigationState *_Nullable _navStateRequest;
 }
 
 - (instancetype)initWithFrame:(CGRect)frame
@@ -268,14 +268,15 @@ - (void)updateProps:(const facebook::react::Props::Shared &)props
   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 =
+        [RNSTabsNavigationState stateWithSelectedScreenKey:selectedScreenKey
+                                                provenance:newComponentProps.navStateRequest.baseProvenance];
+    [_controller setPendingNavigationStateUpdate:[_navStateRequest cloneState]];
   }
 
   if (newComponentProps.rejectStaleNavStateUpdates != oldComponentProps.rejectStaleNavStateUpdates) {

src/components/tabs/host/TabsHost.android.tsx

@@ -25,7 +25,7 @@ function TabsHost(props: TabsHostProps) {
     direction,
     nativeContainerStyle,
     onTabSelected,
-    navState,
+    navStateRequest,
     ...filteredBaseProps
   } = baseProps;
 
@@ -41,7 +41,7 @@ function TabsHost(props: TabsHostProps) {
   return (
     <TabsHostAndroidNativeComponent
       style={[styles.fillParent, { direction }]}
-      navState={navState}
+      navStateRequest={navStateRequest}
       onTabSelected={onTabSelectedCallback}
       nativeContainerBackgroundColor={nativeContainerStyle?.backgroundColor}
       // @ts-ignore suppress ref - debug only

src/components/tabs/host/TabsHost.ios.tsx

@@ -28,7 +28,7 @@ function TabsHost(props: TabsHostProps) {
     direction,
     nativeContainerStyle,
     onTabSelected,
-    navState,
+    navStateRequest,
     ...filteredBaseProps
   } = baseProps;
 
@@ -47,7 +47,7 @@ function TabsHost(props: TabsHostProps) {
   return (
     <TabsHostIOSNativeComponent
       style={styles.fillParent}
-      navState={navState}
+      navStateRequest={navStateRequest}
       onTabSelected={onTabSelectedCallback}
       nativeContainerBackgroundColor={nativeContainerStyle?.backgroundColor}
       // @ts-ignore suppress ref - debug only

src/components/tabs/host/TabsHost.types.ts

@@ -5,7 +5,7 @@ import type { ColorScheme, Direction } from '../../shared/types';
 
 // #region Control
 
-export type TabsHostNavState = {
+export type TabsHostNavStateRequest = {
   /**
    * @summary Valid screen key.
    *
@@ -14,13 +14,12 @@ export type TabsHostNavState = {
    */
   selectedScreenKey: string;
   /**
-   * @summary A number describing the provenance of the state instance.
+   * @summary Provenance of the navigation state this request is derived from.
    *
    * @description
    * The provenance value establishes a relationship between different navigation state instances
-   * held by given state holder. The assumption here is that when the navigation
-   * state is progressed (modified), the provenance number is incremented.
-   * This creates a relationship where we can say that:
+   * held by given state holder. The assumption is that when the navigation state is progressed
+   * (modified), the provenance number is incremented. This creates a relationship where we can say:
    *
    * 1. State with provenance = n + 1 has been derived from state with provenance = n.
    * 2. For two given navigation states A and B, we can say that A *is stale* iff
@@ -31,12 +30,15 @@ export type TabsHostNavState = {
    *
    * Currently, the native implementation of TabsHost is the state holder.
    *
-   * When you use object of this shape to trigger a navigation via {@link TabsHostPropsBase#navState},
-   * pass here THE PROVENANCE OF THE LAST ACKNOWLEDGED state you received from native side
-   * via {@link TabsHostPropsBase#onTabSelected}. In other words this should be the provenance number
-   * of last confirmed state you base your update request on.
+   * Pass here THE PROVENANCE OF THE LAST ACKNOWLEDGED state you received from native side
+   * via {@link TabsHostPropsBase#onTabSelected}. In other words this should be the provenance
+   * number of last confirmed state you base your update request on.
+   *
+   * It is named `baseProvenance` (rather than `provenance`) to disambiguate it from the
+   * `provenance` field on the {@link TabSelectedEvent} payload, which carries the provenance
+   * of the state *resulting* from a transition.
    */
-  provenance: number;
+  baseProvenance: number;
 };
 
 // #endregion Control
@@ -140,15 +142,15 @@ export interface TabsHostPropsBase {
    * the update might get accepted or rejected.
    *
    * @see {@link TabsHostPropsBase#rejectStaleNavStateUpdates}
-   * @see {@link TabsHostNavState} for description of the type model & accepted values.
+   * @see {@link TabsHostNavStateRequest} for description of the type model & accepted values.
    */
-  navState: TabsHostNavState;
+  navStateRequest: TabsHostNavStateRequest;
   /**
    * @summary If true, the native side will reject any navigation state updates coming from JS
    * if they are stale.
    *
    * @description A navigation state update is considered stale if it is based of an stale state
-   * (@{link TabsHostNavState#provenance} indicates the base state).
+   * ({@link TabsHostNavStateRequest#baseProvenance} indicates the base state).
    * A state is stale, when at the time of executing update, there already had been accepted a newer state
    * of different origin.
    *

src/components/tabs/index.ts

@@ -2,7 +2,7 @@ import { TabsHost } from './host';
 import { TabsScreen } from './screen';
 
 export type {
-  TabsHostNavState,
+  TabsHostNavStateRequest,
   TabSelectedEvent,
   TabSelectionRejectedEvent,
   TabSelectionRejectionReason,