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

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

@@ -0,0 +1,264 @@
+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 TabsHostNavState = {
+  /**
+   * @summary Valid screen key.
+   *
+   * @description
+   * It must correspond to one of the keys you assign to the `TabsScreens`.
+   */
+  selectedScreenKey: string;
+  /**
+   * @summary A number describing the provenance of the state instance.
+   *
+   * @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:
+   *
+   * 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.
+   *
+   * 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.
+   */
+  provenance: 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;
+  /**
+   * False in case the event is a result of JS-driven update. True otherwise, e.g. in case of user action (tap)
+   * or implicit UIKit action (app resize, orientation change, etc.).
+   */
+  isNativeAction: boolean;
+};
+
+/**
+ * @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 TabsHostNavState} for description of the type model & accepted values.
+   */
+  navState: TabsHostNavState;
+  /**
+   * @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).
+   * 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?: ViewProps['children'] | undefined;
+  /**
+   * @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,
+  };
+}

package/src/components/tabs/index.ts

@@ -1,16 +1,51 @@
-import TabsHost from './TabsHost';
-import TabsScreen from './TabsScreen';
+import { TabsHost } from './host';
+import { TabsScreen } from './screen';
 
-export type * from './TabsHost.types';
-export type * from './TabsScreen.types';
-export type { TabsAccessoryEnvironment } from './TabsAccessory.types';
+export type {
+  TabsHostNavState,
+  TabSelectedEvent,
+  TabSelectionRejectedEvent,
+  TabSelectionRejectionReason,
+  TabsHostColorScheme,
+  TabsHostDirection,
+  TabsHostNativeContainerStyleProps,
+  TabsHostPropsBase,
+  TabsHostProps,
+  // Android
+  TabsHostPropsAndroid,
+  // iOS
+  MoreTabSelectedEvent,
+  TabsBottomAccessoryComponentFactory,
+  TabBarMinimizeBehavior,
+  TabBarControllerMode,
+  TabsHostPropsIOS,
+} from './host';
+
+export type {
+  TabsScreenEventHandler,
+  TabsScreenOrientation,
+  TabsScreenPropsBase,
+  TabsScreenProps,
+  // Android
+  TabBarItemLabelVisibilityMode,
+  TabsScreenItemStateAppearanceAndroid,
+  TabsScreenAppearanceAndroid,
+  TabsScreenPropsAndroid,
+  // iOS
+  TabsScreenBlurEffect,
+  TabsScreenSystemItem,
+  TabsScreenAppearanceIOS,
+  TabsScreenItemAppearanceIOS,
+  TabsScreenItemStateAppearanceIOS,
+  TabsScreenPropsIOS,
+} from './screen';
+
+export type { TabsBottomAccessoryEnvironment } from './bottom-accessory';
 
 /**
  * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
  */
