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

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalSheet.kt

@@ -29,11 +29,12 @@ import dev.apexnative.navigation.utils.dp
 import kotlin.math.roundToInt
 
 /**
- * A modal shown as a Material bottom sheet (`modal.sheet`): the modal's view in a container with a
- * [BottomSheetBehavior], in the modals' CoordinatorLayout, over a scrim. It stops at the detents of its options —
- * `medium` at half the height, `large` at the full height under the status bar, a number at that height in dp — and the
- * user drags it between them. A drag down past the smallest one closes it, unless `swipeToDismiss` is false: then the
- * sheet stays, and the try is told. The screen under it stays in place.
+ * A modal shown as a Material bottom sheet (`pageSheet`, `formSheet`, `popover`, or `modal.sheet` without a style): the
+ * modal's view in a container with a [BottomSheetBehavior], in the modals' CoordinatorLayout, over a scrim. It stops at
+ * the detents of its options — `medium` at half the height, `large` at the full height under the status bar, a number
+ * at that height in dp — and the user drags it between them. In a window wider than [MAX_WIDTH_DP] it stands in the
+ * middle at that width. A drag down past the smallest one closes it, unless `swipeToDismiss` is false: then the sheet
+ * stays, and the try is told. The screen under it stays in place.
  */
 internal class ModalSheet(
     private val layout: CoordinatorLayout,
@@ -96,11 +97,19 @@ internal class ModalSheet(
                 outline.setRoundRect(0, 0, view.width, view.height + radius.roundToInt(), radius)
             }
         }
-        // The sheet is under the status bar: its screens leave no room for it at their top.
+        // The sheet is under the status bar: its screens leave no room for it at their top. In the middle of a wide
+        // window it reaches no side, and keeps room only for the part of a side bar that is over it.
         ViewCompat.setOnApplyWindowInsetsListener(container) { _, insets ->
             val types = WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout()
             val bars = insets.getInsets(types)
-            WindowInsetsCompat.Builder(insets).setInsets(types, Insets.of(bars.left, 0, bars.right, bars.bottom)).build()
+            val laidOut = container.width > 0
+            val left = if (laidOut) (bars.left - container.left).coerceAtLeast(0) else bars.left
+            val right = if (laidOut) (bars.right - (layout.width - container.right)).coerceAtLeast(0) else bars.right
+            WindowInsetsCompat.Builder(insets).setInsets(types, Insets.of(left, 0, right, bars.bottom)).build()
+        }
+        // Its sides move with the window's width (a rotation, a resize): the room for the side bars follows.
+        container.addOnLayoutChangeListener { _, left, _, right, _, oldLeft, _, oldRight, _ ->
+            if (left != oldLeft || right != oldRight) container.post { ViewCompat.requestApplyInsets(container) }
         }
         container.addView(content, FrameLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT))
         container.addView(grabber, FrameLayout.LayoutParams(WRAP_CONTENT, WRAP_CONTENT, Gravity.TOP or Gravity.CENTER_HORIZONTAL))
@@ -120,7 +129,12 @@ internal class ModalSheet(
         layout.addView(scrim, CoordinatorLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT))
         // As tall as its largest detent (maxHeight), not moved down by a margin: the behavior counts its states from
         // where the sheet is laid out.
-        layout.addView(container, CoordinatorLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT).also { it.behavior = behavior })
+        // In a wide window it stands in the middle, as wide as a Material modal sheet at most.
+        behavior.maxWidth = MAX_WIDTH_DP.dp
+        val params = CoordinatorLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT)
+        params.gravity = Gravity.TOP or Gravity.CENTER_HORIZONTAL
+        params.behavior = behavior
+        layout.addView(container, params)
         shown = onShown
         update(sheetOptions, swipeToDismiss, merge = null)
         selected = sheetOptions.selectedDetent?.takeIf { it in detents }
@@ -334,10 +348,13 @@ internal class ModalSheet(
         }
     }
 
