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

package/src/components/gamma/split/SplitHost.types.ts

@@ -1,4 +1,5 @@
 import type { NativeSyntheticEvent, ViewProps } from 'react-native';
+import type { InterfaceOrientation } from '../../shared/types';
 
 // eslint-disable-next-line @typescript-eslint/ban-types
 type GenericEmptyEvent = Readonly<{}>;
@@ -25,16 +26,7 @@ export type SplitDisplayMode =
   | 'twoOverSecondary'
   | 'twoDisplaceSecondary';
 
-export type SplitHostOrientation =
-  | 'inherit'
-  | 'all'
-  | 'allButUpsideDown'
-  | 'portrait'
-  | 'portraitUp'
-  | 'portraitDown'
-  | 'landscape'
-  | 'landscapeLeft'
-  | 'landscapeRight';
+export type SplitHostOrientation = InterfaceOrientation | 'inherit';
 
 export interface SplitColumnMetrics {
   /**
@@ -42,37 +34,37 @@ export interface SplitColumnMetrics {
    *
    * Specifies the minimum width for the primary column in the Split layout, typically representing the leftmost sidebar.
    */
-  minimumPrimaryColumnWidth?: number;
+  minimumPrimaryColumnWidth?: number | undefined;
   /**
    * @summary Maximum width for the primary sidebar.
    *
    * Specifies the maximum width (in points) for the primary column in the Split layout, typically representing the leftmost sidebar.
    */
-  maximumPrimaryColumnWidth?: number;
+  maximumPrimaryColumnWidth?: number | undefined;
   /**
    * @summary Preferred width for the primary sidebar.
    *
    * Specifies the preferred width (in points or as a fraction for percentage width support) for the primary column in the Split layout, typically representing the leftmost sidebar.
    */
-  preferredPrimaryColumnWidthOrFraction?: number;
+  preferredPrimaryColumnWidthOrFraction?: number | undefined;
   /**
    * @summary Minimum width for the intermediate sidebar.
    *
    * Specifies the minimum width (in points) for the supplementary column in the Split layout, typically representing the intermediate sidebar.
    */
-  minimumSupplementaryColumnWidth?: number;
+  minimumSupplementaryColumnWidth?: number | undefined;
   /**
    * @summary Maximum width for the intermediate sidebar.
    *
    * Specifies the maximum width (in points) for the supplementary column in the Split layout, typically representing the intermediate sidebar.
    */
-  maximumSupplementaryColumnWidth?: number;
+  maximumSupplementaryColumnWidth?: number | undefined;
   /**
    * @summary Preferred width for the intermediate sidebar.
    *
    * Specifies the preferred width (in points or as a fraction for percentage width support) for the supplementary column in the Split layout, typically representing the intermediate sidebar.
    */
-  preferredSupplementaryColumnWidthOrFraction?: number;
+  preferredSupplementaryColumnWidthOrFraction?: number | undefined;
   /**
    * @summary Minimum width for the secondary component.
    *
@@ -80,7 +72,7 @@ export interface SplitColumnMetrics {
    *
    * @supported iOS 26 or higher
    */
-  minimumSecondaryColumnWidth?: number;
+  minimumSecondaryColumnWidth?: number | undefined;
   /**
    * @summary Preferred width for the secondary component.
    *
@@ -88,7 +80,7 @@ export interface SplitColumnMetrics {
    *
    * @supported iOS 26 or higher
    */
-  preferredSecondaryColumnWidthOrFraction?: number;
+  preferredSecondaryColumnWidthOrFraction?: number | undefined;
   /**
    * @summary Minimum width for the inspector component.
    *
@@ -96,7 +88,7 @@ export interface SplitColumnMetrics {
    *
    * @supported iOS 26 or higher
    */
-  minimumInspectorColumnWidth?: number;
+  minimumInspectorColumnWidth?: number | undefined;
   /**
    * @summary Maximum width for the inspector component.
    *
@@ -104,7 +96,7 @@ export interface SplitColumnMetrics {
    *
    * @supported iOS 26 or higher
    */
-  maximumInspectorColumnWidth?: number;
+  maximumInspectorColumnWidth?: number | undefined;
   /**
    * @summary Preferred width for the inspector component.
    *
@@ -112,7 +104,7 @@ export interface SplitColumnMetrics {
    *
    * @supported iOS 26 or higher
    */
-  preferredInspectorColumnWidthOrFraction?: number;
+  preferredInspectorColumnWidthOrFraction?: number | undefined;
 }
 export type SplitNavigableColumn = 'primary' | 'supplementary' | 'secondary';
 
