feat(Android, Stack v5): make Transition API work (#3629)

## Description

> [!note]
> To support predictive back gesture on Android, we need to either use
`Animator API`
> or `Transition API` for screen animations. The [`Animation API` is not
compatible with predictive back
gesture](https://developer.android.com/guide/navigation/custom-back/support-animations#fragments).
> In stack v4, with small exception for formsheets we've heavily relied
on `Animation API` and we can
> not reuse that code, unfortunately.

This PR intends to make Transition API work on Android for us.
Currently, when
attempting to use it we have problems with:

1. disappearing shadows,
2. jumping content,
3. non-continuous animations (e.g. predictive back gesture),
4. native-pop missing animation.


| Most of the bugs described above |
| --- |
| <video
src="https://github.com/user-attachments/assets/7f5cf2e8-5b6a-41ec-8dc4-43e8e40578a0"
alt="before" /> |
| This video does not showcase issues no. 3 & 4, but trust be bro, they
are there |

This identifies root causes for each of those problems and introduces
changes to
fix them.

It also adds an appropriate feature test and sets some Slide animation,
so we
can observe anything when testing. This is not meant to be the default
animation
or something. Just a placeholder animation.

## Changes

I encourage reading through particular commits, as I tried to give each
of them
a meaningful message.

Here I list most important changes:

* CAUTION: bump native android library dependencies & add depencency on
`transition`

    I've decided to bump appcompat, fragment deps.
    This is done mostly in hope to get rid of as many problems
    as possible with animations.

    Dependency on `transition` is added because `transition@1.5.0`
is required for compatibility with predictive back gesture, so I want
    to have that version under control.

`fragment` dependency is required to at least 1.7.0 by predictive back
    gesture.

I've bumped other deps to ensure that they do not force lower version
    for `fragment` or `transition`.

See:
<https://developer.android.com/guide/navigation/custom-back/support-animations#use_existing_apis>

* Set `isTransitionGroup` for `StackScreen` to enable Transition API
usage

This is crucial. This assures that whole StackScreen subtree (including
the StackScreen itself) is animated together. W/o this the animation is
    glitchy - some of the views can disappear, some views can jump to
different location mid-transition, **shadows are lost**. Setting this
    option fixes things.

    I wonder what will be impact of using this on SET & Reanimated
integration. Hopefully it'll be possible to animate some views anyway.

* Merge AddOp & SetPrimaryNavFragmentOp + add OnCommitCallbackFragmentOp

    This is kinda complex change.

First, this commit removes `SetPrimaryNavFragmentOp` and merges it to
    `AddOp` creating new `AddAndSetAsPrimaryOp`. This is done, because
previously, we've executed a `AddOp` that has been saved to back stack
    with e.g. some fragment A, and then we executed another transaction
    impacting fragment A by executing `SetPrimaryNavFragmentOp` & it has
not been saved to back stack. This led to situation, where later popping
    A would not be interpreted as `pop` operation (explained below) by
    fragment manager and in consequence this would break predictive back
gesture & native pop operation - after touch release animation would be
    completed immediately & not by smoothly animating to completion.

Fragment manager interprets a batch of fragment transactions as "pop"
only when last operation in a batch is "pop". Setting primary navigation
fragment is not a "pop" operation. I haven't tested that in runtime, but
    by reading the code of fragment manager I've figured that we can not
    queue the `SetPrimaryNavFragmentOp` before other operations, because
it'll trigger an exception that we try to make not-yet-attached fragment
    primary navigation fragment. However, maybe it's worth trying.
Currently, I've gone with different approach. Now, I batch every add
operation with
set-primary-nav-fragment & add them to back stack together. *Thanks to
that,
we no longer manually manage the primary fragment. Fragment manager does
    that for us, when reverting stack transactions.*

We still have a need to run a callback on transaction commit to update
    the top fragment (prevent native dismiss requirement), therefore
    exactly due to reasons explained above, I've added
    `OnCommitCallbackFragmentOp` and scheduled it before any other
    operations. It can not be batched with other operations, because a
transaction with `runOnCommit` configured can NOT be added to back stack
    (callback can not be serialized).

* Fix transitions in nested stacks

Component views on new architecture receive their first layout after the
view hierarchy is
assembled and attached to window. Note, that in case of screen views &
their sub-trees
(including nested containers) this does not hold. The container is
updated later, after React
mounting transaction ends, therefore the views are attached to the
window much later, hence
their `isLaidOut` returns false, breaking transitions & animations.

    NOTE: Currently, screens attached even to the "top" (non-nested)
container return false from `isLaidOut`! Exactly due to mechanism
described above. I do not know whether it causes any problems, but
potentially - yes. We should be aware of that.

    The fix here is to lay out the container. I need to do that
synchronously, before we schedule the transitions. I'm not aware of
API that allows me to achieve that, so I've introduced
`StackContainerParent` interface.

## Visual documentation


https://github.com/user-attachments/assets/39069381-4a99-445d-98be-9c2fa7a2c608


## 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

FabricExample/android/app/build.gradle

@@ -125,7 +125,7 @@ dependencies {
         // https://github.com/wix/Detox/issues/2848
         exclude group: 'com.google.android.material'
     }
-    implementation "androidx.appcompat:appcompat:1.6.1" // Detox
+    implementation "androidx.appcompat:appcompat:1.7.1" // Detox
 
     // The version of react-native is set by the React Native Gradle Plugin
     implementation("com.facebook.react:react-android")

android/build.gradle

@@ -216,12 +216,13 @@ repositories {
 
 dependencies {
     implementation 'com.facebook.react:react-native:+'
-    implementation 'androidx.appcompat:appcompat:1.6.1'
-    implementation 'androidx.fragment:fragment-ktx:1.6.1'
+    implementation 'androidx.appcompat:appcompat:1.7.1'
+    implementation 'androidx.fragment:fragment-ktx:1.8.9'
+    implementation 'androidx.transition:transition-ktx:1.7.0'
     implementation 'androidx.coordinatorlayout:coordinatorlayout:1.2.0'
     implementation 'androidx.swiperefreshlayout:swiperefreshlayout:1.1.0'
     implementation 'com.google.android.material:material:1.13.0'
-    implementation "androidx.core:core-ktx:1.8.0"
+    implementation "androidx.core:core-ktx:1.17.0"
 
     constraints {
         implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.5.1") {

android/src/main/java/com/swmansion/rnscreens/ext/ViewExt.kt

@@ -46,3 +46,9 @@ internal fun View.findFragmentOrNull(): Fragment? =
     } catch (_: IllegalStateException) {
         null
     }
+
+/**
+ * This will fail in case the view has been measured with (0, 0) dimensions and laid out
+ * before being attached to window.
+ */
+internal fun View.isMeasured(): Boolean = this.measuredWidth != 0 || this.measuredHeight != 0 || this.isLaidOut

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

@@ -10,7 +10,7 @@ internal sealed class FragmentOperation {
     )
 }
 
-internal class AddOp(
+internal class AddAndSetAsPrimaryOp(
     val fragment: StackScreenFragment,
     val containerViewId: Int,
     val addToBackStack: Boolean,
@@ -20,7 +20,7 @@ internal class AddOp(
         fragmentManager: FragmentManager,
         executor: FragmentOperationExecutor,
     ) {
-        executor.executeAddOp(fragmentManager, this)
+        executor.executeAddAndSetAsPrimaryOp(fragmentManager, this)
     }
 }
 
@@ -57,14 +57,15 @@ internal class FlushNowOp : FragmentOperation() {
     }
 }
 
-internal class SetPrimaryNavFragmentOp(
-    val fragment: StackScreenFragment,
-    val onCommitCallback: Runnable? = null,
+internal class OnCommitCallbackOp(
+    val onCommitCallback: Runnable,
+    val allowStateLoss: Boolean = true,
+    val flushSync: Boolean = false,
 ) : FragmentOperation() {
     override fun execute(
         fragmentManager: FragmentManager,
         executor: FragmentOperationExecutor,
     ) {
-        executor.executeSetPrimaryNavFragmentOp(fragmentManager, this)
+        executor.executeOnCommitCallbackOp(fragmentManager, this)
     }
 }

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

@@ -17,15 +17,16 @@ internal class FragmentOperationExecutor {
         }
     }
 
-    internal fun executeAddOp(
+    internal fun executeAddAndSetAsPrimaryOp(
         fragmentManager: FragmentManager,
-        op: AddOp,
+        op: AddAndSetAsPrimaryOp,
     ) {
         fragmentManager.createTransactionWithReordering().let { tx ->
-            tx.add(op.containerViewId, op.fragment)
             if (op.addToBackStack) {
                 tx.addToBackStack(op.fragment.stackScreen.screenKey)
             }
+            tx.add(op.containerViewId, op.fragment)
+            tx.setPrimaryNavigationFragment(op.fragment)
             commitTransaction(tx, op.allowStateLoss)
         }
     }
@@ -57,17 +58,17 @@ internal class FragmentOperationExecutor {
         fragmentManager.executePendingTransactions()
     }
 
-    internal fun executeSetPrimaryNavFragmentOp(
+    internal fun executeOnCommitCallbackOp(
         fragmentManager: FragmentManager,
-        op: SetPrimaryNavFragmentOp,
+        op: OnCommitCallbackOp,
     ) {
-        fragmentManager.createTransactionWithReordering().let { tx ->
-            tx.setPrimaryNavigationFragment(op.fragment)
-            if (op.onCommitCallback != null) {
-                tx.runOnCommit(op.onCommitCallback)
-            }
-            commitTransaction(tx, allowStateLoss = true, flushSync = false)
-        }
+        commitTransaction(
+            fragmentManager
+                .createTransactionWithReordering()
+                .runOnCommit(op.onCommitCallback),
+            allowStateLoss = op.allowStateLoss,
+            flushSync = op.flushSync,
+        )
     }
 
     private fun commitTransaction(

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

@@ -6,6 +6,7 @@ import android.util.Log
 import androidx.coordinatorlayout.widget.CoordinatorLayout
 import androidx.fragment.app.Fragment
 import androidx.fragment.app.FragmentManager
+import com.swmansion.rnscreens.ext.isMeasured
 import com.swmansion.rnscreens.gamma.helpers.FragmentManagerHelper
 import com.swmansion.rnscreens.gamma.helpers.ViewIdGenerator
 import com.swmansion.rnscreens.gamma.stack.screen.StackScreen
@@ -24,6 +25,11 @@ internal class StackContainer(
     private fun requireFragmentManager(): FragmentManager =
         checkNotNull(fragmentManager) { "[RNScreens] Attempt to use nullish FragmentManager" }
 
+    /**
+     * Will crash in case parent does not implement StackContainerParent interface.
+     */
+    private fun containerParentOrNull(): StackContainerParent? = this.parent as StackContainerParent?
+
     /**
      * Describes most up-to-date view of the stack. It might be different from
      * state kept by FragmentManager as this data structure is updated immediately,
@@ -37,6 +43,7 @@ internal class StackContainer(
         get() = pendingPushOperations.isNotEmpty() || pendingPopOperations.isNotEmpty()
 
     private val fragmentOpExecutor: FragmentOperationExecutor = FragmentOperationExecutor()
+    private val fragmentOps: MutableList<FragmentOperation> = arrayListOf()
 
     init {
         id = ViewIdGenerator.generateViewId()
@@ -48,6 +55,15 @@ internal class StackContainer(
 
         setupFragmentManger()
 
+        // Following line works with a couple of assumptions.
+        // First, that this view is laid out by our parent view, which is a component view.
+        // Component views on new architecture receive their first layout after the view hierarchy is
+        // assembled and attached to window. Note, that in case of screen views & their subtrees
+        // (including nested containers) this does not hold. The container is updated later, therefore
+        // the views are attached to window much later ==> their isLaidOut returns false, breaking
+        // transitions & animations.
+        updateLaidOutFlagIfNeededAndPossible()
+
         // We run container update to handle any pending updates requested before container was
         // attached to window.
         performContainerUpdateIfNeeded()
@@ -89,19 +105,39 @@ internal class StackContainer(
     }
 
     private fun performOperations(fragmentManager: FragmentManager) {
-        val fragmentOps = applyOperationsAndComputeFragmentManagerOperations()
+        applyOperationsAndComputeFragmentManagerOperations()
         fragmentOpExecutor.executeOperations(fragmentManager, fragmentOps, flushSync = false)
 
         dumpStackModel()
     }
 
-    private fun applyOperationsAndComputeFragmentManagerOperations(): List<FragmentOperation> {
-        val fragmentOps = mutableListOf<FragmentOperation>()
+    private fun applyOperationsAndComputeFragmentManagerOperations() {
+        fragmentOps.clear()
 
         // Handle pop operations first.
         // We don't care about pop/push duplicates, as long as we don't let the main loop progress
         // before we commit all the transactions, FragmentManager will handle that for us.
 
+        if (hasPendingOperations) {
+            // Top fragment is the primary navigation fragment. If we're going to change anything
+            // in stack model, then we also should update top fragment.
+            //
+            // This is added before other operations, to make sure that they are correctly classified
+            // as pop/non-pop by fragment manager.
+            // This relies on Fragment Manager internal behavior obviously. It classifies
+            // whole batch of transactions as "pop" (argument later passed to `onBackStackChange` commited)
+            // when last operation of the batch is "pop". Empty commit with only onCommit callback
+            // attached is not a "pop" commit, therefore JS-pop commits have not been properly
+            // recognized.
+            fragmentOps.add(
+                OnCommitCallbackOp(
+                    { updateTopFragment() },
+                    allowStateLoss = true,
+                    flushSync = false,
+                ),
+            )
+        }
+
         pendingPopOperations.forEach { operation ->
             val fragment =
                 checkNotNull(stackModel.find { it.stackScreen === operation.screen }) {
@@ -121,8 +157,9 @@ internal class StackContainer(
 
         pendingPushOperations.forEach { operation ->
             val newFragment = createFragmentForScreen(operation.screen)
+
             fragmentOps.add(
-                AddOp(
+                AddAndSetAsPrimaryOp(
                     newFragment,
                     containerViewId = this.id,
                     addToBackStack = stackModel.isNotEmpty(),
@@ -133,37 +170,20 @@ internal class StackContainer(
 
         check(stackModel.isNotEmpty()) { "[RNScreens] Stack should never be empty after updates" }
 
-        // Top fragment is the primary navigation fragment.
-        val topStackFragment = stackModel.last()
-        fragmentOps.add(
-            SetPrimaryNavFragmentOp(topStackFragment, {
-                updateTopFragment()
-            }),
-        )
-
         pendingPopOperations.clear()
         pendingPushOperations.clear()
-
-        return fragmentOps
     }
 
     private fun onNativeFragmentPop(fragment: StackScreenFragment) {
-        Log.d(TAG, "StackContainer [$id] natively removed fragment ${fragment.stackScreen.screenKey}")
         require(stackModel.remove(fragment)) { "[RNScreens] onNativeFragmentPop must be called with the fragment present in stack model" }
         check(stackModel.isNotEmpty()) { "[RNScreens] Stack model should not be empty after a native pop" }
 
-        val fragmentManager = requireFragmentManager()
-        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()
-                }),
-            ),
-        )
+        // The primary navigation fragment should be updated when popping backstack by FragmentManager
+        // reversing the back stack record. At this point we need to just update the top fragment.
+        check(requireFragmentManager().primaryNavigationFragment !== fragment) {
+            "[RNScreens] Primary navigation fragment not updated by native pop"
+        }
+        updateTopFragment()
     }
 
     private fun dumpStackModel() {
@@ -180,10 +200,27 @@ internal class StackContainer(
 
     private fun updateTopFragment() {
         // We try to handle situation where other fragments might be present.
-        val fragments = requireFragmentManager().fragments.filterIsInstance<StackScreenFragment>()
+        val fragmentManager = requireFragmentManager()
+        val fragments = fragmentManager.fragments.filterIsInstance<StackScreenFragment>()
         check(fragments.isNotEmpty()) { "[RNScreens] Empty fragment manager while attempting to update top fragment" }
         fragments.forEach { it.onResignTopFragment() }
         fragments.last().onBecomeTopFragment()
+
+        // This assumes that the updateTopFragment is called already after primary nav frag. is updated.
+        // If this needs to be changed in the future, just remove this assertion.
+        check(fragmentManager.primaryNavigationFragment === fragments.last()) {
+            "[RNScreens] Top fragment different from primary navigation fragment"
+        }
+    }
+
+    /**
+     * If this.isLaidOut == false, then SpecialEffectsController won't perform animations / transitions.
+     * This function tries to ensure that the container is laid out if it already has layout information.
+     */
+    private fun updateLaidOutFlagIfNeededAndPossible() {
+        if (isAttachedToWindow && isMeasured() && !isLaidOut && !isInLayout) {
+            containerParentOrNull()?.layoutContainerNow()
+        }
     }
 
     // This is called after special effects (animations) are dispatched
@@ -200,8 +237,14 @@ internal class StackContainer(
             Log.w(TAG, "[RNScreens] Unexpected type of fragment: ${fragment.javaClass.simpleName}")
             return
         }
-        if (pop) {
-            delegate.get()?.onScreenDismiss(fragment.stackScreen)
+
+        // This callback is called for every fragment involved in the back stack change, even
+        // if its not added or removed, but e.g. set as a primary navigation fragment, hence
+        // we need to check whether the fragment is actually being removed.
+        // I avoid using `pop` parameter here, because transaction might not be classified as `pop`
+        // and still include fragment removal operations.
+        if (fragment.isRemoving) {
+            delegate.get()?.onScreenDismissCommitted(fragment.stackScreen)
             if (stackModel.contains(fragment)) {
                 onNativeFragmentPop(fragment)
             }

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 onScreenDismiss(stackScreen: StackScreen)
+    fun onScreenDismissCommitted(stackScreen: StackScreen)
 }

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

@@ -0,0 +1,8 @@
+package com.swmansion.rnscreens.gamma.stack.host
+
+/**
+ * Parent view of `StackContainer` is expected to implement this interface.
+ */
+internal interface StackContainerParent {
+    fun layoutContainerNow()
+}

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

@@ -19,7 +19,8 @@ class StackHost(
     private val reactContext: ThemedReactContext,
 ) : ViewGroup(reactContext),
     UIManagerListener,
-    StackContainerDelegate {
+    StackContainerDelegate,
+    StackContainerParent {
     internal val renderedScreens: ArrayList<StackScreen> = arrayListOf()
     private val container = StackContainer(reactContext, WeakReference(this))
     private val containerUpdateCoordinator = StackContainerUpdateCoordinator()
@@ -88,7 +89,7 @@ class StackHost(
         }
     }
 
-    override fun onScreenDismiss(stackScreen: StackScreen) {
+    override fun onScreenDismissCommitted(stackScreen: StackScreen) {
         if (stackScreen.activityMode == StackScreen.ActivityMode.ATTACHED) {
             stackScreen.isNativelyDismissed = true
         }
@@ -112,6 +113,16 @@ class StackHost(
         container.layout(l, t, r, b)
     }
 
+    override fun layoutContainerNow() {
+        if (measuredWidth != container.measuredWidth || measuredHeight != container.measuredHeight) {
+            container.measure(
+                MeasureSpec.makeMeasureSpec(measuredWidth, MeasureSpec.EXACTLY),
+                MeasureSpec.makeMeasureSpec(measuredHeight, MeasureSpec.EXACTLY),
+            )
+        }
+        container.layout(left, top, right, bottom)
+    }
+
     override fun didMountItems(uiManager: UIManager) {
         containerUpdateCoordinator.executePendingOperationsIfNeeded(container, renderedScreens)
     }

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

@@ -21,6 +21,12 @@ class StackScreen(
         ATTACHED,
     }
 
+    init {
+        // Needed when Transition API is in use to ensure that shadows do not disappear,
+        // views do not jump around the screen and whole sub-tree is animated as a whole.
+        isTransitionGroup = true
+    }
+
     internal var isPreventNativeDismissEnabled: Boolean by Delegates.observable(false) { _, oldValue, newValue ->
         if (oldValue != newValue) {
             preventNativeDismissChangeObserver?.preventNativeDismissChanged(newValue)