-    private companion object {
+    companion object {
+        /** The widest a sheet is, in dp: the Material modal bottom sheet's `maxWidth`. */
+        const val MAX_WIDTH_DP = 640
+
         /** The dim of a Material modal bottom sheet's scrim. */
-        const val SCRIM_ALPHA = 0.32f
-        const val GRAB_AREA_DP = 48
-        const val ATTEMPT_DISTANCE_DP = 48
+        private const val SCRIM_ALPHA = 0.32f
+        private const val GRAB_AREA_DP = 48
+        private const val ATTEMPT_DISTANCE_DP = 48
     }
 }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalViews.kt

@@ -4,9 +4,9 @@ import android.animation.Animator
 import android.animation.AnimatorListenerAdapter
 import android.animation.AnimatorSet
 import android.animation.ObjectAnimator
-import android.animation.PropertyValuesHolder
 import android.animation.TimeInterpolator
 import android.content.Context
+import android.view.Gravity
 import android.view.View
 import android.view.ViewGroup
 import android.view.animation.LinearInterpolator
@@ -17,6 +17,7 @@ import androidx.core.view.WindowInsetsCompat
 import dev.apexnative.navigation.options.ModalAnimationOptions
 import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.utils.TestIds
+import dev.apexnative.navigation.utils.dp
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
@@ -62,9 +63,15 @@ internal class ModalViews(
         try {
             val view = record.root.view
             (view.parent as? ViewGroup)?.removeView(view)
-            // A sheet's content waits at the sheet's full height, under the status bar.
+            // A sheet's content waits at the sheet's full height, under the status bar, and at its width.
             val params = CoordinatorLayout.LayoutParams(MATCH, MATCH)
-            if (record.isSheet) params.topMargin = statusBarTop()
+            if (record.isSheet) {
+                params.topMargin = statusBarTop()
+                params.gravity = Gravity.CENTER_HORIZONTAL
+                // The modals layer is hidden while it has no modal: the window's content gives the width.
+                val maxWidth = ModalSheet.MAX_WIDTH_DP.dp
+                if (((modalsLayer.parent as? View)?.width ?: 0) > maxWidth) params.width = maxWidth
+            }
             container.addView(view, params)
             modalsLayer.addView(container, FrameLayout.LayoutParams(MATCH, MATCH))
         } catch (e: Throwable) {
@@ -100,14 +107,13 @@ internal class ModalViews(
             container.translationY = 0f
             return playOwn(record, parts, motion, showing = true, onEnd)
         }
+        // The system's slide over the window below: the modal comes up whole, without a fade.
         val distance = distanceOf(container)
-        val animator = ObjectAnimator.ofPropertyValuesHolder(
-            container,
-            PropertyValuesHolder.ofFloat(View.TRANSLATION_Y, distance, 0f),
-            PropertyValuesHolder.ofFloat(View.ALPHA, 0f, 1f),
-        )
-        animator.interpolator = TimeInterpolator { ModalAnimations.decelerate(it) }
-        return play(parts, animator, onEnd)
+        container.alpha = 1f
+        container.translationY = distance
+        val animator = ObjectAnimator.ofFloat(container, View.TRANSLATION_Y, distance, 0f)
+        animator.interpolator = TimeInterpolator { ModalAnimations.linearOutSlowIn(it) }
+        return play(parts, animator, ModalAnimations.SHOW_DURATION, onEnd)
     }
 
     // The root's view leaves the container and goes into the sheet's, in one turn; the sheet slides to its first
@@ -163,13 +169,11 @@ internal class ModalViews(
         if (!animated || !seen) return none(onEnd)
         if (motion != null) return playOwn(record, parts, motion, showing = false, onEnd)
         val container = parts.container
-        val animator = ObjectAnimator.ofPropertyValuesHolder(
-            container,
-            PropertyValuesHolder.ofFloat(View.TRANSLATION_Y, container.translationY, distanceOf(container)),
-            PropertyValuesHolder.ofFloat(View.ALPHA, container.alpha, 0f),
+        val animator = ObjectAnimator.ofFloat(
+            container, View.TRANSLATION_Y, container.translationY, distanceOf(container),
         )
-        animator.interpolator = TimeInterpolator { ModalAnimations.accelerateDecelerate(it) }
-        return play(parts, animator, onEnd)
+        animator.interpolator = TimeInterpolator { ModalAnimations.accelerate(it) }
+        return play(parts, animator, ModalAnimations.DISMISS_DURATION, onEnd)
     }
 
     override fun awaitTargets(
@@ -355,8 +359,8 @@ internal class ModalViews(
     private fun viewOf(node: ViewController<*>): View? =
         parts.entries.firstOrNull { it.key.root === node }?.value?.container ?: node.peekView()
 
-    private fun play(parts: Parts, animator: Animator, onEnd: () -> Unit): () -> Unit {
-        animator.duration = ModalAnimations.DURATION
+    private fun play(parts: Parts, animator: Animator, duration: Long, onEnd: () -> Unit): () -> Unit {
+        animator.duration = duration
         animator.addListener(object : AnimatorListenerAdapter() {
             override fun onAnimationEnd(animation: Animator) {
                 if (parts.animator === animation) parts.animator = null

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/navigator/BackCallbackState.kt

@@ -41,6 +41,10 @@ internal object BackCallbackState {
         entries.removeAll { it.navigator.get().let { attached -> attached == null || attached === navigator } }
     }
 
+    /** JavaScript listens to back (`BackHandler`): it hears a press before the navigation does. */
+    val hasJsListeners: Boolean
+        get() = jsListeners
+
     /** `setBackListeners` of JavaScript; false again when its JavaScript goes. */
     fun setJsListeners(active: Boolean) {
         jsListeners = active

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/navigator/Navigator.kt

@@ -31,6 +31,7 @@ import dev.apexnative.navigation.viewcontrollers.component.ContentReadiness
 import dev.apexnative.navigation.viewcontrollers.component.ScreenReadiness
 import dev.apexnative.navigation.viewcontrollers.externalcomponent.ExternalComponentViewController
 import dev.apexnative.navigation.viewcontrollers.modal.ModalCoordinator
+import dev.apexnative.navigation.viewcontrollers.modal.ModalRecord
 import dev.apexnative.navigation.viewcontrollers.modal.ModalViews
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayCoordinator
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayRecord
@@ -38,6 +39,7 @@ import dev.apexnative.navigation.viewcontrollers.overlay.OverlayViews
 import dev.apexnative.navigation.viewcontrollers.parent.ParentController
 import dev.apexnative.navigation.viewcontrollers.stack.PreparedPushes
 import dev.apexnative.navigation.viewcontrollers.stack.StackCommands
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.stack.topbar.BarComponents
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.animations.FadeThrough
@@ -153,6 +155,15 @@ class Navigator(
     fun handleBack(listener: CommandListener): Boolean =
         modals.handleBack(listener) ?: (root?.handleBack(listener) == true)
 
+    /**
+     * The stack whose top [handleBack] would take away with the default pop: in the top modal, else in the root; none
+     * when back would do anything else.
+     */
+    internal fun stackPoppedByBack(): StackController? {
+        val modalRoot = modals.backTargetRoot()
+        return if (modalRoot != null) modalRoot.stackPoppedByBack() else root?.stackPoppedByBack()
+    }
+
     /**
      * [layer] may wait to show from now on ([WaitingLayer]): the nodes in it ask it through [isInWaitingLayer] and
      * [shownScreensChanged]. The root's layer is there from the start.
@@ -264,9 +275,7 @@ class Navigator(
         if (!made) return answer.reject(ErrorTexts.notDoneYet("setRoot"))
         val steps = layout.modals.mapIndexed { index, node ->
             val last = index == layout.modals.lastIndex
-            RootCoordinator.LayerStep { done ->
-                modals.showInChain(node.id, { makeLayer(node, isOverlay = false) }, last, done)
-            }
+            ModalLayerStep(node, last)
         } + layout.overlays.map { node ->
             RootCoordinator.LayerStep { done ->
                 overlays.showInChain(node.id, { makeLayer(node, isOverlay = true) }, done)
@@ -275,6 +284,35 @@ class Navigator(
         roots.setRoot({ factory.create(layout.root) }, answer, steps)
     }
 
+    // A modal of a `setRoot`'s layout: made with the root and held until its turn, so it renders while the root waits
+    // and comes in; made in its turn instead while an id of it still shows (a modal of the old root with that id goes
+    // with the old root). A modal that couldn't be made is skipped in its turn.
+    private inner class ModalLayerStep(private val node: LayoutNode, private val animated: Boolean) :
+        RootCoordinator.LayerStep {
+        private var prepared = false
+        private var held: ModalRecord? = null
+
+        override fun prepare() {
+            if (LayoutChecks.firstShownId(listOf(node), ::isShownNow) { false } != null) return
+            prepared = true
+            held = modals.hold(node.id, { factory.create(node) }, animated)
+        }
+
+        override fun discard() {
+            held?.let(modals::drop)
+            held = null
+        }
+
+        override fun show(done: () -> Unit): () -> Unit {
+            val record = held
+            held = null
+            if (record != null) return modals.release(record, done)
+            if (!prepared) return modals.showInChain(node.id, { makeLayer(node, isOverlay = false) }, animated, done)
+            done()
+            return {}
+        }
+    }
+
     // A modal or an overlay of a `setRoot`'s layout, made as its turn comes: an id that shows by then fails it.
     private fun makeLayer(node: LayoutNode, isOverlay: Boolean): ViewController<*> {
         val shown = LayoutChecks.firstShownId(listOf(node), ::isShownNow) { isOverlay && isReplacedOverlay(node, it) }
@@ -401,9 +439,10 @@ class Navigator(
     }
 
     /**
-     * The activity is destroyed: every layer goes, with the events of a destroy; a `setRoot` on its way resolves with
-     * `''` (JavaScript sets its root again in the next activity), a modal's or an overlay's show and the commands that
-     * wait for a modal with their roots' ids. Main thread only.
+     * The activity is destroyed: every layer goes, with the events of a destroy; a `setRoot` whose root still waited
+     * resolves with `''` (JavaScript sets its root again in the next activity), one whose root showed resolves with
+     * its id, and a modal's or an overlay's show and the commands that wait for a modal resolve with their roots' ids.
+     * Main thread only.
      */
     internal fun destroyWithActivity() {
         destroyLayers(answerPending = true)

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/navigator/RootCoordinator.kt

@@ -36,7 +36,8 @@ import dev.apexnative.navigation.views.animations.AnimationRules
  * The modals over the old root ([ModalsOverRoot]): taken as the `setRoot` is accepted (commands don't find them), given
  * back when it ends without replacing the root, carried with the old root into its transition and destroyed with it,
  * without `ANN.ModalDismissed`. The modals and the overlays of the layout ([LayerStep]) show after the root, one by
- * one, before the answer: a newer `setRoot` stops them.
+ * one, before the answer: a newer `setRoot` stops them. Its modals are made with the root ([LayerStep.prepare]) and
+ * render unseen while it waits and comes in, so each shows in its turn without a wait of its own.
  *
  * The steps that come later (the wait's timers and readiness signals, the end of the transition, the end of a layer,
  * a stack of the waiting root that changed its top) run under no runner: each goes through one guard, and a failure
@@ -128,11 +129,20 @@ internal class RootCoordinator(
     }
 
     /**
-     * A modal or an overlay of the layout of a `setRoot`, shown after its root: [show] makes it and shows it, and calls
-     * its argument once it showed or went (a failure is logged and skipped); what it returns stops it while it waits —
-     * a newer `setRoot`: it goes without a word.
+     * A modal or an overlay of the layout of a `setRoot`, shown after its root: [show] shows it (made then, unless
+     * [prepare] made it), and calls its argument once it showed or went (a failure is logged and skipped); what it
+     * returns stops it while it waits — a newer `setRoot`: it goes without a word.
      */
     fun interface LayerStep {
+        /**
+         * Right after the root is placed, before its wait: a step may make its layer now, so that it renders unseen
+         * while the root waits and comes in, and shows without a wait of its own in its turn.
+         */
+        fun prepare() = Unit
+
+        /** The `setRoot` ended before this step's turn: what [prepare] made goes without a word. */
+        fun discard() = Unit
+
         fun show(done: () -> Unit): () -> Unit
     }
 
@@ -221,6 +231,7 @@ internal class RootCoordinator(
             modals.rootAccepted()
             val waitForRender = animationsOf(root).enter.waitForRender
             this.pending = pending
+            layers.forEach { it.prepare() }
             firstRoot.rootSet(waitForRender)
             await(pending, waitForRender)
         }
@@ -229,8 +240,9 @@ internal class RootCoordinator(
     /**
      * The activity's layers go: the `setRoot` on its way ends, then the root it replaced, the current root and its root
      * are destroyed, as at any destroy (their events reach only their own JavaScript). [answerPending]: the activity
-     * went, the waiting `setRoot` resolves with `''` (JavaScript sets the root again in the next activity); otherwise
-     * (a reload) it gets no answer.
+     * went; a `setRoot` whose root still waited resolves with `''` (JavaScript sets the root again in the next
+     * activity), one whose root showed (its transition ran, or the modals and overlays of its layout were showing)
+     * resolves with the root's id. Otherwise (a reload) it gets no answer.
      */
     fun destroyAll(answerPending: Boolean) {
         val pending = pending
@@ -245,7 +257,9 @@ internal class RootCoordinator(
         modals.replacedRootGone()
         pending?.let(::releaseState)
         if (pending != null && pending.phase == Phase.Waiting) firstRoot.rootDestroyed()
-        if (answerPending) pending?.answer?.resolve("")
+        if (!answerPending || pending == null) return
+        // An empty id tells JavaScript the root didn't show: its start waits for the next activity and sets it there.
+        pending.answer.resolve(if (pending.phase == Phase.Waiting) "" else pending.root.id)
     }
 
     // Waits for the screens that show when the root shows, then runs its transition. Without `waitForRender` one limit
@@ -367,6 +381,14 @@ internal class RootCoordinator(
         if (!done) pending.stopLayer = stop
     }
 
+    // The layers of [pending] not shown yet go: what they made ahead goes unseen, the others aren't made. Each on its
+    // own: one that fails doesn't keep the others.
+    private fun discardLayers(pending: Pending) {
+        val rest = pending.layers.drop(pending.nextLayer)
+        pending.nextLayer = pending.layers.size
+        rest.forEach { attempt { it.discard() } }
+    }
+
     // A new `setRoot` came while this one was on its way.
     private fun supersede() {
         val pending = pending ?: return
@@ -389,14 +411,15 @@ internal class RootCoordinator(
                 pending.replaced = null
                 modals.replacedRootGone()
             }
-            // Its root is the current root: the modal or the overlay that waits now goes without a word, the others
-            // aren't made; those shown stay over its root, and go with it when the new root replaces it.
+            // Its root is the current root: the modal or the overlay that waits now goes without a word, the others go
+            // unseen or aren't made; those shown stay over its root, and go with it when the new root replaces it.
             Phase.Layers -> {
                 pending.stopLayer?.invoke()
                 pending.stopLayer = null
                 releaseState(pending)
             }
         }
+        discardLayers(pending)
         pending.answer.reject(ErrorTexts.setRootReplaced(pending.root.id))
     }
 
@@ -426,6 +449,7 @@ internal class RootCoordinator(
         pending.wait = null
         when (pending.phase) {
             Phase.Waiting -> {
+                discardLayers(pending)
                 attempt { takeAway(pending.root) }
                 attempt { modals.rootKept() }
                 attempt { firstRoot.rootDestroyed() }
@@ -451,6 +475,7 @@ internal class RootCoordinator(
                 pending.stopLayer = null
             }
         }
+        discardLayers(pending)
         // A root that is up takes the splash away, as at its show.
         if (pending.phase != Phase.Waiting) attempt { onRootShown() }
         attempt { releaseState(pending) }
@@ -482,6 +507,7 @@ internal class RootCoordinator(
     // The root was destroyed while it waited, by something other than a newer `setRoot` or the activity going.
     private fun rootGone(pending: Pending) {
         this.pending = null
+        discardLayers(pending)
         releaseState(pending)
         layer.remove(pending.root)
         modals.rootKept()

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/overlay/OverlayCoordinator.kt

@@ -124,18 +124,18 @@ internal class OverlayCoordinator(
     }
 
     /**
-     * `dismissOverlay`: the overlays with the root id [componentId] go — one that waits is cancelled, one that shows
-     * goes with its events (both, when a replacement of a shown one waits) — and [answer] resolves with the id. An id
-     * no node has: `not shown`; a node that is no overlay's root (Android takes only the root's id): `not in an
-     * overlay`.
+     * `dismissOverlay`: the overlay [componentId] is in — its root or any screen inside it — goes with every overlay of
+     * the same root id: one that waits is cancelled, one that shows goes with its events (both, when a replacement of
+     * a shown one waits). [answer] resolves with the overlay's root id, as on iOS. An id no node has: `not shown`; a
+     * node in no overlay: `not in an overlay`.
      */
     fun dismiss(componentId: String, answer: CommandAnswer) {
-        if (host.find(componentId) == null) return answer.reject(ErrorTexts.screenNotShown(componentId))
-        val matches = records.filter { it.rootId == componentId }
-        if (matches.isEmpty()) return answer.reject(ErrorTexts.notInOverlay(componentId))
+        val node = host.find(componentId) ?: return answer.reject(ErrorTexts.screenNotShown(componentId))
+        val rootId = recordOf(node)?.rootId ?: return answer.reject(ErrorTexts.notInOverlay(componentId))
+        val matches = records.filter { it.rootId == rootId }
         matches.filter { it.state == OverlayRecord.State.Waiting }.forEach(::cancel)
         val shown = matches.filter { it.state == OverlayRecord.State.Shown }
-        if (shown.isEmpty()) return answer.resolve(componentId)
+        if (shown.isEmpty()) return answer.resolve(rootId)
         shown.dropLast(1).forEach { remove(it, null) }
         remove(shown.last(), answer)
     }
@@ -185,6 +185,8 @@ internal class OverlayCoordinator(
 
     private fun start(make: () -> ViewController<*>, answer: CommandAnswer?, chainDone: (() -> Unit)?): OverlayRecord {
         val root = make()
+        // Before the root's view is made: its screens are drawn under the status bar from their first layout.
+        root.shownAsOverlay = true
         val record = OverlayRecord(root)
         // A waiting layer before its views join the window: what is in it isn't on screen from its first layout.
         record.screensChanged = { screensChanged(record) }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/parent/Capabilities.kt

@@ -41,11 +41,18 @@ interface KeepsStatusBarRoom
 /** A node that shows screens in its columns (the split view): `showInColumn` and `setColumnShown` go to it. */
 interface ShowsColumns {
     /**
-     * Shows [screen] in the column after the first one, in place of what it shows; [listener] once it shows, or with
-     * the error reason, which names [from], the screen the command comes from. False when the node doesn't take it now
-     * (its compact layout shows): the core pushes the screen over [from] instead.
+     * Shows [screen] in [column], in place of what it shows; [listener] once it shows, or with the error reason, which
+     * names [from], the screen the command comes from. [goesInStack] says whether [screen]'s layout is what a stack
+     * takes (a screen, a native screen, a pair), not a container. False when the node doesn't take it now (its compact
+     * layout shows): the core pushes the screen over [from] instead.
      */
-    fun showScreen(screen: ViewController<*>, from: ViewController<*>, listener: CommandListener): Boolean
+    fun showScreen(
+        screen: ViewController<*>,
+        column: String,
+        goesInStack: Boolean,
+        from: ViewController<*>,
+        listener: CommandListener,
+    ): Boolean
 
     /** Shows or hides [column]; [done] once the columns have stopped moving. */
     fun setColumnShown(column: String, shown: Boolean, done: Runnable)

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/parent/ContainerBackground.kt

@@ -31,9 +31,9 @@ internal object ContainerBackground {
         if (!colour.hasValue()) return null
         val color = colour.get(node.activity, Color.TRANSPARENT) ?: Color.TRANSPARENT
         // The screens' band rule (`ScreenSafeArea.backgroundBand`) for a layout, which keeps no room at its top: the
-        // status bar's height, but none when it is hidden or the layout is drawn under it, in a side menu, a sheet or
-        // a pair.
-        val full = options.statusBar.isHiddenOrDrawBehind || node.isInSideMenu || node.isInSheet ||
+        // status bar's height, but none when it is hidden or the layout is drawn under it (in an overlay by default),
+        // in a side menu, a sheet or a pair.
+        val full = options.statusBar.isHiddenOrDrawBehind(node.isInOverlay) || node.isInSideMenu || node.isInSheet ||
             node.parentController is KeepsStatusBarRoom
         val band = if (full) 0 else SystemUiUtils.getStatusBarHeight(node.activity)
         if (band <= 0) return ColorDrawable(color)

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/parent/ParentController.kt

@@ -8,6 +8,7 @@ import dev.apexnative.navigation.react.CommandListener
 import dev.apexnative.navigation.viewcontrollers.bottomtabs.TabBarMotion
 import dev.apexnative.navigation.viewcontrollers.child.ChildController
 import dev.apexnative.navigation.viewcontrollers.child.ChildControllersRegistry
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.stack.fab.FabPlacement
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
@@ -210,6 +211,8 @@ abstract class ParentController<V : ViewGroup>(
 
     override fun canHandleBack(): Boolean = getCurrentChild()?.canHandleBack() == true
 
+    override fun stackPoppedByBack(): StackController? = getCurrentChild()?.stackPoppedByBack()
+
     override fun destroy() {
         if (isDestroyed) return
         getChildControllers().forEach { it.destroy() }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/sidemenu/SideMenuController.kt

@@ -16,6 +16,7 @@ import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.parent.ChildOffsetFromRest
 import dev.apexnative.navigation.viewcontrollers.parent.ParentController
 import dev.apexnative.navigation.viewcontrollers.sidemenu.SideMenuMotion.Side
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.sidemenu.SideMenuView
@@ -130,7 +131,7 @@ internal class SideMenuController(
 
     // `mergeOptions` with the side menu's id: its own options, then what a merge does, then the layouts around.
     override fun mergeOptions(options: Options) {
-        this.options = this.options.copy().mergeWith(options)
+        mergeOwnOptions(options)
         applyMerge(options)
         performOnParentController { it.mergeChildOptions(SideMenuRules.withoutSideMenu(options), this) }
     }
@@ -183,6 +184,9 @@ internal class SideMenuController(
 
     override fun canHandleBack(): Boolean = motion.canGoBack || center.canHandleBack()
 
+    // An open menu closes first: no preview of a pop then.
+    override fun stackPoppedByBack(): StackController? = if (motion.canGoBack) null else center.stackPoppedByBack()
+
     // A button's press addressed to the side menu goes to the center.
     override fun sendOnNavigationButtonPressed(buttonId: String) = center.sendOnNavigationButtonPressed(buttonId)
 

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/splitview/SplitPanes.kt

@@ -1,6 +1,8 @@
 package dev.apexnative.navigation.viewcontrollers.splitview
 
 import android.content.Context
+import android.view.View
+import android.view.ViewGroup
 import android.view.WindowInsets
 import androidx.core.graphics.Insets
 import androidx.core.view.WindowInsetsCompat
@@ -14,6 +16,27 @@ class SplitPanes(context: Context) : SlidingPaneLayout(context) {
     /** The panes are side by side. */
     var isSideBySide = false
 
+    /**
+     * Puts [next] in the place of the pane [old], with the structure and the params [old] had. The library wraps the
+     * second view it is given in a view of its own that holds back touches (`addView` with one child there), and its
+     * `removeView` takes that wrapper away: a plain remove and add would wrap a new primary pane, or give a new
+     * secondary one the wrapper's params, and lose its width and weight. So the secondary pane's content changes
+     * inside the wrapper, and a new primary pane goes in before the old one leaves, while two children are there.
+     */
+    internal fun replacePane(old: View, next: View) {
+        val holder = old.parent as? ViewGroup ?: return
+        val params = old.layoutParams
+        if (holder === this) {
+            // A copy: the width that `splitView.width` changes later is the new pane's own.
+            addView(next, indexOfChild(old), if (params is LayoutParams) LayoutParams(params) else params)
+            removeView(old)
+        } else {
+            val index = holder.indexOfChild(old)
+            holder.removeView(old)
+            holder.addView(next, index, params)
+        }
+    }
+
     override fun dispatchApplyWindowInsets(insets: WindowInsets): WindowInsets {
         if (!isSideBySide) return super.dispatchApplyWindowInsets(insets)
         val own = onApplyWindowInsets(insets)