@@ -121,8 +113,8 @@ export type SplitHostCommands = {
 };
 
 export interface SplitHostProps extends ViewProps {
-  children?: React.ReactNode;
-  ref?: React.Ref<SplitHostCommands>;
+  children: NonNullable<React.ReactNode>;
+  ref?: React.Ref<SplitHostCommands> | undefined;
 
   /**
    * @summary An object describing bounds for column widths.
@@ -137,7 +129,7 @@ export interface SplitHostProps extends ViewProps {
    * - `secondary` - the view with the main content
    * - `inspector` - the view which is providing additional data about the secondary column
    */
-  columnMetrics?: SplitColumnMetrics;
+  columnMetrics?: SplitColumnMetrics | undefined;
   /**
    * @summary Determines whether the button for changing the Split display mode is visible on the screen.
    *
@@ -152,24 +144,26 @@ export interface SplitHostProps extends ViewProps {
    *
    * @default automatic
    */
-  displayModeButtonVisibility?: SplitDisplayModeButtonVisibility;
+  displayModeButtonVisibility?: SplitDisplayModeButtonVisibility | undefined;
   /**
    * @summary A callback that gets invoked when the Split was collapsed to a single column.
    */
-  onCollapse?: (e: NativeSyntheticEvent<GenericEmptyEvent>) => void;
+  onCollapse?:
+    | ((e: NativeSyntheticEvent<GenericEmptyEvent>) => void)
+    | undefined;
   /**
    * @summary A callback that gets invoked when the Split displayMode has changed.
    *
    * The purpose of this callback is tracking displayMode updates on host from the JS side.
    * These updates might be a consequence of some native interactions, like pressing native button or performing swipe gesture.
    */
-  onDisplayModeWillChange?: (
-    e: NativeSyntheticEvent<DisplayModeWillChangeEvent>,
-  ) => void;
+  onDisplayModeWillChange?:
+    | ((e: NativeSyntheticEvent<DisplayModeWillChangeEvent>) => void)
+    | undefined;
   /**
    * @summary A callback that gets invoked when the Split was expanded to multiple columns.
    */
-  onExpand?: (e: NativeSyntheticEvent<GenericEmptyEvent>) => void;
+  onExpand?: ((e: NativeSyntheticEvent<GenericEmptyEvent>) => void) | undefined;
   /**
    * @summary A callback that gets invoked when the Split inspector is either programmatically hidden (in column presentation) or dismissed (in modal presentation).
    *
@@ -177,7 +171,9 @@ export interface SplitHostProps extends ViewProps {
    *
    * @supported iOS 26 or higher
    */
-  onInspectorHide?: (e: NativeSyntheticEvent<GenericEmptyEvent>) => void;
+  onInspectorHide?:
+    | ((e: NativeSyntheticEvent<GenericEmptyEvent>) => void)
+    | undefined;
   /**
    * @summary Specifies supported orientations for the tab screen.
    *
@@ -220,11 +216,11 @@ export interface SplitHostProps extends ViewProps {
    *
    * @platform ios
    */
-  orientation?: SplitHostOrientation;
+  orientation?: SplitHostOrientation | undefined;
   /**
    * @summary Determines whether gestures are enabled to change the display mode.
    */
-  presentsWithGesture?: boolean;
+  presentsWithGesture?: boolean | undefined;
   /**
    * @summary Specifies the display mode which will be preferred to use, if the layout requirements are met.
    *
@@ -245,7 +241,7 @@ export interface SplitHostProps extends ViewProps {
    *
    * @default automatic
    */
-  preferredDisplayMode?: SplitDisplayMode;
+  preferredDisplayMode?: SplitDisplayMode | undefined;
   /**
    * @summary Specifies the split behavior which will be preferred to use, if the layout requirements are met.
    *
@@ -263,7 +259,7 @@ export interface SplitHostProps extends ViewProps {
    *
    * @default automatic
    */
-  preferredSplitBehavior?: SplitBehavior;
+  preferredSplitBehavior?: SplitBehavior | undefined;
   /**
    * @summary Specifies the background style of the primary view controller.
    *
@@ -285,7 +281,7 @@ export interface SplitHostProps extends ViewProps {
    * @remarks
    * According to the documentation, this property shouldn't have any effect on iOS. However, on iOS 26 the support for this prop was added.
    */
-  primaryBackgroundStyle?: SplitPrimaryBackgroundStyle;
+  primaryBackgroundStyle?: SplitPrimaryBackgroundStyle | undefined;
   /**
    * @summary Indicates on which side primary sidebar is placed, affecting the split view layout.
    *
@@ -299,7 +295,7 @@ export interface SplitHostProps extends ViewProps {
    *
    * @default leading
    */
-  primaryEdge?: SplitPrimaryEdge;
+  primaryEdge?: SplitPrimaryEdge | undefined;
   /**
    * @summary Determines whether inspector column should be displayed.
    *
@@ -308,11 +304,11 @@ export interface SplitHostProps extends ViewProps {
    *
    * @supported iOS 26 or higher
    */
-  showInspector?: boolean;
+  showInspector?: boolean | undefined;
   /**
    * @summary Determines whether a button to toggle to and from secondaryOnly display mode is visible.
    */
-  showSecondaryToggleButton?: boolean;
+  showSecondaryToggleButton?: boolean | undefined;
   /**
    * @summary Specifies which column should be shown when the split view collapses to a single column.
    *
@@ -327,5 +323,5 @@ export interface SplitHostProps extends ViewProps {
    * - `supplementary` - the supplementary sidebar is shown
    * - `secondary` - the secondary (main content) column is shown
    */
-  topColumnForCollapsing?: SplitNavigableColumn;
+  topColumnForCollapsing?: SplitNavigableColumn | undefined;
 }

