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

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

@@ -0,0 +1,117 @@
+import type {
+  PlatformIconAndroidDrawableResource,
+  PlatformIconIOSSfSymbol,
+  PlatformIconIOSTemplate,
+  PlatformIconIOSXcasset,
+  PlatformIconShared,
+} from '../../shared/types';
+
+/**
+ * How the tab bar renders an `imageSource` icon on iOS. The names follow
+ * `UIImage.RenderingMode`.
+ *
+ * - `default` - the tab bar's default for images, also used when
+ *   `renderingMode` is unset: the image keeps its own colors, as with
+ *   `original`. This is not UIKit's automatic mode, in which the tab bar would
+ *   draw the image as a template image.
+ * - `template` - the image is used as a template image: its shape is drawn in
+ *   the state-dependent item icon color (`tabBarItemIconColor`,
+ *   `tabBarTintColor`).
+ * - `original` - the image keeps its own colors and ignores the item icon color.
+ */
+export type TabsScreenIconImageRenderingModeIOS =
+  | 'default'
+  | 'template'
+  | 'original';
+
+/**
+ * How the tab bar renders an `sfSymbol` icon on iOS. The names follow the
+ * SF Symbols rendering modes.
+ *
+ * - `default` - the system behavior (UIKit's automatic mode), also used when
+ *   `renderingMode` is unset: system symbols are rendered in a single color,
+ *   the state-dependent item icon color; for custom symbols the rendering mode
+ *   set in the asset catalog may change it.
+ * - `monochrome` - the symbol is rendered in a single color: the
+ *   state-dependent item icon color (`tabBarItemIconColor`, `tabBarTintColor`).
+ * - `original` - the symbol keeps its own colors (Apple's "multicolor"
+ *   rendering) and ignores the item icon color. A symbol without color layers
+ *   is drawn as authored.
+ */
+export type TabsScreenIconSymbolRenderingModeIOS =
+  | 'default'
+  | 'monochrome'
+  | 'original';
+
+type WithImageRenderingMode<Icon> = Icon & {
+  /**
+   * @summary How the tab bar renders this image. See
+   * `TabsScreenIconImageRenderingModeIOS`.
+   *
+   * Defaults to `default`, which keeps the image's own colors.
+   *
+   * `icon` and `selectedIcon` may use different values.
+   */
+  renderingMode?: TabsScreenIconImageRenderingModeIOS | undefined;
+};
+
+type WithSymbolRenderingMode<Icon> = Icon & {
+  /**
+   * @summary How the tab bar renders this symbol. See
+   * `TabsScreenIconSymbolRenderingModeIOS`.
+   *
+   * Defaults to `default`, the system behavior. Set `renderingMode`
+   * explicitly to be independent of it.
+   *
+   * `icon` and `selectedIcon` may use different values.
+   */
+  renderingMode?: TabsScreenIconSymbolRenderingModeIOS | undefined;
+};
+
+/**
+ * How the tab bar tints an `imageSource` or `drawableResource` icon on Android.
+ *
+ * - `default` - the tab bar's default, also used when `tinting` is unset: the
+ *   icon is tinted, as with `tinted`.
+ * - `tinted` - the icon is drawn in the state-dependent item icon color
+ *   (`tabBarItemIconColor`).
+ * - `original` - the icon keeps its own colors and ignores the item icon color,
+ *   e.g. a multicolor VectorDrawable.
+ */
+export type TabsScreenIconTintingAndroid = 'default' | 'tinted' | 'original';
+
+type WithTinting<Icon> = Icon & {
+  /**
+   * @summary How the tab bar tints this icon. See
+   * `TabsScreenIconTintingAndroid`.
+   *
+   * Defaults to `default`, which tints the icon.
+   *
+   * `icon` and `selectedIcon` may use different values.
+   */
+  tinting?: TabsScreenIconTintingAndroid | undefined;
+};
+
+/**
+ * @deprecated Use `{ type: 'imageSource', imageSource, renderingMode: 'template' }` instead.
+ */
+export type TabsScreenIconTemplateIOS = PlatformIconIOSTemplate;
+
+/**
+ * @deprecated Use `{ type: 'sfSymbol', name }` for custom symbols from the asset
+ * catalog, or `{ type: 'imageSource', imageSource: { uri: 'name' } }` for asset
+ * catalog images (append `.png` to names containing a dot). `imageSource` keeps
+ * the image's own colors by default, so for an asset whose "Render As" is not
+ * `Original Image`, add `renderingMode: 'template'`.
+ */
+export type TabsScreenIconXcassetIOS = PlatformIconIOSXcasset;
+
+export type TabsScreenIconIOS =
+  | WithSymbolRenderingMode<PlatformIconIOSSfSymbol>
+  | TabsScreenIconXcassetIOS
+  | TabsScreenIconTemplateIOS
+  | WithImageRenderingMode<PlatformIconShared>;
+
+export type TabsScreenIconAndroid =
+  | WithTinting<PlatformIconAndroidDrawableResource>
+  | WithTinting<PlatformIconShared>;

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

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

