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

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 {
+  TabsHostNavStateRequest,
+  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%',
+  },
+});

package/src/components/tabs/screen/TabsScreen.android.types.ts

@@ -0,0 +1,189 @@
+import type { ColorValue, TextStyle } from 'react-native';
+import type { PlatformIconAndroid } from '../../../types';
+
+export type TabBarItemLabelVisibilityMode =
+  | 'auto'
+  | 'selected'
+  | 'labeled'
+  | 'unlabeled';
+
+export interface TabsScreenItemStateAppearanceAndroid {
+  /**
+   * @summary Specifies the font color used for the title of each tab bar item.
+   *
+   * @platform android
+   */
+  tabBarItemTitleFontColor?: TextStyle['color'] | undefined;
+  /**
+   * @summary Specifies the icon color for each tab bar item.
+   *
+   * @platform android
+   */
+  tabBarItemIconColor?: ColorValue | undefined;
+}
+
+export interface TabsScreenAppearanceAndroid {
+  /**
+   * @summary Specifies the background color for the entire tab bar.
+   *
+   * @platform android
+   */
+  tabBarBackgroundColor?: ColorValue | undefined;
+  /**
+   * @summary Specifies the color of each tab bar item's ripple effect.
+   *
+   * @platform android
+   */
+  tabBarItemRippleColor?: ColorValue | undefined;
+  /**
+   * @summary Specifies the label visibility mode.
+   *
+   * The label visibility mode defines when the labels of each item bar should be displayed.
+   *
+   * The following values are available:
+   * - `auto` - the label behaves as in “labeled” mode when there are 3 items or less, or as in “selected” mode when there are 4 items or more
+   * - `selected` - the label is only shown on the selected navigation item
+   * - `labeled` - the label is shown on all navigation items
+   * - `unlabeled` - the label is hidden for all navigation items
+   *
+   * The supported values correspond to the official Material Components documentation:
+   * @see {@link https://github.com/material-components/material-components-android/blob/master/docs/components/BottomNavigation.md#making-navigation-bar-accessible|Material Components documentation}
+   *
+   * @default auto
+   *
+   * @platform android
+   */
+  tabBarItemLabelVisibilityMode?: TabBarItemLabelVisibilityMode | undefined;
+  /**
+   * Defines the colors for all tab bar items which are in their enabled, unselected and unfocused state.
+   * The color scheme is determined by the configuration of the currently selected tab.
+   *
+   * @platform android
+   */
+  normal?: TabsScreenItemStateAppearanceAndroid | undefined;
+  /**
+   * Defines the colors for the tab bar item that is currently active.
+   * The color scheme is determined by the configuration of the currently selected tab itself.
+   * Maps to Android `state_selected=true`.
+   *
+   * @platform android
+   */
+  selected?: TabsScreenItemStateAppearanceAndroid | undefined;
+  /**
+   * Defines the colors for a tab bar item when it receives focus.
+   * The color scheme is determined by the configuration of the currently selected tab.
+   * Maps to Android `state_focused=true` (Used mostly for keyboard navigation).
+   *
+   * @platform android
+   */
+  focused?: TabsScreenItemStateAppearanceAndroid | undefined;
+  /**
+   * Defines the colors for tab bar items when they are disabled.
+   * The color scheme is determined by the configuration of the currently selected tab.
+   * Maps to Android `state_enabled=false`.
+   *
+   * @platform android
+   */
+  disabled?: TabsScreenItemStateAppearanceAndroid | undefined;
+  /**
+   * @summary Specifies the background color of the active indicator.
+   *
+   * @platform android
+   */
+  tabBarItemActiveIndicatorColor?: ColorValue | undefined;
+  /**
+   * @summary Specifies if the active indicator should be used.
+   *
+   * @default true
+   *
+   * @platform android
+   */
+  tabBarItemActiveIndicatorEnabled?: boolean | undefined;
+  /**
+   * @summary Specifies the font family used for the title of each tab bar item.
+   *
+   * @platform android
+   */
+  tabBarItemTitleFontFamily?: TextStyle['fontFamily'] | undefined;
+  /**
+   * @summary Specifies the font size used for the title of unselected tab bar items.
+   *
+   * The size is represented in scale-independent pixels (sp).
+   *
+   * @platform android
+   */
+  tabBarItemTitleSmallLabelFontSize?: TextStyle['fontSize'] | undefined;
+  /**
+   * @summary Specifies the font size used for the title of selected tab bar item.
+   *
+   * The size is represented in scale-independent pixels (sp).
+   *
+   * @platform android
+   */
+  tabBarItemTitleLargeLabelFontSize?: TextStyle['fontSize'] | undefined;
+  /**
+   * @summary Specifies the font weight used for the title of each tab bar item.
+   *
+   * @platform android
+   */
+  tabBarItemTitleFontWeight?: TextStyle['fontWeight'] | undefined;
+  /**
+   * @summary Specifies the font style used for the title of each tab bar item.
+   *
+   * @platform android
+   */
+  tabBarItemTitleFontStyle?: TextStyle['fontStyle'] | undefined;
+  /**
+   * @summary Specifies the background color of the badge.
+   *
+   * @platform android
+   */
+  tabBarItemBadgeBackgroundColor?: ColorValue | undefined;
+  /**
+   * @summary Specifies the text color of the badge.
+   *
+   * @platform android
+   */
+  tabBarItemBadgeTextColor?: ColorValue | undefined;
+}
+
+export interface TabsScreenPropsAndroid {
+  /**
+   * @summary Specifies the standard tab bar appearance.
+   *
+   * Allows to customize the appearance depending on the tab bar item state
+   * (normal, selected, focused, disabled). Configuration for the Bottom Navigation View
+   * is determined by the currently active tab screen.
+   *
+   * @platform android
+   */
+  standardAppearance?: TabsScreenAppearanceAndroid | undefined;
+  /**
+   * @summary Specifies the icon for the tab bar item.
+   *
+   * Supported values:
+   * - `{ type: 'imageSource', imageSource }`
+   *   Uses an image from the provided resource.
+   *
+   *   Remarks: `imageSource` type doesn't support SVGs on Android.
+   *   For loading SVGs use `drawableResource` type.
+   *
+   * - `{ type: 'drawableResource', name }`
+   *   Uses a drawable resource with the given name.
+   *
+   *   Remarks: Requires passing a drawable to resources via Android Studio.
+   *
+   * @platform android
+   */
+  icon?: PlatformIconAndroid | undefined;
+  /**
+   * @summary Specifies the icon for tab bar item when it is selected.
+   *
+   * Supports the same values as `icon` property for given platform.
+   *
+   * To use `selectedIcon`, `icon` must also be provided.
+   *
+   * @platform android
+   */
+  selectedIcon?: PlatformIconAndroid | undefined;
+}

