react-native-screens 4.24.0 → 4.25.0-beta.2

package/src/components/tabs/bottom-accessory/TabsBottomAccessoryContent.types.ts

@@ -0,0 +1,6 @@
+import { ViewProps } from 'react-native';
+import { TabsBottomAccessoryEnvironment } from './TabsBottomAccessory.types';
+
+export type TabsBottomAccessoryContentProps = ViewProps & {
+  environment?: TabsBottomAccessoryEnvironment | undefined;
+};

package/src/components/tabs/bottom-accessory/index.ts

@@ -0,0 +1,5 @@
+export { default as TabsBottomAccessory } from './TabsBottomAccessory';
+export { default as TabsBottomAccessoryContent } from './TabsBottomAccessoryContent';
+
+export type * from './TabsBottomAccessory.types';
+export type * from './TabsBottomAccessoryContent.types';

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

@@ -0,0 +1,65 @@
+'use client';
+
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import TabsHostAndroidNativeComponent, {
+  type NativeProps as TabsHostAndroidNativeComponentProps,
+} from '../../../fabric/tabs/TabsHostAndroidNativeComponent';
+import type { TabsHostProps } from './TabsHost.types';
+import { RNSLog } from '../../../private';
+import { useTabsHost } from './useTabsHost';
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function TabsHost(props: TabsHostProps) {
+  RNSLog.log(`TabsHost render`);
+
+  // android props (even if unused for now) are extracted - these should be handled separately from base props
+  // ios props are safely dropped
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { android, ios, ...baseProps } = props;
+
+  const {
+    children,
+    direction,
+    nativeContainerStyle,
+    onTabSelected,
+    navStateRequest,
+    ...filteredBaseProps
+  } = baseProps;
+
+  const componentNodeRef =
+    React.useRef<React.Component<TabsHostAndroidNativeComponentProps>>(null);
+
+  const { onTabSelected: onTabSelectedCallback } =
+    useTabsHost<TabsHostAndroidNativeComponentProps>({
+      componentNodeRef,
+      onTabSelected,
+    });
+
+  return (
+    <TabsHostAndroidNativeComponent
+      style={[styles.fillParent, { direction }]}
+      navStateRequest={navStateRequest}
+      onTabSelected={onTabSelectedCallback}
+      nativeContainerBackgroundColor={nativeContainerStyle?.backgroundColor}
+      // @ts-ignore suppress ref - debug only
+      ref={componentNodeRef}
+      {...filteredBaseProps}
+      // Android-specific
+      tabBarRespectsIMEInsets={android?.tabBarRespectsIMEInsets}>
+      {children}
+    </TabsHostAndroidNativeComponent>
+  );
+}
+
+export default TabsHost;
+
+const styles = StyleSheet.create({
+  fillParent: {
+    flex: 1,
+    width: '100%',
+    height: '100%',
+  },
+});

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

@@ -0,0 +1,18 @@
+export interface TabsHostPropsAndroid {
+  /**
+   * @summary Determines whether `BottomNavigationView` applies the inset for IME (i.e. keyboard).
+   *
+   * This prop should be used with `android:windowSoftInputMode="adjustResize"`.
+   *
+   * On API prior to 30, setting this prop to `true` has no effect.
+   *
+   * Changing this prop while the keyboard is open will not take effect immediately.
+   * The new value will be applied the next time the keyboard is opened.
+   *
+   * @default false
+   *
+   * @platform android
+   * @supported API 30 or higher
+   */
+  tabBarRespectsIMEInsets?: boolean | undefined;
+}

package/src/components/tabs/host/TabsHost.d.ts

@@ -0,0 +1,15 @@
+/**
+ * TS module resolution does not support this RN platform extension pattern out of the box.
+ * Without a base .tsx file, TS will throw a "Cannot find module" error.
+ *
+ * This file satisfies the TS compiler by providing the correct type signatures,
+ * whereas Metro will handle the proper runtime file resolution.
+ */
+
+import React from 'react';
+import { TabsHostProps } from './TabsHost.types';
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+export default function TabsHost(props: TabsHostProps): React.JSX.Element;

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

