feat(Android, Stack v5): handle preloading screens (#3576)

## Description

Adds support for preloading screens. Allows for multiple operations in
one React transition.

Closes
software-mansion/react-native-screens-labs#819.

### Details

#### Preload

As described in the description of
#3531,
previous approach to handling detached screens did not work due to how
`react-native` works when children views are reordered and inserted
again.

To mitigate this problem, we decided to change the approach. Now,
`StackScreen`s will be rendered inside `StackHost` in the following
order:

1. First, all attached screens are rendered in the order that reflects
current stack state (so ABC always matches to stack with A at the bottom
and C at the top)
2. Then, all detached screens are rendered.

This change has 2 main advantages:

1. We will never move a screen in `attached` state therefore we will
avoid React removing the screen from parent view when trying to reinsert
it.
2. In result of the above, there will never be a situation where an
attached screen will be popped and pushed in one transaction (unless
someone explicitly does so) therefore we don't need to implement a
mechanism for cancelling out those operations.

There is one drawback: this approach will not help with fixing the
inspector, it needs to be handled separately.

#### Multiple operations in one React transaction.

When multiple operations are performed in one transaction, we can't rely
on the order of updates from React.

For example, if we have `ABCdefg` state (lowercase means detached state)
and we perform at the same time:
```
pop(C)
pop(B)
push(G)
push(E)
```

we end up with `AGEbcdf` state. This information is passed to native
side via those operations:

```
remove(G)
remove(E)
insert(G, 1)
insert(E, 2)
update(B, 'detached')
update(C, 'detached')
update(E, 'attached')
update(G, 'attached')
```

If we tried to translate those operations directly without any
reordering, we would get:
```
pop(B)
pop(C)
push(E)
push(G)
```

1. Order of pops is incorrect - we need to pop the top screen (C) first.
2. Order of pushes is incorrect - we would get `AEG...` instead of
desired `AGE...`.

Therefore we need a mechanism to synchronize the order of operations
with the state of the stack. We can use `StackHost`'s children to
determine this - if we know that our children are `AGEbcdf`, we know
that C needs to be popped before B and G needs to be pushed before E.

## Changes

- add `StackContainerUpdateCoordinator` to ensure correct order of push
& pop operations
- add separate push & pop queues to `StackContainer` to ensure order
(first pops, then pushes) + in the future, allow for simple detection of
necessity of using replace animation
- add batch action to `StackContainer`
- create `Test3576` to test batch operations in new stack implementation

## Before & after - visual documentation

### Preload on TestScreenStack

| Before | After |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/52ab058b-7bec-4141-b1d7-939e0ba0619c"
/> | <video
src="https://github.com/user-attachments/assets/75641233-0bf7-4e2b-a430-be3d71371c90"
/> |

### Multiple operations in one transaction


https://github.com/user-attachments/assets/00c61bde-3277-4953-9a06-222953c320bb

## Test plan

1. Run `TestScreenStack`. Preload B, push A, push B. Hierarchy should
contain screens ABA.
4. Run `Test3576`. Run scenario 1. 

## Checklist

- [x] Included code example that can be used to test this change.
- [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [ ] Ensured that CI passes

---------

Co-authored-by: Kacper Kafara <kacperkafara@gmail.com>

Author: kligarski

…screens/gamma/common/BaseEventEmitter.kt …s/gamma/common/event/BaseEventEmitter.ktandroid/src/main/java/com/swmansion/rnscreens/gamma/common/BaseEventEmitter.kt renamed to android/src/main/java/com/swmansion/rnscreens/gamma/common/event/BaseEventEmitter.kt android/src/main/java/com/swmansion/rnscreens/gamma/common/BaseEventEmitter.kt renamed to android/src/main/java/com/swmansion/rnscreens/gamma/common/event/BaseEventEmitter.kt

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.gamma.common
+package com.swmansion.rnscreens.gamma.common.event
 
 import com.facebook.react.bridge.ReactContext
 import com.facebook.react.uimanager.UIManagerHelper

…ens/gamma/common/NamingAwareEventType.kt …mma/common/event/NamingAwareEventType.ktandroid/src/main/java/com/swmansion/rnscreens/gamma/common/NamingAwareEventType.kt renamed to android/src/main/java/com/swmansion/rnscreens/gamma/common/event/NamingAwareEventType.kt android/src/main/java/com/swmansion/rnscreens/gamma/common/NamingAwareEventType.kt renamed to android/src/main/java/com/swmansion/rnscreens/gamma/common/event/NamingAwareEventType.kt

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.gamma.common
+package com.swmansion.rnscreens.gamma.common.event
 
 internal interface NamingAwareEventType {
     /**

android/src/main/java/com/swmansion/rnscreens/gamma/common/event/ViewAppearanceEventEmitter.kt

@@ -0,0 +1,11 @@
+package com.swmansion.rnscreens.gamma.common.event
+
+internal interface ViewAppearanceEventEmitter {
+    fun emitOnWillAppear()
+
+    fun emitOnDidAppear()
+
+    fun emitOnWillDisappear()
+
+    fun emitOnDidDisappear()
+}

android/src/main/java/com/swmansion/rnscreens/gamma/helpers/EventHelpers.kt

@@ -1,6 +1,6 @@
 package com.swmansion.rnscreens.gamma.helpers
 
-import com.swmansion.rnscreens.gamma.common.NamingAwareEventType
+import com.swmansion.rnscreens.gamma.common.event.NamingAwareEventType
 
 internal fun makeEventRegistrationInfo(event: NamingAwareEventType): Pair<String, HashMap<String, String>> =
     event.getEventName() to hashMapOf("registrationName" to event.getEventRegistrationName())

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

@@ -4,7 +4,6 @@ import android.annotation.SuppressLint
 import android.content.Context
 import androidx.coordinatorlayout.widget.CoordinatorLayout
 import androidx.fragment.app.FragmentManager
-import androidx.fragment.app.FragmentTransaction
 import com.swmansion.rnscreens.gamma.helpers.FragmentManagerHelper
 import com.swmansion.rnscreens.gamma.helpers.ViewIdGenerator
 import com.swmansion.rnscreens.gamma.helpers.createTransactionWithReordering
@@ -13,16 +12,6 @@ import com.swmansion.rnscreens.gamma.stack.screen.StackScreenFragment
 import com.swmansion.rnscreens.utils.RNSLog
 import java.lang.ref.WeakReference
 
-internal sealed class StackOperation
-
-internal class AddOperation(
-    val screen: StackScreen,
-) : StackOperation()
-
-internal class PopOperation(
-    val screen: StackScreen,
-) : StackOperation()
-
 @SuppressLint("ViewConstructor") // Only we construct this view, it is never inflated.
 internal class StackContainer(
     context: Context,
@@ -31,7 +20,11 @@ internal class StackContainer(
     private var fragmentManager: FragmentManager? = null
 
     private val stackScreenFragments: MutableList<StackScreenFragment> = arrayListOf()
-    private val pendingOperationQueue: MutableList<StackOperation> = arrayListOf()
+
+    private val pendingPopOperations: MutableList<PopOperation> = arrayListOf()
+    private val pendingPushOperations: MutableList<PushOperation> = arrayListOf()
+    private val hasPendingOperations: Boolean
+        get() = pendingPushOperations.isNotEmpty() || pendingPopOperations.isNotEmpty()
 
     init {
         id = ViewIdGenerator.generateViewId()
@@ -58,91 +51,75 @@ internal class StackContainer(
         // If container update is requested before container is attached to window, we ignore
         // the call because we don't have valid fragmentManager yet.
         // Update will be eventually executed in onAttachedToWindow().
-        if (pendingOperationQueue.isNotEmpty() && isAttachedToWindow) {
+        if (hasPendingOperations && isAttachedToWindow) {
             val fragmentManager =
                 checkNotNull(fragmentManager) { "[RNScreens] Fragment manager was null during stack container update" }
-            performOperations(fragmentManager, false)
+            performOperations(fragmentManager)
         }
     }
 
-    internal fun enqueueAddOperation(stackScreen: StackScreen) {
-        pendingOperationQueue.add(AddOperation(stackScreen))
+    internal fun enqueuePushOperation(stackScreen: StackScreen) {
+        pendingPushOperations.add(PushOperation(stackScreen))
     }
 
     internal fun enqueuePopOperation(stackScreen: StackScreen) {
-        pendingOperationQueue.add(PopOperation(stackScreen))
+        pendingPopOperations.add(PopOperation(stackScreen))
     }
 
-    private fun performOperations(
-        fragmentManager: FragmentManager,
-        commitSync: Boolean = false,
-    ) {
-        val transaction = fragmentManager.createTransactionWithReordering()
-        pendingOperationQueue.forEach { operation -> performOperation(fragmentManager, transaction, operation) }
+    private fun performOperations(fragmentManager: FragmentManager) {
+        pendingPopOperations.forEach { performPopOperation(fragmentManager, it) }
+        pendingPushOperations.forEach { performPushOperation(fragmentManager, it) }
 
-        // TODO: refactor + should every push be added as separate back stack entry to maintain history?
-        val lastPushScreenKey =
-            pendingOperationQueue
-                .asReversed()
-                .filter { it is AddOperation }
-                .map { operation -> (operation as AddOperation).screen.screenKey }
-                .firstOrNull()
-
-        pendingOperationQueue.clear()
-
-        // Pop operation does not use transaction
-        if (!transaction.isEmpty) {
-            require(lastPushScreenKey != null) { "[RNScreens] Expected non-null screenKey for back stack entry." }
-
-            // don't add root to back stack to handle exiting from app.
-            if (fragmentManager.fragments.isNotEmpty()) {
-                transaction.addToBackStack(lastPushScreenKey)
-            }
-
-            if (commitSync) {
-                // TODO: will not work with back stack
-                transaction.commitNowAllowingStateLoss()
-            } else {
-                transaction.commitAllowingStateLoss()
-            }
-        }
+        pendingPopOperations.clear()
+        pendingPushOperations.clear()
     }
 
-    private fun performOperation(
+    private fun performPushOperation(
         fragmentManager: FragmentManager,
-        transaction: FragmentTransaction,
-        operation: StackOperation,
+        operation: PushOperation,
     ) {
-        when (operation) {
-            is AddOperation -> performAddOperation(transaction, operation)
-            is PopOperation -> performPopOperation(fragmentManager, operation)
-        }
-    }
+        val transaction = fragmentManager.createTransactionWithReordering()
 
-    private fun performAddOperation(
-        transaction: FragmentTransaction,
-        operation: AddOperation,
-    ) {
         val associatedFragment = StackScreenFragment(WeakReference(this), operation.screen)
         stackScreenFragments.add(associatedFragment)
+
         transaction.add(this.id, associatedFragment)
+
+        // Don't add root screen to back stack to handle exiting from app.
+        if (fragmentManager.fragments.isNotEmpty()) {
+            transaction.addToBackStack(operation.screen.screenKey)
+        }
+
+        transaction.commitAllowingStateLoss()
     }
 
     private fun performPopOperation(
         fragmentManager: FragmentManager,
         operation: PopOperation,
     ) {
-        val backStackEntryCount = fragmentManager.backStackEntryCount
-        require(backStackEntryCount > 0) { "[RNScreens] Back stack must not be empty." }
+        val associatedFragment = stackScreenFragments.find { it.stackScreen === operation.screen }
+        require(associatedFragment != null) {
+            "[RNScreens] Unable to find a fragment to pop."
+        }
 
-        val lastBackStackEntry = fragmentManager.getBackStackEntryAt(backStackEntryCount - 1)
-        require(lastBackStackEntry.name == operation.screen.screenKey) { "[RNScreens] Popping is supported only for top screen." }
+        val backStackEntryCount = fragmentManager.backStackEntryCount
+        if (backStackEntryCount > 0) {
+            fragmentManager.popBackStack(
+                operation.screen.screenKey,
+                FragmentManager.POP_BACK_STACK_INCLUSIVE,
+            )
+        } else {
+            // When fast refresh is used on root screen, we need to remove the screen manually.
+            val transaction = fragmentManager.createTransactionWithReordering()
+            transaction.remove(associatedFragment)
+            transaction.commitNowAllowingStateLoss()
+        }
 
-        fragmentManager.popBackStack(lastBackStackEntry.name, FragmentManager.POP_BACK_STACK_INCLUSIVE)
+        stackScreenFragments.remove(associatedFragment)
     }
 
     internal fun onFragmentDestroyView(fragment: StackScreenFragment) {
-        delegate.get()?.onDismiss(fragment.stackScreen)
+        delegate.get()?.onScreenDismiss(fragment.stackScreen)
     }
 
     companion object {

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

@@ -3,5 +3,5 @@ package com.swmansion.rnscreens.gamma.stack.host
 import com.swmansion.rnscreens.gamma.stack.screen.StackScreen
 
 internal interface StackContainerDelegate {
-    fun onDismiss(stackScreen: StackScreen)
+    fun onScreenDismiss(stackScreen: StackScreen)
 }

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

@@ -0,0 +1,43 @@
+package com.swmansion.rnscreens.gamma.stack.host
+
+import com.swmansion.rnscreens.gamma.stack.screen.StackScreen
+
+internal class StackContainerUpdateCoordinator {
+    private val pendingPushOperations: MutableList<PushOperation> = arrayListOf()
+    private val pendingPopOperations: MutableList<PopOperation> = arrayListOf()
+    private val hasPendingOperations: Boolean
+        get() = pendingPushOperations.isNotEmpty() || pendingPopOperations.isNotEmpty()
+
+    internal fun addPushOperation(stackScreen: StackScreen) {
+        pendingPushOperations.add(PushOperation(stackScreen))
+    }
+
+    internal fun addPopOperation(stackScreen: StackScreen) {
+        pendingPopOperations.add(PopOperation(stackScreen))
+    }
+
+    internal fun executePendingOperationsIfNeeded(
+        container: StackContainer,
+        renderedScreens: List<StackScreen>,
+    ) {
+        if (!hasPendingOperations) {
+            return
+        }
+
+        pendingPopOperations
+            .map { Pair(renderedScreens.indexOf(it.screen), it) }
+            .sortedBy { it.first }
+            .asReversed()
+            .forEach { (_, operation) -> container.enqueuePopOperation(operation.screen) }
+
+        pendingPushOperations
+            .map { Pair(renderedScreens.indexOf(it.screen), it) }
+            .sortedBy { it.first }
+            .forEach { (_, operation) -> container.enqueuePushOperation(operation.screen) }
+
+        container.performContainerUpdateIfNeeded()
+
+        pendingPopOperations.clear()
+        pendingPushOperations.clear()
+    }
+}

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

@@ -21,6 +21,7 @@ class StackHost(
     StackContainerDelegate {
     internal val renderedScreens: ArrayList<StackScreen> = arrayListOf()
     private val container = StackContainer(reactContext, WeakReference(this))
+    private val containerUpdateCoordinator = StackContainerUpdateCoordinator()
 
     init {
         addView(container)
@@ -44,50 +45,47 @@ class StackHost(
     ) {
         renderedScreens.add(index, stackScreen)
         stackScreen.stackHost = WeakReference(this)
-        enqueueAddOperationToContainerIfNeeded(stackScreen)
+        addPushOperationIfNeeded(stackScreen)
     }
 
     internal fun unmountReactSubviewAt(index: Int) {
         val removedScreen = renderedScreens.removeAt(index)
-        enqueuePopOperationToContainerIfNeeded(removedScreen)
+        addPopOperationIfNeeded(removedScreen)
     }
 
     internal fun unmountReactSubview(reactSubview: StackScreen) {
         renderedScreens.remove(reactSubview)
-        enqueuePopOperationToContainerIfNeeded(reactSubview)
+        addPopOperationIfNeeded(reactSubview)
     }
 
     internal fun unmountAllReactSubviews() {
         renderedScreens.asReversed().forEach {
-            enqueuePopOperationToContainerIfNeeded(it)
+            addPopOperationIfNeeded(it)
         }
         renderedScreens.clear()
     }
 
-    private fun enqueueAddOperationToContainerIfNeeded(stackScreen: StackScreen) {
+    private fun addPushOperationIfNeeded(stackScreen: StackScreen) {
         if (stackScreen.activityMode == StackScreen.ActivityMode.ATTACHED) {
-            container.enqueueAddOperation(stackScreen)
+            containerUpdateCoordinator.addPushOperation(stackScreen)
         }
     }
 
-    private fun enqueuePopOperationToContainerIfNeeded(stackScreen: StackScreen) {
+    private fun addPopOperationIfNeeded(stackScreen: StackScreen) {
         if (stackScreen.activityMode == StackScreen.ActivityMode.ATTACHED && !stackScreen.isNativelyDismissed) {
-            container.enqueuePopOperation(stackScreen)
+            // This shouldn't happen in typical scenarios but it can happen with fast-refresh.
+            containerUpdateCoordinator.addPopOperation(stackScreen)
         }
     }
 
     internal fun stackScreenChangedActivityMode(stackScreen: StackScreen) {
         when (stackScreen.activityMode) {
-            StackScreen.ActivityMode.DETACHED -> container.enqueuePopOperation(stackScreen)
-            StackScreen.ActivityMode.ATTACHED -> container.enqueueAddOperation(stackScreen)
+            StackScreen.ActivityMode.DETACHED -> containerUpdateCoordinator.addPopOperation(stackScreen)
+            StackScreen.ActivityMode.ATTACHED -> containerUpdateCoordinator.addPushOperation(stackScreen)
         }
     }
 
-    override fun onDismiss(stackScreen: StackScreen) {
-        if (stackScreen.activityMode == StackScreen.ActivityMode.ATTACHED) {
-            stackScreen.isNativelyDismissed = true
-        }
-    }
+    override fun onScreenDismiss(stackScreen: StackScreen) = Unit
 
     override fun onMeasure(
         widthMeasureSpec: Int,
@@ -108,7 +106,7 @@ class StackHost(
     }
 
     override fun didMountItems(uiManager: UIManager) {
-        container.performContainerUpdateIfNeeded()
+        containerUpdateCoordinator.executePendingOperationsIfNeeded(container, renderedScreens)
     }
 
     override fun willDispatchViewUpdates(uiManager: UIManager) = Unit

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

@@ -0,0 +1,13 @@
+package com.swmansion.rnscreens.gamma.stack.host
+
+import com.swmansion.rnscreens.gamma.stack.screen.StackScreen
+
+internal sealed class StackOperation
+
+internal class PushOperation(
+    val screen: StackScreen,
+) : StackOperation()
+
+internal class PopOperation(
+    val screen: StackScreen,
+) : StackOperation()

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

@@ -2,6 +2,7 @@ package com.swmansion.rnscreens.gamma.stack.screen
 
 import android.annotation.SuppressLint
 import android.view.ViewGroup
+import androidx.lifecycle.LifecycleOwner
 import com.facebook.react.uimanager.ThemedReactContext
 import com.swmansion.rnscreens.gamma.stack.host.StackHost
 import java.lang.ref.WeakReference
@@ -47,6 +48,16 @@ class StackScreen(
         eventEmitter = StackScreenEventEmitter(reactContext, id)
     }
 
+    internal fun createAppearanceEventsEmitter(viewLifecycleOwner: LifecycleOwner) =
+        StackScreenAppearanceEventsEmitter(viewLifecycleOwner.lifecycle, eventEmitter)
+
+    internal fun onDismiss() {
+        if (activityMode == ActivityMode.ATTACHED) {
+            isNativelyDismissed = true
+        }
+        eventEmitter.emitOnDismiss(isNativelyDismissed)
+    }
+
     override fun onLayout(
         changed: Boolean,
         l: Int,