package/src/components/tabs/screen/TabsScreen.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 { TabsScreenProps } from './TabsScreen.types';
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+export default function TabsScreen(props: TabsScreenProps): React.JSX.Element;

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

@@ -0,0 +1,235 @@
+'use client';
+
+import React from 'react';
+import {
+  ImageResolvedAssetSource,
+  StyleSheet,
+  processColor,
+  type ImageSourcePropType,
+} from 'react-native';
+import TabsScreenIOSNativeComponent, {
+  type IconType,
+  type NativeProps as TabsScreenIOSNativeComponentProps,
+  type Appearance,
+  type ItemAppearance,
+  type ItemStateAppearance,
+} from '../../../fabric/tabs/TabsScreenIOSNativeComponent';
+import type {
+  TabsScreenAppearanceIOS,
+  TabsScreenItemAppearanceIOS,
+  TabsScreenItemStateAppearanceIOS,
+} from './TabsScreen.ios.types';
+import type { TabsScreenProps } from './TabsScreen.types';
+import type { PlatformIconIOS } from '../../../types';
+import { useTabsScreen } from './useTabsScreen';
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function TabsScreen(props: TabsScreenProps) {
+  // android props are safely dropped
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { ios, android, ...baseProps } = props;
+
+  const componentNodeRef =
+    React.useRef<React.Component<TabsScreenIOSNativeComponentProps>>(null);
+
+  const {
+    onDidAppear,
+    onDidDisappear,
+    onWillAppear,
+    onWillDisappear,
+    children,
+    style,
+    ...filteredBaseProps
+  } = baseProps;
+
+  const { lifecycleCallbacks } =
+    useTabsScreen<TabsScreenIOSNativeComponentProps>({
+      componentNodeRef,
+      onDidAppear,
+      onDidDisappear,
+      onWillAppear,
+      onWillDisappear,
+      screenKey: filteredBaseProps.screenKey,
+    });
+
+  const iconProps = parseIconsToNativeProps(ios?.icon, ios?.selectedIcon);
+
+  return (
+    <TabsScreenIOSNativeComponent
+      collapsable={false}
+      style={[style, styles.fillParent]}
+      // @ts-ignore - This is debug only anyway
+      ref={componentNodeRef}
+      {...lifecycleCallbacks}
+      {...iconProps}
+      {...filteredBaseProps}
+      // iOS-specific
+      isTitleUndefined={
+        baseProps.title === null || baseProps.title === undefined
+      }
+      standardAppearance={mapAppearanceToNativeProp(ios?.standardAppearance)}
+      scrollEdgeAppearance={mapAppearanceToNativeProp(
+        ios?.scrollEdgeAppearance,
+      )}
+      userInterfaceStyle={ios?.experimental_userInterfaceStyle}
+      systemItem={ios?.systemItem}
+      overrideScrollViewContentInsetAdjustmentBehavior={
+        ios?.overrideScrollViewContentInsetAdjustmentBehavior
+      }>
+      {children}
+    </TabsScreenIOSNativeComponent>
+  );
+}
+
+function mapAppearanceToNativeProp(
+  appearance?: TabsScreenAppearanceIOS,
+): Appearance | undefined {
+  if (!appearance) return undefined;
+
+  const {
+    stacked,
+    inline,
+    compactInline,
+    tabBarBackgroundColor,
+    tabBarShadowColor,
+  } = appearance;
+
+  return {
+    ...appearance,
+    stacked: mapItemAppearanceToNativeProp(stacked),
+    inline: mapItemAppearanceToNativeProp(inline),
+    compactInline: mapItemAppearanceToNativeProp(compactInline),
+    tabBarBackgroundColor: processColor(tabBarBackgroundColor),
+    tabBarShadowColor: processColor(tabBarShadowColor),
+  };
+}
+
+function mapItemAppearanceToNativeProp(
+  itemAppearance?: TabsScreenItemAppearanceIOS,
+): ItemAppearance | undefined {
+  if (!itemAppearance) return undefined;
+
+  const { normal, selected, focused, disabled } = itemAppearance;
+
+  return {
+    ...itemAppearance,
+    normal: mapItemStateAppearanceToNativeProp(normal),
+    selected: mapItemStateAppearanceToNativeProp(selected),
+    focused: mapItemStateAppearanceToNativeProp(focused),
+    disabled: mapItemStateAppearanceToNativeProp(disabled),
+  };
+}
+
+function mapItemStateAppearanceToNativeProp(
+  itemStateAppearance?: TabsScreenItemStateAppearanceIOS,
+): ItemStateAppearance | undefined {
+  if (!itemStateAppearance) return undefined;
+
+  const {
+    tabBarItemTitleFontColor,
+    tabBarItemIconColor,
+    tabBarItemBadgeBackgroundColor,
+    tabBarItemTitleFontWeight,
+  } = itemStateAppearance;
+
+  return {
+    ...itemStateAppearance,
+    tabBarItemTitleFontColor: processColor(tabBarItemTitleFontColor),
+    tabBarItemIconColor: processColor(tabBarItemIconColor),
+    tabBarItemBadgeBackgroundColor: processColor(
+      tabBarItemBadgeBackgroundColor,
+    ),
+    tabBarItemTitleFontWeight:
+      tabBarItemTitleFontWeight !== undefined
+        ? String(tabBarItemTitleFontWeight)
+        : undefined,
+  };
+}
+
+function parseIconsToNativeProps(
+  icon: PlatformIconIOS | undefined,
+  selectedIcon: PlatformIconIOS | undefined,
+): {
+  imageIconResource?: ImageResolvedAssetSource | undefined;
+  drawableIconResourceName?: string | undefined;
+  iconType?: IconType | undefined;
+  iconImageSource?: ImageSourcePropType | undefined;
+  iconResourceName?: string | undefined;
+  selectedIconImageSource?: ImageSourcePropType | undefined;
+  selectedIconResourceName?: string | undefined;
+} {
+  const parsedIcon = parseIconToNativeProps(icon);
+  const parsedSelectedIcon = parseIconToNativeProps(selectedIcon);
+
+  if (
+    parsedIcon.iconType !== undefined &&
+    parsedSelectedIcon.iconType !== undefined &&
+    parsedIcon.iconType !== parsedSelectedIcon.iconType
+  ) {
+    throw new Error('[RNScreens] icon and selectedIcon must be same type.');
+  } else if (
+    parsedIcon.iconType === undefined &&
+    parsedSelectedIcon.iconType !== undefined
+  ) {
+    throw new Error(
+      '[RNScreens] To use selectedIcon prop, the icon prop must also be provided.',
+    );
+  }
+
+  return {
+    iconType: parsedIcon.iconType,
+    iconImageSource: parsedIcon.iconImageSource,
+    iconResourceName: parsedIcon.iconResourceName,
+    selectedIconImageSource: parsedSelectedIcon.iconImageSource,
+    selectedIconResourceName: parsedSelectedIcon.iconResourceName,
+  };
+}
+
+function parseIconToNativeProps(icon: PlatformIconIOS | undefined): {
+  iconType?: IconType | undefined;
+  iconImageSource?: ImageSourcePropType | undefined;
+  iconResourceName?: string | undefined;
+} {
+  if (!icon) {
+    return {};
+  }
+
+  if (icon.type === 'sfSymbol') {
+    return {
+      iconType: 'sfSymbol',
+      iconResourceName: icon.name,
+    };
+  } else if (icon.type === 'imageSource') {
+    return {
+      iconType: 'image',
+      iconImageSource: icon.imageSource,
+    };
+  } else if (icon.type === 'templateSource') {
+    return {
+      iconType: 'template',
+      iconImageSource: icon.templateSource,
+    };
+  } else if (icon.type === 'xcasset') {
+    return {
+      iconType: 'xcasset',
+      iconResourceName: icon.name,
+    };
+  } else {
+    throw new Error(
+      '[RNScreens] Incorrect icon format for iOS. You must provide `sfSymbol`, `imageSource`, `templateSource` or `xcasset`.',
+    );
+  }
+}
+
+export default TabsScreen;
+
+const styles = StyleSheet.create({
+  fillParent: {
+    position: 'absolute',
+    flex: 1,
+    width: '100%',
+    height: '100%',
+  },
+});