-const Tabs = {
+export const Tabs = {
   Host: TabsHost,
   Screen: TabsScreen,
 };
-
-export default Tabs;

package/src/components/tabs/screen/TabsScreen.android.tsx

@@ -0,0 +1,198 @@
+'use client';
+
+import React from 'react';
+import {
+  Image,
+  ImageResolvedAssetSource,
+  StyleSheet,
+  processColor,
+} from 'react-native';
+import TabsScreenAndroidNativeComponent, {
+  type Appearance,
+  type ItemStateAppearance,
+  type NativeProps as TabsScreenAndroidNativeComponentProps,
+} from '../../../fabric/tabs/TabsScreenAndroidNativeComponent';
+import type {
+  TabsScreenAppearanceAndroid,
+  TabsScreenItemStateAppearanceAndroid,
+} from './TabsScreen.android.types';
+import type { TabsScreenProps } from '../screen/TabsScreen.types';
+import type { PlatformIconAndroid } from '../../../types';
+import { useTabsScreen } from './useTabsScreen';
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function TabsScreen(props: TabsScreenProps) {
+  // ios props are safely dropped
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { android, ios, ...baseProps } = props;
+
+  const componentNodeRef =
+    React.useRef<React.Component<TabsScreenAndroidNativeComponentProps>>(null);
+
+  const {
+    onDidAppear,
+    onDidDisappear,
+    onWillAppear,
+    onWillDisappear,
+    children,
+    style,
+    ...filteredBaseProps
+  } = baseProps;
+
+  const { lifecycleCallbacks } =
+    useTabsScreen<TabsScreenAndroidNativeComponentProps>({
+      componentNodeRef,
+      onDidAppear,
+      onDidDisappear,
+      onWillAppear,
+      onWillDisappear,
+      screenKey: filteredBaseProps.screenKey,
+    });
+
+  const iconProps = parseIconsToNativeProps(
+    android?.icon,
+    android?.selectedIcon,
+  );
+
+  return (
+    <TabsScreenAndroidNativeComponent
+      collapsable={false}
+      style={[style, styles.fillParent]}
+      // @ts-ignore - This is debug only anyway
+      ref={componentNodeRef}
+      {...lifecycleCallbacks}
+      {...iconProps}
+      {...filteredBaseProps}
+      // Android-specific
+      standardAppearance={mapAppearanceToNativeProps(
+        android?.standardAppearance,
+      )}>
+      {children}
+    </TabsScreenAndroidNativeComponent>
+  );
+}
+
+function mapAppearanceToNativeProps(
+  appearance?: TabsScreenAppearanceAndroid,
+): Appearance | undefined {
+  if (!appearance) return undefined;
+
+  const {
+    tabBarBackgroundColor,
+    tabBarItemRippleColor,
+    normal,
+    selected,
+    focused,
+    disabled,
+    tabBarItemActiveIndicatorColor,
+    tabBarItemTitleFontWeight,
+    tabBarItemBadgeBackgroundColor,
+    tabBarItemBadgeTextColor,
+    ...rest
+  } = appearance;
+
+  return {
+    ...rest,
+    tabBarBackgroundColor: processColor(tabBarBackgroundColor),
+    tabBarItemRippleColor: processColor(tabBarItemRippleColor),
+    normal: mapItemStateAppearanceToNativeProp(normal),
+    selected: mapItemStateAppearanceToNativeProp(selected),
+    focused: mapItemStateAppearanceToNativeProp(focused),
+    disabled: mapItemStateAppearanceToNativeProp(disabled),
+    tabBarItemActiveIndicatorColor: processColor(
+      tabBarItemActiveIndicatorColor,
+    ),
+    tabBarItemTitleFontWeight:
+      tabBarItemTitleFontWeight !== undefined
+        ? String(tabBarItemTitleFontWeight)
+        : undefined,
+    tabBarItemBadgeBackgroundColor: processColor(
+      tabBarItemBadgeBackgroundColor,
+    ),
+    tabBarItemBadgeTextColor: processColor(tabBarItemBadgeTextColor),
+  };
+}
+
+function mapItemStateAppearanceToNativeProp(
+  itemStateAppearance?: TabsScreenItemStateAppearanceAndroid,
+): ItemStateAppearance | undefined {
+  if (!itemStateAppearance) return undefined;
+
+  const { tabBarItemTitleFontColor, tabBarItemIconColor, ...rest } =
+    itemStateAppearance;
+
+  return {
+    ...rest,
+    tabBarItemTitleFontColor: processColor(tabBarItemTitleFontColor),
+    tabBarItemIconColor: processColor(tabBarItemIconColor),
+  };
+}
+
+function parseIconsToNativeProps(
+  icon: PlatformIconAndroid | undefined,
+  selectedIcon: PlatformIconAndroid | undefined,
+): {
+  imageIconResource?: ImageResolvedAssetSource | undefined;
+  drawableIconResourceName?: string | undefined;
+  selectedImageIconResource?: ImageResolvedAssetSource | undefined;
+  selectedDrawableIconResourceName?: string | undefined;
+} {
+  const parsedIcon = parseIconToNativeProps(icon);
+  const parsedSelectedIcon = parseIconToNativeProps(selectedIcon);
+
+  return {
+    imageIconResource: parsedIcon.imageIconResource,
+    drawableIconResourceName: parsedIcon.drawableIconResourceName,
+    selectedImageIconResource: parsedSelectedIcon.imageIconResource,
+    selectedDrawableIconResourceName:
+      parsedSelectedIcon.drawableIconResourceName,
+  };
+}
+
+function parseIconToNativeProps(icon: PlatformIconAndroid | undefined): {
+  imageIconResource?: ImageResolvedAssetSource | undefined;
+  drawableIconResourceName?: string | undefined;
+} {
+  if (!icon) {
+    return {};
+  }
+
+  let parsedIconResource;
+  if (icon.type === 'imageSource') {
+    parsedIconResource = Image.resolveAssetSource(icon.imageSource);
+    if (!parsedIconResource) {
+      console.error(
+        '[RNScreens] failed to resolve an asset for bottom tab icon',
+      );
+    }
+
+    return {
+      // I'm keeping undefined as a fallback if `Image.resolveAssetSource` has failed for some reason.
+      // It won't render any icon, but it will prevent from crashing on the native side which is expecting
+      // ReadableMap. Passing `iconResource` directly will result in crash, because `require` API is returning
+      // double as a value.
+      imageIconResource: parsedIconResource || undefined,
+    };
+  } else if (icon.type === 'drawableResource') {
+    return {
+      drawableIconResourceName: icon.name,
+    };
+  } else {
+    throw new Error(
+      '[RNScreens] Incorrect icon format for Android. You must provide `imageSource` or `drawableResource`.',
+    );
+  }
+}
+
+export default TabsScreen;
+
+const styles = StyleSheet.create({
+  fillParent: {
+    position: 'absolute',
+    flex: 1,
+    width: '100%',
+    height: '100%',
+  },
+});