@apexnative/navigation 1.0.0-alpha.2 → 1.0.0-alpha.3

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/StackQueue.kt

@@ -15,6 +15,7 @@ import dev.apexnative.navigation.viewcontrollers.component.Readiness
 import dev.apexnative.navigation.viewcontrollers.component.RenderWait
 import dev.apexnative.navigation.viewcontrollers.parent.OptionsScreen
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.BarMotion
+import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.BarTravel
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.BarVisibility
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.Custom
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.Elements
@@ -71,12 +72,20 @@ internal class StackQueue(
         /** The current child (the top of [shown]) changed: a transition started, or an operation ran at once. */
         fun currentChildChanged()
 
+        /** An operation was accepted: a back gesture's preview that shows ends, the stack as it was. */
+        fun operationAccepted() = Unit
+
         /**
          * The current child is about to change, right before [currentChildChanged]: [motion] is the default transition
          * the bar's row goes with, none when the change comes at once or with an animation of its own; [visibility] is
-         * how the bar shows or hides when the new top wants it otherwise.
+         * how the bar shows or hides when the new top wants it otherwise; [travel]: the bar goes with the screens of an
+         * animation of its own without elements.
          */
-        fun barTransition(motion: StackDisplay.BarMotion?, visibility: BarVisibility) = Unit
+        fun barTransition(
+            motion: StackDisplay.BarMotion?,
+            visibility: BarVisibility,
+            travel: StackDisplay.BarTravel? = null,
+        ) = Unit
 
         /**
          * The current child is about to change, right before [barTransition]: [move] is how the transition goes, which
@@ -140,6 +149,9 @@ internal class StackQueue(
     private var takenOver = false
     private var destroyed = false
 
+    /** [node]'s content is made and nothing waits for it to render as a lower screen. */
+    fun isRendered(node: Node): Boolean = node !in unrendered && node !in lowerWaits
+
     /** The stack as JavaScript sees it, bottom to top. */
     val entries: List<Node>
         get() = entryList
@@ -199,7 +211,9 @@ internal class StackQueue(
 
     /**
      * A cut to [target], an entry that becomes the top: every entry above it leaves. [answer] gets [value]; a back of
-     * the user has none. [silent]: no animation and no appearance events (`popToRootOnBlur`).
+     * the user has none. [silent]: no animation and no appearance events (`popToRootOnBlur`). [gesture]: the release of
+     * a back gesture whose preview shows the pop already (`StackDisplay.finishBackGesture` ends it, the bar shows the
+     * target at once).
      */
     fun cut(
         target: Node,
@@ -208,6 +222,7 @@ internal class StackQueue(
         what: String,
         value: String?,
         silent: Boolean = false,
+        gesture: Boolean = false,
     ) {
         val index = entryList.indexOf(target)
         if (destroyed || index < 0) return refuse(answer, null, componentId, emptyList())
@@ -219,7 +234,7 @@ internal class StackQueue(
         (waiting as? ReplaceOp)?.let(::completeAtOnce)
         val showsAbove = target in shownList && shownList.last() !== target
         val op = if (showsAbove) {
-            CutOp(seq, answer, componentId, what, target, value, silent)
+            CutOp(seq, answer, componentId, what, target, value, silent, gesture)
         } else {
             // A cut that moves nothing more: its answer at its turn.
             NoneOp(seq, answer, null, componentId, what, value, null)
@@ -341,6 +356,8 @@ internal class StackQueue(
     // The table.
 
     private fun enqueue(op: Op) {
+        // Anything but the release of a back gesture ends its preview first.
+        if (!(op is CutOp && op.gesture)) host.operationAccepted()
         queued.addLast(op)
         drain()
     }
@@ -450,7 +467,7 @@ internal class StackQueue(
         val elements = own && AnimationRules.hasElements(push)
         // The bar's row goes with the default transition only; with an animation of its own it changes at once. The tab
         // bar moves with its screens or by its own side.
-        tellBars(animated, own, elements, push, TabBarMotion.Move.WithPush, BarMotion.Push)
+        tellBars(animated, own, elements, push, TabBarMotion.Move.WithPush, BarMotion.Push, BarTravel.Forward)
         host.currentChildChanged()
         finishTakenOver(ended)
         running += op
@@ -581,7 +598,9 @@ internal class StackQueue(
         val animated = !atOnce && !op.silent && display.canAnimate && !pop.enabled.isFalse
         val own = animated && AnimationRules.stackIsOwn(pop)
         val elements = own && AnimationRules.hasElements(pop)
-        tellBars(animated, own, elements, pop, TabBarMotion.Move.WithPop, BarMotion.Pop)
+        // A back gesture's preview shows the target and its bar already: the bar stays as it is.
+        val gesture = op.gesture && animated && !own && leaving.size == 1 && display.hasBackPreview(top, target)
+        tellBars(animated, own, elements, pop, TabBarMotion.Move.WithPop, BarMotion.Pop, BarTravel.Back, gesture)
         host.currentChildChanged()
         finishTakenOver(ended)
         if (display.hasView) target.onViewBroughtToFront()
@@ -592,6 +611,17 @@ internal class StackQueue(
         // The screens between the top and the target leave without animation.
         leaving.drop(1).forEach(display::hide)
         if (!animated) return finishCut(op)
+        if (gesture) {
+            op.animating += top
+            op.animating += target
+            display.finishBackGesture(
+                top,
+                target,
+                { step(op) { screenDone(op, top) } },
+                { step(op) { screenDone(op, target) } },
+            )
+            return
+        }
         // Its own: no wait on a pop; the leaving screen starts from where it is.
         if (own) return animate(op, backMoves(top, target, pop, elements, moving))
         animate(op, listOf(Move(top, Motion.PopOut, true), Move(target, Motion.PopReveal, moving)))
@@ -657,7 +687,7 @@ internal class StackQueue(
         val elements = own && !op.asPush && AnimationRules.hasElements(played)
         val motion = if (op.asPush) BarMotion.Push else BarMotion.FadeThrough
         val system = if (op.asPush) TabBarMotion.Move.WithPush else TabBarMotion.Move.Slide
-        tellBars(animated, own, elements, played, system, motion)
+        tellBars(animated, own, elements, played, system, motion, BarTravel.Forward)
         host.currentChildChanged()
         finishTakenOver(ended)
         op.owned += moved
@@ -1081,9 +1111,10 @@ internal class StackQueue(
     private fun awaitsTargets(animation: StackAnimationOptions, enabled: Boolean): Boolean = enabled &&
         display.canAnimate && !animation.waitForRender.isFalse && AnimationRules.hasElements(animation)
 
-    // The bars with a change of the current child. The row goes with the default transition only; the tab bar rides
-    // with the system's [system] move, slides with an animation of its own or a side of its own, and is where the new
-    // top wants it at once without animation; with elements every bar changes at once.
+    // The bars with a change of the current child. The row goes with the default transition; with an animation of its
+    // own the top bar goes with the screens ([travel]). The tab bar rides with the system's [system] move, slides with an
+    // animation of its own or a side of its own, and is where the new top wants it at once without animation; with
+    // elements every bar changes at once.
     private fun tellBars(
         animated: Boolean,
         own: Boolean,
@@ -1091,6 +1122,9 @@ internal class StackQueue(
         animation: StackAnimationOptions,
         system: TabBarMotion.Move,
         row: BarMotion,
+        travel: BarTravel,
+        // The top bar shows the new top already (a back gesture's preview): it changes at once, the tab bar still moves.
+        barAtOnce: Boolean = false,
     ) {
         val tabs = animation.bottomTabs
         val tabsSide = AnimationRules.barSideGiven(tabs.enter) || AnimationRules.barSideGiven(tabs.exit)
@@ -1100,7 +1134,12 @@ internal class StackQueue(
             else -> system
         }
         host.tabBarTransition(move, tabs.takeIf { move == TabBarMotion.Move.Slide })
-        host.barTransition(if (animated && !own) row else null, barVisibility(animated && !elements, animation.topBar))
+        val barMoves = animated && !barAtOnce
+        host.barTransition(
+            if (barMoves && !own) row else null,
+            barVisibility(barMoves && !elements, animation.topBar),
+            travel.takeIf { barMoves && own && !elements },
+        )
     }
 
     private fun barVisibility(animated: Boolean, side: TopBarEnterExitAnimationOptions): BarVisibility =
@@ -1209,6 +1248,7 @@ internal class StackQueue(
         val target: Node,
         val value: String?,
         val silent: Boolean,
+        val gesture: Boolean,
     ) : Op(seq, answer, null, componentId, what) {
         var leaving: List<Node> = emptyList()
     }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/StackTransitions.kt

@@ -16,11 +16,15 @@ import dev.apexnative.navigation.views.animations.SystemTransition
  * system's transition between activities (`SystemTransition`: 96 dp along the axis in 450 ms on
  * `fast_out_extra_slow_in`, mirrored right to left), `setStackRoot` is Material's fade through (`FadeThrough`). What
  * leaves starts from where it is; what comes in on a push is hidden explicitly until it fades in, as a delay doesn't
- * apply an animator's first value. Main thread only.
+ * apply an animator's first value. The system's windows also extend their edge by the distance they move
+ * ([extendsStart], `StackLayout.extendEdge`). Main thread only.
  */
 internal object StackTransitions {
-    /** The animator of [view] for [motion]; [fromCurrent] for a screen taken over from a transition still running. */
-    fun animator(view: View, motion: Motion, fromCurrent: Boolean): Animator {
+    /**
+     * The animator of [view] for [motion]; [fromCurrent] for a screen taken over from a transition still running.
+     * [onSlide] runs at each frame of its slide.
+     */
+    fun animator(view: View, motion: Motion, fromCurrent: Boolean, onSlide: () -> Unit = {}): Animator {
         val distance = SystemTransition.DISTANCE_DP * view.resources.displayMetrics.density
         // Forward is to the end of the line: right to left, the screens move the other way. The stack's view inherits
         // the app's direction, which `layout.direction` sets on the activity's content (`AppDirection`).
@@ -30,24 +34,37 @@ internal object StackTransitions {
                 view.translationX = forward
                 view.alpha = 0f
                 together(
-                    slide(view, 0f),
+                    slide(view, 0f, onSlide),
                     fade(view, 1f, SystemTransition.PUSH_FADE_DELAY),
                 )
             }
-            Motion.PushCover -> slide(view, -forward)
+            Motion.PushCover -> slide(view, -forward, onSlide)
             Motion.PopOut -> together(
-                slide(view, forward),
+                slide(view, forward, onSlide),
                 fade(view, 0f, SystemTransition.POP_FADE_DELAY),
             )
             Motion.PopReveal -> {
                 if (!fromCurrent) view.translationX = -forward
-                if (view.alpha < 1f) together(slide(view, 0f), fade(view, 1f, 0L)) else slide(view, 0f)
+                if (view.alpha < 1f) together(slide(view, 0f, onSlide), fade(view, 1f, 0L)) else slide(view, 0f, onSlide)
             }
             Motion.FadeIn -> FadeThrough.enter(view)
             Motion.FadeOut -> FadeThrough.exit(view)
         }
     }
 
+    /**
+     * Whether a screen moving by [motion] extends its start edge (the side it moves away from on a push in and a pop
+     * out), its end edge (a push cover, a pop reveal), or none (a fade through: null), as the system's windows do.
+     */
+    fun extendsStart(motion: Motion): Boolean? = when (motion) {
+        Motion.PushIn, Motion.PopOut -> true
+        Motion.PushCover, Motion.PopReveal -> false
+        Motion.FadeIn, Motion.FadeOut -> null
+    }
+
+    /** Whether [motion] animates the screen's alpha: it draws through a hardware layer meanwhile. */
+    fun fades(motion: Motion): Boolean = motion != Motion.PushCover && motion != Motion.PopReveal
+
     /**
      * The fade of a screen around elements: in from 0 to 1, out from where it is to 0, linearly in
      * [AnimationRules.SCREEN_FADE]; none for [Fade.None].
@@ -65,10 +82,11 @@ internal object StackTransitions {
         }
     }
 
-    private fun slide(view: View, to: Float): Animator =
+    private fun slide(view: View, to: Float, onFrame: () -> Unit): Animator =
         ObjectAnimator.ofFloat(view, View.TRANSLATION_X, view.translationX, to).apply {
             duration = SystemTransition.DURATION
             interpolator = SystemTransition.CURVE
+            addUpdateListener { onFrame() }
         }
 
     private fun fade(view: View, to: Float, delay: Long): Animator =

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/StackViews.kt

@@ -9,6 +9,7 @@ import androidx.core.view.WindowInsetsCompat
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleOwner
 import dev.apexnative.navigation.options.LayoutAnimation
+import dev.apexnative.navigation.utils.UiThread
 import dev.apexnative.navigation.utils.whenContentMounted
 import dev.apexnative.navigation.viewcontrollers.component.ComponentViewController
 import dev.apexnative.navigation.viewcontrollers.externalcomponent.ExternalComponentViewController
@@ -16,6 +17,7 @@ import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.Motion
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
+import dev.apexnative.navigation.views.animations.SystemTransition
 import dev.apexnative.navigation.views.element.ElementTransition
 import dev.apexnative.navigation.views.element.TargetsWait
 import dev.apexnative.navigation.views.stack.StackLayout
@@ -29,6 +31,11 @@ import dev.apexnative.navigation.views.stack.StackLayout
  */
 internal class StackViews(private val stack: StackController) : StackDisplay {
     private val animators = HashMap<ViewController<*>, Animator>()
+    // The preview of the back gesture that runs or ends now, and its two screens.
+    private var preview: BackPreview? = null
+    private var previewScreens: Pair<ViewController<*>, ViewController<*>>? = null
+    // The ends of the two screens of a released gesture whose preview plays its end.
+    private var committing: Pair<() -> Unit, () -> Unit>? = null
     // What goes back when a screen's animator ends or stops: the elements its transition carries.
     private val cleanups = HashMap<ViewController<*>, () -> Unit>()
 
@@ -110,11 +117,16 @@ internal class StackViews(private val stack: StackController) : StackDisplay {
     override fun animate(screen: ViewController<*>, motion: Motion, fromCurrent: Boolean, done: () -> Unit) {
         stop(screen)
         val view = screen.peekView() ?: return done()
-        val animator = StackTransitions.animator(view, motion, fromCurrent)
+        val layout = layout
+        val animator = StackTransitions.animator(view, motion, fromCurrent) { layout?.edgesMoved() }
+        cleanups[screen] = dress(view, motion, layout)
         animator.addListener(object : AnimatorListenerAdapter() {
             // Ended or cancelled by anything else than [stop]: the screen's part is done.
             override fun onAnimationEnd(animation: Animator) {
-                if (animators[screen] === animator) animators.remove(screen)
+                if (animators[screen] === animator) {
+                    animators.remove(screen)
+                    cleanups.remove(screen)?.invoke()
+                }
                 done()
             }
         })
@@ -122,6 +134,21 @@ internal class StackViews(private val stack: StackController) : StackDisplay {
         animator.start()
     }
 
+    // For the default transition [view] moves as the system's windows do: its edge extended by the distance it moves,
+    // and its fade drawn through a hardware layer, so the whole screen isn't drawn again at every frame of it. What
+    // undoes both.
+    private fun dress(view: View, motion: Motion, layout: StackLayout?): () -> Unit {
+        StackTransitions.extendsStart(motion)?.let { start ->
+            layout?.extendEdge(view, start, (SystemTransition.DISTANCE_DP * view.resources.displayMetrics.density).toInt())
+        }
+        val layered = StackTransitions.fades(motion) && view.layerType == View.LAYER_TYPE_NONE
+        if (layered) view.setLayerType(View.LAYER_TYPE_HARDWARE, null)
+        return {
+            layout?.dropEdge(view)
+            if (layered && view.layerType == View.LAYER_TYPE_HARDWARE) view.setLayerType(View.LAYER_TYPE_NONE, null)
+        }
+    }
+
     // The elements go into a layer over the screens, and back as the screen's animator ends or stops. A shared element
     // without a duration takes the screen's fade: its own single `alpha`, else 300 ms.
     override fun animateCustom(screen: ViewController<*>, custom: StackDisplay.Custom, done: () -> Unit) {
@@ -167,7 +194,83 @@ internal class StackViews(private val stack: StackController) : StackDisplay {
         done: () -> Unit,
     ): () -> Unit = TargetsWait.start(animation, from, to, waiting, done)
 
+    /**
+     * Starts the preview of a back gesture over [top], [target] under it (`BackPreview`): none without the stack's view
+     * or a window. [onReveal] shows [target] and its bar as the preview's picture is there.
+     */
+    fun startBackPreview(
+        top: ViewController<*>,
+        target: ViewController<*>,
+        fromLeft: Boolean,
+        touchY: Float,
+        onReveal: () -> Unit,
+    ): BackPreview? {
+        val bottomRoom = top.getBottomInset()
+        endPreview()
+        val layout = layout ?: return null
+        val window = stack.activity.window ?: return null
+        val topView = top.peekView() ?: return null
+        val targetView = target.peekView() ?: return null
+        val started = BackPreview(layout, topView, targetView, fromLeft, touchY, bottomRoom, onReveal)
+        preview = started
+        previewScreens = top to target
+        started.start(window)
+        return started
+    }
+
+    /** The preview of the back gesture went: cancelled and put back, or never shown. */
+    fun previewEnded(ended: BackPreview) {
+        if (preview !== ended) return
+        preview = null
+        previewScreens = null
+    }
+
+    override fun hasBackPreview(top: ViewController<*>, target: ViewController<*>): Boolean =
+        preview?.isReady == true && previewScreens == top to target
+
+    override fun finishBackGesture(
+        top: ViewController<*>,
+        target: ViewController<*>,
+        topDone: () -> Unit,
+        targetDone: () -> Unit,
+    ) {
+        val running = preview?.takeIf { hasBackPreview(top, target) } ?: run {
+            topDone()
+            targetDone()
+            return
+        }
+        committing = topDone to targetDone
+        running.commit {
+            committing = null
+            previewEnded(running)
+            topDone()
+            targetDone()
+        }
+    }
+
+    private fun endPreview() {
+        val ended = preview ?: return
+        preview = null
+        previewScreens = null
+        committing = null
+        ended.endAtOnce()
+    }
+
+    // A later transition takes one screen of a released gesture's preview: the preview ends where it is, the popped
+    // screen stays out of sight until the pop takes it away, and the other screen's part ends on the next turn.
+    private fun stopPreview(screen: ViewController<*>) {
+        val (top, target) = previewScreens ?: return
+        if (screen !== top && screen !== target) return
+        val dones = committing
+        endPreview()
+        if (dones == null) return
+        top.peekView()?.alpha = 0f
+        val other = if (screen === top) dones.second else dones.first
+        UiThread.post { other() }
+    }
+
     override fun stop(screen: ViewController<*>) {
+        stopPreview(screen)
         val animator = animators.remove(screen)
         if (animator != null) {
             animator.removeAllListeners()

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/topbar/TopBarPresenter.kt

@@ -49,7 +49,9 @@ import dev.apexnative.navigation.viewcontrollers.stack.search.StackSearchPresent
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.IReactView
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ScrollEventListener
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
+import dev.apexnative.navigation.views.animations.FadeThrough
 import dev.apexnative.navigation.views.animations.SystemTransition
 import dev.apexnative.navigation.views.component.ComponentLayout
 import dev.apexnative.navigation.views.stack.StackLayout
@@ -124,8 +126,13 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
     private var largeTitleShown = false
     private var followed: ScrollEventListener? = null
     private var rowTarget: RowTarget? = null
+    // The large title opening with a push from a screen without one; none at rest.
+    private var largeTitleOpening: ValueAnimator? = null
     // The picture of the part under the row in a leaving screen's overlay: the screen and the picture.
     private var underRow: Pair<ViewController<*>, Drawable>? = null
+    // The bar goes with the screens of a transition of the stack's own, and the screen that leaves with its picture.
+    private var travelling = false
+    private var travelLeaving: ViewController<*>? = null
 
     private enum class Part { Look, Title, Left, Right, Back, LargeTitle, Visible, TestId }
 
@@ -161,12 +168,16 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
      * The stack's current child changes to [incoming] ([motion]: the default transition that brings it, none at once):
      * the row's picture is taken before the bar takes the new screen's options. A push from a large title to a screen
      * without one makes the bar lower at once: the part under the row rides with the leaving screen as a picture in its
-     * overlay, and the row's picture holds the row only. So does a pop back to a screen whose large title is collapsed.
+     * overlay, and the row's picture holds the row only. So does a pop or a fade through (`setStackRoot`) to a screen
+     * without a large title or with its large title collapsed: a picture as tall as the large title would hold the bar
+     * at its height to the end. With a transition of the stack's own ([travel]) the bar goes with the screens instead
+     * ([beginTravel]).
      */
     fun beginRowTransition(
         motion: BarMotion?,
         incoming: ViewController<*>?,
         visibility: StackDisplay.BarVisibility = StackDisplay.BarVisibility.AT_ONCE,
+        travel: StackDisplay.BarTravel? = null,
     ) {
         this.motion = motion
         this.visibilityChange = visibility
@@ -179,14 +190,68 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
         rowTarget?.withLargeTitle = !lowers
         if (lowers) pictureUnderRow(bar, leaving)
         rowTransition?.begin(motion)
+        endTravel()
+        if (travel != null && bar != null && incoming != null) beginTravel(bar, leaving, incoming, travel, visibility)
     }
 
     /** The transition that brought the current child ended: the row at rest, the picture under it gone. */
     fun endRowTransition() {
+        // A large title still opening is open now.
+        largeTitleOpening?.let {
+            largeTitleOpening = null
+            it.end()
+        }
         motion = null
         visibilityChange = StackDisplay.BarVisibility.AT_ONCE
         rowTransition?.end()
         dropPictureUnderRow()
+        endTravel()
+    }
+
+    /**
+     * The bar goes with the screens of a transition of the stack's own, as each screen's bar would: a picture of the
+     * bar as it is goes with [leaving], and the bar, which takes [incoming]'s options next, is drawn flat as [incoming]
+     * moves — under [leaving] on a pop ([StackDisplay.BarTravel.Back]) (`StackLayout.barTravels`). No picture when the
+     * bar doesn't show. Nothing travels when the new top hides the bar by a side of its own
+     * (`animations.*.topBar.exit`), which plays instead, or when the bar can't be drawn in software (a `HARDWARE`
+     * bitmap in it): the bar takes the options in its place.
+     */
+    private fun beginTravel(
+        bar: TopBar,
+        leaving: ViewController<*>?,
+        incoming: ViewController<*>,
+        direction: StackDisplay.BarTravel,
+        visibility: StackDisplay.BarVisibility,
+    ) {
+        val layout = layout ?: return
+        val screen = incoming.peekView()?.takeIf(layout::holds) ?: return
+        val leavingView = leaving?.peekView()?.takeIf(layout::holds)
+        // The new top hides the bar by a side of its own: the side plays on the bar in its place instead.
+        if (host.resolvedOf(incoming).topBar.visible.isFalse && AnimationRules.barSideGiven(visibility.side?.exit)) return
+        val shows = bar.visibility == View.VISIBLE && this.visibility?.isHidden != true
+        val picture = if (shows && leavingView != null) pictureOfBar(bar) ?: return else null
+        travelling = true
+        travelLeaving = leaving.takeIf { picture != null }
+        // Flat: with an elevation the renderer would draw the bar over every screen and out of its alpha layer.
+        bar.isFlat = true
+        layout.barTravels(screen, leavingView, picture, direction == StackDisplay.BarTravel.Back)
+    }
+
+    // The bar's picture where the bar is in the stack, its moves counted.
+    private fun pictureOfBar(bar: TopBar): Drawable? {
+        val bitmap = bar.picture() ?: return null
+        val left = (bar.left + bar.translationX).roundToInt()
+        val top = (bar.top + bar.translationY).roundToInt()
+        return BitmapDrawable(bar.resources, bitmap).apply { setBounds(left, top, left + bitmap.width, top + bitmap.height) }
+    }
+
+    // The bar's travel ends: the picture goes, the bar is drawn in its place again with its shadow.
+    private fun endTravel() {
+        if (!travelling) return
+        travelling = false
+        travelLeaving = null
+        bar?.isFlat = false
+        layout?.endBarTravel()
     }
 
     /**
@@ -205,8 +270,9 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
             keys.clear()
         }
         shownEntry = entry
-        // The screen that left with the picture under the row shows again: the picture goes.
+        // The screen that left with the picture under the row, or of the bar, shows again: the picture goes.
         if (underRow?.first === entry) dropPictureUnderRow()
+        if (travelLeaving === entry) endTravel()
         val options = host.resolvedOf(entry)
         applyAll(bar, entry, screen, options, merge = false)
     }
@@ -334,7 +400,9 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
     /** The stack is destroyed: every component stops. */
     fun destroy() {
         rowTransition?.end()
+        endTravel()
         largeTitleFollower.stop()
+        stopLargeTitleOpening()
         collapse?.disableCollapse()
         components.destroyAll()
         cells.clear()
@@ -370,6 +438,9 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
         )
     }
 
+    /** Whether the bar shows [entry]: its parts are applied, so its place in the layout is [entry]'s. */
+    fun shows(entry: ViewController<*>): Boolean = entry === shownEntry
+
     /** The height of the search under the row of [entry] when it is the screen the bar shows; 0 otherwise. */
     fun searchHeightOf(entry: ViewController<*>): Int =
         if (entry === shownEntry) bar?.searchAreaHeight ?: 0 else 0
@@ -633,11 +704,13 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
     }
 
     // Whether [incoming] shows less of the bar under the row than the large title now: a push to a screen without a
-    // large title, or a pop back to one whose large title is collapsed. The lower bar would cut the row's picture.
+    // large title, or a pop or a fade through to one without a large title or with its large title collapsed. The lower
+    // bar would cut the row's picture.
     private fun lowersBar(motion: BarMotion?, incoming: ViewController<*>, options: Options): Boolean = when (motion) {
         BarMotion.Push -> !largeTitleShownFor(incoming, options)
-        BarMotion.Pop -> largeTitleShownFor(incoming, options) && collapseOf(incoming, options) > 0f
-        else -> false
+        BarMotion.Pop, BarMotion.FadeThrough ->
+            !largeTitleShownFor(incoming, options) || collapseOf(incoming, options) > 0f
+        null -> false
     }
 
     // How far [entry]'s large title is collapsed as it shows: by the offset its list had last, unless it doesn't follow
@@ -675,6 +748,11 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
             large.fontSize.get(null), fontKey(large.font), large.collapseOnScroll.get(null), testId).joinToString()
         if (keys[Part.LargeTitle] == key) return
         keys[Part.LargeTitle] = key
+        // The default push or fade through from a screen without a large title opens it with the screens, on a bar that
+        // shows at rest: the bar's show and its hide on scroll move the same translation.
+        val opening = motion.takeIf { it == BarMotion.Push || it == BarMotion.FadeThrough }
+        val opens = shown && !largeTitleShown && bar.visibility == View.VISIBLE && bar.translationY == 0f
+        stopLargeTitleOpening()
         largeTitleShown = shown
         bar.setLargeTitleShown(shown)
         largeTitleFollower.stop()
@@ -692,9 +770,39 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
         // same frame: back to the screen, after light or dark changed, after a merge.
         if (large.collapseOnScroll.isFalse) scrollOf(entry)?.forgetOffset()
         largeTitleFollower.collapse(collapseOf(entry, options))
+        if (opens) opening?.let { openLargeTitle(bar, collapseOf(entry, options), it) }
         if (!large.collapseOnScroll.isFalse) scrollOf(entry)?.let(largeTitleFollower::follow)
     }
 
+    // The bar grows with the screens' [motion], on its curve and in its time, from the row's height to the large title
+    // as the screen's list left it: the large title comes out from under the row as it does when the list scrolls
+    // back. No frame shows the tall bar before the screens move.
+    private fun openLargeTitle(bar: TopBar, offset: Float, motion: BarMotion) {
+        val range = UiUtils.dpToPx(bar.context, LargeTitleView.HEIGHT)
+        val to = LargeTitleCollapse.shift(offset, range)
+        if (to >= range) return
+        bar.setLargeTitleCollapse(range.toInt())
+        largeTitleOpening = ValueAnimator.ofFloat(range, to).apply {
+            duration = if (motion == BarMotion.FadeThrough) FadeThrough.DURATION else SystemTransition.DURATION
+            interpolator = if (motion == BarMotion.FadeThrough) FadeThrough.CURVE else SystemTransition.CURVE
+            addUpdateListener { bar.setLargeTitleCollapse((it.animatedValue as Float).toInt()) }
+            addListener(object : AnimatorListenerAdapter() {
+                override fun onAnimationEnd(animation: Animator) {
+                    if (largeTitleOpening === animation) largeTitleOpening = null
+                }
+            })
+            start()
+        }
+    }
+
+    // Stopped where it is: what applies next sets the large title.
+    private fun stopLargeTitleOpening() {
+        val opening = largeTitleOpening ?: return
+        largeTitleOpening = null
+        opening.removeAllUpdateListeners()
+        opening.cancel()
+    }
+
     // Shown or hidden: with the transition by its side, or by `animate` in a merge.
     private fun applyVisibility(options: Options, merge: Boolean) {
         val visible = !options.topBar.visible.isFalse
@@ -702,7 +810,10 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
         if (keys[Part.Visible] == key) return
         keys[Part.Visible] = key
         val change = visibilityChange
-        val animated = !options.topBar.animate.isFalse && (merge || change.animated)
+        // While the bar goes with the screens it shows or hides at once, unless its side of its own plays.
+        val travels = !merge && travelling &&
+            !AnimationRules.barSideGiven(if (visible) change.side?.enter else change.side?.exit)
+        val animated = !options.topBar.animate.isFalse && (merge || change.animated) && !travels
         visibility?.apply(visible, animated, if (merge) null else change.side)
     }
 
@@ -960,8 +1071,11 @@ internal class TopBarPresenter(private val activity: Activity, private val host:
                 if (large) View.IMPORTANT_FOR_ACCESSIBILITY_NO else View.IMPORTANT_FOR_ACCESSIBILITY_YES
         }
 
+        // The list scrolled while the large title opens: it follows the list from there.
         override fun onScrollOffset(offsetY: Float) {
-            if (largeTitleShown) collapse(offsetY)
+            if (!largeTitleShown) return
+            stopLargeTitleOpening()
+            collapse(offsetY)
         }
 
         override fun onScrollUp(nextTranslation: Float) = Unit

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/viewcontroller/ViewController.kt

@@ -94,6 +94,19 @@ abstract class ViewController<V : ViewGroup>(
     open val isInSheet: Boolean
         get() = shownAsSheet || parent?.isInSheet == true
 
+    /**
+     * The node is the root of an overlay: the overlays set it before the node's view is made, so its screens are drawn
+     * under the status bar from their first layout (`StatusBarOptions.isHiddenOrDrawBehind`).
+     */
+    internal var shownAsOverlay = false
+
+    /**
+     * The node is in an overlay: it covers the whole window, and is drawn under the status bar by default. It holds from
+     * the start of the show, while `OverlayCoordinator.isInOverlay` answers only for the overlays it lists.
+     */
+    open val isInOverlay: Boolean
+        get() = shownAsOverlay || parent?.isInOverlay == true
+
     /**
      * The node is in a side of a side menu (its left or right menu, not its center): the side goes the whole height of
      * the window, and the node keeps no room for the status bar. The layout around answers for it
@@ -265,6 +278,12 @@ abstract class ViewController<V : ViewGroup>(
     /** Whether [handleBack] would go back. */
     open fun canHandleBack(): Boolean = false
 
+    /**
+     * The stack whose top [handleBack] would take away with the default pop, which a back gesture previews; none when
+     * back would do anything else (hold, close a menu or a pane, a pop of its own) or nothing.
+     */
+    internal open fun stackPoppedByBack(): StackController? = null
+
     /** Starts the node's content (a native screen's view, a React screen's surface). */
     open fun start() = Unit