package/src/fabric/legacy/ScreenStackHeaderSubviewNativeComponent.ts

@@ -7,6 +7,8 @@ import type {
   ViewProps,
 } from 'react-native';
 
+export type HeaderSubviewVisibilityPriority = 'low' | 'standard' | 'high';
+
 export type HeaderSubviewTypes =
   | 'back'
   | 'right'
@@ -18,6 +20,10 @@ export type HeaderSubviewTypes =
 export interface NativeProps extends ViewProps {
   type?: CT.WithDefault<HeaderSubviewTypes, 'left'>;
   hidesSharedBackground?: boolean | undefined;
+  visibilityPriority?: CT.WithDefault<
+    HeaderSubviewVisibilityPriority,
+    'standard'
+  >;
   synchronousShadowStateUpdatesEnabled?: CT.WithDefault<boolean, true>;
 }
 

package/src/fabric/legacy/ScreenStackNativeComponent.ts

@@ -14,6 +14,8 @@ type FinishTransitioningEvent = Readonly<{}>;
 export interface NativeProps extends ViewProps {
   nativeContainerBackgroundColor?: ColorValue | undefined;
 
+  disableDefaultMenuAction?: CT.WithDefault<boolean, false>;
+
   onFinishTransitioning?:
     | CT.DirectEventHandler<FinishTransitioningEvent>
     | undefined;

package/src/fabric/stack/StackHeaderConfigIOSNativeComponent.ts

@@ -15,6 +15,14 @@ import { UnsafeMixed } from '../codegenUtils';
 
 type BackButtonDisplayMode = 'default' | 'generic' | 'minimal';
 
+type MinimizationBehavior =
+  | 'automatic'
+  | 'never'
+  | 'onScrollDown'
+  | 'onScrollUp';
+
+type RestorationBehavior = 'automatic' | 'atScrollEdge';
+
 export type HeaderAppearance = {
   titleFontFamily?: string | undefined;
   titleFontSize?: CT.Float | undefined;
@@ -60,6 +68,9 @@ export interface NativeProps extends ViewProps {
 
   prompt?: string | undefined;
 
+  minimizationBehavior?: CT.WithDefault<MinimizationBehavior, 'automatic'>;
+  restorationBehavior?: CT.WithDefault<RestorationBehavior, 'automatic'>;
+
   titleMenu?: UnsafeMixed<StackHeaderMenuIOS> | undefined;
 
   standardAppearance?: UnsafeMixed<HeaderAppearance> | undefined;

package/src/fabric/stack/StackHeaderItemIOSNativeComponent.ts

@@ -16,6 +16,8 @@ export type Placement =
   | 'subtitle'
   | 'largeSubtitle';
 
+export type Variant = 'plain' | 'prominent';
+
 export type StackHeaderMenuItemIOS = {
   id: string;
   type: 'menuItem';
@@ -67,14 +69,23 @@ export type PlatformIconIOS =
   | PlatformIconIOSTemplate
   | PlatformIconShared;
 
+export type StackHeaderItemVisibilityPriorityIOS = 'low' | 'standard' | 'high';
+
 export interface NativeProps extends ViewProps {
   placement?: CT.WithDefault<Placement, 'trailing'>;
   itemId?: string | undefined;
   identifier?: string | undefined;
   hidesSharedBackground?: CT.WithDefault<boolean, false>;
+  visibilityPriority?: CT.WithDefault<
+    StackHeaderItemVisibilityPriorityIOS,
+    'standard'
+  >;
   title?: string | undefined;
   icon?: UnsafeMixed<PlatformIconIOS> | undefined;
   menu?: UnsafeMixed<StackHeaderMenuIOS> | undefined;
+  menuRepresentation?: UnsafeMixed<StackHeaderMenuIOS> | undefined;
+  variant?: CT.WithDefault<Variant, 'plain'>;
+  disabled?: CT.WithDefault<boolean, false>;
   respondsToOnPress?: CT.WithDefault<boolean, false>;
   onHeaderItemPress?: CT.DirectEventHandler<HeaderItemPressEvent> | undefined;
 }

package/src/fabric/tabs/TabsHostIOSNativeComponent.ts

@@ -58,6 +58,8 @@ type TabBarMinimizeBehavior =
 
 type TabBarControllerMode = 'automatic' | 'tabBar' | 'tabSidebar';
 
+type TabBarSidebarPreferredPlacement = 'automatic' | 'sidebar' | 'tabBar';
+
 // #endregion iOS-specific helpers
 
 export interface NativeProps extends ViewProps {
@@ -89,7 +91,12 @@ export interface NativeProps extends ViewProps {
   tabBarTintColor?: ColorValue | undefined;
   tabBarMinimizeBehavior?: CT.WithDefault<TabBarMinimizeBehavior, 'automatic'>;
   tabBarControllerMode?: CT.WithDefault<TabBarControllerMode, 'automatic'>;
+  tabBarSidebarPreferredPlacement?: CT.WithDefault<
+    TabBarSidebarPreferredPlacement,
+    'automatic'
+  >;
   bottomAccessoryHidden?: CT.WithDefault<boolean, false>;
+  prominentScreenKey?: string | undefined;
 }
 
 export default codegenNativeComponent<NativeProps>('RNSTabsHostIOS', {

package/src/fabric/tabs/TabsScreenAndroidNativeComponent.ts

@@ -24,6 +24,8 @@ type TabBarItemLabelVisibilityMode =
   | 'labeled'
   | 'unlabeled';
 
+export type IconTinting = 'default' | 'tinted' | 'original';
+
 export type ItemStateAppearance = {
   tabBarItemTitleFontColor?: ProcessedColorValue | null | undefined;
   tabBarItemIconColor?: ProcessedColorValue | null | undefined;
@@ -48,9 +50,14 @@ export type Appearance = {
   focused?: ItemStateAppearance | undefined;
   disabled?: ItemStateAppearance | undefined;
 
+  // Per-tab icon size (dp); 0/unset = system default.
+  tabBarItemIconSize?: CT.Float | undefined;
+
   // TabBarItem - Active Indicator
   tabBarItemActiveIndicatorColor?: ProcessedColorValue | null | undefined;
   tabBarItemActiveIndicatorEnabled?: CT.WithDefault<boolean, true>;
+  tabBarItemActiveIndicatorWidth?: CT.Float | undefined;
+  tabBarItemActiveIndicatorHeight?: CT.Float | undefined;
 
   // TabBarItem - Label
   tabBarItemTitleFontFamily?: string | undefined;
@@ -103,6 +110,8 @@ export interface NativeProps extends ViewProps {
   imageIconResource?: ImageSource | undefined;
   selectedDrawableIconResourceName?: string | undefined;
   selectedImageIconResource?: ImageSource | undefined;
+  iconTinting?: CT.WithDefault<IconTinting, 'default'>;
+  selectedIconTinting?: CT.WithDefault<IconTinting, 'default'>;
 
   // Appearance
   standardAppearance?: Appearance | undefined;

package/src/fabric/tabs/TabsScreenIOSNativeComponent.ts

@@ -20,8 +20,12 @@ type GenericEmptyEvent = Readonly<{}>;
 
 // #region iOS-specific helpers
 
-// iOS-specific: SFSymbol, image as a template usage
-export type IconType = 'image' | 'template' | 'sfSymbol' | 'xcasset';
+// iOS-specific: SFSymbol, xcasset usage
+export type IconType = 'image' | 'sfSymbol' | 'xcasset';
+
+export type IconImageRenderingMode = 'default' | 'template' | 'original';
+
+export type IconSymbolRenderingMode = 'default' | 'monochrome' | 'original';
 
 export type ItemStateAppearance = {
   tabBarItemTitleFontFamily?: string | undefined;
@@ -106,6 +110,8 @@ type SystemItem =
   | 'search'
   | 'topRated';
 
+type TabRole = 'none' | 'search';
+
 type UserInterfaceStyle = 'unspecified' | 'light' | 'dark';
 
 // #endregion iOS-specific helpers
@@ -146,6 +152,8 @@ export interface NativeProps extends ViewProps {
   // Tab config
   isTitleUndefined?: CT.WithDefault<boolean, true>;
   systemItem?: CT.WithDefault<SystemItem, 'none'>;
+  tabRole?: CT.WithDefault<TabRole, 'none'>;
+  automaticallyActivatesSearch?: CT.WithDefault<boolean, false>;
 
   // Appearance
   standardAppearance?: UnsafeMixed<Appearance> | undefined;
@@ -153,8 +161,18 @@ export interface NativeProps extends ViewProps {
 
   // Icons
   iconType?: CT.WithDefault<IconType, 'sfSymbol'>;
+  iconImageRenderingMode?: CT.WithDefault<IconImageRenderingMode, 'default'>;
+  iconSymbolRenderingMode?: CT.WithDefault<IconSymbolRenderingMode, 'default'>;
   iconImageSource?: ImageSource | undefined;
   iconResourceName?: string | undefined;
+  selectedIconImageRenderingMode?: CT.WithDefault<
+    IconImageRenderingMode,
+    'default'
+  >;
+  selectedIconSymbolRenderingMode?: CT.WithDefault<
+    IconSymbolRenderingMode,
+    'default'
+  >;
   selectedIconImageSource?: ImageSource | undefined;
   selectedIconResourceName?: string | undefined;
 

package/src/legacy/components/ScreenStackItem.tsx

@@ -18,7 +18,10 @@ import Screen, { type ScreenInstance } from './Screen';
 import ScreenStack from './ScreenStack';
 import { RNSScreensRefContext } from '../contexts';
 import { FooterComponent } from './ScreenFooter';
-import { SafeAreaViewProps } from '../../components/safe-area/SafeAreaView.types';
+import type {
+  Edge,
+  SafeAreaViewProps,
+} from '../../components/safe-area/SafeAreaView.types';
 import { SafeAreaView } from '../../components/safe-area/SafeAreaView';
 import { featureFlags } from '../../flags';
 import { isIOS26OrHigher } from '../../components/helpers/PlatformUtils';
@@ -34,6 +37,30 @@ type Props = Omit<
   screenId: string;
   headerConfig?: ScreenStackHeaderConfigProps | undefined;
   contentStyle?: StyleProp<ViewStyle> | undefined;
+  /**
+   * Per-edge override of the safe area insets applied to the screen's content.
+   *
+   * On iOS 26+ the screen is laid out under the navigation bar and its content
+   * is wrapped in a `SafeAreaView`. By default, the top edge is applied for
+   * non-transparent header. Edges explicitly set to `true` or `false` override
+   * the default.
+   *
+   * When `ScrollView` with `contentInsetAdjustmentBehavior="automatic"` is used
+   * as Screen's content, setting `top: false` might mitigate some problems like
+   * "jumping" behavior with non-transparent header and large title.
+   *
+   * Limitation: with `top: false`, a `formSheet` using `fitToContents` with a
+   * visible header is sized to the content alone, without room for the header,
+   * which overlaps the top of the content.
+   *
+   * Has no effect below iOS 26 and on other platforms.
+   *
+   * Please note that this prop is marked as unstable and might be subject of
+   * breaking changes, including removal.
+   *
+   * @platform ios
+   */
+  unstable_safeAreaEdges?: SafeAreaViewProps['edges'] | undefined;
 };
 
 function ScreenStackItem(
@@ -51,6 +78,8 @@ function ScreenStackItem(
     scrollEdgeEffects,
     // eslint-disable-next-line camelcase
     unstable_sheetFooter,
+    // eslint-disable-next-line camelcase
+    unstable_safeAreaEdges,
     ...rest
   }: Props,
   ref: React.ForwardedRef<ScreenInstance>,
@@ -123,6 +152,11 @@ function ScreenStackItem(
     contentStyle = contentWrapperStyles;
   }
 
+  // On iOS 26+ the screen is laid out under the navigation bar also when the header is opaque
+  // (see `+[RNSScreenStackHeaderConfig screensExtendUnderOpaqueNavigationBar]`), so the content
+  // is inset by our `SafeAreaView`. See `getSafeAreaEdges` for the applied edges. The
+  // `SafeAreaView` is rendered regardless of `unstable_safeAreaEdges` so that changing it does not
+  // remount the content.
   const shouldUseSafeAreaView = isIOS26OrHigher;
 
   const content = (
@@ -133,7 +167,8 @@ function ScreenStackItem(
           style={debugContainerStyle}
           stackPresentation={stackPresentationWithDefault}>
           {shouldUseSafeAreaView ? (
-            <SafeAreaView edges={getSafeAreaEdges(headerConfig)}>
+            <SafeAreaView
+              edges={getSafeAreaEdges(headerConfig, unstable_safeAreaEdges)}>
               {children}
             </SafeAreaView>
           ) : (
@@ -282,24 +317,36 @@ function extractScreenStyles(style: StyleProp<ViewStyle>): SplitStyleResult {
 }
 
 function getSafeAreaEdges(
-  headerConfig?: ScreenStackHeaderConfigProps,
+  headerConfig: ScreenStackHeaderConfigProps | undefined,
+  edgesOverride: SafeAreaViewProps['edges'],
 ): SafeAreaViewProps['edges'] {
-  if (Platform.OS !== 'ios' || parseInt(Platform.Version, 10) < 26) {
+  if (!isIOS26OrHigher) {
     return {};
   }
 
-  let defaultEdges: SafeAreaViewProps['edges'];
-  if (headerConfig?.translucent || headerConfig?.hidden) {
-    defaultEdges = {};
-  } else {
-    defaultEdges = {
-      top: true,
-    };
+  // On iOS 26+ the screen extends under the navigation bar regardless of the header configuration
+  // (see `+[RNSScreenStackHeaderConfig screensExtendUnderOpaqueNavigationBar]`), so by default the
+  // content is inset from the top whenever the header is visible and opaque. Translucent and hidden
+  // headers keep the content under the bar / status bar, as on other iOS versions.
+  const edges: Partial<Record<Edge, boolean>> =
+    headerConfig?.translucent || headerConfig?.hidden ? {} : { top: true };
+
+  // Only edges explicitly set by the user override the defaults. `undefined` must not be copied,
+  // as `SafeAreaView` treats a present-but-undefined edge as disabled.
+  if (edgesOverride) {
+    for (const edge of SAFE_AREA_EDGES) {
+      const value = edgesOverride[edge];
+      if (value !== undefined) {
+        edges[edge] = value;
+      }
+    }
   }
 
-  return defaultEdges;
+  return edges;
 }
 
+const SAFE_AREA_EDGES: readonly Edge[] = ['top', 'right', 'bottom', 'left'];
+
 const styles = StyleSheet.create({
   container: {
     flex: 1,

package/src/legacy/types.ts

@@ -659,6 +659,12 @@ export interface ScreenStackProps extends ViewProps, GestureProps {
     | undefined;
   ref?: React.MutableRefObject<React.Ref<View>> | undefined;
   nativeContainerStyle?: ScreenStackNativeContainerStyleProps | undefined;
+  /**
+   * When true, prevents UIKit from auto-popping on Menu at stack depth > 1 so the
+   * press can reach JS. Requires `TVEventControl.enableTVMenuKey()`.
+   * @platform tvOS
+   */
+  disableDefaultMenuAction?: boolean | undefined;
 }
 
 export interface ScreenStackHeaderConfigProps extends ViewProps {
@@ -1114,6 +1120,14 @@ export interface SearchBarProps {
   shouldShowHintSearchIcon?: boolean | undefined;
 }
 
+/**
+ * Priority deciding which header items are given up first when they do not fit.
+ * Each value maps to the matching UIKit constant.
+ *
+ * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitemvisibilitypriority
+ */
+export type HeaderBarButtonItemVisibilityPriority = 'low' | 'standard' | 'high';
+
 export interface ScreenStackHeaderSubviewProps {
   /**
    * A boolean value indicating whether the background this item may share with other items in the bar should be hidden.
@@ -1123,6 +1137,15 @@ export interface ScreenStackHeaderSubviewProps {
    * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/hidessharedbackground
    */
   hidesSharedBackground?: boolean | undefined;
+  /**
+   * Priority used when the header runs out of room: items with the lowest
+   * priority are moved into the overflow menu first. Defaults to 'standard'.
+   * Only applicable to type="right" and type="left" subviews.
+   * Only available from iOS 27.0 and later.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitemvisibilitypriority
+   */
+  visibilityPriority?: HeaderBarButtonItemVisibilityPriority | undefined;
 }
 
 interface SharedHeaderBarButtonItem {
@@ -1193,6 +1216,14 @@ interface SharedHeaderBarButtonItem {
    * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/identifier
    */
   identifier?: string | undefined;
+  /**
+   * Priority used when the header runs out of room: items with the lowest
+   * priority are moved into the overflow menu first. Defaults to 'standard'.
+   * Only available from iOS 27.0 and later.
+   *
+   * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitemvisibilitypriority
+   */
+  visibilityPriority?: HeaderBarButtonItemVisibilityPriority | undefined;
   /**
    * A badge to be rendered on a item.
    * Only available from iOS 26.0 and later.