@@ -0,0 +1,94 @@
+'use client';
+
+import React, { useState } from 'react';
+import { Platform, StyleSheet } from 'react-native';
+import TabsHostIOSNativeComponent, {
+  type NativeProps as TabsHostIOSNativeComponentProps,
+} from '../../../fabric/tabs/TabsHostIOSNativeComponent';
+import type { TabsHostProps } from './TabsHost.types';
+import { RNSLog } from '../../../private';
+import TabsBottomAccessory from '../bottom-accessory/TabsBottomAccessory';
+import { TabsBottomAccessoryEnvironment } from '../bottom-accessory/TabsBottomAccessory.types';
+import TabsBottomAccessoryContent from '../bottom-accessory/TabsBottomAccessoryContent';
+import { isIOS26OrHigher } from '../../helpers/PlatformUtils';
+import { useTabsHost } from './useTabsHost';
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function TabsHost(props: TabsHostProps) {
+  RNSLog.log(`TabsHost render`);
+
+  // android props are safely dropped
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { ios, android, ...baseProps } = props;
+
+  const {
+    children,
+    direction,
+    nativeContainerStyle,
+    onTabSelected,
+    navStateRequest,
+    ...filteredBaseProps
+  } = baseProps;
+
+  const componentNodeRef =
+    React.useRef<React.Component<TabsHostIOSNativeComponentProps>>(null);
+
+  const { onTabSelected: onTabSelectedCallback } =
+    useTabsHost<TabsHostIOSNativeComponentProps>({
+      componentNodeRef,
+      onTabSelected,
+    });
+
+  const [bottomAccessoryEnvironment, setBottomAccessoryEnvironment] =
+    useState<TabsBottomAccessoryEnvironment>('regular');
+
+  return (
+    <TabsHostIOSNativeComponent
+      style={styles.fillParent}
+      navStateRequest={navStateRequest}
+      onTabSelected={onTabSelectedCallback}
+      nativeContainerBackgroundColor={nativeContainerStyle?.backgroundColor}
+      // @ts-ignore suppress ref - debug only
+      ref={componentNodeRef}
+      {...filteredBaseProps}
+      // iOS-specific
+      layoutDirection={direction}
+      tabBarControllerMode={ios?.tabBarControllerMode}
+      tabBarMinimizeBehavior={ios?.tabBarMinimizeBehavior}
+      tabBarTintColor={ios?.tabBarTintColor}
+      onMoreTabSelected={ios?.onMoreTabSelected}>
+      {children}
+      {ios?.bottomAccessory &&
+        isIOS26OrHigher &&
+        (Platform.constants.reactNativeVersion.minor >= 82 ? (
+          <TabsBottomAccessory>
+            <TabsBottomAccessoryContent environment="regular">
+              {ios.bottomAccessory('regular')}
+            </TabsBottomAccessoryContent>
+            <TabsBottomAccessoryContent environment="inline">
+              {ios.bottomAccessory('inline')}
+            </TabsBottomAccessoryContent>
+          </TabsBottomAccessory>
+        ) : (
+          <TabsBottomAccessory
+            onEnvironmentChange={event => {
+              setBottomAccessoryEnvironment(event.nativeEvent.environment);
+            }}>
+            {ios.bottomAccessory(bottomAccessoryEnvironment)}
+          </TabsBottomAccessory>
+        ))}
+    </TabsHostIOSNativeComponent>
+  );
+}
+
+export default TabsHost;
+
+const styles = StyleSheet.create({
+  fillParent: {
+    flex: 1,
+    width: '100%',
+    height: '100%',
+  },
+});

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

