feat(iOS): add pageSheet presentation for native-stack (#2793)

## Description

Adds new presentation for Native Stack - `pageSheet`
(`UIModalPresentationPageSheet` modal style on iOS, `modal` on Android).

Since the release of iOS 18, screens with `stackPresentation: 'modal'`
changed size on devices with a bigger screen, such as an iPad - they
became much smaller, which impacted applications of the library's users
(see issue
#2549).
This happens because `UIModalPresentationAutomatic`, which is used by
`react-native-screens` for `modal` on iOS, has been changed with the
release of iOS 18. `UIModalPresentationAutomatic` is now mapped to
`UIModalPresentationFormSheet` for iOS >=18 and
`UIModalPresentationPageSheet` for earlier versions (this was the
default before).

~~Apple added SwiftUI API
[(link)](https://developer.apple.com/documentation/swiftui/presentationsizing)
to allow to choose the behavior of the modal (`form`, `page`, `fitted`
or a custom one) but I wasn't able to find an equivalent functionality
in UIKit.~~ It turns out there is a new property in
`UISheetPresentationController`, see
[here](#2793 (review))

We considered 3 possible solutions to this problem:
- changing modal presentation style on iOS from
`UIModalPresentationAutomatic` to `UIModalPresentationPageSheet` for
`stackPresentation: 'modal'` to bring back old behavior for all modals:
- some users might've already designed their apps with the smaller sheet
in mind so changing the style might break their apps,
- adding a feature flag that would allow users to choose whether screens
with `stackPresentation: 'modal'` should use
`UIModalPresentationAutomatic` or `UIModalPresentationPageSheet`
- this solution would provide the easiest fix for the users impacted by
the change,
- even though 2 different sheet sizes would be available, users would
need to choose only one of them for their application,
- adding a new `stackPresentation` that would use
`UIModalPresentationPageSheet` on iOS and a regular `modal` on Android:
- users can choose whether they want to use `Automatic` or `PageSheet`
behavior per-screen basis,
- hopefully, fixing old applications with some find-and-replace magic
won't be difficult.

We decided on the third option.

tvOS does not allow `UIModalPresentationPageSheet` so it fallbacks to
`UIModalPresentationFullScreen` (the same behavior as
`UIModalPresentationAutomatic`).

This change will require changes to `react-navigation/native-stack` as
well.

Resolves
#2549.

## Changes

- add support for the new presentation in native and JS code
- add `pageSheet` examples in `Stack Presentation` and `Modals` example
screens

## Screenshots / GIFs

### `modal`

![modal](https://github.com/user-attachments/assets/657d0130-dfa0-4433-8f11-d8eb32a6146b)

### `pageSheet`

![pageSheet](https://github.com/user-attachments/assets/4759b662-119a-4886-82c4-6712502d3b6a)

## Test code and steps to reproduce

Open `Stack Presentation`, `Modals` example screens and open `pageSheet`
(at the moment, you might need to manually add `pageSheet` in
react-navigation files `packages/native-stack/src`,
`packages/native-stack/src/utils/getModalRoutesKeys.ts`,
`packages/native-stack/src/views`).

## Checklist

- [x] Included code example that can be used to test this change
- [x] Updated TS types
- [x] Updated documentation: <!-- For adding new props to native-stack
-->
- [x]
https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
- [x]
https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
- [x]
https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
- [x]
https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
- [ ] Ensured that CI passes

Author: kligarski

android/src/main/java/com/swmansion/rnscreens/ScreenViewManager.kt

@@ -126,7 +126,7 @@ open class ScreenViewManager :
             when (presentation) {
                 "push" -> Screen.StackPresentation.PUSH
                 "formSheet" -> Screen.StackPresentation.FORM_SHEET
-                "modal", "containedModal", "fullScreenModal" ->
+                "modal", "containedModal", "fullScreenModal", "pageSheet" ->
                     Screen.StackPresentation.MODAL
                 "transparentModal", "containedTransparentModal" ->
                     Screen.StackPresentation.TRANSPARENT_MODAL

apps/src/screens/Modals.tsx

@@ -12,6 +12,7 @@ type StackParamList = {
   FullscreenModal: undefined;
   Alert: undefined;
   ContainedModal: undefined;
+  PageSheet: undefined;
 };
 
 interface MainScreenProps {
@@ -30,6 +31,10 @@ const MainScreen = ({ navigation }: MainScreenProps): React.JSX.Element => (
       title="Open contained modal"
       onPress={() => navigation.navigate('ContainedModal')}
     />
+    <Button
+      title="Open pageSheet"
+      onPress={() => navigation.navigate('PageSheet')}
+    />
     <Button onPress={() => navigation.pop()} title="🔙 Back to Examples" />
   </View>
 );
@@ -50,6 +55,10 @@ const ModalScreen = ({ navigation }: ModalScreenProps): React.JSX.Element => (
       title="Open contained modal"
       onPress={() => navigation.navigate('ContainedModal')}
     />
+    <Button
+      title="Open pageSheet"
+      onPress={() => navigation.push('PageSheet')}
+    />
     <Button title="Go back" onPress={() => navigation.goBack()} />
   </View>
 );
@@ -81,6 +90,11 @@ const App = (): React.JSX.Element => (
       component={ModalScreen}
       options={{ presentation: 'containedModal' }}
     />
+    <Stack.Screen
+      name="PageSheet"
+      component={ModalScreen}
+      options={{ presentation: 'pageSheet' }}
+    />
     <Stack.Screen
       name="Alert"
       component={Alert}

apps/src/screens/StackPresentation.tsx

@@ -16,6 +16,7 @@ type StackParamList = {
   ContainedTransparentModal: undefined;
   FullScreenModal: undefined;
   FormSheet: { usesFormSheetPresentation?: boolean };
+  PageSheet: undefined;
 };
 
 interface MainScreenProps {
@@ -62,6 +63,11 @@ const MainScreen = ({ navigation }: MainScreenProps): React.JSX.Element => {
         onPress={() => navigation.navigate('FormSheet')}
         testID="stack-presentation-form-sheet-button"
       />
+      <Button
+        title="pageSheet"
+        onPress={() => navigation.navigate('PageSheet')}
+        testID="stack-presentation-page-sheet-button"
+      />
       <Button
         testID="stack-presentation-go-back-button"
         onPress={() => navigation.pop()}
@@ -123,6 +129,22 @@ const ModalScreen = ({ navigation }: ModalScreenProps): React.JSX.Element => (
   </View>
 );
 
+interface PageSheetScreenProps {
+  navigation: NativeStackNavigationProp<ParamListBase>;
+}
+
+const PageSheetScreen = ({ navigation }: PageSheetScreenProps): React.JSX.Element => (
+  <View style={styles.container}>
+    <Choose />
+    <Button
+      testID="stack-presentation-page-sheet-screen-go-back-button"
+      title="Go back"
+      onPress={() => navigation.goBack()}
+    />
+  </View>
+);
+
+
 interface FullScreenModalProps {
   navigation: NativeStackNavigationProp<ParamListBase>;
 }
@@ -204,6 +226,11 @@ const App = (): React.JSX.Element => (
         usesFormSheetPresentation: true
       }}
     />
+    <Stack.Screen
+      name="PageSheet"
+      component={PageSheetScreen}
+      options={{ presentation: 'pageSheet' }}
+    />
   </Stack.Navigator>
 );
 

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -242,6 +242,7 @@ Defines how the method that should be used to present the given screen. It is a
 - `containedTransparentModal` – Explained below.
 - `fullScreenModal` – Explained below.
 - `formSheet` – Explained below.
+- `pageSheet` - Explained below.
 
 Using `containedModal` and `containedTransparentModal` with other types of modals in one native stack navigator is not recommended and can result in a freeze or a crash of the application.
 
@@ -253,13 +254,14 @@ For iOS:
    * on iOS 12 and earlier will use [`UIModalPresentationFullScreen`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationfullscreen?language=objc). 
 - `fullScreenModal` will use [`UIModalPresentationFullScreen`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationfullscreen?language=objc)
 - `formSheet` will use [`UIModalPresentationFormSheet`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationformsheet?language=objc)
+- `pageSheet` will use [`UIModalPresentationPageSheet`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/pagesheet?language=objc)
 - `transparentModal` will use [`UIModalPresentationOverFullScreen`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationoverfullscreen?language=objc)
 - `containedModal` will use [`UIModalPresentationCurrentContext`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationcurrentcontext?language=objc)
 - `containedTransparentModal` will use [`UIModalPresentationOverCurrentContext`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationovercurrentcontext?language=objc)
 
 For Android:
 
-`modal`, `containedModal`, `fullScreenModal`, `formSheet` will use `Screen.StackPresentation.MODAL`.
+`modal`, `containedModal`, `fullScreenModal`, `formSheet`, `pageSheet` will use `Screen.StackPresentation.MODAL`.
 
 `transparentModal`, `containedTransparentModal` will use `Screen.StackPresentation.TRANSPARENT_MODAL`.
 

ios/RNSConvert.mm

@@ -49,6 +49,8 @@ + (RNSScreenStackPresentation)RNSScreenStackPresentationFromCppEquivalent:
       return RNSScreenStackPresentationFullScreenModal;
     case FormSheet:
       return RNSScreenStackPresentationFormSheet;
+    case PageSheet:
+      return RNSScreenStackPresentationPageSheet;
     case ContainedModal:
       return RNSScreenStackPresentationContainedModal;
     case TransparentModal:

ios/RNSEnums.h

@@ -5,7 +5,8 @@ typedef NS_ENUM(NSInteger, RNSScreenStackPresentation) {
   RNSScreenStackPresentationContainedModal,
   RNSScreenStackPresentationContainedTransparentModal,
   RNSScreenStackPresentationFullScreenModal,
-  RNSScreenStackPresentationFormSheet
+  RNSScreenStackPresentationFormSheet,
+  RNSScreenStackPresentationPageSheet,
 };
 
 typedef NS_ENUM(NSInteger, RNSScreenStackAnimation) {

ios/RNSScreen.mm

@@ -260,6 +260,15 @@ - (void)setStackPresentation:(RNSScreenStackPresentation)stackPresentation
       }
 #endif
       break;
+
+    case RNSScreenStackPresentationPageSheet:
+#if !TARGET_OS_TV
+      _controller.modalPresentationStyle = UIModalPresentationPageSheet;
+#else
+      _controller.modalPresentationStyle = UIModalPresentationFullScreen;
+#endif
+      break;
+
     case RNSScreenStackPresentationFullScreenModal:
       _controller.modalPresentationStyle = UIModalPresentationFullScreen;
       break;
@@ -2036,6 +2045,7 @@ @implementation RCTConvert (RNSScreen)
       @"modal" : @(RNSScreenStackPresentationModal),
       @"fullScreenModal" : @(RNSScreenStackPresentationFullScreenModal),
       @"formSheet" : @(RNSScreenStackPresentationFormSheet),
+      @"pageSheet" : @(RNSScreenStackPresentationPageSheet),
       @"containedModal" : @(RNSScreenStackPresentationContainedModal),
       @"transparentModal" : @(RNSScreenStackPresentationTransparentModal),
       @"containedTransparentModal" : @(RNSScreenStackPresentationContainedTransparentModal)

native-stack/README.md

@@ -350,6 +350,7 @@ How the screen should be presented. Possible values:
 - `containedTransparentModal` – will use "UIModalPresentationOverCurrentContext" modal style on iOS and will fallback to `"transparentModal"` on Android.
 - `fullScreenModal` – will use "UIModalPresentationFullScreen" modal style on iOS and will fallback to `"modal"` on Android.
 - `formSheet` – will use "UIModalPresentationFormSheet" modal style on iOS and will fallback to `"modal"` on Android.
+- `pageSheet` – will use "UIModalPresentationPageSheet" modal style on iOS and will fallback to `"modal"` on Android.
 
 Defaults to `push`.
 

src/fabric/ModalScreenNativeComponent.ts

@@ -45,6 +45,7 @@ type StackPresentation =
   | 'transparentModal'
   | 'fullScreenModal'
   | 'formSheet'
+  | 'pageSheet'
   | 'containedModal'
   | 'containedTransparentModal';
 

src/fabric/ScreenNativeComponent.ts

@@ -45,6 +45,7 @@ type StackPresentation =
   | 'transparentModal'
   | 'fullScreenModal'
   | 'formSheet'
+  | 'pageSheet'
   | 'containedModal'
   | 'containedTransparentModal';