@apexnative/navigation 1.0.0-alpha.0 → 1.0.0-alpha.10

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) }
@@ -463,8 +488,8 @@ internal class RootCoordinator(
     }
 
     // The navigation state goes once, when the root is in place and its layers have shown, right before the answer:
-    // what the old root's destroy, the root's appearance and each layer ask for meanwhile waits (StateHold). Taken once
-    // per `setRoot`, before the old root goes.
+    // what the old root's destroy, the root's appearance and each layer ask for meanwhile waits (the hold of
+    // NavigationState). Taken once per `setRoot`, before the old root goes.
     private fun holdState(pending: Pending) {
         if (pending.holdsState) return
         pending.holdsState = true
@@ -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
@@ -128,12 +129,9 @@ abstract class ParentController<V : ViewGroup>(
     open fun leavesTopEdgeFree(child: ViewController<*>): Boolean =
         parentController?.leavesTopEdgeFree(this) ?: false
 
-    /**
-     * Whether the safe area of [child] leaves its bottom edge free by default: the tabs show with
-     * `bottomTabs.hideOnScroll` of [screen], the screen that asks.
-     */
-    open fun leavesBottomEdgeFree(child: ViewController<*>, screen: ViewController<*> = child): Boolean =
-        parentController?.leavesBottomEdgeFree(this, screen) ?: false
+    /** Whether a large title shows over [child]: its stack shows the bar with one. No by default. */
+    open fun showsLargeTitleOver(child: ViewController<*>): Boolean =
+        parentController?.showsLargeTitleOver(this) ?: false
 
     /**
      * The tab bar at rest under [child]: where a stack's FAB keeps clear of it, by the options of [screen], the stack's
@@ -210,6 +208,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
@@ -28,7 +29,8 @@ import dev.apexnative.navigation.views.sidemenu.SideMenuView
  * - The current child is the open menu's node, else the center ([SideMenuMotion.openSide]: from the end of the
  *  opening to the end of the closing); the state, the options and back follow it.
  * - The center and the open menu show with the side menu ([visibleChildren]); a wait for the side menu to render
- *   waits for the center ([waitedChildren]); the menus' views are made with the side menu's.
+ *   waits for the center ([waitedChildren]); the menus' views join the drawer as `sideMenu.menusAttachMode` says
+ *   ([attached]): with the side menu's view, once it first appeared, or each as it first starts to show.
  * - Its options ([SideMenuPresenter]): from the resolution of [resolveShownOptions] at creation, at every appearance
  *   of a screen inside, and for the fields a merge names; `sideMenu.<side>.visible` acts once, from a merge or from the
  *  layout at the first show. What goes on up goes without `sideMenu`: the nearest side menu acts.
@@ -63,6 +65,12 @@ internal class SideMenuController(
     // From the end of its appearance's start until it disappears: the drawer's motion tells the menu screens then.
     private var appeared = false
     private var firstShown = false
+    private var firstAppeared = false
+
+    private val attachMode = SideMenuRules.attachModeOf(initialOptions.sideMenu, DefaultOptions.current.sideMenu)
+
+    /** The menus whose nodes' views are in the drawer, or join it as it is made. */
+    internal val attached = HashSet<Side>(2)
     // Its children go first as it is destroyed: nothing reacts to them, nor to the drawer, from the start.
     private var destroying = false
 
@@ -71,6 +79,7 @@ internal class SideMenuController(
 
     init {
         getChildControllers().forEach { it.parentController = this }
+        SideMenuRules.attachedAtCreation(attachMode).filter { childOf(it) != null }.forEach { attached += it }
     }
 
     override fun getChildControllers(): List<ViewController<*>> = listOfNotNull(center, left, right)
@@ -87,13 +96,16 @@ internal class SideMenuController(
 
     private fun childOf(side: Side): ViewController<*>? = if (side == Side.Left) left else right
 
-    // The drawer and its parts, each node's view in its part; the creation's options. An open menu recorded before the
-    // view existed is open in it from the start; the drawer is silent before its first layout.
+    // The drawer and its parts, the view of each node attached so far in its part; the creation's options. An open menu
+    // recorded before the view existed is open in it from the start; the drawer is silent before its first layout.
     override fun createView(): SideMenuView {
         val view = SideMenuView(activity)
         view.setCenter(center.view)
-        left?.let { view.addPart(Side.Left, it.view) }
-        right?.let { view.addPart(Side.Right, it.view) }
+        for (side in Side.entries) {
+            val child = childOf(side) ?: continue
+            view.addPart(side)
+            if (side in attached) view.fillPart(side, child.view)
+        }
         menus.applyOnCreation(view, resolveShownOptions(DefaultOptions.current))
         motion.openSide?.let { view.open(it, false) }
         view.follow(motion)
@@ -130,7 +142,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) }
     }
@@ -171,6 +183,14 @@ internal class SideMenuController(
         motion.containerAppeared()
     }
 
+    // `afterCenter`: the menus join once the side menu first appeared with its center.
+    override fun onViewDidAppear() {
+        super.onViewDidAppear()
+        if (firstAppeared || destroying || isDestroyed) return
+        firstAppeared = true
+        SideMenuRules.attachedAfterAppearance(attachMode).forEach(::attach)
+    }
+
     override fun onViewDisappear() {
         appeared = false
         motion.containerDisappeared()
@@ -183,6 +203,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)
 
@@ -218,6 +241,16 @@ internal class SideMenuController(
         if (child === currentChild) super.tabBarSettled(child)
     }
 
+    // The view of the menu on [side] joins its part, once, before its screens hear that they appear: a stack lays out
+    // its bar as it appears in the window. The drawer's first movement may come while it draws (a peek settles in
+    // `computeScroll`, before the drawer draws its children): the view joins the part then, measured and laid out at the
+    // next frame.
+    private fun attach(side: Side) {
+        val child = childOf(side) ?: return
+        if (destroying || isDestroyed || !attached.add(side)) return
+        peekView()?.fillPart(side, child.view)
+    }
+
     /** Destroys the side menu once: the drawer's callbacks stop first, then the children go. */
     override fun destroy() {
         if (isDestroyed) return
@@ -234,6 +267,8 @@ internal class SideMenuController(
 
         override fun child(side: Side): ViewController<*>? = childOf(side)
 
+        override fun starts(side: Side) = attach(side)
+
         override fun isEnabled(side: Side): Boolean =
             SideMenuRules.isEnabled(resolveShownOptions(DefaultOptions.current).sideMenu, side)
 
@@ -255,9 +290,7 @@ internal class SideMenuController(
         }
 
         // The system UI follows the screen the user sees now, at rest: the open menu's, the center's once a close
-        // ends. The owner reads it before the next frame, when a menu that closed is hidden already. An open without
-        // animation runs this inside `AppearanceDispatcher.withoutWillAppear`: what starts to appear from here would
-        // send no WillAppear.
+        // ends. The owner reads it before the next frame, when a menu that closed is hidden already.
         override fun shownChanged() {
             navigator?.shownScreensChanged(this@SideMenuController)
             navigator?.systemUi?.invalidate()

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

@@ -1,6 +1,7 @@
 package dev.apexnative.navigation.viewcontrollers.sidemenu
 
 import dev.apexnative.navigation.react.events.AppearanceDispatcher
+import dev.apexnative.navigation.utils.SystemAnimations
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 
 /**
@@ -16,8 +17,8 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
  *   the drawer calls `onDrawerClosed` only for a drawer that had opened.
  * - The menu screen's events: WillAppear at the side's first movement, DidAppear when it opened, DidDisappear when it
  *   rests closed; only while the side menu has appeared ([Host.appeared]) — otherwise they come with the side menu's
- *   own appearance (its visible children). An open without animation sends DidAppear without WillAppear
- *  (`AppearanceDispatcher.withoutWillAppear`).
+ *   own appearance (its visible children). An open without animation sends both too, WillAppear first, as on iOS:
+ *   the drawer jumps to its open offset before it calls the open.
  * - At each rest: one state update after the menu's events, the back callback, and the layers that follow the shown
  *  screen.
  * - A drawer that doesn't call back (not laid out since it joined the window, or not in one: `DrawerLayout` only
@@ -26,6 +27,8 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 internal class SideMenuMotion(
     private val drawer: () -> Drawer,
     private val host: Host,
+    /** The system's animations are off ([SystemAnimations]): a command or back moves the drawer at once. */
+    private val animationsOff: () -> Boolean = { SystemAnimations.areOff() },
 ) {
     /** A side of the side menu: physical, `left` stays on the left in RTL too. */
     enum class Side(
@@ -79,6 +82,12 @@ internal class SideMenuMotion(
         /** `sideMenu.<side>.enabled` of the side menu's options now. */
         fun isEnabled(side: Side): Boolean
 
+        /**
+         * The menu on [side] starts to show: the drawer's first movement, or a command that opens it. Before its
+         * screen hears that it appears.
+         */
+        fun starts(side: Side)
+
         /** `visible: true` for a side the layout doesn't have: a warning, nothing else. */
         fun missingSide(side: Side)
 
@@ -119,6 +128,7 @@ internal class SideMenuMotion(
     fun slid(side: Side, offset: Float) {
         // Not more than 0 also takes a NaN: `DrawerLayout` divides by the drawer's width, which may be 0.
         if (destroyed || !(offset > 0f)) return
+        if (!isOnScreen(side)) host.starts(side)
         onScreen += side
         if (side in appearing || !host.appeared) return
         appearing += side
@@ -204,6 +214,7 @@ internal class SideMenuMotion(
         }
         // Never decided by where the other menu is: a side asked to open in the same merge hasn't moved yet.
         if (drawer.has(side.other)) move(side.other, open = false, animate = animated)
+        if (!isOnScreen(side)) host.starts(side)
         onScreen += side
         // A locked menu opened from code can be dragged closed while it is open.
         drawer.lock(side, locked = false)
@@ -242,15 +253,15 @@ internal class SideMenuMotion(
         drawer.lock(side, locked = !isOnScreen(side) && !host.isEnabled(side))
     }
 
-    // The drawer opens or closes [side]; one that doesn't call back has its result recorded here.
+    // The drawer opens or closes [side]; one that doesn't call back has its result recorded here. With the system's
+    // animations off it jumps, unless it moves: the drag and the settle aren't animators, and it can't jump while it
+    // settles.
     private fun move(side: Side, open: Boolean, animate: Boolean) {
         val drawer = drawer()
+        val animated = animate && (moving || !animationsOff())
         val silent = !drawer.callsBack
-        val run = {
-            if (open) drawer.open(side, animate) else drawer.close(side, animate)
-            if (silent) record(side, open)
-        }
-        if (open && !animate && host.appeared) AppearanceDispatcher.withoutWillAppear(run) else run()
+        if (open) drawer.open(side, animated) else drawer.close(side, animated)
+        if (silent) record(side, open)
     }
 
     private fun record(side: Side, open: Boolean) {

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

@@ -18,15 +18,14 @@ import dev.apexnative.navigation.views.sidemenu.SideMenuView
  * `testID`s. Each moment applies its part, from the side menu's resolved options
  * (`SideMenuController.resolveShownOptions`: the current part's chain, the center's `sideMenu` over an open menu's) —
  * at creation everything with the heights, at every appearance of a screen inside everything but the heights, at a
- * merge the fields it names, at a repaint the background and the `testID`s. The locks of `enabled` and the command
+ * merge the fields it names (a width or a height at once, an open menu too), at a repaint the background and the
+ * `testID`s. The locks of `enabled` and the command
  * `visible` are the node's ([SideMenuMotion]). Main thread only.
  */
 internal class SideMenuPresenter(activity: Activity) : Presenter(activity, Options()) {
-    /** The side menu's [view] is made, with [options], resolved: the heights, read only now. */
+    /** The side menu's [view] is made, with [options], resolved: the heights too, which only a merge changes after. */
     fun applyOnCreation(view: SideMenuView, options: Options) {
-        for (side in Side.entries) {
-            view.setPartHeight(side, SideMenuRules.height(SideMenuRules.sideOf(options.sideMenu, side), ::toPixels))
-        }
+        applyHeights(view, options.sideMenu)
         applyWidths(view, options.sideMenu)
         applyBackground(view, options)
         applyTestIds(view, options.sideMenu)
@@ -46,14 +45,18 @@ internal class SideMenuPresenter(activity: Activity) : Presenter(activity, Optio
     /**
      * A merge reached the side menu, its own or through a screen inside (`mergeOptions` step 3): the fields [options]
      * name, with the values of the side menu's resolution now, so a screen off what shows changes nothing until it
-     * appears. A width waits for the next appearance, a height for nothing.
+     * appears. A width or a height resizes its menu at once, open or closed, as on iOS.
      */
     override fun mergeOptions(viewController: ViewController<*>, options: Options) {
         val layout = viewController.peekView() as? SideMenuView ?: return
         val touchesBackground = SideMenuRules.touchesBackground(options)
         val touchesTestIds = SideMenuRules.touchesTestIds(options.sideMenu)
-        if (!touchesBackground && !touchesTestIds) return
+        val touchesWidths = SideMenuRules.touchesWidths(options.sideMenu)
+        val touchesHeights = SideMenuRules.touchesHeights(options.sideMenu)
+        if (!touchesBackground && !touchesTestIds && !touchesWidths && !touchesHeights) return
         val shown = viewController.resolveShownOptions(DefaultOptions.current)
+        if (touchesWidths) applyWidths(layout, shown.sideMenu)
+        if (touchesHeights) applyHeights(layout, shown.sideMenu)
         if (touchesBackground) applyBackground(layout, shown)
         if (touchesTestIds) applyTestIds(layout, shown.sideMenu)
     }
@@ -71,6 +74,12 @@ internal class SideMenuPresenter(activity: Activity) : Presenter(activity, Optio
         }
     }
 
+    private fun applyHeights(view: SideMenuView, options: SideMenuOptions) {
+        for (side in Side.entries) {
+            view.setPartHeight(side, SideMenuRules.height(SideMenuRules.sideOf(options, side), ::toPixels))
+        }
+    }
+
     // `layout.backgroundColor` on the drawer, its whole height, under the status bar; unset leaves the view as it is,
     // `'NoColor'` clears it.
     private fun applyBackground(view: View, options: Options) {

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

@@ -11,11 +11,23 @@ import kotlin.math.min
 
 /**
  * What the options of a side menu do on Android (`sideMenu.*`), without views: the values of each moment, `visible` as
- * a command, the sizes, the `testID`s. Android reads `enabled`, `width`, `height`, `visible`, `animate` and the
- * `testID`s of `sideMenu`; `openGestureMode`, `animationType`, `openMode`, `shouldStretchDrawer`, `animationVelocity`
- * and `glass` are iOS's.
+ * a command, the sizes, the `testID`s, when the menus join the drawer. Android reads `enabled`, `width`, `height`,
+ * `visible`, `animate`, `menusAttachMode` and the `testID`s of `sideMenu`; `openGestureMode`, `animationType`,
+ * `openMode`, `shouldStretchDrawer`, `animationVelocity` and `glass` are iOS's.
  */
 internal object SideMenuRules {
+    /** When the views of the menus' nodes join the drawer (`sideMenu.menusAttachMode`): their content renders then. */
+    enum class AttachMode {
+        /** With the side menu's view. */
+        Together,
+
+        /** Once the side menu first appeared, with its center. */
+        AfterCenter,
+
+        /** Each as it first starts to show: the drawer's first movement, or a command that opens it. */
+        OnOpen,
+    }
+
     /** A side's `visible` of one merge: open or close it, with its `animate`. */
     data class Command(val side: Side, val visible: Boolean, val animate: Boolean)
 
@@ -43,6 +55,26 @@ internal object SideMenuRules {
      */
     fun firstShow(layout: SideMenuOptions): List<Side> = Side.entries.filter { sideOf(layout, it).visible.isTrue }
 
+    /**
+     * The mode of `sideMenu.menusAttachMode`: the side menu's [own] options, else the [defaults]; `together` without
+     * either. Read once, as the side menu is made.
+     */
+    fun attachModeOf(own: SideMenuOptions, defaults: SideMenuOptions): AttachMode {
+        val value = own.menusAttachMode.takeIf { it.hasValue() } ?: defaults.menusAttachMode
+        return when (value.get(null)) {
+            "afterCenter" -> AttachMode.AfterCenter
+            "onOpen" -> AttachMode.OnOpen
+            else -> AttachMode.Together
+        }
+    }
+
+    /** The menus that join as the side menu is made: both with `together`. */
+    fun attachedAtCreation(mode: AttachMode): List<Side> = if (mode == AttachMode.Together) Side.entries else emptyList()
+
+    /** The menus that join once the side menu first appeared: both with `afterCenter`. */
+    fun attachedAfterAppearance(mode: AttachMode): List<Side> =
+        if (mode == AttachMode.AfterCenter) Side.entries else emptyList()
+
     /** `enabled` of [side]: true unless `false`, from the side menu's resolved options. */
     fun isEnabled(options: SideMenuOptions, side: Side): Boolean = !sideOf(options, side).enabled.isFalse
 
@@ -54,6 +86,13 @@ internal object SideMenuRules {
     fun touchesTestIds(merge: SideMenuOptions): Boolean =
         merge.testID.hasValue() || merge.left.testID.hasValue() || merge.right.testID.hasValue()
 
+    /** A merge names `width` of a side: the menus take their widths again. */
+    fun touchesWidths(merge: SideMenuOptions): Boolean = merge.left.width.hasValue() || merge.right.width.hasValue()
+
+    /** A merge names `height` of a side: the menus take their heights again. */
+    fun touchesHeights(merge: SideMenuOptions): Boolean =
+        merge.left.height.hasValue() || merge.right.height.hasValue()
+
     /** A merge names the background of the side menu (`layout.backgroundColor`). */
     fun touchesBackground(merge: Options): Boolean = merge.layout.backgroundColor.hasValue()
 
@@ -64,7 +103,7 @@ internal object SideMenuRules {
     fun wantedWidth(options: SideMenuSideOptions, toPixels: (Double) -> Int): Int? =
         options.width.get(null)?.let { max(0, toPixels(it)) }
 
-    /** The height of a side, in pixels: `height` (dp) by [toPixels], read at creation only; none: the whole height. */
+    /** The height of a side, in pixels: `height` (dp) by [toPixels]; none: the whole height. */
     fun height(options: SideMenuSideOptions, toPixels: (Double) -> Int): Int? =
         options.height.get(null)?.let { max(0, toPixels(it)) }
 

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)