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

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

@@ -0,0 +1,312 @@
+import type { ColorValue, TextStyle } from 'react-native';
+import type { UserInterfaceStyle, BlurEffect } from '../../shared/types';
+import type { PlatformIconIOS } from '../../../types';
+
+export type TabsScreenBlurEffect = BlurEffect | 'systemDefault';
+
+export type TabsScreenSystemItem =
+  | 'bookmarks'
+  | 'contacts'
+  | 'downloads'
+  | 'favorites'
+  | 'featured'
+  | 'history'
+  | 'more'
+  | 'mostRecent'
+  | 'mostViewed'
+  | 'recents'
+  | 'search'
+  | 'topRated';
+
+export interface TabsScreenAppearanceIOS {
+  /**
+   * @summary Specifies the appearance of tab bar items when they are in stacked layout.
+   *
+   * Tab bar items in stacked layout have the icon above the title.
+   * Stacked layout is used e.g. on the iPhone in portrait orientation.
+   *
+   * @platform ios
+   */
+  stacked?: TabsScreenItemAppearanceIOS | undefined;
+  /**
+   * @summary Specifies the appearance of tab bar items when they are in inline layout.
+   *
+   * Tab bar items in inline layout have the icon next to the title.
+   * Inline layout is used in regular-width environments, e.g. in landscape orientation on the iPhone 16 Pro Max.
+   *
+   * Complete list of size classes for iOS and iPadOS devices is available in Apple's Human Interface Guidelines:
+   * @see {@link https://developer.apple.com/design/human-interface-guidelines/layout#iOS-iPadOS-device-size-classes|HIG: Device size classes}
+   *
+   * @platform ios
+   */
+  inline?: TabsScreenItemAppearanceIOS | undefined;
+  /**
+   * @summary Specifies the appearance of tab bar items when they are in compact inline layout.
+   *
+   * Tab bar items in compact inline layout have the icon next to the title.
+   * Compact inline layout is used in compact-width environments, e.g. in landscape orientation on the iPhone 16 Pro.
+   *
+   * Complete list of size classes for iOS and iPadOS devices is available in Apple's Human Interface Guidelines:
+   * @see {@link https://developer.apple.com/design/human-interface-guidelines/layout#iOS-iPadOS-device-size-classes|HIG: Device size classes}
+   *
+   * @platform ios
+   */
+  compactInline?: TabsScreenItemAppearanceIOS | undefined;
+
+  /**
+   * @summary Specifies the background color for the entire tab bar when tab screen is selected.
+   *
+   * This property does not affect the tab bar starting from iOS 26.
+   *
+   * @platform ios
+   * @supported iOS 18 or lower
+   */
+  tabBarBackgroundColor?: ColorValue | undefined;
+  /**
+   * @summary Specifies the blur effect applied to the tab bar when tab screen is selected.
+   *
+   * Works with backgroundColor's alpha < 1.
+   *
+   * This property does not affect the tab bar starting from iOS 26.
+   *
+   * The following values are currently supported:
+   *
+   * - `none` - disables blur effect
+   * - `systemDefault` - uses UIKit's default tab bar blur effect
+   * - one of styles mapped from UIKit's UIBlurEffectStyle, e.g. `systemUltraThinMaterial`
+   *
+   * Complete list of possible blur effect styles is available in the official UIKit documentation:
+   * @see {@link https://developer.apple.com/documentation/uikit/uiblureffect/style|UIBlurEffect.Style}
+   *
+   * @default systemDefault
+   *
+   * @platform ios
+   * @supported iOS 18 or lower
+   */
+  tabBarBlurEffect?: TabsScreenBlurEffect | undefined;
+  /**
+   * @summary Specifies the shadow color for the tab bar when tab screen is selected.
+   *
+   * This property does not affect the tab bar starting from iOS 26.
+   *
+   * @platform ios
+   * @supported iOS 18 or lower
+   */
+  tabBarShadowColor?: ColorValue | undefined;
+}
+
+export interface TabsScreenItemAppearanceIOS {
+  /**
+   * Defines appearance 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 ios
+   */
+  normal?: TabsScreenItemStateAppearanceIOS | undefined;
+  /**
+   * Defines appearance for the tab bar item that is currently active.
+   * The appearance is determined by the configuration of the currently selected tab itself.
+   *
+   * @platform ios
+   */
+  selected?: TabsScreenItemStateAppearanceIOS | undefined;
+  /**
+   * Defines appearance for a tab bar item when it receives focus.
+   * The appearance is determined by the configuration of the currently selected tab.
+   *
+   * @platform ios
+   */
+  focused?: TabsScreenItemStateAppearanceIOS | undefined;
+  /**
+   * Defines appearance for tab bar items when they are disabled.
+   * The appearance is determined by the configuration of the currently selected tab.
+   *
+   * @platform ios
+   */
+  disabled?: TabsScreenItemStateAppearanceIOS | undefined;
+}
+
+export interface TabsScreenItemStateAppearanceIOS {
+  /**
+   * @summary Specifies the font family used for the title of each tab bar item
+   * when tab screen is selected.
+   *
+   * @platform ios
+   */
+  tabBarItemTitleFontFamily?: TextStyle['fontFamily'] | undefined;
+  /**
+   * @summary Specifies the font size used for the title of each tab bar item
+   * when tab screen is selected.
+   *
+   * @platform ios
+   */
+  tabBarItemTitleFontSize?: TextStyle['fontSize'] | undefined;
+  /**
+   * @summary Specifies the font weight used for the title of each tab bar item
+   * when tab screen is selected.
+   *
+   * @platform ios
+   */
+  tabBarItemTitleFontWeight?: TextStyle['fontWeight'] | undefined;
+  /**
+   * @summary Specifies the font style used for the title of each tab bar item
+   * when tab screen is selected.
+   *
+   * @platform ios
+   */
+  tabBarItemTitleFontStyle?: TextStyle['fontStyle'] | undefined;
+  /**
+   * @summary Specifies the font color used for the title of each tab bar item
+   * when tab screen is selected.
+   *
+   * Overrides the color defined in `tabBarTintColor` and `tabBarItemIconColor`.
+   *
+   * @platform ios
+   */
+  tabBarItemTitleFontColor?: TextStyle['color'] | undefined;
+  /**
+   * @summary Specifies the title offset for each tab bar item when tab screen
+   * is selected.
+   *
+   * Depending on the iOS version and the device's interface orientation,
+   * this setting may affect the alignment of the text, badge and icon.
+   *
+   * @platform ios
+   */
+  tabBarItemTitlePositionAdjustment?:
+    | {
+        horizontal?: number | undefined;
+        vertical?: number | undefined;
+      }
+    | undefined;
+  /**
+   * @summary Specifies the icon color for each tab bar item when tab screen
+   * is selected.
+   *
+   * This also impacts the title text color.
+   *
+   * Starting from iOS 26, it only applies to selected tab bar item. Other items
+   * adopt a dark or light appearance depending on the theme of the tab bar.
+   *
+   * Is overridden by `tabBarItemTitleFontColor` (for title text color).
+   * Overrides `tabBarTintColor`.
+   *
+   * @platform ios
+   */
+  tabBarItemIconColor?: ColorValue | undefined;
+  /**
+   * @summary Specifies the background color of badges for each tab bar item
+   * when tab screen is selected.
+   *
+   * @platform ios
+   */
+  tabBarItemBadgeBackgroundColor?: ColorValue | undefined;
+}
+
+export interface TabsScreenPropsIOS {
+  /**
+   * @summary Specifies the standard tab bar appearance.
+   *
+   * Allows to customize the appearance depending on the tab bar item layout (stacked,
+   * inline, compact inline) and state (normal, selected, focused, disabled).
+   *
+   * @platform ios
+   */
+  standardAppearance?: TabsScreenAppearanceIOS | undefined;
+  /**
+   * @summary Specifies the tab bar appearace when edge of scrollable content aligns
+   * with the edge of the tab bar.
+   *
+   * Allows to customize the appearance depending on the tab bar item layout (stacked,
+   * inline, compact inline) and state (normal, selected, focused, disabled).
+   *
+   * If this property is `undefined`, UIKit uses `standardAppearance`, modified to
+   * have a transparent background.
+   *
+   * @platform ios
+   */
+  scrollEdgeAppearance?: TabsScreenAppearanceIOS | undefined;
+  /**
+   * @summary Specifies the icon for the tab bar item.
+   *
+   * Supported values:
+   * - `{ type: 'imageSource', imageSource }`
+   *   Uses an image from the provided resource.
+   * - `{ type: 'sfSymbol', name }`
+   *   Uses an SF Symbol with the specified name.
+   * - `{ type: 'xcasset', name }`
+   *   Uses asset from Xcassets.
+   * - `{ type: 'templateSource', templateSource }`
+   *   Uses the provided image as a template image.
+   *   The icon color will depend on the current state
+   *   of the tab bar item and icon color-related props.
+   *
+   * If no `selectedIcon` is provided, this icon will also
+   * be used as the selected state icon.
+   *
+   * @platform ios
+   */
+  icon?: PlatformIconIOS | undefined;
+  /**
+   * @summary Specifies the icon for tab bar item when it is selected.
+   *
+   * Supports the same values as `icon` property.
+   *
+   * To use `selectedIcon`, `icon` must also be provided.
+   *
+   * @platform ios
+   */
+  selectedIcon?: PlatformIconIOS | undefined;
+  /**
+   * @summary System-provided tab bar item with predefined icon and title
+   *
+   * Uses Apple's built-in tab bar items (e.g., bookmarks, contacts, downloads) with
+   * standard iOS styling and localized titles. Custom `icon` or `selectedIcon`
+   * properties will override the system icon, but the system-defined title cannot
+   * be customized.
+   *
+   * @see {@link https://developer.apple.com/documentation/uikit/uitabbaritem/systemitem|UITabBarItem.SystemItem}
+   *
+   * @platform ios
+   */
+  systemItem?: TabsScreenSystemItem | undefined;
+  /**
+   * @summary Specifies if `contentInsetAdjustmentBehavior` of first ScrollView
+   * in first descendant chain from tab screen should be overridden back from `never`
+   * to `automatic`.
+   *
+   * By default, `react-native`'s ScrollView has `contentInsetAdjustmentBehavior`
+   * set to `never` instead of UIKit-default (which is `automatic`). This
+   * prevents ScrollViews from respecting navigation bar insets.
+   * When this prop is set to `true`, `automatic` behavior is reverted.
+   *
+   * Supported only on Fabric.
+   *
+   * @default true
+   *
+   * @platform ios
+   */
+  overrideScrollViewContentInsetAdjustmentBehavior?: boolean | undefined;
+  /**
+   * @summary Allows to override system appearance for the tab bar.
+   *
+   * Does not support dynamic changes to the prop value for the currently visible screen.
+   *
+   * Please note that this prop is marked as **experimental** and might be subject to breaking changes or even removal.
+   * Consider using `colorScheme` on `TabsHost` instead.
+   *
+   * The following values are currently supported:
+   * - `unspecified` - an unspecified interface style,
+   * - `light` - the light interface style,
+   * - `dark` - the dark interface style.
+   *
+   * The supported values correspond to the official UIKit documentation:
+   *
+   * @see {@link https://developer.apple.com/documentation/uikit/uiuserinterfacestyle|UIUserInterfaceStyle}
+   *
+   * @default unspecified
+   *
+   * @platform ios
+   */
+  experimental_userInterfaceStyle?: UserInterfaceStyle | undefined;
+}

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

