feat(Android, Stack v5): prevent native dismiss support (#3620)

## Description

**Add initial implementation of prevent native dismiss on Android**
This commit adds support for "prevent native dismiss" behavior on
Android for stack screens.

The added interface consists of prop on `StackScreen`:
`preventNativeDismiss` and event `onNativeDismissPrevented`, which
lets the programmer react to the native dismiss attempt.

This implementation follows
[RFC-0717](https://github.com/software-mansion/react-native-screens-labs/blob/main-issue-tracker/rfcs/0717-stack-prevent-dismiss.md).
**It does not handle JS-side of the mechanism.**

Closes
software-mansion/react-native-screens-labs#881

## Changes

This is achieved by leveraging a couple of native mechanisms.
First, I lean into usage of `OnBackPressedCallback` AndroidX API, which
lets us handle this very gracefully & hopefully correct on many
SDK levels.

> [!note]
> TODO: The behavior on lower SDK levels has not been tested yet.

Now, for each `StackScreenFragment` we add a dedicated callback, which
is enabled or disabled depending on the value. I do not add/remove the
callbacks because their order in the `OnBackPressedDispatcher` matter,
and we can add a callback only to the end of the list.

> [!caution]
> This implementation assumes that the fragments will move to `created`
> state in the order they are in the fragment manager (stack order).
> If this ever turns out to not be the case, we'll need to modify this
> implementation.

Beside above ☝🏻 the added code also introduces "top-fragment" mechanism.
It is necessary to prevent non-top-fragment from blocking native
dismiss.
Likely, when we introduce proper attach/detach mechanism for "non
visible" fragments we will be able to get rid of this new mechanism, but
currently it is necessary. Please see commit description:
1212f36

**Add missing "exported custom direct event type constants"**
I don't know how our events have worked so far. I thought that
overriding this method is obligatory. Apparently not. Maybe its
just hint for the React machinery. I'm not sure right now,
but I've verified that this code is indeed called & React gathers
this information.

## Visual documentation


https://github.com/user-attachments/assets/cfd8ab97-55c6-4d81-b3ec-1b50b4e46580


## Test plan

These do not test "dynamic" case. It requires a bit more setup in
`StackContainer` code that is too much outside of the scope of this PR.
I'll work on it separately.

`prevent-native-dismiss-single-stack`
`prevent-native-dismiss-nested-stack`


## Checklist

- [x] Included code example that can be used to test this change.
- [x] Updated / created local changelog entries in relevant test files.
- [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [x] For API changes, updated relevant public types.
- [x] Ensured that CI passes

Author: kkafar

android/src/main/java/com/swmansion/rnscreens/gamma/stack/host/FragmentOperation.kt

@@ -59,6 +59,7 @@ internal class FlushNowOp : FragmentOperation() {
 
 internal class SetPrimaryNavFragmentOp(
     val fragment: StackScreenFragment,
+    val onCommitCallback: Runnable? = null,
 ) : FragmentOperation() {
     override fun execute(
         fragmentManager: FragmentManager,

android/src/main/java/com/swmansion/rnscreens/gamma/stack/host/FragmentOperationExecutor.kt

@@ -63,6 +63,9 @@ internal class FragmentOperationExecutor {
     ) {
         fragmentManager.createTransactionWithReordering().let { tx ->
             tx.setPrimaryNavigationFragment(op.fragment)
+            if (op.onCommitCallback != null) {
+                tx.runOnCommit(op.onCommitCallback)
+            }
             commitTransaction(tx, allowStateLoss = true, flushSync = false)
         }
     }

android/src/main/java/com/swmansion/rnscreens/gamma/stack/host/StackContainer.kt

@@ -134,7 +134,12 @@ internal class StackContainer(
         check(stackModel.isNotEmpty()) { "[RNScreens] Stack should never be empty after updates" }
 
         // Top fragment is the primary navigation fragment.
-        fragmentOps.add(SetPrimaryNavFragmentOp(stackModel.last()))
+        val topStackFragment = stackModel.last()
+        fragmentOps.add(
+            SetPrimaryNavFragmentOp(topStackFragment, {
+                updateTopFragment()
+            }),
+        )
 
         pendingPopOperations.clear()
         pendingPushOperations.clear()
@@ -148,14 +153,17 @@ internal class StackContainer(
         check(stackModel.isNotEmpty()) { "[RNScreens] Stack model should not be empty after a native pop" }
 
         val fragmentManager = requireFragmentManager()
-        if (fragmentManager.primaryNavigationFragment === fragment) {
-            // We need to update the primary navigation fragment, otherwise the fragment manager
-            // will have invalid state, pointing to the dismissed fragment.
-            fragmentOpExecutor.executeOperations(
-                fragmentManager,
-                listOf(SetPrimaryNavFragmentOp(stackModel.last())),
-            )
-        }
+        check(fragmentManager.primaryNavigationFragment === fragment) { "[RNScreens] primaryNavFragment should be the one popped" }
+        // We need to update the primary navigation fragment, otherwise the fragment manager
+        // will have invalid state, pointing to the dismissed fragment.
+        fragmentOpExecutor.executeOperations(
+            fragmentManager,
+            listOf(
+                SetPrimaryNavFragmentOp(stackModel.last(), {
+                    updateTopFragment()
+                }),
+            ),
+        )
     }
 
     private fun dumpStackModel() {
@@ -170,6 +178,14 @@ internal class StackContainer(
             Log.d(TAG, "Created Fragment $it for screen ${screen.screenKey}")
         }
 
+    private fun updateTopFragment() {
+        // We try to handle situation where other fragments might be present.
+        val fragments = requireFragmentManager().fragments.filterIsInstance<StackScreenFragment>()
+        check(fragments.isNotEmpty()) { "[RNScreens] Empty fragment manager while attempting to update top fragment" }
+        fragments.forEach { it.onResignTopFragment() }
+        fragments.last().onBecomeTopFragment()
+    }
+
     // This is called after special effects (animations) are dispatched
     override fun onBackStackChanged() = Unit
 

android/src/main/java/com/swmansion/rnscreens/gamma/stack/screen/PreventNativeDismissCallback.kt

@@ -0,0 +1,72 @@
+package com.swmansion.rnscreens.gamma.stack.screen
+
+import android.util.Log
+import androidx.activity.OnBackPressedCallback
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleEventObserver
+import androidx.lifecycle.LifecycleOwner
+
+internal class PreventNativeDismissCallback(
+    lifecycleOwner: LifecycleOwner,
+    private val screen: StackScreen,
+    canBeEnabled: Boolean,
+) : OnBackPressedCallback(false),
+    LifecycleEventObserver,
+    PreventNativeDismissChangeObserver {
+    /**
+     * A kill-switch whether this callback can even be enabled or not. If set to false,
+     * no matter other conditions this callback won't be enabled.
+     */
+    internal var canBeEnabled: Boolean = canBeEnabled
+        set(value) {
+            field = value
+            determineEnabledStatus()
+        }
+
+    private val shouldBeEnabled
+        get() = canBeEnabled && screen.isPreventNativeDismissEnabled
+
+    init {
+        lifecycleOwner.lifecycle.addObserver(this)
+    }
+
+    override fun handleOnBackPressed() {
+        Log.i("RNScreens", "PreventNativeDismissCallback called for screen ${screen.screenKey}")
+        screen.onNativeDismissPrevented()
+    }
+
+    override fun onStateChanged(
+        source: LifecycleOwner,
+        event: Lifecycle.Event,
+    ) {
+        when (event) {
+            Lifecycle.Event.ON_CREATE -> {
+                screen.preventNativeDismissChangeObserver = this
+            }
+
+            Lifecycle.Event.ON_START -> {
+                determineEnabledStatus()
+            }
+
+            Lifecycle.Event.ON_STOP -> {
+                this.isEnabled = false
+            }
+
+            Lifecycle.Event.ON_DESTROY -> {
+                source.lifecycle.removeObserver(this)
+                screen.preventNativeDismissChangeObserver = null
+            }
+
+            else -> {
+            }
+        }
+    }
+
+    override fun preventNativeDismissChanged(newValue: Boolean) {
+        determineEnabledStatus()
+    }
+
+    private fun determineEnabledStatus() {
+        this.isEnabled = shouldBeEnabled
+    }
+}

android/src/main/java/com/swmansion/rnscreens/gamma/stack/screen/PreventNativeDismissChangeObserver.kt

@@ -0,0 +1,5 @@
+package com.swmansion.rnscreens.gamma.stack.screen
+
+internal interface PreventNativeDismissChangeObserver {
+    fun preventNativeDismissChanged(newValue: Boolean)
+}

android/src/main/java/com/swmansion/rnscreens/gamma/stack/screen/StackScreen.kt

@@ -21,6 +21,12 @@ class StackScreen(
         ATTACHED,
     }
 
+    internal var isPreventNativeDismissEnabled: Boolean by Delegates.observable(false) { _, oldValue, newValue ->
+        if (oldValue != newValue) {
+            preventNativeDismissChangeObserver?.preventNativeDismissChanged(newValue)
+        }
+    }
+
     internal var isNativelyDismissed = false
         set(value) {
             require(value) {
@@ -46,6 +52,11 @@ class StackScreen(
 
     internal lateinit var eventEmitter: StackScreenEventEmitter
 
+    /**
+     * Use this to set/unset the observer.
+     */
+    internal var preventNativeDismissChangeObserver: PreventNativeDismissChangeObserver? = null
+
     internal fun onViewManagerAddEventEmitters() {
         // When this is called from View Manager the view tag is already set
         check(id != NO_ID) { "[RNScreens] StackScreen must have its tag set when registering event emitters" }
@@ -62,6 +73,10 @@ class StackScreen(
         eventEmitter.emitOnDismiss(isNativelyDismissed)
     }
 
+    internal fun onNativeDismissPrevented() {
+        eventEmitter.emitOnNativeDismissPrevented()
+    }
+
     override fun onLayout(
         changed: Boolean,
         l: Int,

android/src/main/java/com/swmansion/rnscreens/gamma/stack/screen/StackScreenEventEmitter.kt

@@ -6,6 +6,7 @@ import com.swmansion.rnscreens.gamma.common.event.ViewAppearanceEventEmitter
 import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenDidAppearEvent
 import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenDidDisappearEvent
 import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenDismissEvent
+import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenNativeDismissPreventedEvent
 import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenWillAppearEvent
 import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenWillDisappearEvent
 
@@ -40,6 +41,15 @@ internal class StackScreenEventEmitter(
         )
     }
 
+    internal fun emitOnNativeDismissPrevented() {
+        reactEventDispatcher.dispatchEvent(
+            StackScreenNativeDismissPreventedEvent(
+                surfaceId,
+                viewTag,
+            ),
+        )
+    }
+
     companion object {
         const val TAG = "StackScreenEventEmitter"
     }

android/src/main/java/com/swmansion/rnscreens/gamma/stack/screen/StackScreenFragment.kt

@@ -12,6 +12,24 @@ internal class StackScreenFragment(
 ) : Fragment() {
     private var screenLifecycleEventEmitter: StackScreenAppearanceEventsEmitter? = null
 
+    /**
+     * This holds the screen strongly for now. Beware of retain cycle.
+     *
+     * Since each StackScreenFragment owns a PreventNativeDismissCallback & adds it to the
+     * OnBackPressedDispatcher the callback should be enabled only when the top fragment is this fragment.
+     */
+    private val preventNativeDismissBackPressedCallback =
+        PreventNativeDismissCallback(this, stackScreen, canBeEnabled = true)
+
+    private var isTopFragment: Boolean = false
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        requireActivity().onBackPressedDispatcher.addCallback(
+            preventNativeDismissBackPressedCallback,
+        )
+    }
+
     override fun onCreateView(
         inflater: LayoutInflater,
         container: ViewGroup?,
@@ -35,5 +53,30 @@ internal class StackScreenFragment(
         super.onDestroy()
         Log.i("StackScreenFragment", "onDestroy")
         stackScreen.onDismiss()
+        preventNativeDismissBackPressedCallback.remove()
+    }
+
+    /**
+     * Notifies this fragment that it has become "top fragment" in its fragment manager.
+     *
+     * This function should be idempotent.
+     */
+    internal fun onBecomeTopFragment() {
+        if (isTopFragment) return
+
+        isTopFragment = true
+        preventNativeDismissBackPressedCallback.canBeEnabled = true
+    }
+
+    /**
+     * Notifies this fragment that it is not longer the "top fragment" in its fragment manager.
+     *
+     * This function should be idempotent.
+     */
+    internal fun onResignTopFragment() {
+        if (!isTopFragment) return
+
+        isTopFragment = false
+        preventNativeDismissBackPressedCallback.canBeEnabled = false
     }
 }

android/src/main/java/com/swmansion/rnscreens/gamma/stack/screen/StackScreenViewManager.kt

@@ -7,6 +7,13 @@ import com.facebook.react.uimanager.ViewGroupManager
 import com.facebook.react.uimanager.ViewManagerDelegate
 import com.facebook.react.viewmanagers.RNSStackScreenManagerDelegate
 import com.facebook.react.viewmanagers.RNSStackScreenManagerInterface
+import com.swmansion.rnscreens.gamma.helpers.makeEventRegistrationInfo
+import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenDidAppearEvent
+import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenDidDisappearEvent
+import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenDismissEvent
+import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenNativeDismissPreventedEvent
+import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenWillAppearEvent
+import com.swmansion.rnscreens.gamma.stack.screen.event.StackScreenWillDisappearEvent
 
 @ReactModule(name = StackScreenViewManager.REACT_CLASS)
 class StackScreenViewManager :
@@ -28,6 +35,16 @@ class StackScreenViewManager :
         view.onViewManagerAddEventEmitters()
     }
 
+    override fun getExportedCustomDirectEventTypeConstants(): Map<String, Any> =
+        mutableMapOf(
+            makeEventRegistrationInfo(StackScreenWillAppearEvent),
+            makeEventRegistrationInfo(StackScreenWillDisappearEvent),
+            makeEventRegistrationInfo(StackScreenDidAppearEvent),
+            makeEventRegistrationInfo(StackScreenDidDisappearEvent),
+            makeEventRegistrationInfo(StackScreenDismissEvent),
+            makeEventRegistrationInfo(StackScreenNativeDismissPreventedEvent),
+        )
+
     override fun setActivityMode(
         view: StackScreen,
         value: String?,
@@ -49,6 +66,13 @@ class StackScreenViewManager :
         view.screenKey = value
     }
 
+    override fun setPreventNativeDismiss(
+        view: StackScreen,
+        value: Boolean,
+    ) {
+        view.isPreventNativeDismissEnabled = value
+    }
+
     companion object {
         const val REACT_CLASS = "RNSStackScreen"
     }

android/src/main/java/com/swmansion/rnscreens/gamma/stack/screen/event/StackScreenNativeDismissPreventedEvent.kt

@@ -0,0 +1,22 @@
+package com.swmansion.rnscreens.gamma.stack.screen.event
+
+import com.swmansion.rnscreens.gamma.common.event.NamingAwareEventType
+
+internal class StackScreenNativeDismissPreventedEvent(
+    surfaceId: Int,
+    viewId: Int,
+) : StackScreenLifecycleEvent<StackScreenNativeDismissPreventedEvent>(
+        surfaceId,
+        viewId,
+        EVENT_NAME,
+        EVENT_REGISTRATION_NAME,
+    ) {
+    companion object : NamingAwareEventType {
+        const val EVENT_NAME = "topNativeDismissPrevented"
+        const val EVENT_REGISTRATION_NAME = "onNativeDismissPrevented"
+
+        override fun getEventName() = EVENT_NAME
+
+        override fun getEventRegistrationName() = EVENT_REGISTRATION_NAME
+    }
+}