feat: provide a way to prevent native navigation

TestsExample/src/Test556.js

@@ -31,4 +31,3 @@ function Second({navigation}) {
     <Button title="Tap me for second screen" onPress={() => navigation.navigate('First')} />
   );
 }
-

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

@@ -35,6 +35,7 @@ class Screen constructor(context: ReactContext?) : ViewGroup(context) {
     private var mStatusBarTranslucent: Boolean? = null
     private var mStatusBarColor: Int? = null
     var isStatusBarAnimated: Boolean? = null
+    private var mNativeBackButtonDismissalEnabled = true
 
     init {
         // we set layout params as WindowManager.LayoutParams to workaround the issue with TextInputs
@@ -228,6 +229,12 @@ class Screen constructor(context: ReactContext?) : ViewGroup(context) {
             fragment?.let { ScreenWindowTraits.setColor(this, it.tryGetActivity(), it.tryGetContext()) }
         }
 
+    var nativeBackButtonDismissalEnabled: Boolean
+        get() = mNativeBackButtonDismissalEnabled
+        set(enableNativeBackButtonDismissal) {
+            mNativeBackButtonDismissalEnabled = enableNativeBackButtonDismissal
+        }
+
     enum class StackPresentation {
         PUSH, MODAL, TRANSPARENT_MODAL
     }

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

@@ -13,6 +13,7 @@ import com.facebook.react.bridge.ReactContext
 import com.facebook.react.bridge.UiThreadUtil
 import com.facebook.react.uimanager.UIManagerModule
 import com.facebook.react.uimanager.events.Event
+import com.swmansion.rnscreens.events.HeaderBackButtonClickedEvent
 import com.swmansion.rnscreens.events.ScreenAppearEvent
 import com.swmansion.rnscreens.events.ScreenDisappearEvent
 import com.swmansion.rnscreens.events.ScreenDismissedEvent
@@ -179,6 +180,13 @@ open class ScreenFragment : Fragment {
         }
     }
 
+    fun dispatchHeaderBackButtonClickedEvent() {
+        (screen.context as ReactContext)
+            .getNativeModule(UIManagerModule::class.java)
+            ?.eventDispatcher
+            ?.dispatchEvent(HeaderBackButtonClickedEvent(screen.id))
+    }
+
     fun dispatchTransitionProgress(alpha: Float, closing: Boolean) {
         if (this is ScreenStackFragment) {
             if (mProgress != alpha) {

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

@@ -46,10 +46,18 @@ class ScreenStackHeaderConfig(context: Context) : ViewGroup(context) {
             if (stack != null && stack.rootScreen == it.screen) {
                 val parentFragment = it.parentFragment
                 if (parentFragment is ScreenStackFragment) {
-                    parentFragment.dismiss()
+                    if (parentFragment.screen.nativeBackButtonDismissalEnabled) {
+                        parentFragment.dismiss()
+                    } else {
+                        parentFragment.dispatchHeaderBackButtonClickedEvent()
+                    }
                 }
             } else {
-                it.dismiss()
+                if (it.screen.nativeBackButtonDismissalEnabled) {
+                    it.dismiss()
+                } else {
+                    it.dispatchHeaderBackButtonClickedEvent()
+                }
             }
         }
     }

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

@@ -6,6 +6,7 @@ import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.ViewGroupManager
 import com.facebook.react.uimanager.annotations.ReactProp
+import com.swmansion.rnscreens.events.HeaderBackButtonClickedEvent
 import com.swmansion.rnscreens.events.ScreenAppearEvent
 import com.swmansion.rnscreens.events.ScreenDisappearEvent
 import com.swmansion.rnscreens.events.ScreenDismissedEvent
@@ -111,8 +112,16 @@ class ScreenViewManager : ViewGroupManager<Screen>() {
         view.isStatusBarHidden = statusBarHidden
     }
 
-    override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any>? {
-        return MapBuilder.of(
+    @ReactProp(name = "nativeBackButtonDismissalEnabled")
+    fun setNativeBackButtonDismissalEnabled(
+        view: Screen,
+        nativeBackButtonDismissalEnabled: Boolean
+    ) {
+        view.nativeBackButtonDismissalEnabled = nativeBackButtonDismissalEnabled
+    }
+
+    override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any> {
+        val map: MutableMap<String, Any> = MapBuilder.of(
             ScreenDismissedEvent.EVENT_NAME,
             MapBuilder.of("registrationName", "onDismissed"),
             ScreenWillAppearEvent.EVENT_NAME,
@@ -126,8 +135,11 @@ class ScreenViewManager : ViewGroupManager<Screen>() {
             StackFinishTransitioningEvent.EVENT_NAME,
             MapBuilder.of("registrationName", "onFinishTransitioning"),
             ScreenTransitionProgressEvent.EVENT_NAME,
-            MapBuilder.of("registrationName", "onTransitionProgress"),
+            MapBuilder.of("registrationName", "onTransitionProgress")
         )
+        // there is no `MapBuilder.of` with more than 7 items
+        map[HeaderBackButtonClickedEvent.EVENT_NAME] = MapBuilder.of("registrationName", "onHeaderBackButtonClicked")
+        return map
     }
 
     companion object {

android/src/main/java/com/swmansion/rnscreens/events/HeaderBackButtonClickedEvent.kt

@@ -0,0 +1,24 @@
+package com.swmansion.rnscreens.events
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.uimanager.events.Event
+import com.facebook.react.uimanager.events.RCTEventEmitter
+
+class HeaderBackButtonClickedEvent(viewId: Int) : Event<ScreenAppearEvent>(viewId) {
+    override fun getEventName(): String {
+        return EVENT_NAME
+    }
+
+    override fun getCoalescingKey(): Short {
+        // All events for a given view can be coalesced.
+        return 0
+    }
+
+    override fun dispatch(rctEventEmitter: RCTEventEmitter) {
+        rctEventEmitter.receiveEvent(viewTag, eventName, Arguments.createMap())
+    }
+
+    companion object {
+        const val EVENT_NAME = "topHeaderBackButtonClickedEvent"
+    }
+}

createNativeStackNavigator/README.md

@@ -162,7 +162,7 @@ Whether to show or hide the header for the screen. The header is shown by defaul
 Style object for the header. Supported properties:
 
 - `backgroundColor`
-- `blurEffect` (iOS only). Possible values can be checked in `index.d.ts` file.
+- `blurEffect` (iOS only).
 
 #### `headerTintColor`
 
@@ -189,6 +189,13 @@ A Boolean to that lets you opt out of insetting the header. You may want to * se
 
 Boolean indicating whether the navigation bar is translucent.
 
+#### `nativeBackButtonDismissalEnabled` (Android only)
+
+Boolean indicating whether, when the Android default back button is clicked, the `pop` action should be performed on the native side or on the JS side to be able to prevent it.
+Unfortunately the same behavior is not available on iOS since the behavior of native back button cannot be changed there.
+
+Defaults to `false`.
+
 #### `replaceAnimation`
 
 How should the screen replacing another screen animate.

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -48,6 +48,13 @@ Boolean indicating whether the swipe gesture should work on whole screen. Swipin
 
 When set to `false` the back swipe gesture will be disabled. The default value is `true`.
 
+### `nativeBackButtonDismissalEnabled` (Android only)
+
+Boolean indicating whether, when the Android default back button is clicked, the `pop` action should be performed on the native side or on the JS side to be able to prevent it.
+Unfortunately the same behavior is not available on iOS since the behavior of native back button cannot be changed there.
+
+Defaults to `false`.
+
 ### `onAppear`
 
 A callback that gets called when the current screen appears.
@@ -60,6 +67,10 @@ A callback that gets called when the current screen disappears.
 
 A callback that gets called when the current screen is dismissed by hardware back (on Android) or dismiss gesture (swipe back or down). The callback takes no arguments.
 
+### `onHeaderBackButtonClicked` (Android only)
+
+A callback that gets called when the native header back button is clicked on Android and `enableNativeBackButtonDismissal` is set to `false`.
+
 ### `onWillAppear`
 
 A callback that gets called when the current screen will appear. This is called as soon as the transition begins.

ios/RNSScreen.h

@@ -79,7 +79,9 @@ typedef NS_ENUM(NSInteger, RNSWindowTrait) {
 @property (nonatomic, copy) RCTDirectEventBlock onDismissed;
 @property (nonatomic, copy) RCTDirectEventBlock onWillAppear;
 @property (nonatomic, copy) RCTDirectEventBlock onWillDisappear;
+@property (nonatomic, copy) RCTDirectEventBlock onNativeDismissCancelled;
 @property (nonatomic, copy) RCTDirectEventBlock onTransitionProgress;
+
 @property (weak, nonatomic) UIView<RNSScreenContainerDelegate> *reactSuperview;
 @property (nonatomic, retain) UIViewController *controller;
 @property (nonatomic, readonly) BOOL dismissed;
@@ -88,6 +90,7 @@ typedef NS_ENUM(NSInteger, RNSWindowTrait) {
 @property (nonatomic) RNSScreenStackAnimation stackAnimation;
 @property (nonatomic) RNSScreenStackPresentation stackPresentation;
 @property (nonatomic) RNSScreenReplaceAnimation replaceAnimation;
+@property (nonatomic) BOOL preventNativeDismiss;
 @property (nonatomic) BOOL hasOrientationSet;
 @property (nonatomic) BOOL hasStatusBarStyleSet;
 @property (nonatomic) BOOL hasStatusBarAnimationSet;

ios/RNSScreen.m

@@ -274,6 +274,13 @@ - (void)notifyDisappear
   }
 }
 
+- (void)notifyDismissCancelledWithDismissCount:(int)dismissCount
+{
+  if (self.onNativeDismissCancelled) {
+    self.onNativeDismissCancelled(@{@"dismissCount" : @(dismissCount)});
+  }
+}
+
 - (void)notifyTransitionProgress:(double)progress closing:(BOOL)closing goingForward:(BOOL)goingForward
 {
   if (self.onTransitionProgress) {
@@ -342,6 +349,10 @@ - (RCTTouchHandler *)touchHandler
 
 - (BOOL)presentationControllerShouldDismiss:(UIPresentationController *)presentationController
 {
+  if (_preventNativeDismiss) {
+    [self notifyDismissCancelledWithDismissCount:1];
+    return NO;
+  }
   return _gestureEnabled;
 }
 
@@ -621,8 +632,15 @@ - (void)viewDidDisappear:(BOOL)animated
   [super viewDidDisappear:animated];
 
   if (self.parentViewController == nil && self.presentingViewController == nil) {
-    // screen dismissed, send event
-    [((RNSScreenView *)self.view) notifyDismissedWithCount:_dismissCount];
+    if (((RNSScreenView *)self.view).preventNativeDismiss) {
+      // if we want to prevent the native dismiss, we do not send dismissal event,
+      // but instead call `updateContainer`, which restores the JS navigation stack
+      [((RNSScreenView *)self.view).reactSuperview updateContainer];
+      [((RNSScreenView *)self.view) notifyDismissCancelledWithDismissCount:_dismissCount];
+    } else {
+      // screen dismissed, send event
+      [((RNSScreenView *)self.view) notifyDismissedWithCount:_dismissCount];
+    }
   }
 
   // same flow as in viewDidAppear
@@ -711,24 +729,27 @@ @implementation RNSScreenManager
 
 // we want to handle the case when activityState is nil
 RCT_REMAP_VIEW_PROPERTY(activityState, activityStateOrNil, NSNumber)
+RCT_EXPORT_VIEW_PROPERTY(customAnimationOnSwipe, BOOL);
+RCT_EXPORT_VIEW_PROPERTY(fullScreenSwipeEnabled, BOOL);
 RCT_EXPORT_VIEW_PROPERTY(gestureEnabled, BOOL)
+RCT_EXPORT_VIEW_PROPERTY(preventNativeDismiss, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(replaceAnimation, RNSScreenReplaceAnimation)
 RCT_EXPORT_VIEW_PROPERTY(stackPresentation, RNSScreenStackPresentation)
 RCT_EXPORT_VIEW_PROPERTY(stackAnimation, RNSScreenStackAnimation)
-RCT_EXPORT_VIEW_PROPERTY(onWillAppear, RCTDirectEventBlock);
-RCT_EXPORT_VIEW_PROPERTY(onWillDisappear, RCTDirectEventBlock);
+
 RCT_EXPORT_VIEW_PROPERTY(onAppear, RCTDirectEventBlock);
 RCT_EXPORT_VIEW_PROPERTY(onDisappear, RCTDirectEventBlock);
 RCT_EXPORT_VIEW_PROPERTY(onDismissed, RCTDirectEventBlock);
+RCT_EXPORT_VIEW_PROPERTY(onNativeDismissCancelled, RCTDirectEventBlock);
 RCT_EXPORT_VIEW_PROPERTY(onTransitionProgress, RCTDirectEventBlock);
-RCT_EXPORT_VIEW_PROPERTY(customAnimationOnSwipe, BOOL);
-RCT_EXPORT_VIEW_PROPERTY(fullScreenSwipeEnabled, BOOL);
+RCT_EXPORT_VIEW_PROPERTY(onWillAppear, RCTDirectEventBlock);
+RCT_EXPORT_VIEW_PROPERTY(onWillDisappear, RCTDirectEventBlock);
 
 #if !TARGET_OS_TV
 RCT_EXPORT_VIEW_PROPERTY(screenOrientation, UIInterfaceOrientationMask)
-RCT_EXPORT_VIEW_PROPERTY(statusBarStyle, RNSStatusBarStyle)
 RCT_EXPORT_VIEW_PROPERTY(statusBarAnimation, UIStatusBarAnimation)
 RCT_EXPORT_VIEW_PROPERTY(statusBarHidden, BOOL)
+RCT_EXPORT_VIEW_PROPERTY(statusBarStyle, RNSStatusBarStyle)
 #endif
 
 - (UIView *)view

ios/RNSScreenContainer.h

@@ -3,6 +3,7 @@
 @protocol RNSScreenContainerDelegate
 
 - (void)markChildUpdated;
+- (void)updateContainer;
 
 @end
 

ios/RNSScreenStack.m

@@ -558,6 +558,7 @@ - (BOOL)gestureRecognizerShouldBegin:(UIGestureRecognizer *)gestureRecognizer
   if (!topScreen.gestureEnabled || _controller.viewControllers.count < 2) {
     return NO;
   }
+
 #if TARGET_OS_TV
   [self cancelTouchesInParent];
   return YES;

native-stack/README.md

@@ -155,7 +155,7 @@ Whether to show or hide the header for the screen. The header is shown by defaul
 Style object for the header. Supported properties:
 
 - `backgroundColor`
-- `blurEffect` (iOS only). Possible values can be checked in `index.d.ts` file.
+- `blurEffect` (iOS only).
 
 #### `headerTintColor`
 
@@ -182,6 +182,13 @@ A Boolean to that lets you opt out of insetting the header. You may want to * se
 
 Boolean indicating whether the navigation bar is translucent.
 
+#### `nativeBackButtonDismissalEnabled` (Android only)
+
+Boolean indicating whether, when the Android default back button is clicked, the `pop` action should be performed on the native side or on the JS side to be able to prevent it.
+Unfortunately the same behavior is not available on iOS since the behavior of native back button cannot be changed there.
+
+Defaults to `false`.
+
 #### `replaceAnimation`
 
 How should the screen replacing another screen animate.

src/createNativeStackNavigator.tsx

@@ -478,6 +478,9 @@ function StackView({
                 ? true
                 : options.gestureEnabled
             }
+            nativeBackButtonDismissalEnabled={
+              options.nativeBackButtonDismissalEnabled
+            }
             fullScreenSwipeEnabled={options.fullScreenSwipeEnabled}
             screenOrientation={options.screenOrientation}
             statusBarAnimation={options.statusBarAnimation}
@@ -489,6 +492,9 @@ function StackView({
             onWillAppear={() => options?.onWillAppear?.()}
             onWillDisappear={() => options?.onWillDisappear?.()}
             onDisappear={() => options?.onDisappear?.()}
+            onHeaderBackButtonClicked={() =>
+              removeScene(route, 1, routeNavigationProp)
+            }
             onDismissed={(e) =>
               removeScene(
                 route,

src/native-stack/types.tsx

@@ -243,6 +243,14 @@ export type NativeStackNavigationOptions = {
    * Boolean indicating whether the navigation bar is translucent.
    */
   headerTranslucent?: boolean;
+  /**
+   * Boolean indicating whether, when the Android default back button is clicked, the `pop` action should be performed on the native side or on the JS side to be able to prevent it.
+   * Unfortunately the same behavior is not available on iOS since the behavior of native back button cannot be changed there.
+   * Defaults to `false`.
+   *
+   * @platform android
+   */
+  nativeBackButtonDismissalEnabled?: boolean;
   /**
    * How should the screen replacing another screen animate. Defaults to `pop`.
    * The following values are currently supported:

src/native-stack/views/NativeStackView.tsx

@@ -153,6 +153,7 @@ const RouteView = ({
     fullScreenSwipeEnabled,
     gestureEnabled,
     headerShown,
+    nativeBackButtonDismissalEnabled = false,
     replaceAnimation = 'pop',
     screenOrientation,
     stackAnimation,
@@ -189,11 +190,12 @@ const RouteView = ({
     <Screen
       key={route.key}
       enabled
-      style={StyleSheet.absoluteFill}
       isNativeStack
+      style={StyleSheet.absoluteFill}
       customAnimationOnSwipe={customAnimationOnSwipe}
-      gestureEnabled={isAndroid ? false : gestureEnabled}
       fullScreenSwipeEnabled={fullScreenSwipeEnabled}
+      gestureEnabled={isAndroid ? false : gestureEnabled}
+      nativeBackButtonDismissalEnabled={nativeBackButtonDismissalEnabled}
       replaceAnimation={replaceAnimation}
       screenOrientation={screenOrientation}
       stackAnimation={stackAnimation}
@@ -203,6 +205,13 @@ const RouteView = ({
       statusBarHidden={statusBarHidden}
       statusBarStyle={statusBarStyle}
       statusBarTranslucent={statusBarTranslucent}
+      onHeaderBackButtonClicked={() => {
+        navigation.dispatch({
+          ...StackActions.pop(),
+          source: route.key,
+          target: stateKey,
+        });
+      }}
       onWillAppear={() => {
         navigation.emit({
           type: 'transitionStart',