@@ -0,0 +1,139 @@
+import type { ReactNode } from 'react';
+import type { TabsBottomAccessoryEnvironment } from '../bottom-accessory/TabsBottomAccessory.types';
+import type { ColorValue, NativeSyntheticEvent } from 'react-native';
+
+/**
+ * @summary Payload of the event emitted when the user taps the "More" tab bar item.
+ *
+ * @description
+ * This event fires when the user taps the system-generated "More" tab bar item.
+ * It does NOT fire when a tab is selected from within the More list — that triggers
+ * the normal `onTabSelected` event instead.
+ *
+ * The payload carries the navigation state that was active at the moment the "More" tab was tapped.
+ *
+ * @platform ios
+ */
+export type MoreTabSelectedEvent = {
+  /** Screen key of the tab that was active when "More" was tapped. */
+  selectedScreenKey: string;
+  /** Provenance of the navigation state when "More" was tapped. */
+  provenance: number;
+};
+
+export type TabsBottomAccessoryComponentFactory = (
+  environment: TabsBottomAccessoryEnvironment,
+) => ReactNode;
+
+export type TabBarMinimizeBehavior =
+  | 'automatic'
+  | 'never'
+  | 'onScrollDown'
+  | 'onScrollUp';
+
+export type TabBarControllerMode = 'automatic' | 'tabBar' | 'tabSidebar';
+
+export interface TabsHostPropsIOS {
+  /**
+   * @summary Specifies the color used for selected tab's text and icon color.
+   *
+   * Starting from iOS 26, it also impacts glow of Liquid Glass tab
+   * selection view.
+   *
+   * `tabBarItemTitleFontColor` and `tabBarItemIconColor` defined on
+   * TabsScreen component override this color.
+   *
+   * @platform ios
+   */
+  tabBarTintColor?: ColorValue | undefined;
+  /**
+   * @summary Specifies the minimize behavior for the tab bar.
+   *
+   * Available starting from iOS 26.
+   *
+   * The following values are currently supported:
+   *
+   * - `automatic` - resolves to the system default minimize behavior
+   * - `never` - the tab bar does not minimize
+   * - `onScrollDown` - the tab bar minimizes when scrolling down and
+   *   expands when scrolling back up
+   * - `onScrollUp` - the tab bar minimizes when scrolling up and expands
+   *   when scrolling back down
+   *
+   * The supported values correspond to the official UIKit documentation:
+   * @see {@link https://developer.apple.com/documentation/uikit/uitabbarcontroller/minimizebehavior|UITabBarController.MinimizeBehavior}
+   *
+   * @default Defaults to `automatic`.
+   *
+   * @platform ios
+   * @supported iOS 26 or higher
+   */
+  tabBarMinimizeBehavior?: TabBarMinimizeBehavior | undefined;
+  /**
+   * @summary Specifies component used as bottom accessory.
+   *
+   * This prop is a function that accepts `environment` as a parameter and returns
+   * the component that will be rendered in the bottom accessory.
+   *
+   * `environment` can be one of the following values:
+   *
+   * - `regular` - the accessory is laid out above the bottom tab bar,
+   * - `inline` - the accessory is laid out inline with the collapsed bottom
+   *   tab bar.
+   *
+   * If this prop is `undefined`, the bottom accessory will not be rendered.
+   *
+   * On legacy architecture (Paper) and on new architecture (Fabric) with RN < 0.82,
+   * implementation uses DisplayLink which might result in the size of bottom
+   * accessory being updated with a delay.
+   *
+   * Starting from RN 0.82, this issue is mitigated but in order to allow accessory
+   * rendering based on environment, component is rendered 2 times for both `regular`
+   * and `inline` environments at the same time. Environment determines which component
+   * is visible at given moment. This might require implementing a solution to share
+   * state between both rendered components (e.g. usage of context).
+   *
+   * Available starting from iOS 26.
+   *
+   * @platform iOS
+   * @supported iOS 26 or higher
+   */
+  bottomAccessory?: TabsBottomAccessoryComponentFactory | undefined;
+  /**
+   * @summary Specifies the display mode for the tab bar.
+   *
+   * Available starting from iOS 18.
+   * Not supported on tvOS.
+   *
+   * The following values are currently supported:
+   *
+   * - `automatic` - the system sets the display mode based on the tab’s content
+   * - `tabBar` - the system displays the content only as a tab bar
+   * - `tabSidebar` - the tab bar is displayed as a sidebar
+   *
+   * See the official documentation for more details:
+   * @see {@link https://developer.apple.com/documentation/uikit/uitabbarcontroller/mode|UITabBarController.Mode}
+   *
+   * @default Defaults to `automatic`.
+   *
+   * @platform ios
+   * @supported iOS 18 or higher
+   */
+  tabBarControllerMode?: TabBarControllerMode | undefined;
+  /**
+   * @summary
+   * A callback that gets invoked when the user taps the "More" tab bar item.
+   *
+   * @description
+   * This event fires when the user taps the system-generated "More" tab bar item.
+   * It does NOT fire when a tab is selected from within the More list — that triggers
+   * the normal `onTabSelected` event instead.
+   *
+   * @see {@link MoreTabSelectedEvent}
+   *
+   * @platform ios
+   */
+  onMoreTabSelected?:
+    | ((event: NativeSyntheticEvent<MoreTabSelectedEvent>) => void)
+    | undefined;
+}

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

