react-native-screens 4.0.0-beta.2 → 4.0.0-beta.4

package/native-stack/README.md

@@ -287,9 +287,11 @@ Defaults to system default.
 
 #### `sheetInitialDetent`
 
-Initial detent for the sheet.
+Index of the detent the sheet should expand to after being opened.
 Works only when `presentation` is set to `formSheet`.
 
+Defaults to `0` - which represents first detent in the detents array.
+
 #### `sheetGrabberVisible` (iOS only)
 
 Boolean indicating whether the sheet shows a grabber at the top.
@@ -326,7 +328,6 @@ How the given screen should appear/disappear when pushed or popped at the top of
 - `slide_from_bottom` – performs a slide from bottom animation
 - `slide_from_right` - slide in the new screen from right to left (Android only, resolves to default transition on iOS)
 - `slide_from_left` - slide in the new screen from left to right
-- `"ios"` - @deprecated iOS like slide in animation. pushes in the new screen from right to left (Android only, resolves to default transition on iOS)  (will be removed in v4.0.0 in favor of `ios_from_right`)
 - `"ios_from_right"` - iOS like slide in animation. pushes in the new screen from right to left (Android only, resolves to default transition on iOS)
 - `"ios_from_left"` - iOS like slide in animation. pushes in the new screen from left to right (Android only, resolves to default transition on iOS)
 - `none` - the screen appears/disappears without an animation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-screens",
