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

package/src/components/gamma/stack/index.ts

@@ -1,15 +1,36 @@
-import StackHost from './StackHost';
-import StackScreen from './StackScreen';
+import { StackHost } from './host';
+import { StackScreen } from './screen';
+import { StackHeaderConfig } from './header';
 
-export * from './StackHost.types';
-export * from './StackScreen.types';
+export type { StackHostProps } from './host';
+
+export type {
+  OnDismissEventPayload,
+  EmptyEventPayload, // TODO: Remove this from public types (we need one shared type for this)
+  OnDismissEvent,
+  StackScreenActivityMode,
+  StackScreenEventHandler,
+  StackScreenProps,
+} from './screen';
+
+export type {
+  StackHeaderConfigPropsBase,
+  StackHeaderConfigProps,
+  // Android
+  StackHeaderTypeAndroid,
+  StackHeaderBackgroundSubviewCollapseModeAndroid,
+  StackHeaderToolbarSubviewAndroid,
+  StackHeaderBackgroundSubviewAndroid,
+  StackHeaderConfigPropsAndroid,
+  // iOS
+  StackHeaderConfigPropsIOS,
+} from './header';
 
 /**
  * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
  */
-const Stack = {
+export const Stack = {
   Host: StackHost,
   Screen: StackScreen,
+  HeaderConfig: StackHeaderConfig,
 };
-
-export default Stack;

package/src/components/gamma/stack/{StackScreen.tsx → screen/StackScreen.tsx}

@@ -1,8 +1,8 @@
 import React from 'react';
 import { StyleSheet } from 'react-native';
-import StackScreenNativeComponent from '../../../fabric/gamma/stack/StackScreenNativeComponent';
+import StackScreenNativeComponent from '../../../../fabric/gamma/stack/StackScreenNativeComponent';
 import { OnDismissEvent, StackScreenProps } from './StackScreen.types';
-import { useRenderDebugInfo } from '../../../private/';
+import { useRenderDebugInfo } from '../../../../private';
 
 /**
  * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE

package/src/components/gamma/stack/{StackScreen.types.ts → screen/StackScreen.types.ts}

@@ -15,22 +15,22 @@ export type StackScreenEventHandler = (
 ) => void;
 
 export type StackScreenProps = {
-  children?: ViewProps['children'];
+  children?: ViewProps['children'] | undefined;
 
   // Control
   activityMode: StackScreenActivityMode;
   screenKey: string;
 
   // Events
-  onWillAppear?: StackScreenEventHandler;
-  onDidAppear?: StackScreenEventHandler;
-  onWillDisappear?: StackScreenEventHandler;
-  onDidDisappear?: StackScreenEventHandler;
+  onWillAppear?: StackScreenEventHandler | undefined;
+  onDidAppear?: StackScreenEventHandler | undefined;
+  onWillDisappear?: StackScreenEventHandler | undefined;
+  onDidDisappear?: StackScreenEventHandler | undefined;
 
-  onDismiss?: (screenKey: string) => void;
-  onNativeDismiss?: (screenKey: string) => void;
-  onNativeDismissPrevented?: StackScreenEventHandler;
+  onDismiss?: ((screenKey: string) => void) | undefined;
+  onNativeDismiss?: ((screenKey: string) => void) | undefined;
+  onNativeDismissPrevented?: StackScreenEventHandler | undefined;
 
   // Configuration
-  preventNativeDismiss?: boolean;
+  preventNativeDismiss?: boolean | undefined;
 };

package/src/components/gamma/stack/screen/index.ts

@@ -0,0 +1,3 @@
+export { default as StackScreen } from './StackScreen';
+
+export type * from './StackScreen.types';

package/src/components/helpers/PlatformUtils.ts

@@ -0,0 +1,4 @@
+import { Platform } from 'react-native';
+
+export const isIOS26OrHigher =
+  Platform.OS === 'ios' && parseInt(Platform.Version, 10) >= 26;

package/src/components/helpers/prepareHeaderBarButtonItems.ts

@@ -8,10 +8,12 @@ const prepareMenu = (
   menu: HeaderBarButtonItemWithMenu['menu'],
   index: number,
   side: 'left' | 'right',
+  path: string = '',
 ): HeaderBarButtonItemWithMenu['menu'] => {
   return {
     ...menu,
     items: menu.items.map((menuItem, menuIndex) => {
+      const currentPath = path ? `${path}.${menuIndex}` : `${menuIndex}`;
       const iconType = menuItem.icon?.type;
       const sfSymbolName =
         iconType === 'sfSymbol' ? menuItem.icon?.name : undefined;
@@ -32,7 +34,7 @@ const prepareMenu = (
           xcassetName,
           imageSource,
           templateSource,
-          ...prepareMenu(menuItem, menuIndex, side),
+          ...prepareMenu(menuItem, index, side, currentPath),
         };
       }
       return {
@@ -41,7 +43,7 @@ const prepareMenu = (
         xcassetName,
         imageSource,
         templateSource,
-        menuId: `${menuIndex}-${index}-${side}`,
+        menuId: `${currentPath}-${index}-${side}`,
       };
     }),
   };

package/src/components/safe-area/SafeAreaView.tsx

@@ -9,7 +9,7 @@ import SafeAreaViewNativeComponent, {
 } from '../../fabric/safe-area/SafeAreaViewNativeComponent';
 import { StyleSheet } from 'react-native';
 
-function SafeAreaView(props: SafeAreaViewProps) {
+export function SafeAreaView(props: SafeAreaViewProps) {
   return (
     <SafeAreaViewNativeComponent
       {...props}
@@ -19,8 +19,6 @@ function SafeAreaView(props: SafeAreaViewProps) {
   );
 }
 
-export default SafeAreaView;
-
 function getNativeEdgesProp(
   edges: SafeAreaViewProps['edges'],
 ): SafeAreaViewNativeComponentProps['edges'] {

package/src/components/safe-area/SafeAreaView.types.ts

@@ -8,7 +8,7 @@ export type Edge = 'top' | 'right' | 'bottom' | 'left';
 export type InsetType = 'all' | 'system' | 'interface';
 
 export interface SafeAreaViewProps extends ViewProps {
-  edges?: Readonly<Partial<Record<Edge, boolean>>>;
+  edges?: Readonly<Partial<Record<Edge, boolean>>> | undefined;
   // Android-only
-  insetType?: InsetType;
+  insetType?: InsetType | undefined;
 }

package/src/components/safe-area/index.ts

@@ -0,0 +1,3 @@
+export { SafeAreaView } from './SafeAreaView';
+
+export type { Edge, InsetType, SafeAreaViewProps } from './SafeAreaView.types';

package/src/components/shared/types.ts

@@ -1,3 +1,40 @@
+export type BlurEffect =
+  | 'none'
+  | 'extraLight'
+  | 'light'
+  | 'dark'
+  | 'regular'
+  | 'prominent'
+  | 'systemUltraThinMaterial'
+  | 'systemThinMaterial'
+  | 'systemMaterial'
+  | 'systemThickMaterial'
+  | 'systemChromeMaterial'
+  | 'systemUltraThinMaterialLight'
+  | 'systemThinMaterialLight'
+  | 'systemMaterialLight'
+  | 'systemThickMaterialLight'
+  | 'systemChromeMaterialLight'
+  | 'systemUltraThinMaterialDark'
+  | 'systemThinMaterialDark'
+  | 'systemMaterialDark'
+  | 'systemThickMaterialDark'
+  | 'systemChromeMaterialDark';
+
+export type ColorScheme = 'light' | 'dark';
+
+export type Direction = 'ltr' | 'rtl';
+
+export type InterfaceOrientation =
+  | 'all'
+  | 'allButUpsideDown'
+  | 'portrait'
+  | 'portraitUp'
+  | 'portraitDown'
+  | 'landscape'
+  | 'landscapeLeft'
+  | 'landscapeRight';
+
 export type ScrollEdgeEffect = 'automatic' | 'hard' | 'soft' | 'hidden';
 
 export type UserInterfaceStyle = 'unspecified' | 'light' | 'dark';

package/src/components/tabs/{TabsAccessory.tsx → bottom-accessory/TabsBottomAccessory.tsx}

@@ -1,12 +1,12 @@
 import React from 'react';
-import TabsBottomAccessoryNativeComponent from '../../fabric/tabs/TabsBottomAccessoryNativeComponent';
-import { TabsAccessoryProps } from './TabsAccessory.types';
+import TabsBottomAccessoryNativeComponent from '../../../fabric/tabs/TabsBottomAccessoryNativeComponent';
+import { TabsBottomAccessoryProps } from './TabsBottomAccessory.types';
 import { StyleSheet } from 'react-native';
 
 /**
  * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
  */
-export default function TabsAccessory(props: TabsAccessoryProps) {
+export default function TabsBottomAccessory(props: TabsBottomAccessoryProps) {
   return (
     <TabsBottomAccessoryNativeComponent
       {...props}

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

@@ -0,0 +1,15 @@
+import { NativeSyntheticEvent, ViewProps } from 'react-native';
+
+export type TabsBottomAccessoryEnvironment = 'regular' | 'inline';
+
+export type TabsBottomAccessoryEnvironmentChangeEvent = {
+  environment: TabsBottomAccessoryEnvironment;
+};
+
+export type TabsBottomAccessoryProps = ViewProps & {
+  onEnvironmentChange?:
+    | ((
+        event: NativeSyntheticEvent<TabsBottomAccessoryEnvironmentChangeEvent>,
+      ) => void)
+    | undefined;
+};

package/src/components/tabs/bottom-accessory/TabsBottomAccessoryContent.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import { TabsBottomAccessoryContentProps } from './TabsBottomAccessoryContent.types';
+import TabsBottomAccessoryContentNativeComponent from '../../../fabric/tabs/TabsBottomAccessoryContentNativeComponent';
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+export default function TabsBottomAccessoryContent(
+  props: TabsBottomAccessoryContentProps,
+) {
+  return (
+    <TabsBottomAccessoryContentNativeComponent
+      {...props}
+      collapsable={false}
+      style={[props.style, StyleSheet.absoluteFill]}
+    />
+  );
+}

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,
+    navState,
+    ...filteredBaseProps
+  } = baseProps;
+
+  const componentNodeRef =
+    React.useRef<React.Component<TabsHostAndroidNativeComponentProps>>(null);
+
+  const { onTabSelected: onTabSelectedCallback } =
+    useTabsHost<TabsHostAndroidNativeComponentProps>({
+      componentNodeRef,
+      onTabSelected,
+    });
+
+  return (
+    <TabsHostAndroidNativeComponent
+      style={[styles.fillParent, { direction }]}
+      navState={navState}
+      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,
+    navState,
+    ...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}
+      navState={navState}
+      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;
+}