@@ -0,0 +1,274 @@
+import type { ColorValue, NativeSyntheticEvent, ViewProps } from 'react-native';
+import type { TabsHostPropsAndroid } from './TabsHost.android.types';
+import type { TabsHostPropsIOS } from './TabsHost.ios.types';
+import type { ColorScheme, Direction } from '../../shared/types';
+
+// #region Control
+
+export type TabsHostNavStateRequest = {
+  /**
+   * @summary Valid screen key.
+   *
+   * @description
+   * It must correspond to one of the keys you assign to the `TabsScreens`.
+   */
+  selectedScreenKey: string;
+  /**
+   * @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 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
+   * A.provenance <= B.provenance.
+   *
+   * This allows us to mitigate and resolve state conflicts that can happen with
+   * asynchronous navigation.
+   *
+   * Currently, the native implementation of TabsHost is the state holder.
+   *
+   * 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.
+   */
+  baseProvenance: number;
+};
+
+// #endregion Control
+
+// #region General helpers
+
+/**
+ * @summary Payload of the event emitted when a tab selection occurs on the native side.
+ *
+ * @description
+ * This event is emitted both for user-initiated and programmatic tab changes.
+ * It carries the resulting navigation state along with metadata about the selection context.
+ */
+export type TabSelectedEvent = {
+  /** Screen key of the newly selected tab. */
+  selectedScreenKey: string;
+  /** Provenance of the navigation state after the selection. */
+  provenance: number;
+  /** Whether the same tab that was already selected has been selected again. */
+  isRepeated: boolean;
+  /** Whether the selection triggered a special effect (e.g. scroll-to-top on repeated selection). */
+  hasTriggeredSpecialEffect: boolean;
+  /**
+   * @summary Origin (actor) that requested this tab transition.
+   *
+   * @description
+   * - `user` — direct native UI interaction (e.g. tab bar tap, iOS tab drag-and-drop).
+   * - `programmatic-js` — JS-initiated request delivered via the `navStateRequest` prop.
+   * - `programmatic-native` — request initiated from the native side by an actor
+   *   integrating directly against the native container.
+   * - `implicit` — platform side effect not attributable to an explicit actor
+   *   (e.g. UIKit reshuffling the selection during a horizontal size-class transition on iPad).
+   *   Currently only emitted on iOS.
+   */
+  actionOrigin: 'user' | 'programmatic-js' | 'programmatic-native' | 'implicit';
+};
+
+/**
+ * @summary Reason why a tab selection request was rejected by the native side.
+ *
+ * - `stale` — the update was based on a stale navigation state,
+ *   meaning a newer state has already been applied. Only reported when
+ *   {@link TabsHostPropsBase#rejectStaleNavStateUpdates} is enabled.
+ * - `repeated` — the requested tab is already selected.
+ */
+export type TabSelectionRejectionReason = 'stale' | 'repeated';
+
+/**
+ * @summary Payload of the event emitted when the native side rejects a tab selection request.
+ *
+ * @description
+ * Contains the currently active navigation state (`selectedScreenKey`, `provenance`)
+ * alongside the rejected request details, so that the JS side can reconcile its state.
+ *
+ * @see {@link TabSelectionRejectionReason} for possible rejection reasons.
+ * @see {@link TabsHostPropsBase#rejectStaleNavStateUpdates}
+ */
+export type TabSelectionRejectedEvent = {
+  /** Screen key of the currently selected (active) tab. */
+  selectedScreenKey: string;
+  /** Provenance of the currently active navigation state. */
+  provenance: number;
+  /** Screen key of the tab whose selection was rejected. */
+  rejectedScreenKey: string;
+  /** Provenance of the rejected navigation state update. */
+  rejectedProvenance: number;
+  /** Reason the selection was rejected. */
+  rejectionReason: TabSelectionRejectionReason;
+};
+
+/**
+ * @summary Payload of the event emitted when the native side prevents a tab selection
+ * because the target screen has `preventNativeSelection` enabled.
+ */
+export type TabSelectionPreventedEvent = {
+  /** Screen key of the currently selected (active) tab. */
+  selectedScreenKey: string;
+  /** Provenance of the currently active navigation state. */
+  provenance: number;
+  /** Screen key of the tab whose selection was prevented. */
+  preventedScreenKey: string;
+};
+
+export type TabsHostColorScheme = ColorScheme | 'inherit';
+
+export type TabsHostDirection = Direction | 'inherit';
+
+export type TabsHostNativeContainerStyleProps = {
+  /**
+   * @summary Specifies the background color of the native container.
+   *
+   * @platform android, ios
+   */
+  backgroundColor?: ColorValue | undefined;
+};
+
+// #endregion General helpers
+
+export interface TabsHostPropsBase {
+  // Control
+  /**
+   * @summary
+   * Allows to pass desired navigation state request to the native side.
+   * It also determines initial navigation state after first render.
+   *
+   * @description
+   * This prop can be thought of as a "next navigation state suggestion for the native side".
+   * Depending on configuration and the provenance of the update
+   * the update might get accepted or rejected.
+   *
+   * @see {@link TabsHostPropsBase#rejectStaleNavStateUpdates}
+   * @see {@link TabsHostNavStateRequest} for description of the type model & accepted values.
+   */
+  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 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.
+   *
+   * This can happen, when an update from JS is dispatched, but before it reaches the native
+   * side, another update happens on UI thread, e.g. user selects another tab. For such
+   * situations, where to-be-applied navigation state update had been dispatched w/o
+   * full context of actual navigation state you can toggle this prop. Please note,
+   * that above definition means, that an JS update won't be rejected if you send a series of
+   * udpates with the same provenance, unless some action has been taken by the user "in the meantime".
+   *
+   * If an update is rejected due to being stale, the `onTabSelectionRejected` event will be
+   * emitted with details of the rejected update and the currently active navigation state.
+   *
+   * @default false
+   */
+  rejectStaleNavStateUpdates?: boolean | undefined;
+
+  // General
+  children: NonNullable<ViewProps['children']>;
+  /**
+   * @summary Hides the tab bar.
+   *
+   * @default false
+   *
+   * @platform android, ios
+   */
+  tabBarHidden?: boolean | undefined;
+  /**
+   * @summary Allows for native container view customization.
+   *
+   * On Android, style is applied to `FrameLayout` that wraps currently focused screen
+   * and `BottomNavigationView`. On iOS, style is applied to `UITabBarController`'s
+   * view.
+   *
+   * @platform android, ios
+   */
+  nativeContainerStyle?: TabsHostNativeContainerStyleProps | undefined;
+  /**
+   * @summary Specifies the layout direction of the native container, its views and child containers.
+   *
+   * The following values are currently supported:
+   *
+   * - `inherit` - uses parent's layout direction,
+   * - `ltr` - forces left-to-right layout direction,
+   * - `rtl` - forces right-to-left layout direction.
+   *
+   * On Android, this property relies on `react-native`'s `style.direction`
+   * (which sets native Android `layoutDirection` View property). Property is
+   * propagated via the view hierarchy. The value will fallback to direction
+   * set on one of the parent views.
+   *
+   * On iOS, this property sets `layoutDirection` trait override for the
+   * native tab bar controller. Property is propagated via the native trait
+   * system. The value will fallback to direction of the **native** app
+   * (`userInterfaceLayoutDirection`), potentially ignoring `react-native`'s
+   * override (e.g. when `forceRTL` is used). To mitigate this, you can pass
+   * `ltr`/`rtl` to this property depending on the value of `I18nManager.isRTL`.
+   *
+   * @default inherit
+   *
+   * @platform android, ios
+   */
+  direction?: TabsHostDirection | undefined;
+  /**
+   * @summary Specifies the color scheme used by the container and any child containers.
+   *
+   * The following values are currently supported:
+   * - `inherit` - the interface style from parent,
+   * - `light` - the light interface style,
+   * - `dark` - the dark interface style.
+   *
+   * @default inherit
+   *
+   * @platform android, ios
+   */
+  colorScheme?: TabsHostColorScheme | undefined;
+
+  // Events
+  /**
+   * @summary A callback that gets invoked when the selected tab changes.
+   *
+   * @platform android, ios
+   */
+  onTabSelected?:
+    | ((event: NativeSyntheticEvent<TabSelectedEvent>) => void)
+    | undefined;
+
+  /**
+   * @summary
+   * A callback that gets invoked when the native side rejects a tab selection request.
+   *
+   * @see {@link TabSelectionRejectedEvent}
+   */
+  onTabSelectionRejected?:
+    | ((event: NativeSyntheticEvent<TabSelectionRejectedEvent>) => void)
+    | undefined;
+
+  /**
+   * @summary
+   * A callback that gets invoked when the native side prevents a tab selection
+   * because the target screen has `preventNativeSelection` enabled.
+   *
+   * @see {@link TabSelectionPreventedEvent}
+   */
+  onTabSelectionPrevented?:
+    | ((event: NativeSyntheticEvent<TabSelectionPreventedEvent>) => void)
+    | undefined;
+}
+
+export interface TabsHostProps extends TabsHostPropsBase {
+  ios?: TabsHostPropsIOS | undefined;
+  android?: TabsHostPropsAndroid | undefined;
+}

