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

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.
@@ -214,7 +225,7 @@ class Navigator(
      * it itself, `ComponentPresenter`); the system UI follows (only what changed is written).
      */
     internal fun optionsMerged(node: ViewController<*>, options: Options = Options()) {
-        modals.optionsMergedInto(node)
+        modals.optionsMergedInto(node, options)
         overlays.optionsMergedInto(node)
         val navigationBar = options.navigationBar
         val padding = navigationBar.drawBehind.hasValue() || navigationBar.backgroundColor.hasValue()
@@ -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) }

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)
         }
@@ -367,6 +378,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 +408,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 +446,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 +472,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 +504,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

@@ -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/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
@@ -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)
 
@@ -255,9 +259,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

@@ -16,8 +16,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
@@ -246,11 +246,8 @@ internal class SideMenuMotion(
     private fun move(side: Side, open: Boolean, animate: Boolean) {
         val drawer = drawer()
         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, animate) else drawer.close(side, animate)
+        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

@@ -54,6 +54,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 +71,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/SplitViewController.kt

@@ -26,11 +26,12 @@ 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.parent.ReturnsScreenFromColumn
-import dev.apexnative.navigation.viewcontrollers.parent.ShowsColumns
 import dev.apexnative.navigation.viewcontrollers.parent.ShownChildren
+import dev.apexnative.navigation.viewcontrollers.parent.ShowsColumns
 import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import kotlin.math.roundToInt
 
 /**
  * A split view: the primary pane beside the secondary one when the width takes both (a tablet, a phone in landscape).
@@ -365,6 +366,19 @@ class SplitViewController(
         return can || super.canHandleBack()
     }
 
+    // As handleBack: the pane whose back goes first decides; an open sliding pane that would close previews nothing.
+    override fun stackPoppedByBack(): StackController? {
+        if (!isViewCreated) return super.stackPoppedByBack()
+        val layout = getView()
+        return when {
+            layout.isCompact -> compact?.stackPoppedByBack()
+            isSliding && !layout.panes.isOpen -> primary.stackPoppedByBack()
+            isSliding -> if (secondary.canHandleBack()) secondary.stackPoppedByBack() else null
+            secondary.canHandleBack() -> secondary.stackPoppedByBack()
+            else -> primary.stackPoppedByBack()
+        }
+    }
+
     /**
      * How far the pane of [child] is from where it rests: the secondary pane sliding over the primary one rests over
      * it, closed or on its way. Zero for the other children.
@@ -489,7 +503,7 @@ class SplitViewController(
         root.mergeOptions(options)
     }
 
-    private fun dp(value: Double) = UiUtils.dpToPx(activity, value.toFloat()).toInt()
+    private fun dp(value: Double) = UiUtils.dpToPx(activity, value.toFloat()).roundToInt()
 
     companion object {
         private const val PRIMARY = "primary"