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

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
@@ -14,10 +14,15 @@ import android.widget.FrameLayout
 import androidx.coordinatorlayout.widget.CoordinatorLayout
 import androidx.core.view.ViewCompat
 import androidx.core.view.WindowInsetsCompat
+import dev.apexnative.navigation.options.DefaultOptions
 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.component.ComponentViewController
+import dev.apexnative.navigation.viewcontrollers.parent.ParentController
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import dev.apexnative.navigation.views.animations.AnimationLayer
 import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
 import dev.apexnative.navigation.views.element.ElementTransition
@@ -62,9 +67,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) {
@@ -88,7 +99,7 @@ internal class ModalViews(
         val container = parts.container
         container.isWaiting = false
         container.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_AUTO
-        if (record.isSheet) return presentSheet(record, parts, options, seen, events, onEnd)
+        if (record.isSheet) return presentSheet(record, parts, options, animated, seen, events, onEnd)
         applyTestIds(record, parts, options)
         if (!animated || !seen) {
             SideAnimator.rest(container)
@@ -100,22 +111,23 @@ 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
-    // detent. Nobody sees the activity: the show counts as done now, the sheet's later end does nothing.
+    // detent, or stands there at once when not [animated]. Nobody sees the activity: the show counts as done now, the
+    // sheet's later end does nothing.
     private fun presentSheet(
         record: ModalRecord,
         parts: Parts,
         options: Options,
+        animated: Boolean,
         seen: Boolean,
         events: ModalSheet.Events,
         onEnd: () -> Unit,
@@ -123,7 +135,16 @@ internal class ModalViews(
         val container = parts.container
         val view = record.root.view
         container.removeView(view)
-        val sheet = ModalSheet(container, view, events)
+        val sheet = ModalSheet(
+            container,
+            view,
+            events,
+            shownContent = { (shownScreen(record.root) as? ComponentViewController)?.content },
+            adjustsForKeyboard = {
+                val screen = shownScreen(record.root)
+                screen == null || !screen.resolveCurrentOptions(DefaultOptions.current).layout.adjustResize.isFalse
+            },
+        )
         parts.sheet = sheet
         container.alpha = 1f
         applyTestIds(record, parts, options)
@@ -134,11 +155,18 @@ internal class ModalViews(
                 onEnd()
             }
         }
-        sheet.show(options.modal.sheet, swipeToDismissOf(options)) { shown() }
+        sheet.show(options.modal.sheet, swipeToDismissOf(options), animated) { shown() }
         if (!seen) shown()
         return { told = true }
     }
 
+    // The screen a layout shows now: down through the child each parent shows.
+    private fun shownScreen(root: ViewController<*>): ViewController<*>? {
+        var node = root
+        while (node is ParentController<*>) node = node.currentChild ?: return null
+        return node
+    }
+
     override fun dismiss(
         record: ModalRecord,
         animated: Boolean,
@@ -152,7 +180,7 @@ internal class ModalViews(
         if (sheet != null) {
             if (!seen) return none(onEnd)
             var told = false
-            sheet.close {
+            sheet.close(animated) {
                 if (!told) {
                     told = true
                     onEnd()
@@ -163,13 +191,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(
@@ -245,10 +271,10 @@ internal class ModalViews(
         hideEmptyLayer()
     }
 
-    override fun update(record: ModalRecord, options: Options, move: Boolean) {
+    override fun update(record: ModalRecord, options: Options, merge: Options?) {
         val parts = parts[record] ?: return
         applyTestIds(record, parts, options)
-        parts.sheet?.update(options.modal.sheet, swipeToDismissOf(options), move)
+        parts.sheet?.update(options.modal.sheet, swipeToDismissOf(options), merge?.modal?.sheet)
     }
 
     override fun repaint(record: ModalRecord) {
@@ -259,6 +285,8 @@ internal class ModalViews(
         parts[record]?.container?.requestLayout()
     }
 
+    override fun sheetBack(record: ModalRecord): SheetBack? = parts[record]?.sheet
+
     // `modal.testID` on the modal's view; a sheet's on the sheet's container, `modal.sheet.testID` first, and its
     // grabber and scrim after it.
     private fun applyTestIds(record: ModalRecord, parts: Parts, options: Options) {
@@ -289,7 +317,11 @@ internal class ModalViews(
         val under = motion.underSide?.let { side -> underView?.let { SideAnimator.build(it, side, underBase) } }
         if (under != null && underView != null) {
             if (showing) moved[underView] = record else moved.remove(underView)
+            AnimationLayer.during(underView, under)
         }
+        // A fade of the modal or of the layer under it draws it through a hardware layer, given back at its end and at
+        // any stop (the set's cancel cancels it).
+        for (animator in listOfNotNull(side, fade)) AnimationLayer.during(container, animator)
         val fadeLength = motion.side?.takeIf(AnimationRules::isSingleAlpha)?.let(AnimationRules::lengthOf)
         val elements = motion.elements?.let { animation ->
             val content = modalsLayer.parent as? ViewGroup ?: return@let null
@@ -355,8 +387,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/modal/SheetBack.kt

@@ -0,0 +1,42 @@
+package dev.apexnative.navigation.viewcontrollers.modal
+
+import androidx.activity.BackEventCompat
+
+/**
+ * A modal's sheet as back sees it ([ModalSheet]): whether a release of back would hide it, and the preview of that
+ * hide during the back gesture (Android 14+). [ModalCoordinator.backTargetSheet] gives the one back would dismiss now.
+ * Main thread only.
+ */
+internal interface SheetBack {
+    /**
+     * Back's release would hide the sheet, as a drag down does: it stands at a detent from which it goes down (its
+     * smallest, while it lets the user close it), laid out, and it isn't closing already. False at a larger detent:
+     * the Material behavior would only collapse it there.
+     */
+    val hidesOnBack: Boolean
+
+    /**
+     * Starts the preview of back on the sheet with the gesture's first [event]: the sheet shrinks a little toward the
+     * bottom with the progress, the scrim following it. None when [hidesOnBack] doesn't hold or a preview runs.
+     */
+    fun startBackPreview(event: BackEventCompat): Gesture?
+
+    /** A back gesture over the sheet ([startBackPreview]). */
+    interface Gesture {
+        /** The sheet the gesture previews. */
+        val sheet: SheetBack
+
+        /** The gesture moved. */
+        fun progress(event: BackEventCompat)
+
+        /** Cancelled, or back went elsewhere: the sheet grows back to where it stood, the scrim with it. */
+        fun cancel()
+
+        /**
+         * Released: the sheet slides down from where the preview left it and goes as one the user dragged down (its
+         * events, its dismissal). False when the preview stopped since it started (a command closed or moved the
+         * sheet): back goes the usual way.
+         */
+        fun commit(): Boolean
+    }
+}

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

@@ -0,0 +1,83 @@
+package dev.apexnative.navigation.viewcontrollers.modal
+
+import dev.apexnative.navigation.options.SheetDetent
+
+/**
+ * Where a sheet rests: the stops it keeps of its detents, how the Material behavior stands at them, and where a shown
+ * sheet goes at new options, as on iOS: the sheet keeps the stop it stands at (the user's last drag included) until a
+ * `selectedDetent` arrives in a `mergeOptions`, or until its stop is no longer among the detents.
+ */
+internal object SheetStops {
+    /** The Material behavior has three resting states: collapsed, half expanded and expanded. */
+    const val MAX_STOPS = 3
+
+    /**
+     * The stops of the sheet, from the lowest: [detents] by their height ([heightOf]), one of each height (the first
+     * the options give), and at most [MAX_STOPS] of them: the lowest, the highest, and between them [selected] when
+     * it stands there, else the lowest of the rest.
+     */
+    fun stops(detents: List<SheetDetent>, heightOf: (SheetDetent) -> Int, selected: SheetDetent?): List<SheetDetent> {
+        val sorted = detents.sortedBy(heightOf).distinctBy(heightOf)
+        if (sorted.size <= MAX_STOPS) return sorted
+        val between = sorted.subList(1, sorted.size - 1)
+        val middle = selected?.takeIf { it in between } ?: between.first()
+        return listOf(sorted.first(), middle, sorted.last())
+    }
+
+    /**
+     * How the Material behavior stands at the stops: [fitToContents] with one or two (collapsed and expanded, the
+     * sheet as tall as the highest, [maxHeight]), else half expanded between them at [halfExpandedRatio] of the
+     * layout, and expanded [expandedOffset] below its top. [skipCollapsed] with one stop: the sheet has only that.
+     * The heights are in pixels, as is the rest.
+     */
+    data class Material(
+        val fitToContents: Boolean,
+        val skipCollapsed: Boolean,
+        val peekHeight: Int,
+        val halfExpandedRatio: Float?,
+        val expandedOffset: Int,
+        val maxHeight: Int,
+    )
+
+    /**
+     * The behavior's settings for stops [heights] tall (from the lowest, each higher than the one before) in a layout
+     * [parentHeight] tall.
+     */
+    fun material(heights: List<Int>, parentHeight: Int): Material {
+        val lowest = heights.first()
+        val highest = heights.last()
+        val three = heights.size == MAX_STOPS && parentHeight > 0
+        return Material(
+            fitToContents = !three,
+            skipCollapsed = heights.size == 1,
+            peekHeight = lowest,
+            halfExpandedRatio = if (three) heights[1].toFloat() / parentHeight else null,
+            expandedOffset = (parentHeight - highest).coerceAtLeast(0),
+            maxHeight = highest,
+        )
+    }
+
+    /**
+     * The heights of stops [heights] tall (from the lowest, each higher) lifted by [lift] pixels, the part of the
+     * keyboard over the navigation bar: the sheet stands on the keyboard as it stood on the bottom. At most [full]
+     * each, and each still higher than the one below, so the behavior keeps all of its states.
+     */
+    fun lifted(heights: List<Int>, lift: Int, full: Int): List<Int> =
+        heights.mapIndexed { i, height -> (height + lift).coerceAtMost(full - (heights.lastIndex - i)) }
+
+    /**
+     * The stop to move to, or null to stay: [arrived] (the `selectedDetent` the merge names) when it is among
+     * [detents]; else, when [settled] (the stop the sheet rests at) is no longer one of them, [selected] (the resolved
+     * `selectedDetent`) when it is, or the lowest.
+     */
+    fun target(
+        settled: SheetDetent?,
+        detents: List<SheetDetent>,
+        arrived: SheetDetent?,
+        selected: SheetDetent?,
+    ): SheetDetent? = when {
+        arrived != null && arrived in detents -> arrived
+        settled != null && settled !in detents -> selected?.takeIf { it in detents } ?: detents.first()
+        else -> null
+    }
+}

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

@@ -0,0 +1,50 @@
+package dev.apexnative.navigation.viewcontrollers.navigator
+
+import android.util.Log
+import dev.apexnative.navigation.utils.NavigationLog
+
+/**
+ * The check of [BackCallbackState]'s triggers in debug builds (`NavigationActivity` makes it only when
+ * `BuildConfig.DEBUG`): it compares an activity's back callback with what back does now
+ * ([BackCallbackState.mismatchOf]) and writes a mismatch to the log once per state, with the screen on top. It never
+ * changes the callback, so a missing trigger behaves as in a release build. A [sample] before a frame runs at most
+ * every [SAMPLE_MILLIS] and reports a mismatch only when the sample before saw the same one: a change whose trigger
+ * comes at the end of its motion (a pane that slides, a menu dragged open) isn't reported while it moves. A back event
+ * ([atBack]) reports at once. Main thread only.
+ */
+internal class BackCallbackCheck(
+    private val log: (String) -> Unit = { Log.w(NavigationLog.TAG, it) },
+) {
+    private var lastSample: Long? = null
+    private var previous: String? = null
+    private val logged = HashSet<String>()
+
+    /** Before a frame of the activity of [navigator], at [now] (`SystemClock.uptimeMillis`). */
+    fun sample(navigator: Navigator, now: Long) {
+        val last = lastSample
+        if (last != null && now - last < SAMPLE_MILLIS) return
+        lastSample = now
+        val mismatch = BackCallbackState.mismatchOf(navigator)
+        if (mismatch != null && mismatch == previous) report(mismatch)
+        previous = mismatch
+    }
+
+    /** A back event reached the callback of the activity of [navigator], before it acts. */
+    fun atBack(navigator: Navigator) {
+        BackCallbackState.mismatchOf(navigator)?.let(::report)
+    }
+
+    // Once per state, and not without end.
+    private fun report(mismatch: String) {
+        if (logged.size >= MAX_LOGGED || !logged.add(mismatch)) return
+        log("[ApexNavigation] $mismatch: a change of what back does came without its trigger")
+    }
+
+    companion object {
+        /** The least time between two samples. */
+        const val SAMPLE_MILLIS = 500L
+
+        // The states logged at most: a debug check, not a second log.
+        private const val MAX_LOGGED = 32
+    }
+}

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

@@ -2,21 +2,38 @@ package dev.apexnative.navigation.viewcontrollers.navigator
 
 import android.util.Log
 import androidx.activity.OnBackPressedCallback
+import dev.apexnative.navigation.react.events.AppearanceDispatcher
 import dev.apexnative.navigation.utils.NavigationLog
 import java.lang.ref.WeakReference
 
 /**
  * Keeps the back callback of each navigation activity enabled only while back has something to do in the app: its
- * navigation can go back ([Navigator.canHandleBack]), or JavaScript listens to it (`BackHandler`). Otherwise the
- * callback is disabled and the system does its own back. The system plays its back animation (to the home screen, to
- * another task) only when no callback of the app is enabled as the gesture starts, and it decides that before the app
- * hears of the gesture.
+ * navigation can go back ([Navigator.canHandleBack]), the screen back acts on keeps it from the system
+ * (`hardwareBackButton.systemAnimation: false`, [Navigator.keepsBackFromSystem]), or JavaScript listens to it
+ * (`BackHandler`). Otherwise the callback is disabled and the system does its own back. The system plays its back
+ * animation (to the home screen, to another task) only when no callback of the app is enabled as the gesture starts,
+ * and it decides that before the app hears of the gesture.
  *
  * A stale "enabled" only loses that animation; a stale "disabled" would leave the app where back has to go back. So
- * the value is computed again whenever what back does can have changed: before each frame of the activity's window,
- * when a command is done, when JavaScript reports its listeners, and when a side menu, the panes of a split view or a
- * search open or close (the first two after their last frame). Each activity has its own navigator and callback; the
- * listeners of JavaScript count for all of them. Main thread only.
+ * the value is computed again on every event that can change what back does, never by walking the layouts before
+ * each frame:
+ * - the end of each command's main-thread task, `setDefaultOptions` and `mergeOptions` too (`CommandRunner`);
+ * - a stack's operation accepted, its current child changed, and the operation ended or rejected
+ *   (`StackController`'s queue host), which covers a push or a `setStackRoot` that waited for its screen, a prepared
+ *   push, back of the user and the back arrow;
+ * - a layout that changed the screens it shows (`Navigator.shownScreensChanged`: the tabs, a side menu, a split view,
+ *   a pair) and the end of a tab's switch;
+ * - every change of the modals (`ModalCoordinator.Host.backChanged`): a show, a dismissal by a command, by back or by
+ *   the user (a sheet dragged down, its scrim), a failure, a `setRoot` that takes them;
+ * - a root that changed or showed, and the layers that went (a reload: `Navigator.destroy`);
+ * - a side menu, the panes of a split view or a search that opened or closed (the first two after their last frame),
+ *   and a split view's width that changed;
+ * - the release and the cancel of a back gesture, and each back press;
+ * - JavaScript's listeners ([setJsListeners]), and the activity resumed or focused, as a safety net.
+ *
+ * Overlays don't count: back never goes to them. Each activity has its own navigator and callback; the listeners of
+ * JavaScript count for all of them. Debug builds check the triggers ([mismatchOf], `BackCallbackCheck`). Main thread
+ * only.
  */
 internal object BackCallbackState {
     private class Entry(navigator: Navigator, callback: OnBackPressedCallback) {
@@ -41,6 +58,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
@@ -52,22 +73,36 @@ internal object BackCallbackState {
         for (entry in entries.toList()) update(entry)
     }
 
-    /** The callback of the activity of [navigator]: before its frames and at its back presses. */
+    /** The callback of the activity of [navigator]: after a change in its navigation. */
     fun update(navigator: Navigator) {
         entries.firstOrNull { it.navigator.get() === navigator }?.let(::update)
     }
 
+    /**
+     * Debug builds only: a callback of [navigator]'s activity that differs from what back does now — a change without
+     * its trigger —, described with the screen on top; null when it is right or not attached. It changes nothing.
+     */
+    fun mismatchOf(navigator: Navigator): String? {
+        val callback = entries.firstOrNull { it.navigator.get() === navigator }?.callback?.get() ?: return null
+        val expected = jsListeners || takesBack(navigator)
+        if (callback.isEnabled == expected) return null
+        val top = navigator.visibleLayout?.let { AppearanceDispatcher.visibleNode(it).id } ?: "none"
+        val state = if (callback.isEnabled) "enabled" else "disabled"
+        val back = if (expected) "back stays in the app" else "back leaves the app"
+        return "the back callback is $state where $back (on top: '$top')"
+    }
+
     // Enables or disables the callback when what back does changed.
     private fun update(entry: Entry) {
         val callback = entry.callback.get() ?: return
-        val enabled = jsListeners || canHandleBack(entry.navigator.get())
+        val enabled = jsListeners || takesBack(entry.navigator.get())
         if (callback.isEnabled != enabled) callback.isEnabled = enabled
     }
 
-    // A layout that fails to answer leaves back to the navigation, as before: this runs before each frame, and an
-    // exception here would end the app.
-    private fun canHandleBack(navigator: Navigator?): Boolean = try {
-        navigator?.canHandleBack() == true
+    // A layout that fails to answer leaves back to the navigation, as before: this runs from the triggers of layouts
+    // and animators, and an exception here would end the app.
+    private fun takesBack(navigator: Navigator?): Boolean = try {
+        navigator != null && (navigator.canHandleBack() || navigator.keepsBackFromSystem())
     } catch (e: RuntimeException) {
         if (!failureLogged) {
             failureLogged = true

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

@@ -31,14 +31,16 @@ 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.modal.SheetBack
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayCoordinator
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayRecord
 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.topbar.BarComponents
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.animations.FadeThrough
 import dev.apexnative.navigation.views.animations.SideAnimator
@@ -103,7 +105,10 @@ class Navigator(
         readiness = ContentReadiness,
         scheduler = scheduler,
         firstRoot = firstRootDraw,
-        onRootChanged = { root = it },
+        onRootChanged = {
+            root = it
+            BackCallbackState.update(this)
+        },
         onRootShown = {
             onRootShown?.invoke()
             BackCallbackState.update(this)
@@ -140,10 +145,21 @@ class Navigator(
 
     /**
      * Whether back has something to do in the navigation: the mirror of [handleBack], without acting — the top modal
-     * first, then the root. The back callback asks it before each frame (`BackCallbackState`).
+     * first, then the root. The back callback asks it whenever what back does can have changed (`BackCallbackState`).
      */
     fun canHandleBack(): Boolean = modals.canHandleBack() ?: (root?.canHandleBack() == true)
 
+    /**
+     * Whether back stays in the app also when the navigation has nothing to do: the layout back acts on — the top
+     * modal's, else the root — shows a screen with `hardwareBackButton.systemAnimation: false`. The system then doesn't
+     * play its animation of going home, and the press does the activity's own back ([handleBack] is false). The back
+     * callback asks it with [canHandleBack] (`BackCallbackState`).
+     */
+    fun keepsBackFromSystem(): Boolean {
+        val layout = modals.backTargetRoot() ?: root ?: return false
+        return layout.resolveShownOptions(DefaultOptions.current).hardwareBackButton.systemAnimation.isFalse
+    }
+
     /**
      * The navigation's step of back, after JavaScript's listeners didn't take it: the top modal first (its content,
      * else it closes or holds), else the root does the first thing it can (a stack's top leaves or holds, an open side
@@ -153,6 +169,18 @@ 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()
+    }
+
+    /** The sheet [handleBack] would dismiss, as a drag down of the user would; none when back would do anything else. */
+    internal fun sheetDismissedByBack(): SheetBack? = modals.backTargetSheet()
+
     /**
      * [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.
@@ -176,12 +204,14 @@ class Navigator(
      * A layout of [node] (a stack, the tabs, a side menu, a split view, a pair) changed the screens it shows: when it
      * is in a layer that still waits, the layer waits for the screens it shows now, and no longer for one that went
      * ([WaitingLayer.shownScreensChanged]); so does the operation of its stack that waits for [node] as its entry (a
-     * pushed pair); a modal's sheet takes the hold of the screen it shows now.
+     * pushed pair); a modal's sheet takes the hold of the screen it shows now; what back does is computed again (the
+     * tab, the pane or the menu back goes to, and the options of the screen it shows).
      */
     internal fun shownScreensChanged(node: ViewController<*>) {
         waitingLayerOf(node)?.shownScreensChanged()
         node.findParentStack()?.queue?.shownScreensChanged(node)
         modals.visibleScreenChanged(node)
+        BackCallbackState.update(this)
     }
 
     // The waiting layer [node] is in, up through the layouts around it; none.
@@ -214,7 +244,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 +294,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 +303,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) }
@@ -397,13 +454,15 @@ class Navigator(
         destroyLayers(answerPending = false)
         // Nothing the old screens told of their readiness holds for the screens of the new JavaScript.
         ScreenReadiness.reset()
-        BarComponents.reset()
+        // Without layers back leaves the app until the new JavaScript sets its root.
+        BackCallbackState.update(this)
     }
 
     /**
-     * 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)