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

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

@@ -172,19 +172,20 @@ internal class FabPresenter(
         alignStart = options.alignHorizontally.get("right") == "left"
         val source = source
         fab?.let { fab ->
-            applyButton(fab, options)
+            applyButton(fab, options, mayWait = fab.drawable != null || options.visible.isFalse)
             TestIds.apply(fab, options.testID.takeIf { it.hasValue() }?.get())
             val id = shownId.orEmpty()
             fab.setOnClickListener { press(source, id) }
         }
         menu?.let { menu ->
-            applyButton(menu.main, options)
+            applyButton(menu.main, options, mayWait = menu.main.drawable != null || options.visible.isFalse)
             TestIds.apply(menu.main, options.testID.takeIf { it.hasValue() }?.get())
             menu.scrimColor = options.scrimColor.get(activity, null)
             menu.setActions(options.actions.orEmpty().map { action ->
                 val actionId = action.id.get("")
                 Fab(activity, actionId).also { button ->
-                    applyButton(button, action)
+                    // The actions show only while the menu is open.
+                    applyButton(button, action, mayWait = !menu.isOpen)
                     TestIds.apply(button, action.testID.takeIf { it.hasValue() }?.get())
                     button.setOnClickListener {
                         press(source, actionId)
@@ -205,9 +206,10 @@ internal class FabPresenter(
         place()
     }
 
-    private fun applyButton(button: Fab, options: FabOptions) {
+    // [mayWait]: the button can take its icon when it is ready (it shows one, or it stays hidden), see [Fab.applyIcon].
+    private fun applyButton(button: Fab, options: FabOptions, mayWait: Boolean) {
         val icon = options.icon.takeIf { it.hasValue() }?.get()?.ifEmpty { null }
-        if (icon != null) button.applyIcon(icon, options.iconColor)
+        if (icon != null) button.applyIcon(icon, options.iconColor, mayWait)
         applyColors(button, options)
         button.setMini(options.size.get("regular") == "mini")
     }

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

@@ -14,7 +14,6 @@ import androidx.core.view.WindowCompat
 import androidx.core.view.WindowInsetsCompat
 import com.facebook.react.ReactApplication
 import dev.apexnative.navigation.options.SearchBarOptions
-import dev.apexnative.navigation.options.params.Text
 import dev.apexnative.navigation.options.params.ThemeColour
 import dev.apexnative.navigation.react.events.EventEmitter
 import dev.apexnative.navigation.utils.dp
@@ -148,10 +147,11 @@ class StackSearchPresenter(
 
     private fun searchOf(screen: ViewController<*>): ScreenSearch =
         searches.getOrPut(screen.view) {
-            // The search of a pair of screens is its primary's: its events name that screen, which keeps the scope.
+            // The search of a pair of screens is its primary's: its events name that screen, which keeps the scope in
+            // its user layer, where a merge that sends the same options again doesn't take it away.
             val owner = (screen as? OptionsScreen)?.optionsScreen ?: screen
             ScreenSearch(this, owner.id, styleContext(), loadIcon) { scope ->
-                owner.changeOptions { it.topBar.searchBar.selectedScope = Text(scope) }
+                owner.changeChoices { it.pickScope(scope) }
             }
         }
 

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

@@ -1,16 +1,14 @@
 package dev.apexnative.navigation.viewcontrollers.stack.topbar
 
-import dev.apexnative.navigation.options.ButtonMenuOptions
-import dev.apexnative.navigation.options.ButtonOptions
 import dev.apexnative.navigation.options.Options
-import dev.apexnative.navigation.options.copyMenu
+import dev.apexnative.navigation.options.UserChoices
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 
 /**
- * The check of a single-selection menu the user picked: written through [ViewController.changeOptions] into the
- * screen's own menu, never into a menu other screens share (the stack's, the defaults'). A menu that came from
- * elsewhere is copied into the screen's own options first — for a button, its whole side, as lists of buttons replace
- * whole. The check stays with the screen until new options give the menu. Main thread only.
+ * The check of a single-selection menu the user picked: written into the screen's user layer
+ * ([ViewController.changeChoices]), never into its own options nor into a menu other screens share (the stack's, the
+ * defaults'). It goes over the menu as the screen's options resolve, by the button's id and the item's id, and stays
+ * until the app changes that menu's checks or takes the item away. Main thread only.
  */
 internal object MenuChecks {
     /**
@@ -19,54 +17,13 @@ internal object MenuChecks {
      */
     fun write(screen: ViewController<*>, resolved: Options, buttonId: String?, itemId: String) {
         val topBar = resolved.topBar
-        if (buttonId == null) {
-            val menu = topBar.overflowMenu ?: return
-            if (!checks(menu, itemId)) return
-            screen.changeOptions { own ->
-                val copy = (own.topBar.overflowMenu ?: menu).copyMenu()
-                check(copy, itemId)
-                own.topBar.overflowMenu = copy
-            }
-            return
-        }
-        val left = topBar.buttons.left?.any { it.id.get(null) == buttonId } == true
-        val list = (if (left) topBar.buttons.left else topBar.buttons.right) ?: return
-        val menu = list.firstOrNull { it.id.get(null) == buttonId }?.menu ?: return
-        if (!checks(menu, itemId)) return
-        screen.changeOptions { own ->
-            val ownList = (if (left) own.topBar.buttons.left else own.topBar.buttons.right)
-                ?: list.map(ButtonOptions::copyWithMenu)
-            val button = ownList.firstOrNull { it.id.get(null) == buttonId } ?: return@changeOptions
-            val copy = (button.menu ?: menu).copyMenu()
-            check(copy, itemId)
-            button.menu = copy
-            if (left) own.topBar.buttons.left = ownList else own.topBar.buttons.right = ownList
-        }
-    }
-
-    /** Whether picking [itemId] moves a check: its level has `singleSelection`. */
-    fun checks(menu: ButtonMenuOptions, itemId: String): Boolean = levelOf(menu.items, menu.singleSelection, itemId) == true
-
-    /** Moves the check of [itemId]'s level to it, in [menu] itself. */
-    fun check(menu: ButtonMenuOptions, itemId: String) {
-        mark(menu.items, menu.singleSelection, itemId)
-    }
-
-    // Whether the level holding [itemId] has single selection; null when [itemId] isn't in [elements].
-    private fun levelOf(elements: List<ButtonMenuOptions.Element>, single: Boolean, itemId: String): Boolean? {
-        if (elements.any { it is ButtonMenuOptions.Item && it.id == itemId }) return single
-        for (element in elements) {
-            if (element !is ButtonMenuOptions.Submenu) continue
-            levelOf(element.items, element.singleSelection, itemId)?.let { return it }
-        }
-        return null
-    }
-
-    private fun mark(elements: List<ButtonMenuOptions.Element>, single: Boolean, itemId: String): Boolean {
-        if (elements.any { it is ButtonMenuOptions.Item && it.id == itemId }) {
-            if (single) elements.forEach { if (it is ButtonMenuOptions.Item) it.checked = it.id == itemId }
-            return true
-        }
-        return elements.any { it is ButtonMenuOptions.Submenu && mark(it.items, it.singleSelection, itemId) }
+        val menu = if (buttonId == null) {
+            topBar.overflowMenu
+        } else {
+            (topBar.buttons.left.orEmpty() + topBar.buttons.right.orEmpty()).firstOrNull { it.id.get(null) == buttonId }
+                ?.menu
+        } ?: return
+        if (!UserChoices.checks(menu, itemId)) return
+        screen.changeChoices { it.check(buttonId, menu, itemId) }
     }
 }

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

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

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

@@ -6,6 +6,7 @@ import android.view.ViewGroup
 import dev.apexnative.navigation.options.DefaultOptions
 import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.options.OptionsCache
+import dev.apexnative.navigation.options.UserChoices
 import dev.apexnative.navigation.options.params.Bool
 import dev.apexnative.navigation.options.params.NullBool
 import dev.apexnative.navigation.react.CommandListener
@@ -30,11 +31,11 @@ abstract class ViewController<V : ViewGroup>(
     var initialOptions: Options,
 ) {
     /**
-     * The node's own options: those it was made with, with every `mergeOptions` and every user's choice over them.
-     * Writing them is one of the two places the options change ([OptionsCache]): the setter takes away the one-shot
-     * options, keeps the object (a stripped copy when it has a one-shot option: the caller's object never changes), and
-     * makes every resolved result stale. Don't change the object in place: [changeOptions] or [mergeOptions] write a
-     * changed copy.
+     * The node's own options: those it was made with, with every `mergeOptions` over them; what the user chose in the
+     * native UI is not here but in [choices]. Writing them is one of the places the options change ([OptionsCache]):
+     * the setter takes away the one-shot options, keeps the object (a stripped copy when it has a one-shot option: the
+     * caller's object never changes), and makes every resolved result stale. Don't change the object in place:
+     * [changeOptions] or [mergeOptions] write a changed copy.
      */
     var options: Options = initialOptions.copy().also(Options::clearOneShotOptions)
         set(value) {
@@ -42,6 +43,10 @@ abstract class ViewController<V : ViewGroup>(
             OptionsCache.optionsChanged()
         }
 
+    // The user layer: what the user chose in the native UI (a menu's check, a search scope), over the node's own
+    // options as they resolve ([changeChoices]).
+    private val choices = UserChoices()
+
     /**
      * The JavaScript the node was made for (`ReloadCoordinator`): the events of the node and its screens reach only
      * that one.
@@ -94,6 +99,19 @@ abstract class ViewController<V : ViewGroup>(
     open val isInSheet: Boolean
         get() = shownAsSheet || parent?.isInSheet == true
 
+    /**
+     * The node is the root of an overlay: the overlays set it before the node's view is made, so its screens are drawn
+     * under the status bar from their first layout (`StatusBarOptions.isHiddenOrDrawBehind`).
+     */
+    internal var shownAsOverlay = false
+
+    /**
+     * The node is in an overlay: it covers the whole window, and is drawn under the status bar by default. It holds from
+     * the start of the show, while `OverlayCoordinator.isInOverlay` answers only for the overlays it lists.
+     */
+    open val isInOverlay: Boolean
+        get() = shownAsOverlay || parent?.isInOverlay == true
+
     /**
      * The node is in a side of a side menu (its left or right menu, not its center): the side goes the whole height of
      * the window, and the node keeps no room for the status bar. The layout around answers for it
@@ -143,9 +161,9 @@ abstract class ViewController<V : ViewGroup>(
     }
 
     /**
-     * The node's options over those of the layouts around it, without the default options: the parents' resolution,
-     * then the node's own. A new object at each call, which the caller may change. For a layout of nodes this is not
-     * what it shows with: that is [resolveShownOptions].
+     * The node's options over those of the layouts around it, without the default options and without the user layer
+     * ([changeChoices]): the parents' resolution, then the node's own. A new object at each call, which the caller may
+     * change. For a layout of nodes this is not what it shows with: that is [resolveShownOptions].
      */
     open fun resolveCurrentOptions(): Options {
         val resolved = parent?.resolveChildOptions(this) ?: Options()
@@ -153,21 +171,21 @@ abstract class ViewController<V : ViewGroup>(
     }
 
     /**
-     * The node's options over those of the layouts around it and [defaultOptions]: what it shows with. With the app's
-     * default options ([DefaultOptions.current]) the result is kept and given again while no options changed
-     * ([OptionsCache]) and the layouts around the node and its current children are the same: it is read-only, whoever
-     * changes it copies it first. Main thread only.
+     * The node's options over those of the layouts around it and [defaultOptions], with the user layer over them
+     * ([changeChoices]): what it shows with. With the app's default options ([DefaultOptions.current]) the result is
+     * kept and given again while no options changed ([OptionsCache]) and the layouts around the node and its current
+     * children are the same: it is read-only, whoever changes it copies it first. Main thread only.
      *
      * For a layout of nodes (a stack, tabs, a side menu) it is the layout's own options over those around it, without
      * any child's: not what the layout shows with, which [resolveShownOptions] gives.
      */
     open fun resolveCurrentOptions(defaultOptions: Options): Options {
-        if (defaultOptions !== DefaultOptions.current) return resolveCurrentOptions().withDefaultOptions(defaultOptions)
+        if (defaultOptions !== DefaultOptions.current) return withChoices(defaultOptions)
         val generation = OptionsCache.generation
         val along = resolvedAlong()
         val kept = resolved
         if (kept != null && resolvedGeneration == generation && sameNodes(along, resolvedAlong)) return kept
-        val result = resolveCurrentOptions().withDefaultOptions(defaultOptions)
+        val result = withChoices(defaultOptions)
         resolved = result
         resolvedGeneration = generation
         resolvedAlong = along.map(::WeakReference)
@@ -183,6 +201,10 @@ abstract class ViewController<V : ViewGroup>(
      */
     open fun resolveShownOptions(defaultOptions: Options): Options = resolveCurrentOptions(defaultOptions)
 
+    // The resolution in its order: the defaults, the parents, the node's own options, then the user layer over them.
+    private fun withChoices(defaultOptions: Options): Options =
+        choices.applyTo(resolveCurrentOptions().withDefaultOptions(defaultOptions))
+
     // The layouts around this node, nearest first, then its current children down the visible chain.
     private fun resolvedAlong(): List<ViewController<*>> {
         val nodes = ArrayList<ViewController<*>>()
@@ -203,9 +225,9 @@ abstract class ViewController<V : ViewGroup>(
         nodes.size == kept.size && nodes.indices.all { nodes[it] === kept[it].get() }
 
     /**
-     * Changes the node's own options: [change] gets a copy, which is stored ([options]). A presenter or a module that
-     * writes a user's choice into the options (a menu's checkmark, a search scope, tokens, a toggled button) does it
-     * this way; a button menu keeps its own shared `checked` (`ButtonMenuOptions`).
+     * Changes the node's own options: [change] gets a copy, which is stored ([options]). It is for the library's own
+     * bookkeeping of a merge (a side color written into the node's buttons, the back button's visibility); what the
+     * user chose goes through [changeChoices].
      */
     fun changeOptions(change: (Options) -> Unit) {
         val copy = options.copy()
@@ -213,14 +235,40 @@ abstract class ViewController<V : ViewGroup>(
         options = copy
     }
 
+    /**
+     * Changes the node's user layer: what the user chose in the native UI (a single-selection menu's check, a search
+     * scope). It goes over the node's own options as they resolve, by the ids of the buttons, items and scopes, and
+     * stays through an unrelated `mergeOptions`, the same values sent again and `setDefaultOptions`; a merge that
+     * changes the chosen field takes it away ([mergeOwnOptions]). Every resolved result is stale after it
+     * ([OptionsCache]).
+     */
+    internal fun changeChoices(change: (UserChoices) -> Unit) {
+        change(choices)
+        OptionsCache.optionsChanged()
+    }
+
+    /**
+     * [delta] of a `mergeOptions` goes over the node's own options ([options]); a choice of the user layer whose field
+     * the merge changes, or whose button, item or scope it took away, leaves, so the app's value shows
+     * (`UserChoices.yieldTo`). Every `mergeOptions` into a node writes its own options this way.
+     */
+    protected fun mergeOwnOptions(delta: Options) {
+        val own = options
+        val before = if (choices.isEmpty) null else resolveCurrentOptions().withDefaultOptions(DefaultOptions.current)
+        options = own.copy().mergeWith(delta)
+        before ?: return
+        val after = resolveCurrentOptions().withDefaultOptions(DefaultOptions.current)
+        if (choices.yieldTo(delta, own, before, after)) OptionsCache.optionsChanged()
+    }
+
     /**
      * `mergeOptions` with the node's id (`mergeOptions`): [options] go over its own and stay there (one-shot options
-     * not kept); what shows applies them ([applyMergedOptions], when the view shows; otherwise as it appears); the
-     * layouts around it apply their part (`ParentController.mergeChildOptions`, each passes it on). [options] still
-     * carry the one-shot options to them. Containers that hand the merge to a child override it.
+     * not kept, [mergeOwnOptions]); what shows applies them ([applyMergedOptions], when the view shows; otherwise as it
+     * appears); the layouts around it apply their part (`ParentController.mergeChildOptions`, each passes it on).
+     * [options] still carry the one-shot options to them. Containers that hand the merge to a child override it.
      */
     open fun mergeOptions(options: Options) {
-        this.options = this.options.copy().mergeWith(options)
+        mergeOwnOptions(options)
         if (isViewShown) applyMergedOptions(options)
         performOnParentController { it.mergeChildOptions(options, this) }
     }
@@ -265,6 +313,12 @@ abstract class ViewController<V : ViewGroup>(
     /** Whether [handleBack] would go back. */
     open fun canHandleBack(): Boolean = false
 
+    /**
+     * The stack whose top [handleBack] would take away with the default pop, which a back gesture previews; none when
+     * back would do anything else (hold, close a menu or a pane, a pop of its own) or nothing.
+     */
+    internal open fun stackPoppedByBack(): StackController? = null
+
     /** Starts the node's content (a native screen's view, a React screen's surface). */
     open fun start() = Unit
 

package/android/src/main/java/dev/apexnative/navigation/views/animations/Curves.kt

@@ -96,6 +96,9 @@ internal object Curves {
      * linear between them — the values of AndroidX's `FastOutSlowInInterpolator`, computed here.
      */
     object FastOutSlowIn : Curve() {
+        // Before the table, which is made from it.
+        private val curve = CubicBezier(0.4, 0.0, 0.2, 1.0)
+
         /** The 201 values. */
         val table: DoubleArray = DoubleArray(TABLE_STEPS + 1) {
             round(bezierAt(it.toDouble() / TABLE_STEPS) * DECIMALS) / DECIMALS
@@ -109,7 +112,25 @@ internal object Curves {
         }
 
         /** y of the Bézier at its x = [x], exactly (to 1e-12). */
-        fun bezierAt(x: Double): Double {
+        fun bezierAt(x: Double): Double = curve.yAt(x)
+
+        private const val DECIMALS = 1e4
+    }
+
+    /**
+     * A cubic Bézier from (0, 0) to (1, 1) with the control points ([x1], [y1]) and ([x2], [y2]), as the framework's
+     * `PathInterpolator` draws it, computed exactly: the system's curves without a framework class.
+     */
+    class CubicBezier(
+        private val x1: Double,
+        private val y1: Double,
+        private val x2: Double,
+        private val y2: Double,
+    ) : Curve() {
+        override fun at(p: Double): Double = yAt(p)
+
+        /** y of the curve at its x = [x], exactly (to 1e-12). */
+        fun yAt(x: Double): Double {
             if (x <= 0.0) return 0.0
             if (x >= 1.0) return 1.0
             // x(t) only grows with t: a bisection finds t, then y(t).
@@ -118,23 +139,20 @@ internal object Curves {
             var t = x
             repeat(BISECTION_STEPS) {
                 t = (low + high) / 2
-                if (bezier(t, X1, X2) < x) low = t else high = t
+                if (coordinate(t, x1, x2) < x) low = t else high = t
             }
-            return bezier(t, Y1, Y2)
+            return coordinate(t, y1, y2)
         }
 
-        // One coordinate of the curve from (0, 0) to (1, 1) with the control points' coordinates [c1], [c2].
-        private fun bezier(t: Double, c1: Double, c2: Double): Double {
+        // One coordinate of the curve with the control points' coordinates [c1], [c2].
+        private fun coordinate(t: Double, c1: Double, c2: Double): Double {
             val u = 1 - t
             return 3 * u * u * t * c1 + 3 * u * t * t * c2 + t * t * t
         }
 
-        private const val X1 = 0.4
-        private const val Y1 = 0.0
-        private const val X2 = 0.2
-        private const val Y2 = 1.0
-        private const val BISECTION_STEPS = 60
-        private const val DECIMALS = 1e4
+        private companion object {
+            const val BISECTION_STEPS = 60
+        }
     }
 
     /**