@@ -0,0 +1,202 @@
+import type {
+  NativeSyntheticEvent,
+  StyleProp,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
+
+import type { TabsScreenPropsIOS } from './TabsScreen.ios.types';
+import type { TabsScreenPropsAndroid } from './TabsScreen.android.types';
+import type { InterfaceOrientation } from '../../shared/types';
+
+// #region General helpers
+
+export type EmptyObject = Record<string, never>;
+
+export type TabsScreenEventHandler<T> = (
+  event: NativeSyntheticEvent<T>,
+) => void;
+
+// Currently iOS-only, but we plan to support it on Android
+export type TabsScreenOrientation = InterfaceOrientation | 'inherit';
+
+// #endregion General helpers
+
+export interface TabsScreenPropsBase {
+  // Control
+  /**
+   * @summary Identifies screen, e.g. when receiving onNativeFocusChange event.
+   *
+   * @platform android, ios
+   */
+  screenKey: string;
+  /**
+   * @summary When set to `true`, prevents native tab selection for this screen.
+   *
+   * @default false
+   *
+   * @platform android, ios
+   */
+  preventNativeSelection?: boolean | undefined;
+
+  // General
+  children?: ViewProps['children'] | undefined;
+  style?: StyleProp<Pick<ViewStyle, 'backgroundColor'>> | undefined;
+  /**
+   * @summary Title of the tab screen, displayed in the tab bar item.
+   *
+   * @platform android, ios
+   */
+  title?: string | undefined;
+  /**
+   * @summary Specifies content of tab bar item badge.
+   *
+   * On iOS, badge is displayed as regular string.
+   *
+   * On Android, the value is interpreted in the following order:
+   * - if the string can be parsed to integer, displays the value as a number;
+   * - otherwise if the string is empty, displays "small dot" badge;
+   * - otherwise, displays the value as a text.
+   *
+   * @platform android, ios
+   */
+  badgeValue?: string | undefined;
+  /**
+   * @summary Specifies which special effects (also known as microinteractions)
+   * are enabled for the tab screen.
+   *
+   * For repeated tab selection (selecting already focused tab bar item),
+   * there are 2 supported special effects:
+   * - `popToRoot` - when Stack is nested inside tab screen and repeated
+   *   selection is detected, the Stack will pop to root screen,
+   * - `scrollToTop` - when there is a ScrollView in first descendant
+   *   chain from tab screen and repeated selection is detected, ScrollView
+   *   will be scrolled to top.
+   *
+   * `popToRoot` has priority over `scrollToTop`.
+   *
+   * @default All special effects are enabled by default.
+   *
+   * @platform android, ios
+   */
+  specialEffects?:
+    | {
+        repeatedTabSelection?:
+          | {
+              /**
+               * @default true
+               */
+              popToRoot?: boolean | undefined;
+              /**
+               * @default true
+               */
+              scrollToTop?: boolean | undefined;
+            }
+          | undefined;
+      }
+    | undefined;
+  /**
+   * @summary Specifies supported orientations for the tab screen.
+   *
+   * Procedure for determining supported orientations:
+   * 1. Traversal initiates from the root component and moves to the
+   *    deepest child possible.
+   * 2. Components are queried for their supported orientations:
+   *    - if `orientation` is explicitly set (e.g., `portrait`,
+   *      `landscape`), it is immediately used,
+   *    - if `orientation` is set to `inherit`, the parent component
+   *      is queried.
+   *
+   * Note that:
+   * - some components (like `SplitHost`) may choose not to query
+   *   its child components,
+   * - Stack v4 implementation **ALWAYS** returns some supported
+   *   orientations (`allButUpsideDown` by default), overriding
+   *   orientation from tab screen.
+   *
+   * The following values are currently supported:
+   *
+   * - `inherit` - tab screen supports the same orientations as parent
+   *   component,
+   * - `all` - tab screen supports all orientations,
+   * - `allButUpsideDown` - tab screen supports all but the upside-down
+   *   portrait interface orientation,
+   * - `portrait` - tab screen supports both portrait-up and portrait-down
+   *   interface orientations,
+   * - 'portraitUp' - tab screen supports a portrait-up interface
+   *   orientation,
+   * - `portraitDown` - tab screen supports a portrait-down interface
+   *   orientation,
+   * - `landscape` - tab screen supports both landscape-left and
+   *   landscape-right interface orientations,
+   * - `landscapeLeft` - tab screen supports landscape-left interface
+   *   orientaion,
+   * - `landscapeRight` - tab screen supports landscape-right interface
+   *   orientaion.
+   *
+   * The supported values (apart from `inherit`, `portrait`, `portraitUp`,
+   * `portraitDown`) correspond to the official UIKit documentation:
+   *
+   * @see {@link https://developer.apple.com/documentation/uikit/uiinterfaceorientationmask|UIInterfaceOrientationMask}
+   *
+   * @default inherit
+   *
+   * @platform ios
+   */
+  orientation?: TabsScreenOrientation | undefined;
+
+  // Accessibility
+  /**
+   * @summary testID for the TabsScreen
+   */
+  testID?: string | undefined;
+  /**
+   * @summary accessibilityLabel for the TabsScreen
+   */
+  accessibilityLabel?: string | undefined;
+  /**
+   * @summary testID for the TabBarItem
+   */
+  tabBarItemTestID?: string | undefined;
+  /**
+   * @summary accessibilityLabel for the TabBarItem
+   *
+   * @supported iOS, Android API level >=26
+   */
+  tabBarItemAccessibilityLabel?: string | undefined;
+
+  // Events
+  /**
+   * @summary A callback that gets invoked when the tab screen will appear.
+   * This is called as soon as the transition begins.
+   *
+   * @platform android, ios
+   */
+  onWillAppear?: TabsScreenEventHandler<EmptyObject> | undefined;
+  /**
+   * @summary A callback that gets invoked when the tab screen did appear.
+   * This is called as soon as the transition ends.
+   *
+   * @platform android, ios
+   */
+  onDidAppear?: TabsScreenEventHandler<EmptyObject> | undefined;
+  /**
+   * @summary A callback that gets invoked when the tab screen will disappear.
+   * This is called as soon as the transition begins.
+   *
+   * @platform android, ios
+   */
+  onWillDisappear?: TabsScreenEventHandler<EmptyObject> | undefined;
+  /**
+   * @summary A callback that gets invoked when the tab screen did disappear.
+   * This is called as soon as the transition ends.
+   *
+   * @platform android, ios
+   */
+  onDidDisappear?: TabsScreenEventHandler<EmptyObject> | undefined;
+}
+
+export interface TabsScreenProps extends TabsScreenPropsBase {
+  ios?: TabsScreenPropsIOS | undefined;
+  android?: TabsScreenPropsAndroid | undefined;
+}

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

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

package/src/components/tabs/screen/useTabsScreen.ts

@@ -0,0 +1,97 @@
+import React from 'react';
+import { findNodeHandle, type NativeSyntheticEvent } from 'react-native';
+import type { NativeProps as TabsScreenAndroidNativeComponentProps } from '../../../fabric/tabs/TabsScreenAndroidNativeComponent';
+import type { NativeProps as TabsScreenIOSNativeComponentProps } from '../../../fabric/tabs/TabsScreenIOSNativeComponent';
+import { RNSLog } from '../../../private';
+import type { EmptyObject, TabsScreenEventHandler } from './TabsScreen.types';
+
+type TabsScreenPlatformNativeComponentProps =
+  | TabsScreenAndroidNativeComponentProps
+  | TabsScreenIOSNativeComponentProps;
+
+interface TabsScreenConfig<T> {
+  componentNodeRef: React.RefObject<React.Component<T> | null>;
+  onDidAppear?: TabsScreenEventHandler<EmptyObject> | undefined;
+  onDidDisappear?: TabsScreenEventHandler<EmptyObject> | undefined;
+  onWillAppear?: TabsScreenEventHandler<EmptyObject> | undefined;
+  onWillDisappear?: TabsScreenEventHandler<EmptyObject> | undefined;
+  screenKey: string;
+}
+
+export function useTabsScreen<
+  T extends TabsScreenPlatformNativeComponentProps,
+>({
+  componentNodeRef,
+  onDidAppear,
+  onDidDisappear,
+  onWillAppear,
+  onWillDisappear,
+  screenKey,
+}: TabsScreenConfig<T>) {
+  const componentNodeHandle = React.useRef<number>(-1);
+
+  React.useEffect(() => {
+    if (componentNodeRef.current != null) {
+      componentNodeHandle.current =
+        findNodeHandle(componentNodeRef.current) ?? -1;
+    } else {
+      componentNodeHandle.current = -1;
+    }
+  }, []);
+
+  const onWillAppearCallback = React.useCallback(
+    (event: NativeSyntheticEvent<EmptyObject>) => {
+      RNSLog.log(
+        `TabsScreen [${componentNodeHandle.current}] onWillAppear received`,
+      );
+      onWillAppear?.(event);
+    },
+    [onWillAppear],
+  );
+
+  const onDidAppearCallback = React.useCallback(
+    (event: NativeSyntheticEvent<EmptyObject>) => {
+      RNSLog.log(
+        `TabsScreen [${componentNodeHandle.current}] onDidAppear received`,
+      );
+      onDidAppear?.(event);
+    },
+    [onDidAppear],
+  );
+
+  const onWillDisappearCallback = React.useCallback(
+    (event: NativeSyntheticEvent<EmptyObject>) => {
+      RNSLog.log(
+        `TabsScreen [${componentNodeHandle.current}] onWillDisappear received`,
+      );
+      onWillDisappear?.(event);
+    },
+    [onWillDisappear],
+  );
+
+  const onDidDisappearCallback = React.useCallback(
+    (event: NativeSyntheticEvent<EmptyObject>) => {
+      RNSLog.log(
+        `TabsScreen [${componentNodeHandle.current}] onDidDisappear received`,
+      );
+      onDidDisappear?.(event);
+    },
+    [onDidDisappear],
+  );
+
+  RNSLog.log(
+    `TabsScreen [${
+      componentNodeHandle.current ?? -1
+    }] render; screenKey: ${screenKey}`,
+  );
+
+  return {
+    componentNodeRef,
+    lifecycleCallbacks: {
+      onWillAppear: onWillAppearCallback,
+      onDidAppear: onDidAppearCallback,
+      onWillDisappear: onWillDisappearCallback,
+      onDidDisappear: onDidDisappearCallback,
+    },
+  };
+}

package/src/experimental/index.ts

@@ -3,12 +3,9 @@
  * BE SUBJECT TO BREAKING CHANGES WITHOUT NOTICE OR LIBRARY MAJOR VERSION CHANGE.
  */
 
-// Types
-export type * from './types';
+// Components & types
 
-// Components
-
-export { default as Stack } from '../components/gamma/stack';
-
-export { default as Split } from '../components/gamma/split';
-export { default as SafeAreaView } from '../components/safe-area/SafeAreaView';
+export * from '../components/gamma/stack';
+export * from '../components/gamma/split';
+export * from '../components/safe-area';
+export * from '../components/gamma/scroll-view-marker';