-  "version": "4.0.0-beta.2",
+  "version": "4.0.0-beta.4",
   "description": "Native navigation primitives for your React Native app.",
   "scripts": {
     "submodules": "git submodule update --init --recursive && (cd react-navigation && yarn)",

package/src/components/Screen.tsx

@@ -17,11 +17,19 @@ import {
 import ScreenNativeComponent from '../fabric/ScreenNativeComponent';
 import ModalScreenNativeComponent from '../fabric/ModalScreenNativeComponent';
 
-export const NativeScreen: React.ComponentType<ScreenProps> =
-  ScreenNativeComponent as React.ComponentType<ScreenProps>;
+type NativeScreenProps = Omit<
+  ScreenProps,
+  'sheetInitialDetentIndex' | 'sheetLargestUndimmedDetentIndex'
+> & {
+  sheetInitialDetent: number;
+  sheetLargestUndimmedDetent: number;
+};
+
+export const NativeScreen: React.ComponentType<NativeScreenProps> =
+  ScreenNativeComponent as React.ComponentType<NativeScreenProps>;
 const AnimatedNativeScreen = Animated.createAnimatedComponent(NativeScreen);
 const AnimatedNativeModalScreen = Animated.createAnimatedComponent(
-  ModalScreenNativeComponent as React.ComponentType<ScreenProps>,
+  ModalScreenNativeComponent as React.ComponentType<NativeScreenProps>,
 );
 
 // Incomplete type, all accessible properties available at:
@@ -52,12 +60,31 @@ const SHEET_COMPAT_ALL = [0.5, 1.0];
 const SHEET_DIMMED_ALWAYS = -1;
 // const SHEET_DIMMED_NEVER = 9999;
 
+function assertDetentsArrayIsSorted(array: number[]) {
+  for (let i = 1; i < array.length; i++) {
+    if (array[i - 1] > array[i]) {
+      throw new Error(
+        '[RNScreens] The detent array is not sorted in ascending order!',
+      );
+    }
+  }
+}
+
 // These exist to transform old 'legacy' values used by the formsheet API to the new API shape.
 // We can get rid of it, once we get rid of support for legacy values: 'large', 'medium', 'all'.
 function resolveSheetAllowedDetents(
   allowedDetentsCompat: ScreenProps['sheetAllowedDetents'],
 ): number[] {
   if (Array.isArray(allowedDetentsCompat)) {
+    if (__DEV__) {
+      assertDetentsArrayIsSorted(allowedDetentsCompat);
+      if (Platform.OS === 'android' && allowedDetentsCompat.length > 3) {
+        console.warn(
+          '[RNScreens] Sheets API on Android do accept only up to 3 values. Any surplus value are ignored.',
+        );
+        allowedDetentsCompat = allowedDetentsCompat.slice(0, 3);
+      }
+    }
     return allowedDetentsCompat;
   } else if (allowedDetentsCompat === 'fitToContents') {
     return SHEET_FIT_TO_CONTENTS;
@@ -74,13 +101,22 @@ function resolveSheetAllowedDetents(
 }
 
 function resolveSheetLargestUndimmedDetent(
-  lud: ScreenProps['sheetLargestUndimmedDetent'],
-  largestDetentIndex: number,
+  lud: ScreenProps['sheetLargestUndimmedDetentIndex'],
+  lastDetentIndex: number,
 ): number {
   if (typeof lud === 'number') {
+    if (!isIndexInClosedRange(lud, SHEET_DIMMED_ALWAYS, lastDetentIndex)) {
+      if (__DEV__) {
+        throw new Error(
+          "[RNScreens] Provided value of 'sheetLargestUndimmedDetentIndex' prop is out of bounds of 'sheetAllowedDetents' array.",
+        );
+      }
+      // Return default in production
+      return SHEET_DIMMED_ALWAYS;
+    }
     return lud;
-  } else if (lud === 'largest') {
-    return largestDetentIndex;
+  } else if (lud === 'last') {
+    return lastDetentIndex;
   } else if (lud === 'none' || lud === 'all') {
     return SHEET_DIMMED_ALWAYS;
   } else if (lud === 'large') {
@@ -93,6 +129,36 @@ function resolveSheetLargestUndimmedDetent(
   }
 }
 
+function resolveSheetInitialDetentIndex(
+  index: ScreenProps['sheetInitialDetentIndex'],
+  lastDetentIndex: number,
+): number {
+  if (index === 'last') {
+    index = lastDetentIndex;
+  } else if (index == null) {
+    // Intentional check for undefined & null ^
+    index = 0;
+  }
+  if (!isIndexInClosedRange(index, 0, lastDetentIndex)) {
+    if (__DEV__) {
+      throw new Error(
+        "[RNScreens] Provided value of 'sheetInitialDetentIndex' prop is out of bounds of 'sheetAllowedDetents' array.",
+      );
+    }
+    // Return default in production
+    return 0;
+  }
+  return index;
+}
+
+function isIndexInClosedRange(
+  value: number,
+  lowerBound: number,
+  upperBound: number,
+): boolean {
+  return Number.isInteger(value) && value >= lowerBound && value <= upperBound;
+}
+
 export const InnerScreen = React.forwardRef<View, ScreenProps>(
   function InnerScreen(props, ref) {
     const innerRef = React.useRef<ViewConfig | null>(null);
@@ -118,13 +184,12 @@ export const InnerScreen = React.forwardRef<View, ScreenProps>(
     const {
       // formSheet presentation related props
       sheetAllowedDetents = [1.0],
-      sheetLargestUndimmedDetent = SHEET_DIMMED_ALWAYS,
+      sheetLargestUndimmedDetentIndex = SHEET_DIMMED_ALWAYS,
       sheetGrabberVisible = false,
       sheetCornerRadius = -1.0,
       sheetExpandsWhenScrolledToEdge = true,
       sheetElevation = 24,
-      sheetInitialDetent = 0,
-
+      sheetInitialDetentIndex = 0,
       // Other
       stackPresentation,
     } = rest;
@@ -134,9 +199,13 @@ export const InnerScreen = React.forwardRef<View, ScreenProps>(
         resolveSheetAllowedDetents(sheetAllowedDetents);
       const resolvedSheetLargestUndimmedDetent =
         resolveSheetLargestUndimmedDetent(
-          sheetLargestUndimmedDetent,
+          sheetLargestUndimmedDetentIndex,
           resolvedSheetAllowedDetents.length - 1,
         );
+      const resolvedSheetInitialDetentIndex = resolveSheetInitialDetentIndex(
+        sheetInitialDetentIndex,
+        resolvedSheetAllowedDetents.length - 1,
+      );
       // Due to how Yoga resolves layout, we need to have different components for modal nad non-modal screens
       const AnimatedScreen =
         Platform.OS === 'android' ||
@@ -200,7 +269,7 @@ export const InnerScreen = React.forwardRef<View, ScreenProps>(
             sheetGrabberVisible={sheetGrabberVisible}
             sheetCornerRadius={sheetCornerRadius}
             sheetExpandsWhenScrolledToEdge={sheetExpandsWhenScrolledToEdge}
-            sheetInitialDetent={sheetInitialDetent}
+            sheetInitialDetent={resolvedSheetInitialDetentIndex}
             gestureResponseDistance={{
               start: gestureResponseDistance?.start ?? -1,
               end: gestureResponseDistance?.end ?? -1,

package/src/components/ScreenContentWrapper.web.tsx

@@ -1,4 +1,6 @@
 import { View } from 'react-native';
 
 export const NativeScreenContentWrapper = View;
-export const ScreenContentWrapper = View;
+
+const ScreenContentWrapper = View;
+export default ScreenContentWrapper;

package/src/components/ScreenFooter.web.tsx

@@ -0,0 +1,6 @@
+import { View } from 'react-native';
+
+export const NativeScreenFooter = View;
+
+const ScreenFooter = View;
+export default ScreenFooter;

package/src/fabric/ModalScreenNativeComponent.ts

@@ -75,6 +75,7 @@ export interface NativeProps extends ViewProps {
   sheetGrabberVisible?: WithDefault<boolean, false>;
   sheetCornerRadius?: WithDefault<Float, -1.0>;
   sheetExpandsWhenScrolledToEdge?: WithDefault<boolean, false>;
+  sheetInitialDetent?: WithDefault<Int32, 0>;
   customAnimationOnSwipe?: boolean;
   fullScreenSwipeEnabled?: boolean;
   fullScreenSwipeShadowEnabled?: boolean;

package/src/fabric/ScreenNativeComponent.ts

@@ -58,7 +58,6 @@ type StackAnimation =
   | 'slide_from_left'
   | 'slide_from_bottom'
   | 'fade_from_bottom'
-  | 'ios'
   | 'ios_from_right'
   | 'ios_from_left';
 

package/src/native-stack/types.tsx

@@ -418,7 +418,7 @@ export type NativeStackNavigationOptions = {
    *
    * Defaults to `0` - which represents first detent in the detents array.
    */
-  sheetInitialDetent?: ScreenProps['sheetInitialDetent'];
+  sheetInitialDetentIndex?: ScreenProps['sheetInitialDetentIndex'];
   /**
    * The largest sheet detent for which a view underneath won't be dimmed.
    * Works only when `stackPresentation` is set to `formSheet`.
@@ -436,7 +436,7 @@ export type NativeStackNavigationOptions = {
    *
    * Defaults to `none`, indicating that the dimming view should be always present.
    */
-  sheetLargestUndimmedDetent?: ScreenProps['sheetLargestUndimmedDetent'];
+  sheetLargestUndimmedDetentIndex?: ScreenProps['sheetLargestUndimmedDetentIndex'];
   /**
    * How the screen should appear/disappear when pushed or popped at the top of the stack.
    * The following values are currently supported:
@@ -448,7 +448,6 @@ export type NativeStackNavigationOptions = {
    * - "slide_from_bottom" – performs a slide from bottom animation
    * - "slide_from_right" - slide in the new screen from right to left (Android only, resolves to default transition on iOS)
    * - "slide_from_left" - slide in the new screen from left to right
-   * - "ios" - @deprecated iOS like slide in animation. pushes in the new screen from right to left (Android only, resolves to default transition on iOS) (will be removed in v4.0.0 in favor of `ios_from_right`)
    * - "ios_from_right" - iOS like slide in animation. pushes in the new screen from right to left (Android only, resolves to default transition on iOS)
    * - "ios_from_left" - iOS like slide in animation. pushes in the new screen from left to right (Android only, resolves to default transition on iOS)
    * - "none" – the screen appears/dissapears without an animation

package/src/native-stack/views/NativeStackView.tsx

@@ -195,12 +195,12 @@ const RouteView = ({
     headerShown,
     hideKeyboardOnSwipe,
     homeIndicatorHidden,
-    sheetLargestUndimmedDetent = 'none',
+    sheetLargestUndimmedDetentIndex = 'none',
     sheetGrabberVisible = false,
     sheetCornerRadius = -1.0,
     sheetElevation = 24,
     sheetExpandsWhenScrolledToEdge = true,
-    sheetInitialDetent = 0,
+    sheetInitialDetentIndex = 0,
     nativeBackButtonDismissalEnabled = false,
     navigationBarColor,
     navigationBarTranslucent,
@@ -318,9 +318,9 @@ const RouteView = ({
       hasLargeHeader={hasLargeHeader}
       style={[StyleSheet.absoluteFill, unstable_screenStyle]}
       sheetAllowedDetents={sheetAllowedDetents}
-      sheetLargestUndimmedDetent={sheetLargestUndimmedDetent}
+      sheetLargestUndimmedDetentIndex={sheetLargestUndimmedDetentIndex}
       sheetGrabberVisible={sheetGrabberVisible}
-      sheetInitialDetent={sheetInitialDetent}
+      sheetInitialDetentIndex={sheetInitialDetentIndex}
       sheetCornerRadius={sheetCornerRadius}
       sheetElevation={sheetElevation}
       sheetExpandsWhenScrolledToEdge={sheetExpandsWhenScrolledToEdge}

package/src/types.tsx

@@ -39,7 +39,6 @@ export type StackAnimationTypes =
   | 'slide_from_bottom'
   | 'slide_from_right'
   | 'slide_from_left'
-  | 'ios'
   | 'ios_from_right'
   | 'ios_from_left';
 export type BlurEffectTypes =
@@ -290,13 +289,19 @@ export interface ScreenProps extends ViewProps {
   unstable_screenStyle?: Pick<ViewStyle, 'backgroundColor'>;
   /**
    * Describes heights where a sheet can rest.
-   * Works only when `stackPresentation` is set to `formSheet`.
+   * Works only when `presentation` is set to `formSheet`.
    *
    * Heights should be described as fraction (a number from `[0, 1]` interval) of screen height / maximum detent height.
-   * There is also possibility to specify `[-1]` literal array with single element, which intets to set the sheet height
+   * You can pass an array of ascending values each defining allowed sheet detent. iOS accepts any number of detents,
+   * while **Android is limited to three**.
+   *
+   * There is also possibility to specify `fitToContents` literal, which intents to set the sheet height
    * to the height of its contents.
    *
-   * Please note that the array **must** be sorted in ascending order.
+   * Please note that the array **must** be sorted in ascending order. This invariant is verified only in developement mode,
+   * where violation results in error.
+   *
+   * **Android is limited to up 3 values in the array** -- any surplus values, beside first three are ignored.
    *
    * There are also legacy & **deprecated** options available:
    *
@@ -304,7 +309,9 @@ export interface ScreenProps extends ViewProps {
    * * 'large' - corresponds to `[1.0]` detent value, maximum height,
    * * 'all' - corresponds to `[0.5, 1.0]` value, the name is deceiving due to compatibility reasons.
    *
-   * Defaults to `[1.0]` literal.
+   * These are provided solely for **temporary** backward compatibility and are destined for removal in future versions.
+   *
+   * Defaults to `[1.0]`.
    */
   sheetAllowedDetents?: number[] | 'fitToContents' | 'medium' | 'large' | 'all';
   /**
@@ -351,30 +358,40 @@ export interface ScreenProps extends ViewProps {
    * This prop can be set to an number, which indicates index of detent in `sheetAllowedDetents` array for which
    * there won't be a dimming view beneath the sheet.
    *
+   * If the specified index is out of bounds of `sheetAllowedDetents` array, in dev environment mode error will be thrown,
+   * in production the value will be reset to default value.
+   *
    * Additionaly there are following options available:
    *
    * * `none` - there will be dimming view for all detents levels,
-   * * `largest` - there won't be a dimming view for any detent level.
+   * * `last` - there won't be a dimming view for any detent level.
    *
    * There also legacy & **deprecated** prop values available: `medium`, `large` (don't confuse with `largest`), `all`, which work in tandem with
    * corresponding legacy prop values for `sheetAllowedDetents` prop.
    *
+   * These are provided solely for **temporary** backward compatibility and are destined for removal in future versions.
+   *
    * Defaults to `none`, indicating that the dimming view should be always present.
    */
-  sheetLargestUndimmedDetent?:
+  sheetLargestUndimmedDetentIndex?:
     | number
     | 'none'
-    | 'largest'
-    | 'medium'
-    | 'large'
-    | 'all';
+    | 'last'
+    | 'medium' // deprecated
+    | 'large' // deprecated
+    | 'all'; // deprecated
   /**
    * Index of the detent the sheet should expand to after being opened.
    * Works only when `stackPresentation` is set to `formSheet`.
    *
+   * If the specified index is out of bounds of `sheetAllowedDetents` array, in dev environment more error will be thrown,
+   * in production the value will be reset to default value.
+   *
+   * Additionaly there is `last` value available, when set the sheet will expand initially to last (largest) detent.
+   *
    * Defaults to `0` - which represents first detent in the detents array.
    */
-  sheetInitialDetent?: number;
+  sheetInitialDetentIndex?: number | 'last';
   /**
    * How the screen should appear/disappear when pushed or popped at the top of the stack.
    * The following values are currently supported:
@@ -386,7 +403,6 @@ export interface ScreenProps extends ViewProps {
    * - `slide_from_bottom` – performs a slide from bottom animation
    * - "slide_from_right" - slide in the new screen from right to left (Android only, resolves to default transition on iOS)
    * - "slide_from_left" - slide in the new screen from left to right
-   * - "ios" - @deprecated iOS like slide in animation. pushes in the new screen from right to left (Android only, resolves to default transition on iOS) (will be removed in v4.0.0 in favor of `ios_from_right`)
    * - "ios_from_right" - iOS like slide in animation. pushes in the new screen from right to left (Android only, resolves to default transition on iOS)
    * - "ios_from_left" - iOS like slide in animation. pushes in the new screen from left to right (Android only, resolves to default transition on iOS)
    * - "none" – the screen appears/dissapears without an animation

package/windows/RNScreens/Screen.h

@@ -11,7 +11,6 @@ enum class StackAnimation {
   SIMPLE_FROM_BOTTOM,
   SLIDE_FROM_RIGHT,
   SLIDE_FROM_LEFT,
-  IOS,
   IOS_FROM_RIGHT,
   IOS_FROM_LEFT
 };