package/src/components/tabs/host/index.ts

@@ -0,0 +1,6 @@
+export { default as TabsHost } from './TabsHost';
+
+export type * from './TabsHost.types';
+
+export type * from './TabsHost.android.types';
+export type * from './TabsHost.ios.types';

package/src/components/tabs/host/useTabsHost.ts

@@ -0,0 +1,49 @@
+import React from 'react';
+import { findNodeHandle, type NativeSyntheticEvent } from 'react-native';
+import type { NativeProps as TabsHostAndroidNativeComponentProps } from '../../../fabric/tabs/TabsHostAndroidNativeComponent';
+import type { NativeProps as TabsHostIOSNativeComponentProps } from '../../../fabric/tabs/TabsHostIOSNativeComponent';
+import { RNSLog } from '../../../private';
+import type { TabSelectedEvent } from './TabsHost.types';
+
+type TabsHostPlatformNativeComponentProps =
+  | TabsHostAndroidNativeComponentProps
+  | TabsHostIOSNativeComponentProps;
+
+interface TabsHostConfig<T> {
+  componentNodeRef: React.RefObject<React.Component<T> | null>;
+  onTabSelected?:
+    | ((event: NativeSyntheticEvent<TabSelectedEvent>) => void)
+    | undefined;
+}
+
+export function useTabsHost<T extends TabsHostPlatformNativeComponentProps>({
+  componentNodeRef,
+  onTabSelected,
+}: TabsHostConfig<T>) {
+  const componentNodeHandle = React.useRef<number>(-1);
+
+  React.useEffect(() => {
+    if (componentNodeRef.current != null) {
+      componentNodeHandle.current =
+        findNodeHandle(componentNodeRef.current) ?? -1;
+    } else {
+      componentNodeHandle.current = -1;
+    }
+  }, []);
+
+  const onTabSelectedCallback = React.useCallback(
+    (event: NativeSyntheticEvent<TabSelectedEvent>) => {
+      RNSLog.log(
+        `TabsHost [${
+          componentNodeHandle.current ?? -1
+        }] onTabSelected: ${JSON.stringify(event.nativeEvent)}`,
+      );
+      onTabSelected?.(event);
+    },
+    [onTabSelected],
+  );
+
+  return {
+    onTabSelected: onTabSelectedCallback,
+  };
+}