react-native-screens 5.0.0-alpha.1 → 5.0.0-alpha.3

package/src/components/stack/header/StackHeaderConfig.ios.tsx

@@ -5,6 +5,7 @@ import React, {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useMemo,
   useRef,
 } from 'react';
 import type {
@@ -13,6 +14,7 @@ import type {
 } from './StackHeaderConfig.types';
 import StackHeaderConfigIOSNativeComponent, {
   Commands as StackHeaderConfigIOSNativeCommands,
+  HeaderAppearance,
   MenuItemPressEvent,
   MenuSelectionChangeEvent,
   NativeMenuElementOptionsIOS,
@@ -21,8 +23,9 @@ import type { StackHeaderItemPlacement } from './ios/StackHeaderItem.ios.types';
 import { StackHeaderItemSpacerPlacement } from './ios/StackHeaderItemSpacer.ios.types';
 import StackHeaderItemSpacer from './ios/StackHeaderItemSpacer.ios';
 import StackHeaderItem from './ios/StackHeaderItem.ios';
-import { NativeSyntheticEvent, StyleSheet } from 'react-native';
+import { NativeSyntheticEvent, StyleSheet, processColor } from 'react-native';
 import type {
+  StackHeaderAppearanceIOS,
   StackHeaderInlineCustomItemIOS,
   StackHeaderInlineItemIOS,
   StackHeaderMenuItemOptionsIOS,
@@ -30,8 +33,8 @@ import type {
   StackHeaderSpacerItemIOS,
   StackHeaderTitleCustomItemIOS,
 } from './StackHeaderConfig.ios.types';
-import { findMenuElementByIdInItems, validateMenuCallbacks } from './utils';
-import { resolveIconAssetSources } from './ios/iconUtils.ios';
+import { findMenuElementByIdInMenus, validateMenuCallbacks } from './utils';
+import { resolveIconAssetSources, resolveMenuIcons } from './ios/iconUtils.ios';
 
 /**
  * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
@@ -48,11 +51,18 @@ function StackHeaderConfig(
     leadingItems,
     trailingItems,
     titleItem,
+    titleMenu,
     subtitleItem,
     largeSubtitleItem,
     largeTitle,
     largeSubtitle,
     largeTitleEnabled,
+    prompt,
+    backButtonTitle,
+    backButtonDisplayMode,
+    backButtonMenuEnabled,
+    standardAppearance,
+    scrollEdgeAppearance,
   } = ios ?? {};
 
   const nativeRef =
@@ -95,56 +105,70 @@ function StackHeaderConfig(
     },
   }));
 
+  const allMenus = useMemo(
+    () =>
+      [
+        ...(leadingItems ?? [])
+          .filter(it => it && it.type === 'item')
+          .map(it => it.menu),
+        ...(trailingItems ?? [])
+          .filter(it => it && it.type === 'item')
+          .map(it => it.menu),
+        titleMenu,
+      ].filter(it => !!it),
+    [leadingItems, trailingItems, titleMenu],
+  );
+
   const handleMenuItemPress = useCallback(
     (event: NativeSyntheticEvent<MenuItemPressEvent>) => {
-      const items = Array.of(
-        ...(leadingItems ?? []).filter(it => it && it.type === 'item'),
-        ...(trailingItems ?? []).filter(it => it && it.type === 'item'),
-      );
-      const menuElement = findMenuElementByIdInItems(
-        items,
+      const menuElement = findMenuElementByIdInMenus(
+        allMenus,
         event.nativeEvent.menuItemId,
       );
       if (menuElement && menuElement.type === 'menuItem') {
         menuElement.onPress?.();
       }
     },
-    [leadingItems, trailingItems],
+    [allMenus],
   );
 
-  const allMenuItems = [
-    ...(leadingItems ?? []),
-    ...(trailingItems ?? []),
-  ].filter(it => it && it.type === 'item');
-
   const handleSelectionChange = useCallback(
     (event: NativeSyntheticEvent<MenuSelectionChangeEvent>) => {
       const { menuId, selectedMenuItemIds } = event.nativeEvent;
-      const menu = findMenuElementByIdInItems(allMenuItems, menuId);
+      const menu = findMenuElementByIdInMenus(allMenus, menuId);
       if (menu && menu.type === 'menu') {
         menu.onSelectionChange?.(selectedMenuItemIds);
       }
     },
-    [allMenuItems],
+    [allMenus],
   );
 
   useEffect(() => {
-    for (const item of allMenuItems) {
-      if ('menu' in item && item.menu) {
-        validateMenuCallbacks(item.menu);
-      }
+    for (const menu of allMenus) {
+      validateMenuCallbacks(menu);
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [leadingItems, trailingItems]);
+  }, [allMenus]);
+
+  const resolvedTitleMenu = useMemo(
+    () => (titleMenu != null ? resolveMenuIcons(titleMenu) : undefined),
+    [titleMenu],
+  );
 
   return (
     <StackHeaderConfigIOSNativeComponent
       ref={nativeRef}
       {...restProps}
       collapsable={false}
+      backButtonTitle={backButtonTitle}
+      backButtonDisplayMode={backButtonDisplayMode}
+      backButtonMenuEnabled={backButtonMenuEnabled}
       largeTitle={largeTitle}
       largeSubtitle={largeSubtitle}
       largeTitleEnabled={!!largeTitleEnabled}
+      prompt={prompt}
+      standardAppearance={mapAppearanceToNativeProp(standardAppearance)}
+      scrollEdgeAppearance={mapAppearanceToNativeProp(scrollEdgeAppearance)}
+      titleMenu={resolvedTitleMenu}
       style={styles.config}
       onMenuItemPress={handleMenuItemPress}
       onMenuSelectionChange={handleSelectionChange}>
@@ -158,6 +182,36 @@ function StackHeaderConfig(
   );
 }
 
+function mapAppearanceToNativeProp(
+  appearance?: StackHeaderAppearanceIOS,
+): HeaderAppearance | undefined {
+  if (!appearance) return undefined;
+
+  const {
+    titleFontColor,
+    titleFontWeight,
+    largeTitleFontColor,
+    largeTitleFontWeight,
+    subtitleFontColor,
+    subtitleFontWeight,
+  } = appearance;
+
+  return {
+    ...appearance,
+    titleFontColor: processColor(titleFontColor),
+    titleFontWeight:
+      titleFontWeight !== undefined ? String(titleFontWeight) : undefined,
+    largeTitleFontColor: processColor(largeTitleFontColor),
+    largeTitleFontWeight:
+      largeTitleFontWeight !== undefined
+        ? String(largeTitleFontWeight)
+        : undefined,
+    subtitleFontColor: processColor(subtitleFontColor),
+    subtitleFontWeight:
+      subtitleFontWeight !== undefined ? String(subtitleFontWeight) : undefined,
+  };
+}
+
 function makeItemViewFromItem(
   item:
     | StackHeaderInlineItemIOS

package/src/components/stack/header/StackHeaderConfig.ios.types.ts

@@ -1,4 +1,5 @@
 import type { ReactElement } from 'react';
+import type { TextStyle } from 'react-native';
 import type { PlatformIconIOS } from '../../shared/types';
 import type { StackHeaderMenuIOS } from './ios/StackHeaderMenu.ios.types';
 
@@ -94,6 +95,43 @@ export interface SupportsMenuIOS {
   menu?: StackHeaderMenuIOS | undefined;
 }
 
+export interface SupportsSharedBackgroundIOS {
+  /**
+   * @summary Whether the liquid glass background for this item should be hidden.
+   *
+   * @description
+   * On iOS 26, adjacent bar button items are grouped inside a shared liquid
+   * glass background. Setting this to `true` removes the shared background
+   * from this item.
+   *
+   * @default false
+   *
+   * @platform iOS
+   *
+   * @supported iOS 26 and higher
+   */
+  hidesSharedBackground?: boolean | undefined;
+}
+
+export interface SupportsIdentifierIOS {
+  /**
+   * @summary Stable identifier used to match the item across different screens
+   * for more intelligent animation on transition.
+   *
+   * @description
+   * When navigating between screens, iOS tries to match similarly looking items (i.e. same sfSymbol)
+   * and animate between them. If the heuristic fails, a simpler crossfade is applied.
+   * In a situation where visually different items should be logically considered the same across screens,
+   * you may use this prop to tell this fact to the system. The identifier shouldn't be updated at runtime;
+   * doing so will result in item rebuild and visual flash.
+   *
+   * @platform iOS
+   *
+   * @supported iOS 26 and higher
+   */
+  identifier?: string | undefined;
+}
+
 /**
  * @summary Native header item with text label.
  *
@@ -101,7 +139,9 @@ export interface SupportsMenuIOS {
  */
 export interface StackHeaderInlineItemIOS
   extends StackHeaderBaseItemIOS,
-    SupportsMenuIOS {
+    SupportsMenuIOS,
+    SupportsIdentifierIOS,
+    SupportsSharedBackgroundIOS {
   /**
    * @summary Marks this object as a header item definition.
    *
@@ -126,7 +166,10 @@ export interface StackHeaderInlineItemIOS
  *
  * @platform iOS
  */
-export interface StackHeaderInlineCustomItemIOS extends SupportsMenuIOS {
+export interface StackHeaderInlineCustomItemIOS
+  extends SupportsMenuIOS,
+    SupportsIdentifierIOS,
+    SupportsSharedBackgroundIOS {
   /**
    * @summary A unique identifier within the screen header.
    *
@@ -250,7 +293,172 @@ export interface StackHeaderTitleCustomItemIOS {
   render: () => ReactElement;
 }
 
+/**
+ * @summary Controls how the back button title is displayed.
+ *
+ * @description
+ * - `default`: the system chooses the title depending on available space.
+ *   On iOS < 26 options include: custom title (defaults to previous screen title),
+ *   generic "Back", no title; on iOS >= 26 it's either custom title (if set) or no title.
+ * - `generic`: on iOS < 26, the system uses a generic "Back" title or no title;
+ *   on iOS >= 26 it's the same as `minimal`.
+ * - `minimal`: no title is displayed next to the back button chevron.
+ *
+ * @platform iOS
+ */
+export type StackHeaderBackButtonDisplayModeIOS =
+  | 'default'
+  | 'generic'
+  | 'minimal';
+
+export interface StackHeaderAppearanceIOS {
+  /**
+   * @summary Specifies the font family used for the title of the header.
+   *
+   * @platform ios
+   */
+  titleFontFamily?: TextStyle['fontFamily'] | undefined;
+  /**
+   * @summary Specifies the font size used for the title of the header.
+   *
+   * @platform ios
+   */
+  titleFontSize?: TextStyle['fontSize'] | undefined;
+  /**
+   * @summary Specifies the font weight used for the title of the header.
+   *
+   * @platform ios
+   */
+  titleFontWeight?: TextStyle['fontWeight'] | undefined;
+  /**
+   * @summary Specifies the font style used for the title of the header.
+   *
+   * @platform ios
+   */
+  titleFontStyle?: TextStyle['fontStyle'] | undefined;
+  /**
+   * @summary Specifies the font color used for the title of the header.
+   *
+   * @platform ios
+   */
+  titleFontColor?: TextStyle['color'] | undefined;
+  /**
+   * @summary Specifies the font family used for the large title of the header.
+   *
+   * @platform ios
+   */
+  largeTitleFontFamily?: TextStyle['fontFamily'] | undefined;
+  /**
+   * @summary Specifies the font size used for the large title of the header.
+   *
+   * @platform ios
+   */
+  largeTitleFontSize?: TextStyle['fontSize'] | undefined;
+  /**
+   * @summary Specifies the font weight used for the large title of the header.
+   *
+   * @platform ios
+   */
+  largeTitleFontWeight?: TextStyle['fontWeight'] | undefined;
+  /**
+   * @summary Specifies the font style used for the large title of the header.
+   *
+   * @platform ios
+   */
+  largeTitleFontStyle?: TextStyle['fontStyle'] | undefined;
+  /**
+   * @summary Specifies the font color used for the large title of the header.
+   *
+   * @platform ios
+   */
+  largeTitleFontColor?: TextStyle['color'] | undefined;
+  /**
+   * @summary Specifies the font family used for the subtitle of the header.
+   *
+   * @description Applies to both the regular and the large subtitle.
+   *
+   * @platform ios
+   *
+   * @supported iOS 26 and higher
+   */
+  subtitleFontFamily?: TextStyle['fontFamily'] | undefined;
+  /**
+   * @summary Specifies the font size used for the subtitle of the header.
+   *
+   * @description Applies to both the regular and the large subtitle.
+   *
+   * @platform ios
+   *
+   * @supported iOS 26 and higher
+   */
+  subtitleFontSize?: TextStyle['fontSize'] | undefined;
+  /**
+   * @summary Specifies the font weight used for the subtitle of the header.
+   *
+   * @description Applies to both the regular and the large subtitle.
+   *
+   * @platform ios
+   *
+   * @supported iOS 26 and higher
+   */
+  subtitleFontWeight?: TextStyle['fontWeight'] | undefined;
+  /**
+   * @summary Specifies the font style used for the subtitle of the header.
+   *
+   * @description Applies to both the regular and the large subtitle.
+   *
+   * @platform ios
+   *
+   * @supported iOS 26 and higher
+   */
+  subtitleFontStyle?: TextStyle['fontStyle'] | undefined;
+  /**
+   * @summary Specifies the font color used for the subtitle of the header.
+   *
+   * @description Applies to both the regular and the large subtitle.
+   *
+   * @platform ios
+   *
+   * @supported iOS 26 and higher
+   */
+  subtitleFontColor?: TextStyle['color'] | undefined;
+}
+
 export interface StackHeaderConfigPropsIOS {
+  /**
+   * @summary Title displayed next to the back button on this screen.
+   *
+   * @description
+   * Configured on the screen whose back button it applies to (the screen that
+   * is pushed on top). When unset, the system derives the back title from the
+   * previous screen's `title`.
+   *
+   * @platform iOS
+   */
+  backButtonTitle?: string | undefined;
+  /**
+   * @summary Controls how the back button title is displayed.
+   *
+   * @default 'default'
+   *
+   * @platform iOS
+   */
+  backButtonDisplayMode?: StackHeaderBackButtonDisplayModeIOS | undefined;
+  /**
+   * @summary Whether the back button shows the navigation history menu.
+   *
+   * @description
+   * Configured on the screen whose back button it applies to (the screen that
+   * is pushed on top). When `false`, the navigation history menu is not shown
+   * on either of the gestures that normally open it: long-pressing the back
+   * button and secondary-clicking it (trackpad / mouse right click); tapping
+   * it still pops the screen.
+   *
+   * @default true
+   *
+   * @platform iOS
+   */
+  backButtonMenuEnabled?: boolean | undefined;
   /**
    * @summary Custom item to display as a subtitle.
    *
@@ -287,6 +495,19 @@ export interface StackHeaderConfigPropsIOS {
    * @platform iOS
    */
   titleItem?: StackHeaderTitleCustomItemIOS | undefined;
+  /**
+   * @summary Menu definition for the title context menu.
+   *
+   * @description
+   * Configures a dropdown menu attached to the navigation bar title area.
+   * Works independently of {@link titleItem}; the menu appears for both
+   * plain text and custom view title.
+   *
+   * @platform iOS
+   *
+   * @supported iOS 16 and higher
+   */
+  titleMenu?: StackHeaderMenuIOS | undefined;
   /**
    * @summary A list of items placed starting from the trailing edge.
    * If there is not enough space to fit some items, they are moved to the overflow menu, one by one.
@@ -338,6 +559,34 @@ export interface StackHeaderConfigPropsIOS {
    * @supported iOS 26 and higher
    */
   largeSubtitleItem?: StackHeaderTitleCustomItemIOS | undefined;
+  /**
+   * @summary A single line of text displayed at the top of the navigation bar,
+   * above the title.
+   *
+   * @description
+   * Setting this prop increases the height of the navigation bar.
+   *
+   * @platform iOS
+   */
+  prompt?: string | undefined;
+  /**
+   * @summary Appearance of the header when the edge of scrollable content
+   * is not aligned with the edge of the header.
+   *
+   * @platform ios
+   */
+  standardAppearance?: StackHeaderAppearanceIOS | undefined;
+  /**
+   * @summary Appearance of the header when the edge of scrollable content
+   * is aligned with the edge of the header.
+   *
+   * @description If unset, derives the configuration from `standardAppearance`,
+   * otherwise becomes a standalone definition. In both cases it keeps transparent
+   * background by default (iOS <18).
+   *
+   * @platform ios
+   */
+  scrollEdgeAppearance?: StackHeaderAppearanceIOS | undefined;
 }
 
 export interface StackHeaderConfigCommandsIOS {

package/src/components/stack/header/StackHeaderConfig.types.ts

@@ -11,9 +11,9 @@ export interface StackHeaderConfigPropsBase {
    */
   title?: string | undefined;
   /**
-   * @summary Subtitle displayed in the header. Currently unsupported on Android.
+   * @summary Subtitle displayed in the header.
    *
-   * @platform ios
+   * @platform android, ios
    */
   subtitle?: string | undefined;
   /**

package/src/components/stack/header/ios/StackHeaderItem.ios.tsx

@@ -2,30 +2,8 @@ import React, { useCallback, useMemo } from 'react';
 import StackHeaderItemIOSNativeComponent from '../../../../fabric/stack/StackHeaderItemIOSNativeComponent';
 import type { HeaderItemPressEvent } from '../../../../fabric/stack/StackHeaderItemIOSNativeComponent';
 import type { StackHeaderItemProps } from './StackHeaderItem.ios.types';
-import type {
-  StackHeaderMenuIOS,
-  StackHeaderMenuElementIOS,
-} from './StackHeaderMenu.ios.types';
 import { NativeSyntheticEvent, StyleSheet } from 'react-native';
-import { resolveIconAssetSources } from './iconUtils.ios';
-
-function resolveMenuElementIcons(
-  element: StackHeaderMenuElementIOS,
-): StackHeaderMenuElementIOS {
-  if (element.type === 'menuItem') {
-    if (element.icon == null) {
-      return element;
-    }
-    return { ...element, icon: resolveIconAssetSources(element.icon) };
-  }
-  return resolveMenuIcons(element);
-}
-
-function resolveMenuIcons(menu: StackHeaderMenuIOS): StackHeaderMenuIOS {
-  const resolvedIcon = resolveIconAssetSources(menu.icon);
-  const resolvedChildren = menu.children.map(resolveMenuElementIcons);
-  return { ...menu, icon: resolvedIcon, children: resolvedChildren };
-}
+import { resolveIconAssetSources, resolveMenuIcons } from './iconUtils.ios';
 
 export default function StackHeaderItem(props: StackHeaderItemProps) {
   const { render, onPress, icon, menu, ...rest } = props;

package/src/components/stack/header/ios/StackHeaderItem.ios.types.ts

@@ -12,6 +12,8 @@ export type StackHeaderItemPlacement =
 export type StackHeaderItemProps = {
   placement: StackHeaderItemPlacement;
   itemId?: string | undefined;
+  identifier?: string | undefined;
+  hidesSharedBackground?: boolean | undefined;
   title?: string | undefined;
   icon?: PlatformIconIOS | undefined;
   render?: (() => ReactElement) | undefined;

package/src/components/stack/header/ios/iconUtils.ios.ts

@@ -1,5 +1,9 @@
 import type { PlatformIconIOS as ResolvedPlatformIconIOS } from '../../../../fabric/stack/StackHeaderItemIOSNativeComponent';
 import type { PlatformIconIOS } from '../../../shared/types';
+import type {
+  StackHeaderMenuIOS,
+  StackHeaderMenuElementIOS,
+} from './StackHeaderMenu.ios.types';
 import { Image } from 'react-native';
 
 export function resolveIconAssetSources(
@@ -9,16 +13,48 @@ export function resolveIconAssetSources(
     return undefined;
   }
   if (icon.type === 'imageSource') {
+    const resolvedImageSource = Image.resolveAssetSource(icon.imageSource);
+
+    if (!resolvedImageSource) {
+      return undefined;
+    }
+
     return {
       type: 'imageSource',
-      imageSource: Image.resolveAssetSource(icon.imageSource),
+      imageSource: resolvedImageSource,
     };
   }
   if (icon.type === 'templateSource') {
+    const resolvedTemplateSource = Image.resolveAssetSource(
+      icon.templateSource,
+    );
+
+    if (!resolvedTemplateSource) {
+      return undefined;
+    }
+
     return {
       type: 'templateSource',
-      templateSource: Image.resolveAssetSource(icon.templateSource),
+      templateSource: resolvedTemplateSource,
     };
   }
   return icon;
 }
+
+export function resolveMenuElementIcons(
+  element: StackHeaderMenuElementIOS,
+): StackHeaderMenuElementIOS {
+  if (element.type === 'menuItem') {
+    if (element.icon == null) {
+      return element;
+    }
+    return { ...element, icon: resolveIconAssetSources(element.icon) };
+  }
+  return resolveMenuIcons(element);
+}
+
+export function resolveMenuIcons(menu: StackHeaderMenuIOS): StackHeaderMenuIOS {
+  const resolvedIcon = resolveIconAssetSources(menu.icon);
+  const resolvedChildren = menu.children.map(resolveMenuElementIcons);
+  return { ...menu, icon: resolvedIcon, children: resolvedChildren };
+}

package/src/components/stack/header/utils.ts

@@ -2,20 +2,15 @@ import {
   StackHeaderMenuElementIOS,
   StackHeaderMenuIOS,
 } from './ios/StackHeaderMenu.ios.types';
-import { SupportsMenuIOS } from './StackHeaderConfig.ios.types';
 
-export function findMenuElementByIdInItems(
-  items: SupportsMenuIOS[],
+export function findMenuElementByIdInMenus(
+  menus: StackHeaderMenuIOS[],
   id: string,
 ): StackHeaderMenuElementIOS | null {
-  for (const item of items) {
-    if (item.menu === undefined) {
-      continue;
-    }
-
-    const menu = findMenuElementById(item.menu, id);
-    if (menu !== null) {
-      return menu;
+  for (const menu of menus) {
+    const element = findMenuElementById(menu, id);
+    if (element !== null) {
+      return element;
     }
   }
 

package/src/components/stack/host/StackHost.tsx

@@ -6,9 +6,11 @@ import type { StackHostProps } from './StackHost.types';
 /**
  * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
  */
-function StackHost({ children, ref }: StackHostProps) {
+function StackHost(props: StackHostProps) {
+  const { children, ref, ...restProps } = props;
+
   return (
-    <StackHostNativeComponent ref={ref} style={styles.container}>
+    <StackHostNativeComponent ref={ref} style={styles.container} {...restProps}>
       {children}
     </StackHostNativeComponent>
   );

package/src/components/stack/host/StackHost.types.ts

@@ -1,13 +1,37 @@
 import React from 'react';
-import type { ReactNativeElement, ViewProps } from 'react-native';
+import type { HostInstance, ViewProps } from 'react-native';
 import { type NativeProps } from '../../../fabric/stack/StackHostNativeComponent';
+import type { ColorScheme } from '../../shared/types';
+
+export type StackHostColorScheme = ColorScheme | 'inherit';
 
 export type StackHostProps = {
+  // General
   children: NonNullable<ViewProps['children']>;
   // TODO: Work on these types
   ref?:
-    | React.RefObject<
-        (React.Component<NativeProps> & ReactNativeElement) | null
-      >
+    | React.RefObject<(React.Component<NativeProps> & HostInstance) | null>
     | 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.
+   *
+   * @remarks
+   * Color scheme isn't currently supported on iOS.
+   *
+   * On Android, changing the effective color scheme rebuilds the header.
+   * Toolbar menu state survives the rebuild: checkbox/radio selections and
+   * changes applied via the `updateToolbarMenuElements` view command are
+   * reapplied to the new toolbar.
+   *
+   * @default inherit
+   *
+   * @platform android
+   */
+  colorScheme?: StackHostColorScheme | undefined;
 };