react-native-screens 4.25.0 → 4.25.2

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

@@ -26,9 +26,11 @@ import com.google.android.material.bottomsheet.BottomSheetBehavior
 import com.google.android.material.shape.CornerFamily
 import com.google.android.material.shape.MaterialShapeDrawable
 import com.google.android.material.shape.ShapeAppearanceModel
+import com.swmansion.rnscreens.bottomsheet.SheetAnimationCoordinator
 import com.swmansion.rnscreens.bottomsheet.SheetDetents
 import com.swmansion.rnscreens.bottomsheet.fitToContentsSheetHeight
 import com.swmansion.rnscreens.bottomsheet.isSheetFitToContents
+import com.swmansion.rnscreens.bottomsheet.resolveClampedHeight
 import com.swmansion.rnscreens.bottomsheet.updateMetrics
 import com.swmansion.rnscreens.bottomsheet.useSingleDetent
 import com.swmansion.rnscreens.bottomsheet.usesFormSheetPresentation
@@ -50,6 +52,8 @@ class Screen(
     val sheetBehavior: BottomSheetBehavior<Screen>?
         get() = (layoutParams as? CoordinatorLayout.LayoutParams)?.behavior as? BottomSheetBehavior<Screen>
 
+    internal val sheetAnimationCoordinator: SheetAnimationCoordinator by lazy { SheetAnimationCoordinator(this) }
+
     val reactEventDispatcher: EventDispatcher?
         get() = UIManagerHelper.getEventDispatcherForReactTag(reactContext, id)
 
@@ -155,7 +159,7 @@ class Screen(
                 if (isInitial) {
                     setupInitialSheetContentHeight(sheetBehavior, height)
                 } else if (sheetDefaultResizeAnimationEnabled) {
-                    updateSheetContentHeightWithAnimation(sheetBehavior, oldHeight, height)
+                    sheetAnimationCoordinator.updateSheetContentHeightWithAnimation(sheetBehavior, oldHeight, height)
                 } else {
                     updateSheetContentHeightWithoutAnimation(sheetBehavior, height)
                 }
@@ -171,104 +175,6 @@ class Screen(
         updateState(width, height, headerHeight)
     }
 
-    /**
-     * This should be used only with sheet in `fitToContents` mode.
-     */
-    private fun updateSheetContentHeightWithAnimation(
-        behavior: BottomSheetBehavior<Screen>,
-        oldHeight: Int,
-        newHeight: Int,
-    ) {
-        val currentTranslationY = this.translationY
-
-        /*
-         * WHY OVERFLOW MATTERS:
-         * BottomSheetBehavior has a physical limit (maxHeight) defined by the parent container.
-         * If the new content height exceeds this limit (by its size or keyboard offset), simply
-         * animating translationY back to 'currentTranslationY' would attempt to render the sheet
-         * larger than the screen.
-         *
-         * We need to have constraint height inside the container's bounds.
-         * By including this overflow to our animation, we ensure the sheet stops
-         * expanding exactly at the maxHeight, preventing from being pushed
-         * off-screen or causing layout synchronization issues with the CoordinatorLayout.
-         */
-        val clampedOldHeight = resolveClampedHeight(oldHeight, currentTranslationY)
-        val clampedNewHeight = resolveClampedHeight(newHeight, currentTranslationY)
-        val visibleDelta = (clampedNewHeight - clampedOldHeight).toFloat()
-
-        if (visibleDelta == 0f) return
-
-        val isContentExpanding = visibleDelta > 0
-
-        if (isContentExpanding) {
-            /*
-             * Expanding content animation:
-             *
-             * Before animation, we're updating the SheetBehavior - the maximum height is the new
-             * content height, then we're forcing a layout pass. This ensures the view calculates
-             * with its new bounds when the animation starts.
-             *
-             * In the animation, we're translating the Screen back to it's (newly calculated) origin
-             * position, providing an impression that FormSheet expands. It already has the final size,
-             * but some content is not yet visible on the screen.
-             *
-             * After animation, we just need to send a notification that ShadowTree state should be updated,
-             * as the positioning of pressables has changed due to the Y translation manipulation.
-             */
-            this.translationY += visibleDelta
-            this
-                .animate()
-                .translationY(currentTranslationY)
-                .withStartAction {
-                    behavior.updateMetrics(clampedNewHeight)
-                    layout(this.left, this.bottom - clampedNewHeight, this.right, this.bottom)
-                }.withEndAction {
-                    // Force a layout pass on the CoordinatorLayout to synchronize BottomSheetBehavior's
-                    // internal offsets with the new maxHeight. This prevents the sheet from snapping back
-                    // to its old position when the user starts a gesture.
-                    parent.requestLayout()
-                    onSheetYTranslationChanged()
-                }.start()
-        } else {
-            /*
-             * Shrinking content animation:
-             *
-             * Before the animation, our Screen translationY is 0 - because its actual layout and visual position are equal.
-             *
-             * Before the animation, I'm updating sheet metrics to the target value - it won't update until the next layout pass,
-             * which is controlled by end action. This is done deliberately, to allow catching the case when quick combination
-             * of shrink & expand animation is detected.
-             *
-             * In the animation, we're translating the Screen down by the calculated height delta to the position (which will
-             * be new absolute 0 for the Screen, after ending the transition), providing an impression that FormSheet shrinks.
-             * FormSheet's size remains unchanged during the whole animation, therefore there is no view clipping.
-             *
-             * After animation, we can update the layout: the maximum FormSheet height is updated and we're forcing
-             * another layout pass. Additionally, since the actual layout and the target position are equal,
-             * we can reset translationY to 0.
-             *
-             * After animation, we need to send a notification that ShadowTree state should be updated,
-             * as the FormSheet size has changed and the positioning of pressables has changed due to the Y translation manipulation.
-             */
-            val targetTranslationY = currentTranslationY - visibleDelta
-            this
-                .animate()
-                .translationY(targetTranslationY)
-                .withStartAction {
-                    behavior.updateMetrics(clampedNewHeight)
-                }.withEndAction {
-                    layout(this.left, this.bottom - clampedNewHeight, this.right, this.bottom)
-                    this.translationY = currentTranslationY
-                    // Force a layout pass on the CoordinatorLayout to synchronize BottomSheetBehavior's
-                    // internal offsets with the new maxHeight. This prevents the sheet from snapping back
-                    // to its old position when the user starts a gesture.
-                    parent.requestLayout()
-                    onSheetYTranslationChanged()
-                }.start()
-        }
-    }
-
     private fun updateSheetContentHeightWithoutAnimation(
         behavior: BottomSheetBehavior<Screen>,
         height: Int,
@@ -299,22 +205,6 @@ class Screen(
         requestLayout()
     }
 
-    private fun resolveClampedHeight(
-        targetHeight: Int,
-        currentTranslationY: Float,
-    ): Int {
-        val maxAvailableVerticalSpace =
-            this.fragment
-                ?.asScreenStackFragment()
-                ?.sheetDelegate
-                ?.tryResolveMaxFormSheetHeight() ?: return targetHeight
-
-        // Please note that currentTranslationY is rather < 0 here.
-        // The translation is included in constraining the available space, because the FormSheet can have some offset, e.g. to
-        // avoid the keyboard.
-        return targetHeight.coerceAtMost((maxAvailableVerticalSpace + currentTranslationY).toInt())
-    }
-
     fun registerLayoutCallbackForWrapper(wrapper: ScreenContentWrapper) {
         wrapper.delegate = this
     }
@@ -358,7 +248,7 @@ class Screen(
         }
 
         if (coordinatorLayoutDidChange) {
-            updateShadowNodeScreenSize(width, height, top)
+            updateShadowNodeScreenSize(width, height, top + translationY.toInt())
         }
 
         footer?.onParentLayout(coordinatorLayoutDidChange, left, top, right, bottom, container!!.height)

package/android/src/main/java/com/swmansion/rnscreens/ScreenStackFragment.kt

@@ -270,6 +270,14 @@ class ScreenStackFragment :
                 object : WindowInsetsAnimationCompat.Callback(
                     WindowInsetsAnimationCompat.Callback.DISPATCH_MODE_STOP,
                 ) {
+                    override fun onPrepare(animation: WindowInsetsAnimationCompat) {
+                        super.onPrepare(animation)
+
+                        if ((animation.typeMask and WindowInsetsCompat.Type.ime()) != 0) {
+                            sheetDelegate.notifyKeyboardAnimationStart()
+                        }
+                    }
+
                     // Replace InsetsAnimationCallback created by BottomSheetBehavior
                     // to avoid interfering with custom animations.
                     // See: https://github.com/software-mansion/react-native-screens/pull/2909
@@ -288,6 +296,10 @@ class ScreenStackFragment :
                     override fun onEnd(animation: WindowInsetsAnimationCompat) {
                         super.onEnd(animation)
 
+                        if ((animation.typeMask and WindowInsetsCompat.Type.ime()) != 0) {
+                            sheetDelegate.notifyKeyboardAnimationEnd()
+                        }
+
                         screen.onSheetYTranslationChanged()
                     }
                 }

package/android/src/main/java/com/swmansion/rnscreens/bottomsheet/SheetAnimationCoordinator.kt

@@ -0,0 +1,364 @@
+package com.swmansion.rnscreens.bottomsheet
+
+import android.animation.Animator
+import android.animation.AnimatorListenerAdapter
+import android.animation.AnimatorSet
+import android.animation.ValueAnimator
+import androidx.coordinatorlayout.widget.CoordinatorLayout
+import androidx.core.view.WindowInsetsCompat
+import com.google.android.material.bottomsheet.BottomSheetBehavior
+import com.swmansion.rnscreens.Screen
+import com.swmansion.rnscreens.ScreenStackFragment
+import com.swmansion.rnscreens.events.ScreenAnimationDelegate
+import com.swmansion.rnscreens.events.ScreenEventEmitter
+import com.swmansion.rnscreens.ext.asScreenStackFragment
+import com.swmansion.rnscreens.transition.ExternalBoundaryValuesEvaluator
+import java.lang.ref.WeakReference
+
+internal class SheetAnimationCoordinator(
+    screen: Screen,
+) {
+    private val screenRef = WeakReference(screen)
+    private val screen: Screen get() =
+        checkNotNull(screenRef.get()) {
+            "[RNScreens] Screen has been destroyed and shouldn't be the subject of any animations"
+        }
+    private var activeKeyboardAnimationsCount: Int = 0
+    private val isKeyboardAnimationInProgress: Boolean
+        get() = activeKeyboardAnimationsCount > 0
+    private var isSheetAnimationInProgress: Boolean = false
+    private var currentContentAnimator: ValueAnimator? = null
+
+    private var lastKeyboardBottomOffset: Int = 0
+
+    internal fun createSheetEnterAnimator(sheetAnimationContext: SheetDelegate.SheetAnimationContext): Animator {
+        val animatorSet = AnimatorSet()
+
+        val dimmingDelegate = sheetAnimationContext.dimmingDelegate
+        val screenStackFragment = sheetAnimationContext.fragment
+
+        val alphaAnimator = createDimmingViewAlphaAnimator(0f, dimmingDelegate.maxAlpha, dimmingDelegate)
+        val slideAnimator = createSheetSlideInAnimator()
+
+        animatorSet
+            .play(slideAnimator)
+            .takeIf {
+                dimmingDelegate.willDimForDetentIndex(screen, screen.sheetInitialDetentIndex)
+            }?.with(alphaAnimator)
+
+        attachCommonListeners(animatorSet, isEnter = true, screenStackFragment)
+
+        return animatorSet
+    }
+
+    internal fun createSheetExitAnimator(sheetAnimationContext: SheetDelegate.SheetAnimationContext): Animator {
+        val animatorSet = AnimatorSet()
+
+        val coordinatorLayout = sheetAnimationContext.coordinatorLayout
+        val dimmingDelegate = sheetAnimationContext.dimmingDelegate
+        val screenStackFragment = sheetAnimationContext.fragment
+
+        val alphaAnimator =
+            createDimmingViewAlphaAnimator(dimmingDelegate.dimmingView.alpha, 0f, dimmingDelegate)
+        val slideAnimator = createSheetSlideOutAnimator(coordinatorLayout)
+
+        animatorSet.play(alphaAnimator).with(slideAnimator)
+
+        attachCommonListeners(animatorSet, isEnter = false, screenStackFragment)
+
+        return animatorSet
+    }
+
+    /**
+     * This should be used only with sheet in `fitToContents` mode.
+     *
+     * If an entry/exit animation is already in progress, we silently update the
+     * behavior metrics and view layout without starting a competing translationY
+     * animation - this is the fix for the race condition between the slide-in
+     * ValueAnimator and externally triggered layout pass (e.g. applying padding from SAV insets).
+     */
+    internal fun updateSheetContentHeightWithAnimation(
+        behavior: BottomSheetBehavior<Screen>,
+        oldHeight: Int,
+        newHeight: Int,
+    ) {
+        val currentTranslationY = screen.translationY
+
+        /*
+         * WHY OVERFLOW MATTERS:
+         * BottomSheetBehavior has a physical limit (maxHeight) defined by the parent container.
+         * If the new content height exceeds this limit (by its size or keyboard offset), simply
+         * animating translationY back to 'currentTranslationY' would attempt to render the sheet
+         * larger than the screen.
+         *
+         * We need to constrain the height within the container's bounds.
+         * By including this overflow to our animation, we ensure the sheet stops
+         * expanding exactly at the maxHeight, preventing from being pushed
+         * off-screen or causing layout synchronization issues with the CoordinatorLayout.
+         */
+        val clampedOldHeight = screen.resolveClampedHeight(oldHeight, currentTranslationY)
+        val clampedNewHeight = screen.resolveClampedHeight(newHeight, currentTranslationY)
+
+        // If an entry/exit animation or a keyboard animation is in progress - it owns
+        // translationY writes. Then when the content size is changing, we silently
+        // update behavior metrics and re-layout so the ongoing slide animation
+        // lands at the correct final geometry, without firing a competing animation.
+        if (isSheetAnimationInProgress || isKeyboardAnimationInProgress) {
+            behavior.updateMetrics(clampedNewHeight)
+            screen.layoutBottomSheetAtHeight(clampedNewHeight)
+            screen.finalizeBottomSheetLayoutUpdates()
+            return
+        }
+
+        val visibleDelta = (clampedNewHeight - clampedOldHeight).toFloat()
+        if (visibleDelta == 0f) return
+
+        if (visibleDelta > 0) {
+            animateContentExpanding(behavior, clampedNewHeight, currentTranslationY, visibleDelta)
+        } else {
+            animateContentShrinking(behavior, clampedNewHeight, currentTranslationY, visibleDelta)
+        }
+    }
+
+    /*
+     * Expanding content animation:
+     *
+     * Before animation, we're updating the SheetBehavior - the maximum height is the new
+     * content height, then we're forcing a layout pass. This ensures the view calculates
+     * with its new bounds when the animation starts.
+     *
+     * In the animation, we're translating the Screen back to its (newly calculated) origin
+     * position, providing an impression that FormSheet expands. It already has the final size,
+     * but some content is not yet visible on the screen.
+     *
+     * After animation, we just need to send a notification that ShadowTree state should be updated,
+     * as the positioning of pressables has changed due to the Y translation manipulation.
+     */
+    private fun animateContentExpanding(
+        behavior: BottomSheetBehavior<Screen>,
+        clampedNewHeight: Int,
+        currentTranslationY: Float,
+        visibleDelta: Float,
+    ) {
+        screen.translationY += visibleDelta
+        cancelCurrentContentAnimation()
+        currentContentAnimator =
+            ValueAnimator.ofFloat(screen.translationY, currentTranslationY).apply {
+                addListener(
+                    object : AnimatorListenerAdapter() {
+                        override fun onAnimationStart(animation: Animator) {
+                            behavior.updateMetrics(clampedNewHeight)
+                            screen.layoutBottomSheetAtHeight(clampedNewHeight)
+                        }
+
+                        override fun onAnimationEnd(animation: Animator) {
+                            currentContentAnimator = null
+                            screen.finalizeBottomSheetLayoutUpdates()
+                        }
+                    },
+                )
+                addUpdateListener { screen.translationY = it.animatedValue as Float }
+                start()
+            }
+    }
+
+    /*
+     * Shrinking content animation:
+     *
+     * Before the animation, our Screen translationY is 0 - because its actual layout and visual position are equal.
+     *
+     * Before the animation, I'm updating sheet metrics to the target value - it won't update until the next layout pass,
+     * which is controlled by end action. This is done deliberately, to allow catching the case when quick combination
+     * of shrink & expand animation is detected.
+     *
+     * In the animation, we're translating the Screen down by the calculated height delta to the position (which will
+     * be new absolute 0 for the Screen, after ending the transition), providing an impression that FormSheet shrinks.
+     * FormSheet's size remains unchanged during the whole animation, therefore there is no view clipping.
+     *
+     * After animation, we can update the layout: the maximum FormSheet height is updated and we're forcing
+     * another layout pass. Additionally, since the actual layout and the target position are equal,
+     * we can reset translationY to 0.
+     *
+     * After animation, we need to send a notification that ShadowTree state should be updated,
+     * as the FormSheet size has changed and the positioning of pressables has changed due to the Y translation manipulation.
+     */
+    private fun animateContentShrinking(
+        behavior: BottomSheetBehavior<Screen>,
+        clampedNewHeight: Int,
+        currentTranslationY: Float,
+        visibleDelta: Float,
+    ) {
+        val targetTranslationY = currentTranslationY - visibleDelta
+        cancelCurrentContentAnimation()
+        currentContentAnimator =
+            ValueAnimator.ofFloat(currentTranslationY, targetTranslationY).apply {
+                addListener(
+                    object : AnimatorListenerAdapter() {
+                        override fun onAnimationStart(animation: Animator) {
+                            behavior.updateMetrics(clampedNewHeight)
+                        }
+
+                        override fun onAnimationEnd(animation: Animator) {
+                            currentContentAnimator = null
+                            screen.layoutBottomSheetAtHeight(clampedNewHeight)
+                            screen.translationY = currentTranslationY
+                            screen.finalizeBottomSheetLayoutUpdates()
+                        }
+                    },
+                )
+                addUpdateListener { screen.translationY = it.animatedValue as Float }
+                start()
+            }
+    }
+
+    internal fun notifyKeyboardAnimationStart() {
+        activeKeyboardAnimationsCount++
+    }
+
+    internal fun notifyKeyboardAnimationEnd() {
+        activeKeyboardAnimationsCount = maxOf(0, activeKeyboardAnimationsCount - 1)
+    }
+
+    internal fun handleKeyboardInsetsProgress(insets: WindowInsetsCompat) {
+        lastKeyboardBottomOffset = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom
+        // Prioritize enter/exit animations over direct keyboard inset reactions.
+        // We store the latest keyboard offset in `lastKeyboardBottomOffset`
+        // so that it can always be respected when applying translations in `updateSheetTranslationY`.
+        //
+        // This approach allows screen translation to be triggered from two sources, but without messing them together:
+        // - During enter/exit animations, while accounting for the keyboard height.
+        // - While interacting with a TextInput inside the bottom sheet, to handle keyboard show/hide events.
+        if (!isSheetAnimationInProgress) {
+            updateSheetTranslationY(0f)
+        }
+    }
+
+    // This function calculates the Y offset to which the FormSheet should animate
+    // when appearing (entering) or disappearing (exiting) with the on-screen keyboard (IME) present.
+    // Its purpose is to ensure the FormSheet does not exceed the top edge of the screen.
+    // It tries to display the FormSheet fully above the keyboard when there's enough space.
+    // Otherwise, it shifts the sheet as high as possible, even if it means part of its content
+    // will remain hidden behind the keyboard.
+    private fun computeSheetOffsetYWithIMEPresent(keyboardHeight: Int): Int {
+        val containerHeight =
+            screen.fragment
+                ?.asScreenStackFragment()
+                ?.sheetDelegate
+                ?.tryResolveMaxFormSheetHeight()
+        check(containerHeight != null) {
+            "[RNScreens] Failed to find window height during bottom sheet behaviour configuration"
+        }
+
+        if (screen.isSheetFitToContents()) {
+            val contentHeight = screen.contentWrapper?.height ?: 0
+            val offsetFromTop = maxOf(containerHeight - contentHeight, 0)
+            // If the content is higher than the Screen, offsetFromTop becomes negative.
+            // In such cases, we return 0 because a negative translation would shift the Screen
+            // to the bottom, which is not intended.
+            return minOf(offsetFromTop, keyboardHeight)
+        }
+
+        val detents = screen.sheetDetents
+
+        val detentValue = detents.highest().coerceIn(0.0, 1.0)
+        val sheetHeight = (detentValue * containerHeight).toInt()
+        val offsetFromTop = containerHeight - sheetHeight
+
+        return minOf(offsetFromTop, keyboardHeight)
+    }
+
+    private fun updateSheetTranslationY(baseTranslationY: Float) {
+        val keyboardCorrection = lastKeyboardBottomOffset
+        val bottomOffset = computeSheetOffsetYWithIMEPresent(keyboardCorrection).toFloat()
+
+        screen.translationY = baseTranslationY - bottomOffset
+    }
+
+    private fun createSheetSlideInAnimator(): ValueAnimator {
+        val startValueCallback = { _: Number? -> screen.height.toFloat() }
+        val evaluator = ExternalBoundaryValuesEvaluator(startValueCallback, { 0f })
+
+        return ValueAnimator.ofObject(evaluator, screen.height.toFloat(), 0f).apply {
+            addUpdateListener { updateSheetTranslationY(it.animatedValue as Float) }
+        }
+    }
+
+    private fun createSheetSlideOutAnimator(coordinatorLayout: CoordinatorLayout): ValueAnimator {
+        val endValue = (coordinatorLayout.bottom - screen.top - screen.translationY)
+
+        return ValueAnimator.ofFloat(0f, endValue).apply {
+            addUpdateListener {
+                updateSheetTranslationY(it.animatedValue as Float)
+            }
+        }
+    }
+
+    private fun createDimmingViewAlphaAnimator(
+        from: Float,
+        to: Float,
+        dimmingDelegate: DimmingViewManager,
+    ): ValueAnimator =
+        ValueAnimator.ofFloat(from, to).apply {
+            addUpdateListener { animator ->
+                (animator.animatedValue as? Float)?.let {
+                    dimmingDelegate.dimmingView.alpha = it
+                }
+            }
+        }
+
+    private fun cancelCurrentContentAnimation() {
+        currentContentAnimator?.removeAllListeners()
+        currentContentAnimator?.removeAllUpdateListeners()
+        currentContentAnimator?.cancel()
+        currentContentAnimator = null
+    }
+
+    private fun Screen.layoutBottomSheetAtHeight(height: Int) = layout(left, bottom - height, right, bottom)
+
+    private fun Screen.finalizeBottomSheetLayoutUpdates() {
+        // Force a layout pass on the CoordinatorLayout to synchronize BottomSheetBehavior's
+        // internal offsets with the new maxHeight. This prevents the sheet from snapping back
+        // to its old position when the user starts a gesture.
+        parent.requestLayout()
+
+        // Notify that ShadowTree state should be updated, as the positioning of pressables
+        // has changed due to the Y translation manipulation.
+        onSheetYTranslationChanged()
+    }
+
+    private fun attachCommonListeners(
+        animatorSet: AnimatorSet,
+        isEnter: Boolean,
+        screenStackFragment: ScreenStackFragment,
+    ) {
+        animatorSet.addListener(
+            ScreenAnimationDelegate(
+                screenStackFragment,
+                ScreenEventEmitter(screen),
+                if (isEnter) {
+                    ScreenAnimationDelegate.AnimationType.ENTER
+                } else {
+                    ScreenAnimationDelegate.AnimationType.EXIT
+                },
+            ),
+        )
+
+        animatorSet.addListener(
+            object : AnimatorListenerAdapter() {
+                override fun onAnimationStart(animation: Animator) {
+                    isSheetAnimationInProgress = true
+                }
+
+                override fun onAnimationCancel(animation: Animator) {
+                    isSheetAnimationInProgress = false
+                }
+
+                override fun onAnimationEnd(animation: Animator) {
+                    isSheetAnimationInProgress = false
+
+                    screen.onSheetYTranslationChanged()
+                }
+            },
+        )
+    }
+}

package/android/src/main/java/com/swmansion/rnscreens/bottomsheet/SheetDelegate.kt

@@ -1,9 +1,6 @@
 package com.swmansion.rnscreens.bottomsheet
 
 import android.animation.Animator
-import android.animation.AnimatorListenerAdapter
-import android.animation.AnimatorSet
-import android.animation.ValueAnimator
 import android.content.Context
 import android.os.Build
 import android.view.View
@@ -24,9 +21,6 @@ import com.swmansion.rnscreens.KeyboardState
 import com.swmansion.rnscreens.KeyboardVisible
 import com.swmansion.rnscreens.Screen
 import com.swmansion.rnscreens.ScreenStackFragment
-import com.swmansion.rnscreens.events.ScreenAnimationDelegate
-import com.swmansion.rnscreens.events.ScreenEventEmitter
-import com.swmansion.rnscreens.transition.ExternalBoundaryValuesEvaluator
 import com.swmansion.rnscreens.utils.isSoftKeyboardVisibleOrNull
 
 class SheetDelegate(
@@ -36,10 +30,7 @@ class SheetDelegate(
     private var isKeyboardVisible: Boolean = false
     private var keyboardState: KeyboardState = KeyboardNotVisible
 
-    private var isSheetAnimationInProgress: Boolean = false
-
     private var lastTopInset: Int = 0
-    private var lastKeyboardBottomOffset: Int = 0
 
     var lastStableDetentIndex: Int = screen.sheetInitialDetentIndex
         private set
@@ -348,36 +339,6 @@ class SheetDelegate(
         }
     }
 
-    // This function calculates the Y offset to which the FormSheet should animate
-    // when appearing (entering) or disappearing (exiting) with the on-screen keyboard (IME) present.
-    // Its purpose is to ensure the FormSheet does not exceed the top edge of the screen.
-    // It tries to display the FormSheet fully above the keyboard when there's enough space.
-    // Otherwise, it shifts the sheet as high as possible, even if it means part of its content
-    // will remain hidden behind the keyboard.
-    internal fun computeSheetOffsetYWithIMEPresent(keyboardHeight: Int): Int {
-        val containerHeight = tryResolveMaxFormSheetHeight()
-        check(containerHeight != null) {
-            "[RNScreens] Failed to find window height during bottom sheet behaviour configuration"
-        }
-
-        if (screen.isSheetFitToContents()) {
-            val contentHeight = screen.contentWrapper?.height ?: 0
-            val offsetFromTop = maxOf(containerHeight - contentHeight, 0)
-            // If the content is higher than the Screen, offsetFromTop becomes negative.
-            // In such cases, we return 0 because a negative translation would shift the Screen
-            // to the bottom, which is not intended.
-            return minOf(offsetFromTop, keyboardHeight)
-        }
-
-        val detents = screen.sheetDetents
-
-        val detentValue = detents.highest().coerceIn(0.0, 1.0)
-        val sheetHeight = (detentValue * containerHeight).toInt()
-        val offsetFromTop = containerHeight - sheetHeight
-
-        return minOf(offsetFromTop, keyboardHeight)
-    }
-
     // This is listener function, not the view's.
     override fun onApplyWindowInsets(
         v: View,
@@ -473,128 +434,18 @@ class SheetDelegate(
 
     // Sheet entering/exiting animations
 
-    internal fun createSheetEnterAnimator(sheetAnimationContext: SheetAnimationContext): Animator {
-        val animatorSet = AnimatorSet()
-
-        val dimmingDelegate = sheetAnimationContext.dimmingDelegate
-        val screenStackFragment = sheetAnimationContext.fragment
-
-        val alphaAnimator = createDimmingViewAlphaAnimator(0f, dimmingDelegate.maxAlpha, dimmingDelegate)
-        val slideAnimator = createSheetSlideInAnimator()
-
-        animatorSet
-            .play(slideAnimator)
-            .takeIf {
-                dimmingDelegate.willDimForDetentIndex(screen, screen.sheetInitialDetentIndex)
-            }?.with(alphaAnimator)
-
-        attachCommonListeners(animatorSet, isEnter = true, screenStackFragment)
-
-        return animatorSet
-    }
-
-    internal fun createSheetExitAnimator(sheetAnimationContext: SheetAnimationContext): Animator {
-        val animatorSet = AnimatorSet()
-
-        val coordinatorLayout = sheetAnimationContext.coordinatorLayout
-        val dimmingDelegate = sheetAnimationContext.dimmingDelegate
-        val screenStackFragment = sheetAnimationContext.fragment
-
-        val alphaAnimator =
-            createDimmingViewAlphaAnimator(dimmingDelegate.dimmingView.alpha, 0f, dimmingDelegate)
-        val slideAnimator = createSheetSlideOutAnimator(coordinatorLayout)
-
-        animatorSet.play(alphaAnimator).with(slideAnimator)
-
-        attachCommonListeners(animatorSet, isEnter = false, screenStackFragment)
-
-        return animatorSet
-    }
-
-    private fun createDimmingViewAlphaAnimator(
-        from: Float,
-        to: Float,
-        dimmingDelegate: DimmingViewManager,
-    ): ValueAnimator =
-        ValueAnimator.ofFloat(from, to).apply {
-            addUpdateListener { animator ->
-                (animator.animatedValue as? Float)?.let {
-                    dimmingDelegate.dimmingView.alpha = it
-                }
-            }
-        }
+    internal fun createSheetEnterAnimator(sheetAnimationContext: SheetAnimationContext): Animator =
+        screen.sheetAnimationCoordinator.createSheetEnterAnimator(sheetAnimationContext)
 
-    private fun createSheetSlideInAnimator(): ValueAnimator {
-        val startValueCallback = { _: Number? -> screen.height.toFloat() }
-        val evaluator = ExternalBoundaryValuesEvaluator(startValueCallback, { 0f })
-
-        return ValueAnimator.ofObject(evaluator, screen.height.toFloat(), 0f).apply {
-            addUpdateListener { updateSheetTranslationY(it.animatedValue as Float) }
-        }
-    }
+    internal fun createSheetExitAnimator(sheetAnimationContext: SheetAnimationContext): Animator =
+        screen.sheetAnimationCoordinator.createSheetExitAnimator(sheetAnimationContext)
 
-    private fun createSheetSlideOutAnimator(coordinatorLayout: CoordinatorLayout): ValueAnimator {
-        val endValue = (coordinatorLayout.bottom - screen.top - screen.translationY)
+    internal fun handleKeyboardInsetsProgress(insets: WindowInsetsCompat) =
+        screen.sheetAnimationCoordinator.handleKeyboardInsetsProgress(insets)
 
-        return ValueAnimator.ofFloat(0f, endValue).apply {
-            addUpdateListener {
-                updateSheetTranslationY(it.animatedValue as Float)
-            }
-        }
-    }
-
-    private fun updateSheetTranslationY(baseTranslationY: Float) {
-        val keyboardCorrection = lastKeyboardBottomOffset
-        val bottomOffset = computeSheetOffsetYWithIMEPresent(keyboardCorrection).toFloat()
-
-        screen.translationY = baseTranslationY - bottomOffset
-    }
+    internal fun notifyKeyboardAnimationStart() = screen.sheetAnimationCoordinator.notifyKeyboardAnimationStart()
 
-    internal fun handleKeyboardInsetsProgress(insets: WindowInsetsCompat) {
-        lastKeyboardBottomOffset = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom
-        // Prioritize enter/exit animations over direct keyboard inset reactions.
-        // We store the latest keyboard offset in `lastKeyboardBottomOffset`
-        // so that it can always be respected when applying translations in `updateSheetTranslationY`.
-        //
-        // This approach allows screen translation to be triggered from two sources, but without messing them together:
-        // - During enter/exit animations, while accounting for the keyboard height.
-        // - While interacting with a TextInput inside the bottom sheet, to handle keyboard show/hide events.
-        if (!isSheetAnimationInProgress) {
-            updateSheetTranslationY(0f)
-        }
-    }
-
-    private fun attachCommonListeners(
-        animatorSet: AnimatorSet,
-        isEnter: Boolean,
-        screenStackFragment: ScreenStackFragment,
-    ) {
-        animatorSet.addListener(
-            ScreenAnimationDelegate(
-                screenStackFragment,
-                ScreenEventEmitter(screen),
-                if (isEnter) {
-                    ScreenAnimationDelegate.AnimationType.ENTER
-                } else {
-                    ScreenAnimationDelegate.AnimationType.EXIT
-                },
-            ),
-        )
-
-        animatorSet.addListener(
-            object : AnimatorListenerAdapter() {
-                override fun onAnimationStart(animation: Animator) {
-                    isSheetAnimationInProgress = true
-                }
-
-                override fun onAnimationEnd(animation: Animator) {
-                    isSheetAnimationInProgress = false
-
-                    screen.onSheetYTranslationChanged()
-                }
-            },
-        )
-    }
+    internal fun notifyKeyboardAnimationEnd() = screen.sheetAnimationCoordinator.notifyKeyboardAnimationEnd()
 
     private inner class KeyboardHandler : BottomSheetBehavior.BottomSheetCallback() {
         override fun onStateChanged(

package/android/src/main/java/com/swmansion/rnscreens/bottomsheet/SheetUtils.kt

@@ -158,3 +158,19 @@ fun Screen.sheetShouldUseDimmingView(): Boolean {
  * is reattached to container.
  */
 fun View.isLaidOutOrHasCachedLayout() = this.isLaidOut || height > 0 || width > 0
+
+internal fun Screen.resolveClampedHeight(
+    targetHeight: Int,
+    currentTranslationY: Float,
+): Int {
+    val maxAvailableVerticalSpace =
+        fragment
+            ?.asScreenStackFragment()
+            ?.sheetDelegate
+            ?.tryResolveMaxFormSheetHeight() ?: return targetHeight
+
+    // Please note that currentTranslationY is rather < 0 here.
+    // The translation is included in constraining the available space, because the FormSheet can have some offset, e.g. to
+    // avoid the keyboard.
+    return targetHeight.coerceAtMost((maxAvailableVerticalSpace + currentTranslationY).toInt())
+}

package/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/container/CustomBottomNavigationView.kt

@@ -0,0 +1,37 @@
+package com.swmansion.rnscreens.gamma.tabs.container
+
+import android.annotation.SuppressLint
+import android.content.Context
+import com.google.android.material.bottomnavigation.BottomNavigationView
+
+@SuppressLint("ViewConstructor") // Should not be restored & should only be constructed by us.
+class CustomBottomNavigationView(
+    context: Context,
+    val container: TabsContainer,
+) : BottomNavigationView(context) {
+    private var actionOrigin: TabsActionOrigin? = null
+
+    internal fun setSelectedItemIdWithActionOrigin(
+        itemId: Int,
+        actionOrigin: TabsActionOrigin,
+    ) {
+        require(actionOrigin !== TabsActionOrigin.USER) {
+            "[RNScreens] User-triggered actions should be processed via regular setSelectedItemId callback"
+        }
+        this.actionOrigin = actionOrigin
+        selectedItemId = itemId
+        this.actionOrigin = null
+    }
+
+    override fun setSelectedItemId(itemId: Int) {
+        if (this.actionOrigin == null) {
+            this.actionOrigin = TabsActionOrigin.USER
+        }
+
+        val actionOrigin = checkNotNull(this.actionOrigin)
+        super.setSelectedItemId(itemId)
+        container.onAfterSetSelectedItemId(itemId, actionOrigin)
+
+        this.actionOrigin = null
+    }
+}

package/android/src/main/java/com/swmansion/rnscreens/gamma/tabs/container/TabsContainer.kt

@@ -109,8 +109,8 @@ class TabsContainer internal constructor(
             R.style.Theme_Material3_DayNight_NoActionBar,
         )
 
-    internal val bottomNavigationView: BottomNavigationView =
-        BottomNavigationView(themedContext).apply {
+    internal val bottomNavigationView: CustomBottomNavigationView =
+        CustomBottomNavigationView(themedContext, this).apply {
             layoutParams =
                 LayoutParams(
                     LayoutParams.MATCH_PARENT,
@@ -256,6 +256,16 @@ class TabsContainer internal constructor(
         setPendingNavigationStateUpdate(null)
     }
 
+    internal fun onAfterSetSelectedItemId(
+        itemId: Int,
+        actionOrigin: TabsActionOrigin,
+    ) {
+        if (actionOrigin === TabsActionOrigin.USER) {
+            // For non-user actions these will be performed in [performContainerUpdate]
+            performPostSelectedTabUpdateActions()
+        }
+    }
+
     // endregion
 
     // region View lifecycle / insets / appearance
@@ -265,6 +275,19 @@ class TabsContainer internal constructor(
 
         super.onAttachedToWindow()
         setupFragmentManager()
+
+        // When TabsContainer is reattached to window, it might find new fragment manager (other
+        // than previous instance, e.g. in Stack v4 when screen is pushed & popped over screen with
+        // Tabs). In such case, we need to re-add currently selected tab screen fragment. As there
+        // might be another operation pending, we need to make sure that the state is restored
+        // before flushPendingUpdates is called. That's why inside restoreNavigationStateIfNeeded
+        // we're committing the transaction synchronously. This might lead to a crash if another
+        // transaction is currently being committed. If this happens to be problematic, we might need
+        // to reevaluate our approach. See #4035.
+        if (navState.isNotEmpty()) {
+            restoreNavigationStateIfNeeded()
+        }
+
         flushPendingUpdates()
 
         colorSchemeCoordinator.setup(this) { uiNightMode ->
@@ -275,6 +298,7 @@ class TabsContainer internal constructor(
     override fun onDetachedFromWindow() {
         super.onDetachedFromWindow()
         teardownFragmentManager()
+        colorSchemeCoordinator.teardown()
     }
 
     override fun onConfigurationChanged(newConfig: Configuration?) {
@@ -392,27 +416,62 @@ class TabsContainer internal constructor(
 
     // region Private helpers
 
+    /**
+     * This is where programmatic update flow starts.
+     * This includes any JS-triggered action (navigation state update, prop update, etc.)
+     * and native programmatic actions - tab change.
+     *
+     * This method is supposed to perform all the necessary steps, satisfying all invalidation
+     * signals in a coordinated manner.
+     *
+     * The update actions are split into three phases: pre-, selection change, and post-.
+     * Pre-selection actions are run only here, in programmatic flow. This is not a hard requirement,
+     * it is just not needed now.
+     *
+     * Post-selection actions are performed here or in parallel flow triggered on user selection.
+     *
+     * The selected tab update takes place here only for programmatic changes.
+     * User triggered changes have separate entry-point.
+     */
     private fun performContainerUpdate() {
+        performPreSelectedTabUpdateActions()
+        performSelectedTabUpdateIfNeeded()
+        performPostSelectedTabUpdateActions()
+    }
+
+    private fun performPreSelectedTabUpdateActions() {
+        updateNavigationMenuStructureIfNeeded()
+    }
+
+    private fun performPostSelectedTabUpdateActions() {
+        updateBottomNavigationViewAppearanceIfNeeded()
+    }
+
+    private fun updateNavigationMenuStructureIfNeeded() {
         if (invalidationFlags.isNavigationMenuStructureInvalidated) {
             invalidationFlags.isNavigationMenuStructureInvalidated = false
             updateNavigationMenuStructure()
         }
+    }
 
+    private fun performSelectedTabUpdateIfNeeded() {
         if (invalidationFlags.isSelectedTabInvalidated) {
             invalidationFlags.isSelectedTabInvalidated = false
-            performOperation()
+            performSelectedTabUpdate()
         }
+    }
 
+    private fun updateBottomNavigationViewAppearanceIfNeeded() {
         if (invalidationFlags.isNavigationMenuAppearanceInvalidated) {
             invalidationFlags.isNavigationMenuAppearanceInvalidated = false
-            this.updateBottomNavigationViewAppearance()
+            updateBottomNavigationViewAppearance()
             a11yCoordinator.setA11yPropertiesToAllTabItems()
         }
     }
 
-    private fun performOperation() {
+    private fun performSelectedTabUpdate() {
         if (pendingStateUpdateRequest == null) {
-            RNSLog.w(TAG, "TabsContainer::performOperation called w/o pending operation; skipping update")
+            RNSLog.w(TAG, "TabsContainer::performSelectedTabUpdate called w/o pending operation; skipping update")
             return
         }
 
@@ -436,7 +495,7 @@ class TabsContainer internal constructor(
         if (bottomNavigationView.selectedItemId != nextSelectedMenuItemId || navState.isEmpty()) {
             isInExternalOperationContext = true
             // This triggers on OnMenuItemClicked callback, where we perform actual update from
-            bottomNavigationView.selectedItemId = nextSelectedMenuItemId
+            bottomNavigationView.setSelectedItemIdWithActionOrigin(nextSelectedMenuItemId, stateUpdateRequest.actionOrigin)
             isInExternalOperationContext = false
         } else {
             observerRegistry.emitOnNavigationStateUpdateRejected(
@@ -545,6 +604,13 @@ class TabsContainer internal constructor(
         val hasTriggeredSpecialEffect =
             if (isRepeated) specialEffectsHandler.handleRepeatedTabSelection() else false
 
+        if (stateChanged && !isRepeated) {
+            // If we've effectively changed the tab, we need to raise appropriate flags.
+            // This line assumes that any required e.g. appearance actions will be performed
+            // synchronously later in the flow.
+            invalidationFlags.invalidateOnSelectedTabChanged()
+        }
+
         if (stateChanged) {
             observerRegistry.emitOnNavigationStateUpdate(
                 navState,
@@ -558,6 +624,36 @@ class TabsContainer internal constructor(
         return true
     }
 
+    /**
+     * When Tabs are reattached to window, they might find new fragment manager. In this case we
+     * need to restore navigation state. We're committing the transaction synchronously so that any
+     * following operations have valid restored state before their execution.
+     *
+     * This function is a no-op if navigation state is empty.
+     */
+    private fun restoreNavigationStateIfNeeded() {
+        if (navState.isEmpty()) {
+            return
+        }
+
+        val currentFragments =
+            requireFragmentManager.fragments
+                .filterIsInstance<TabsScreenFragment>()
+                .filter { it in tabsModel }
+                .toList()
+
+        if (currentFragments.size == 1 && currentFragments[0] === selectedTab) {
+            return
+        } else if (currentFragments.isEmpty()) {
+            requireFragmentManager
+                .createTransactionWithReordering()
+                .add(contentView.id, selectedTab)
+                .commitNowAllowingStateLoss()
+        } else {
+            error("[RNScreens] Unexpected fragment manager state.")
+        }
+    }
+
     private fun applyDayNightUiMode(uiMode: Int) {
         // update the appearance when user toggles between dark/light mode
         when (uiMode) {
@@ -650,4 +746,8 @@ internal class TabsContainerInvalidationFlags(
         isNavigationMenuAppearanceInvalidated = true
         isNavigationMenuStructureInvalidated = true
     }
+
+    internal fun invalidateOnSelectedTabChanged() {
+        isNavigationMenuAppearanceInvalidated = true
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-screens",
-  "version": "4.25.0",
+  "version": "4.25.2",
   "description": "Native navigation primitives for your React Native app.",
   "scripts": {
     "submodules": "git submodule update --init --recursive && (cd react-navigation && yarn && yarn build && cd ../)",