package/src/components/gamma/split/SplitScreen.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { StyleSheet } from 'react-native';
-import SplitViewScreenNativeComponent from '../../../fabric/gamma/SplitViewScreenNativeComponent';
+import SplitScreenNativeComponent from '../../../fabric/gamma/split/SplitScreenNativeComponent';
 import { SplitScreenProps } from './SplitScreen.types';
 
 /**
@@ -8,12 +8,12 @@ import { SplitScreenProps } from './SplitScreen.types';
  */
 function Column(props: SplitScreenProps) {
   return (
-    <SplitViewScreenNativeComponent
+    <SplitScreenNativeComponent
       columnType="column"
       {...props}
       style={StyleSheet.absoluteFill}>
       {props.children}
-    </SplitViewScreenNativeComponent>
+    </SplitScreenNativeComponent>
   );
 }
 
@@ -22,12 +22,12 @@ function Column(props: SplitScreenProps) {
  */
 function Inspector(props: SplitScreenProps) {
   return (
-    <SplitViewScreenNativeComponent
+    <SplitScreenNativeComponent
       columnType="inspector"
       {...props}
       style={StyleSheet.absoluteFill}>
       {props.children}
-    </SplitViewScreenNativeComponent>
+    </SplitScreenNativeComponent>
   );
 }
 

package/src/components/gamma/split/SplitScreen.types.ts

@@ -6,29 +6,37 @@ type GenericEmptyEvent = Readonly<{}>;
 export type SplitScreenColumnType = 'column' | 'inspector';
 
 export interface SplitScreenProps extends ViewProps {
-  children?: React.ReactNode;
+  children?: React.ReactNode | undefined;
   /**
    * @summary A callback that gets invoked when the current SplitScreen did appear.
    *
    * This is called as soon as the transition ends.
    */
-  onDidAppear?: (e: NativeSyntheticEvent<GenericEmptyEvent>) => void;
+  onDidAppear?:
+    | ((e: NativeSyntheticEvent<GenericEmptyEvent>) => void)
+    | undefined;
   /**
    * @summary A callback that gets invoked when the current SplitScreen did disappear.
    *
    * This is called as soon as the transition ends.
    */
-  onDidDisappear?: (e: NativeSyntheticEvent<GenericEmptyEvent>) => void;
+  onDidDisappear?:
+    | ((e: NativeSyntheticEvent<GenericEmptyEvent>) => void)
+    | undefined;
   /**
    * @summary A callback that gets invoked when the current SplitScreen will appear.
    *
    * This is called as soon as the transition begins.
    */
-  onWillAppear?: (e: NativeSyntheticEvent<GenericEmptyEvent>) => void;
+  onWillAppear?:
+    | ((e: NativeSyntheticEvent<GenericEmptyEvent>) => void)
+    | undefined;
   /**
    * @summary A callback that gets invoked when the current SplitScreen will disappear.
    *
    * This is called as soon as the transition begins.
    */
-  onWillDisappear?: (e: NativeSyntheticEvent<GenericEmptyEvent>) => void;
+  onWillDisappear?:
+    | ((e: NativeSyntheticEvent<GenericEmptyEvent>) => void)
+    | undefined;
 }

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

@@ -1,16 +1,30 @@
 import SplitHost from './SplitHost';
 import SplitScreen from './SplitScreen';
 
-export * from './SplitHost.types';
-export * from './SplitScreen.types';
+export type {
+  DisplayModeWillChangeEvent, // TODO: This event should be renamed to match the convention
+  SplitDisplayModeButtonVisibility,
+  SplitBehavior,
+  SplitPrimaryEdge,
+  SplitPrimaryBackgroundStyle,
+  SplitDisplayMode,
+  SplitHostOrientation,
+  SplitColumnMetrics,
+  SplitNavigableColumn,
+  SplitHostCommands,
+  SplitHostProps,
+} from './SplitHost.types';
+
+export type {
+  SplitScreenColumnType,
+  SplitScreenProps,
+} from './SplitScreen.types';
 
 /**
  * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
  */
-const Split = {
+export const Split = {
   Host: SplitHost,
   Column: SplitScreen.Column,
   Inspector: SplitScreen.Inspector,
 };
-
-export default Split;

package/src/components/gamma/stack/header/StackHeaderConfig.android.tsx

@@ -0,0 +1,166 @@
+import React from 'react';
+import { Image, StyleSheet } from 'react-native';
+import type { StackHeaderConfigProps } from './StackHeaderConfig.types';
+import StackHeaderConfigAndroidNativeComponent from '../../../../fabric/gamma/stack/StackHeaderConfigAndroidNativeComponent';
+import type { NativeProps as StackHeaderConfigAndroidNativeComponentProps } from '../../../../fabric/gamma/stack/StackHeaderConfigAndroidNativeComponent';
+import StackHeaderSubview from './android/StackHeaderSubview.android';
+import type {
+  StackHeaderConfigPropsAndroid,
+  StackHeaderTypeAndroid,
+} from './StackHeaderConfig.android.types';
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function StackHeaderConfig(props: StackHeaderConfigProps) {
+  // ios props are safely dropped
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { android, ios, ...baseProps } = props;
+
+  const {
+    backgroundSubview,
+    leadingSubview,
+    centerSubview,
+    trailingSubview,
+    backButtonIcon,
+    scrollFlagScroll,
+    scrollFlagEnterAlways,
+    scrollFlagEnterAlwaysCollapsed,
+    scrollFlagExitUntilCollapsed,
+    scrollFlagSnap,
+    ...filteredAndroidProps
+  } = android ?? {};
+
+  const backButtonIconProps = parseBackButtonIconToNativeProps(backButtonIcon);
+  const scrollFlagProps = resolveScrollFlags(filteredAndroidProps.type, {
+    scrollFlagScroll,
+    scrollFlagEnterAlways,
+    scrollFlagEnterAlwaysCollapsed,
+    scrollFlagExitUntilCollapsed,
+    scrollFlagSnap,
+  });
+
+  return (
+    <StackHeaderConfigAndroidNativeComponent
+      collapsable={false}
+      style={StyleSheet.absoluteFill}
+      {...baseProps}
+      {...filteredAndroidProps}
+      {...backButtonIconProps}
+      {...scrollFlagProps}>
+      {/*
+        Please note that the order of the subviews MUST match
+        the order in native StackHeaderConfig.getConfigSubviewAt.
+        */}
+      {backgroundSubview && (
+        <StackHeaderSubview
+          type="background"
+          collapseMode={backgroundSubview.collapseMode}>
+          {backgroundSubview.Component}
+        </StackHeaderSubview>
+      )}
+      {leadingSubview && (
+        <StackHeaderSubview type="leading">
+          {leadingSubview.Component}
+        </StackHeaderSubview>
+      )}
+      {centerSubview && (
+        <StackHeaderSubview type="center">
+          {centerSubview.Component}
+        </StackHeaderSubview>
+      )}
+      {trailingSubview && (
+        <StackHeaderSubview type="trailing">
+          {trailingSubview.Component}
+        </StackHeaderSubview>
+      )}
+    </StackHeaderConfigAndroidNativeComponent>
+  );
+}
+
+function parseBackButtonIconToNativeProps(
+  icon: StackHeaderConfigPropsAndroid['backButtonIcon'],
+): Pick<
+  StackHeaderConfigAndroidNativeComponentProps,
+  'backButtonImageIconResource' | 'backButtonDrawableIconResourceName'
+> {
+  if (!icon) {
+    return {};
+  }
+
+  if (icon.type === 'imageSource') {
+    const resolved = Image.resolveAssetSource(icon.imageSource);
+    if (!resolved) {
+      console.error(
+        '[RNScreens] failed to resolve an asset for back button icon',
+      );
+    }
+    return {
+      backButtonImageIconResource: resolved || undefined,
+    };
+  } else if (icon.type === 'drawableResource') {
+    return {
+      backButtonDrawableIconResourceName: icon.name,
+    };
+  } else {
+    throw new Error(
+      '[RNScreens] Incorrect icon format for Android. You must provide `imageSource` or `drawableResource`.',
+    );
+  }
+}
+
+type ScrollFlagFields = {
+  scrollFlagScroll: boolean;
+  scrollFlagEnterAlways: boolean;
+  scrollFlagEnterAlwaysCollapsed: boolean;
+  scrollFlagExitUntilCollapsed: boolean;
+  scrollFlagSnap: boolean;
+};
+
+const SCROLL_FLAG_DEFAULTS_BY_TYPE: Record<
+  StackHeaderTypeAndroid,
+  ScrollFlagFields
+> = {
+  small: {
+    scrollFlagScroll: false,
+    scrollFlagEnterAlways: false,
+    scrollFlagEnterAlwaysCollapsed: false,
+    scrollFlagExitUntilCollapsed: false,
+    scrollFlagSnap: false,
+  },
+  medium: {
+    scrollFlagScroll: true,
+    scrollFlagEnterAlways: false,
+    scrollFlagEnterAlwaysCollapsed: false,
+    scrollFlagExitUntilCollapsed: true,
+    scrollFlagSnap: true,
+  },
+  large: {
+    scrollFlagScroll: true,
+    scrollFlagEnterAlways: false,
+    scrollFlagEnterAlwaysCollapsed: false,
+    scrollFlagExitUntilCollapsed: true,
+    scrollFlagSnap: true,
+  },
+};
+
+function resolveScrollFlags(
+  type: StackHeaderTypeAndroid | undefined,
+  overrides: Pick<StackHeaderConfigPropsAndroid, keyof ScrollFlagFields>,
+): ScrollFlagFields {
+  const defaults = SCROLL_FLAG_DEFAULTS_BY_TYPE[type ?? 'small'];
+  return {
+    scrollFlagScroll: overrides.scrollFlagScroll ?? defaults.scrollFlagScroll,
+    scrollFlagEnterAlways:
+      overrides.scrollFlagEnterAlways ?? defaults.scrollFlagEnterAlways,
+    scrollFlagEnterAlwaysCollapsed:
+      overrides.scrollFlagEnterAlwaysCollapsed ??
+      defaults.scrollFlagEnterAlwaysCollapsed,
+    scrollFlagExitUntilCollapsed:
+      overrides.scrollFlagExitUntilCollapsed ??
+      defaults.scrollFlagExitUntilCollapsed,
+    scrollFlagSnap: overrides.scrollFlagSnap ?? defaults.scrollFlagSnap,
+  };
+}
+
+export default StackHeaderConfig;