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

package/android/src/main/java/dev/apexnative/navigation/options/HardwareBackButtonOptions.kt

@@ -15,20 +15,27 @@ class HardwareBackButtonOptions {
     @JvmField var popStackOnPress: Bool = NullBool()
     /** Internal. */
     @JvmField var dismissModalOnPress: Bool = NullBool()
+    /**
+     * `systemAnimation`: `false` keeps back in the app on the first screen too, so the system doesn't play its
+     * animation of going home; the press then does the activity's own back.
+     */
+    @JvmField var systemAnimation: Bool = NullBool()
 
     fun hasValue(): Boolean = bottomTabsOnPress.hasValue() || popStackOnPress.hasValue() ||
-        dismissModalOnPress.hasValue()
+        dismissModalOnPress.hasValue() || systemAnimation.hasValue()
 
     fun mergeWith(other: HardwareBackButtonOptions) {
         if (other.bottomTabsOnPress.hasValue()) bottomTabsOnPress = other.bottomTabsOnPress
         if (other.popStackOnPress.hasValue()) popStackOnPress = other.popStackOnPress
         if (other.dismissModalOnPress.hasValue()) dismissModalOnPress = other.dismissModalOnPress
+        if (other.systemAnimation.hasValue()) systemAnimation = other.systemAnimation
     }
 
     fun mergeWithDefault(defaults: HardwareBackButtonOptions) {
         if (!bottomTabsOnPress.hasValue()) bottomTabsOnPress = defaults.bottomTabsOnPress
         if (!popStackOnPress.hasValue()) popStackOnPress = defaults.popStackOnPress
         if (!dismissModalOnPress.hasValue()) dismissModalOnPress = defaults.dismissModalOnPress
+        if (!systemAnimation.hasValue()) systemAnimation = defaults.systemAnimation
     }
 
     fun copy() = HardwareBackButtonOptions().also { it.mergeWith(this) }
@@ -43,6 +50,7 @@ class HardwareBackButtonOptions {
             options.bottomTabsOnPress = TextParser.parse(map, "bottomTabsOnPress", BOTTOM_TABS_ON_PRESS)
             options.popStackOnPress = BoolParser.parse(map, "popStackOnPress")
             options.dismissModalOnPress = BoolParser.parse(map, "dismissModalOnPress")
+            options.systemAnimation = BoolParser.parse(map, "systemAnimation")
             return options
         }
     }

package/android/src/main/java/dev/apexnative/navigation/options/LargeTitleOptions.kt

@@ -22,7 +22,7 @@ class LargeTitleOptions {
     @JvmField var collapseOnScroll: Bool = NullBool()
     @JvmField var fontSize: Fraction = NullFraction()
     @JvmField var color: ThemeColour = NullThemeColour()
-    @JvmField var font = FontOptions()
+    @ReadFromParent @JvmField var font = FontOptions()
 
     /**
      * When the large title shows: [ALWAYS], [NEVER] or [AUTOMATIC], as on the screen below. `displayMode` over

package/android/src/main/java/dev/apexnative/navigation/options/LayoutAnimation.kt

@@ -9,7 +9,7 @@ import com.facebook.react.bridge.ReadableMap
  * first).
  */
 open class LayoutAnimation(
-    @JvmField var sharedElements: SharedElements = SharedElements(),
+    @OptionKey("sharedElementTransitions") @JvmField var sharedElements: SharedElements = SharedElements(),
     @JvmField var elementTransitions: ElementTransitions = ElementTransitions(),
 ) {
     open fun hasValue(): Boolean = sharedElements.hasValue() || elementTransitions.hasValue()

package/android/src/main/java/dev/apexnative/navigation/options/OptionKey.kt

@@ -0,0 +1,18 @@
+package dev.apexnative.navigation.options
+
+/**
+ * The JSON key of an option field whose name is not that key (`topBar.backButton` is `TopBarButtons.back`), for the
+ * paths of [OptionPaths]; also the flag that tells a value is given, which goes with it. A field without it answers to
+ * its own name.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class OptionKey(val name: String)
+
+/**
+ * A group the reader takes from the object of the group that holds it, not from a key of its own (the font of a text,
+ * the top bar's buttons): for the paths of [OptionPaths] its fields answer to the keys of that object.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class ReadFromParent

package/android/src/main/java/dev/apexnative/navigation/options/OptionPaths.kt

@@ -0,0 +1,91 @@
+package dev.apexnative.navigation.options
+
+import dev.apexnative.navigation.options.params.Param
+import dev.apexnative.navigation.options.params.ThemeColour
+import java.lang.reflect.Field
+import java.lang.reflect.Modifier
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * The options at a JSON key path, the keys of the options joined with dots (`topBar.subtitle`, `bottomTab.badge`), as
+ * the readers parse them: `clearOptions` takes them out of a node's own options. Generic over the whole tree, by
+ * reflection on the fields of the groups: a field answers to the key of its name, or of its [OptionKey]; a group the
+ * reader takes from the object of its parent ([ReadFromParent]: the font of a text, the top bar's buttons) answers with
+ * its fields to the keys of that object. A group is a class with a `mergeWith` of its own class; anything else (a
+ * value, a color, a list, a button menu) ends a path.
+ */
+internal object OptionPaths {
+    /**
+     * What a path names: the fields of [group] that answer to its last key, [members] (one, or a value and the flag
+     * that tells it is given, as `modal.sheet.largestUndimmedDetent`).
+     */
+    class Place(val group: Any, val members: List<Field>) {
+        /** The value at the path, of the first field. */
+        val value: Any? get() = members.first().get(group)
+    }
+
+    // The fields of each class walked, its superclasses' first.
+    private val fieldsOfType = ConcurrentHashMap<Class<*>, List<Field>>()
+
+    /**
+     * Takes the value at [path] out of [options], which it changes in place: the field gets the value a freshly made
+     * group has for it (unset; a group, an empty one). Whether the path names a field; an empty or unknown path, or
+     * one that goes on inside a value (a side of a color), changes nothing.
+     */
+    fun clear(options: Options, path: String): Boolean {
+        val place = find(options, path) ?: return false
+        val fresh = newGroup(place.group.javaClass) ?: return false
+        place.members.forEach { it.set(place.group, it.get(fresh)) }
+        return true
+    }
+
+    /** The fields [path] names in [options]; none for an empty or unknown path or one inside a value. */
+    fun find(options: Options, path: String): Place? {
+        val keys = path.split('.')
+        if (keys.any(String::isEmpty)) return null
+        var group: Any = options
+        for (key in keys.dropLast(1)) {
+            group = fieldOf(group, key)?.value?.takeIf(::isGroup) ?: return null
+        }
+        return fieldOf(group, keys.last())?.takeIf { newGroup(it.group.javaClass) != null }
+    }
+
+    // The fields of [group] that answer to [key]: its own, else those of a group read from the same object.
+    private fun fieldOf(group: Any, key: String): Place? {
+        val fields = fieldsOf(group.javaClass)
+        fields.filter { !it.isAnnotationPresent(ReadFromParent::class.java) && keyOf(it) == key }
+            .takeIf { it.isNotEmpty() }
+            ?.let { return Place(group, it) }
+        for (field in fields) {
+            if (!field.isAnnotationPresent(ReadFromParent::class.java)) continue
+            val inner = field.get(group)?.takeIf(::isGroup) ?: continue
+            fieldOf(inner, key)?.let { return it }
+        }
+        return null
+    }
+
+    private fun keyOf(field: Field): String = field.getAnnotation(OptionKey::class.java)?.name ?: field.name
+
+    private fun fieldsOf(type: Class<*>): List<Field> = fieldsOfType.getOrPut(type) {
+        generateSequence(type) { it.superclass }
+            .takeWhile { it != Any::class.java }
+            .toList()
+            .asReversed()
+            .flatMap { it.declaredFields.asList() }
+            .filter { !Modifier.isStatic(it.modifiers) && !it.isSynthetic }
+            .onEach { it.isAccessible = true }
+    }
+
+    private fun isGroup(value: Any): Boolean {
+        if (value is Param<*> || value is ThemeColour) return false
+        val type = value.javaClass
+        return type.declaredMethods.any { it.name == "mergeWith" && it.parameterTypes.contentEquals(arrayOf(type)) }
+    }
+
+    // A group as its class makes it, every field unset; none for a class without a constructor of no arguments.
+    private fun newGroup(type: Class<*>): Any? = try {
+        type.getDeclaredConstructor().newInstance()
+    } catch (_: ReflectiveOperationException) {
+        null
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/options/OptionsCache.kt

@@ -3,9 +3,10 @@ package dev.apexnative.navigation.options
 /**
  * The one point where the options of the app change: a process-wide generation that grows at each change. A node's
  * resolved options are kept while the generation stays and the nodes they were built along are the same
- * (`ViewController.resolveCurrentOptions`). Exactly two places call [optionsChanged]: the write of a node's own options
- * (`ViewController.options`, and `changeOptions` through it) and the store of new default options
- * ([DefaultOptions.set]). Nothing else changes a node's own options or the defaults. Main thread only.
+ * (`ViewController.resolveCurrentOptions`). Three places call [optionsChanged]: the write of a node's own options
+ * (`ViewController.options`, and `changeOptions` and `mergeOwnOptions` through it), the write of a node's user layer
+ * (`ViewController.changeChoices`, and a merge that takes a choice away) and the store of new default options
+ * ([DefaultOptions.set]). Nothing else changes a node's own options, its user layer or the defaults. Main thread only.
  */
 object OptionsCache {
     /** The generation of the options; it only grows. */
@@ -13,7 +14,10 @@ object OptionsCache {
     var generation: Long = 0
         private set
 
-    /** A node's own options or the default options changed: every resolved result built before is stale. */
+    /**
+     * A node's own options, its user layer or the default options changed: every resolved result built before is
+     * stale.
+     */
     @JvmStatic
     fun optionsChanged() {
         generation++

package/android/src/main/java/dev/apexnative/navigation/options/SheetOptions.kt

@@ -12,25 +12,28 @@ import dev.apexnative.navigation.options.parsers.FractionParser
 import dev.apexnative.navigation.options.parsers.TextParser
 
 /**
- * A height a sheet stops at: about half the screen, the full height, or a height in dp. `content` stops at half the
- * screen on Android: the Material sheet has no height of its content.
+ * A height a sheet stops at: about half the screen, the full height, the height of the screen's content, or a height in
+ * dp.
  */
 sealed class SheetDetent {
     object Medium : SheetDetent()
     object Large : SheetDetent()
+    object Content : SheetDetent()
     data class Height(val dp: Double) : SheetDetent()
 
     /** The detent as the app names it, in `sheetDetentChanged`. */
     fun toValue(): Any = when (this) {
         Medium -> "medium"
         Large -> "large"
+        Content -> "content"
         is Height -> dp
     }
 
     companion object {
         fun parse(value: Any?): SheetDetent? = when (value) {
-            "medium", "content" -> Medium
+            "medium" -> Medium
             "large" -> Large
+            "content" -> Content
             // A number is a height only when it is finite and positive.
             is Number -> value.toDouble().takeIf { it.isFinite() && it > 0 }?.let { Height(it) }
             else -> null
@@ -47,7 +50,7 @@ class SheetOptions {
     @JvmField var selectedDetent: SheetDetent? = null
     @JvmField var largestUndimmedDetent: SheetDetent? = null
     /** The options give `largestUndimmedDetent`, `null` included. */
-    @JvmField var hasLargestUndimmedDetent = false
+    @OptionKey("largestUndimmedDetent") @JvmField var hasLargestUndimmedDetent = false
     @JvmField var grabber: Bool = NullBool()
     @JvmField var expandsOnScroll: Bool = NullBool()
     @JvmField var cornerRadius: Fraction = NullFraction()

package/android/src/main/java/dev/apexnative/navigation/options/SideMenuOptions.kt

@@ -20,16 +20,18 @@ class SideMenuOptions {
     @JvmField var right = SideMenuSideOptions()
     @JvmField var openGestureMode: Text = NullText()
     @JvmField var animationType: Text = NullText()
+    @JvmField var menusAttachMode: Text = NullText()
     @JvmField var testID: Text = NullText()
 
     fun hasValue(): Boolean = left.hasValue() || right.hasValue() || openGestureMode.hasValue() ||
-        animationType.hasValue() || testID.hasValue()
+        animationType.hasValue() || menusAttachMode.hasValue() || testID.hasValue()
 
     fun mergeWith(other: SideMenuOptions) {
         left.mergeWith(other.left)
         right.mergeWith(other.right)
         if (other.openGestureMode.hasValue()) openGestureMode = other.openGestureMode
         if (other.animationType.hasValue()) animationType = other.animationType
+        if (other.menusAttachMode.hasValue()) menusAttachMode = other.menusAttachMode
         if (other.testID.hasValue()) testID = other.testID
     }
 
@@ -38,6 +40,7 @@ class SideMenuOptions {
         right.mergeWithDefault(defaults.right)
         if (!openGestureMode.hasValue()) openGestureMode = defaults.openGestureMode
         if (!animationType.hasValue()) animationType = defaults.animationType
+        if (!menusAttachMode.hasValue()) menusAttachMode = defaults.menusAttachMode
         if (!testID.hasValue()) testID = defaults.testID
     }
 
@@ -46,6 +49,7 @@ class SideMenuOptions {
     companion object {
         private val OPEN_GESTURE_MODES = setOf("bezel", "entireScreen")
         private val ANIMATION_TYPES = setOf("parallax", "slide", "slide-and-scale", "door")
+        private val MENUS_ATTACH_MODES = setOf("together", "afterCenter", "onOpen")
 
         @JvmStatic
         fun parse(map: ReadableMap?): SideMenuOptions {
@@ -55,6 +59,7 @@ class SideMenuOptions {
             options.right = map.group("right") { SideMenuSideOptions.parse(it) }
             options.openGestureMode = TextParser.parse(map, "openGestureMode", OPEN_GESTURE_MODES)
             options.animationType = TextParser.parse(map, "animationType", ANIMATION_TYPES)
+            options.menusAttachMode = TextParser.parse(map, "menusAttachMode", MENUS_ATTACH_MODES)
             options.testID = TextParser.parse(map, "testID")
             return options
         }

package/android/src/main/java/dev/apexnative/navigation/options/StackAnimationOptions.kt

@@ -99,8 +99,8 @@ class BottomTabsEnterExitAnimationOptions {
 }
 
 /**
- * `StackAnimationOptions`: the animation of `pop`, and the base of `push` and `setStackRoot`; over the shared elements
- * and element transitions of [LayoutAnimation].
+ * `StackAnimationOptions`: the base of the animations of `push`, `pop` and `setStackRoot`; over the shared elements and
+ * element transitions of [LayoutAnimation].
  */
 open class StackAnimationOptions : LayoutAnimation() {
     @JvmField var enabled: Bool = NullBool()
@@ -188,6 +188,44 @@ class StackPushAnimationOptions : StackAnimationOptions() {
     }
 }
 
+/**
+ * `StackPopAnimationOptions`: the animation of `pop`, and `preview`: whether a back gesture over the stack previews the
+ * pop of its top (Android 14+); `false` pops it when the gesture is released, as on Android 13.
+ */
+class StackPopAnimationOptions : StackAnimationOptions() {
+    @JvmField var preview: Bool = NullBool()
+
+    override fun hasValue(): Boolean = super.hasValue() || preview.hasValue()
+
+    fun mergeWith(other: StackPopAnimationOptions) {
+        super.mergeWith(other)
+        if (other.preview.hasValue()) preview = other.preview
+    }
+
+    fun mergeWithDefault(defaults: StackPopAnimationOptions) {
+        super.mergeWithDefault(defaults)
+        if (!preview.hasValue()) preview = defaults.preview
+    }
+
+    override fun copy(): StackPopAnimationOptions = StackPopAnimationOptions().also { it.mergeWith(this) }
+
+    // Reads the fields of this class from [map], after those of its parent.
+    private fun readStackPopAnimationOptions(map: ReadableMap) {
+        readStackAnimationOptions(map)
+        preview = BoolParser.parse(map, "preview")
+    }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): StackPopAnimationOptions {
+            val options = StackPopAnimationOptions()
+            if (map == null) return options
+            options.readStackPopAnimationOptions(map)
+            return options
+        }
+    }
+}
+
 /** `SetStackRootAnimationOptions`: the animation of `setStackRoot`. */
 class SetStackRootAnimationOptions : StackAnimationOptions() {
     @JvmField var asPush: Bool = NullBool()

package/android/src/main/java/dev/apexnative/navigation/options/StatusBarOptions.kt

@@ -22,9 +22,13 @@ class StatusBarOptions {
     @JvmField var hideWithTopBar: Bool = NullBool()
     @JvmField var blur: Bool = NullBool()
 
-    /** The status bar is hidden, or the screen is drawn under it: the screen keeps no room for it. */
-    val isHiddenOrDrawBehind: Boolean
-        get() = visible.isFalse || drawBehind.isTrue
+    /**
+     * The status bar is hidden, or the screen is drawn under it: the screen keeps no room for it. Without `drawBehind`, a
+     * screen or a layout in an overlay ([inOverlay]) is drawn under it: an overlay covers the whole window, its dimmed
+     * backdrop the status bar too.
+     */
+    fun isHiddenOrDrawBehind(inOverlay: Boolean): Boolean =
+        visible.isFalse || if (drawBehind.hasValue()) drawBehind.isTrue else inOverlay
 
     fun hasValue(): Boolean = visible.hasValue() || style.hasValue() || backgroundColor.hasValue() ||
         drawBehind.hasValue() || translucent.hasValue() || animate.hasValue() || hideWithTopBar.hasValue() ||

package/android/src/main/java/dev/apexnative/navigation/options/TitleOptions.kt

@@ -22,7 +22,7 @@ class TitleOptions {
     @JvmField var text: Text = NullText()
     @JvmField var fontSize: Fraction = NullFraction()
     @JvmField var color: ThemeColour = NullThemeColour()
-    @JvmField var font = FontOptions()
+    @ReadFromParent @JvmField var font = FontOptions()
     @JvmField var component = TitleComponentOptions()
     /** Shared between copies, as its module wants. */
     @JvmField var menu: ButtonMenuOptions? = null
@@ -98,7 +98,7 @@ class SubtitleOptions {
     @JvmField var text: Text = NullText()
     @JvmField var fontSize: Fraction = NullFraction()
     @JvmField var color: ThemeColour = NullThemeColour()
-    @JvmField var font = FontOptions()
+    @ReadFromParent @JvmField var font = FontOptions()
     @JvmField var alignment: Text = NullText()
 
     fun hasValue(): Boolean =

package/android/src/main/java/dev/apexnative/navigation/options/TopBarAppearanceOptions.kt

@@ -109,7 +109,7 @@ class TopBarBackgroundOptions {
  */
 class ScrollEdgeAppearanceTitleOptions {
     @JvmField var color: ThemeColour = NullThemeColour()
-    @JvmField var font = FontOptions()
+    @ReadFromParent @JvmField var font = FontOptions()
     @JvmField var fontSize: Fraction = NullFraction()
 
     fun hasValue(): Boolean = color.hasValue() || font.hasValue() || fontSize.hasValue()

package/android/src/main/java/dev/apexnative/navigation/options/TopBarOptions.kt

@@ -34,12 +34,14 @@ class TopBarOptions {
     @JvmField var rightButtonDisabledColor: ThemeColour = NullThemeColour()
     @JvmField var centerButtonColor: ThemeColour = NullThemeColour()
     @JvmField var centerButtonDisabledColor: ThemeColour = NullThemeColour()
+    @JvmField var menuBackgroundColor: ThemeColour = NullThemeColour()
+    @JvmField var menuTextColor: ThemeColour = NullThemeColour()
     @JvmField var drawBehind: Bool = NullBool()
     @JvmField var testID: Text = NullText()
     @JvmField var title = TitleOptions()
     @JvmField var subtitle = SubtitleOptions()
     /** `backButton`, `leftButtons`, `rightButtons`, `centerButtons`. */
-    @JvmField var buttons = TopBarButtons()
+    @ReadFromParent @JvmField var buttons = TopBarButtons()
     @JvmField var customizationId: Text = NullText()
     /** Shared between copies, as its module wants. */
     @JvmField var overflowMenu: ButtonMenuOptions? = null
@@ -63,7 +65,8 @@ class TopBarOptions {
         hideOnTap.hasValue() || hideOnKeyboard.hasValue() || leftButtonColor.hasValue() ||
         rightButtonColor.hasValue() || leftButtonBackgroundColor.hasValue() || rightButtonBackgroundColor.hasValue() ||
         leftButtonDisabledColor.hasValue() || rightButtonDisabledColor.hasValue() || centerButtonColor.hasValue() ||
-        centerButtonDisabledColor.hasValue() || drawBehind.hasValue() || testID.hasValue() || title.hasValue() ||
+        centerButtonDisabledColor.hasValue() || menuBackgroundColor.hasValue() || menuTextColor.hasValue() ||
+        drawBehind.hasValue() || testID.hasValue() || title.hasValue() ||
         subtitle.hasValue() || buttons.hasValue() || customizationId.hasValue() || overflowMenu != null ||
         verticalBarKeeps.hasValue() || background.hasValue() || scrollEdgeAppearance.hasValue() ||
         barStyle.hasValue() || style.hasValue() || noBorder.hasValue() || searchBar.hasAnyValue() ||
@@ -85,6 +88,8 @@ class TopBarOptions {
         rightButtonDisabledColor = rightButtonDisabledColor.mergeWith(other.rightButtonDisabledColor)
         centerButtonColor = centerButtonColor.mergeWith(other.centerButtonColor)
         centerButtonDisabledColor = centerButtonDisabledColor.mergeWith(other.centerButtonDisabledColor)
+        menuBackgroundColor = menuBackgroundColor.mergeWith(other.menuBackgroundColor)
+        menuTextColor = menuTextColor.mergeWith(other.menuTextColor)
         if (other.drawBehind.hasValue()) drawBehind = other.drawBehind
         if (other.testID.hasValue()) testID = other.testID
         title.mergeWith(other.title)
@@ -127,6 +132,8 @@ class TopBarOptions {
         rightButtonDisabledColor = rightButtonDisabledColor.withDefault(defaults.rightButtonDisabledColor)
         centerButtonColor = centerButtonColor.withDefault(defaults.centerButtonColor)
         centerButtonDisabledColor = centerButtonDisabledColor.withDefault(defaults.centerButtonDisabledColor)
+        menuBackgroundColor = menuBackgroundColor.withDefault(defaults.menuBackgroundColor)
+        menuTextColor = menuTextColor.withDefault(defaults.menuTextColor)
         if (!drawBehind.hasValue()) drawBehind = defaults.drawBehind
         if (!testID.hasValue()) testID = defaults.testID
         title.mergeWithDefault(defaults.title)
@@ -178,6 +185,8 @@ class TopBarOptions {
             options.rightButtonDisabledColor = ThemeColour.parse(context, map, "rightButtonDisabledColor")
             options.centerButtonColor = ThemeColour.parse(context, map, "centerButtonColor")
             options.centerButtonDisabledColor = ThemeColour.parse(context, map, "centerButtonDisabledColor")
+            options.menuBackgroundColor = ThemeColour.parse(context, map, "menuBackgroundColor")
+            options.menuTextColor = ThemeColour.parse(context, map, "menuTextColor")
             options.drawBehind = BoolParser.parse(map, "drawBehind")
             options.testID = TextParser.parse(map, "testID")
             options.title = map.group("title") { TitleOptions.parse(context, it) }
@@ -212,13 +221,13 @@ class TopBarOptions {
  * don't give it; `[]` takes the buttons of the layers below away.
  */
 class TopBarButtons {
-    @JvmField var back = BackButtonOptions()
+    @OptionKey("backButton") @JvmField var back = BackButtonOptions()
     /** `topBar.leftButtons`; null when the options don't give them. */
-    @JvmField var left: List<ButtonOptions>? = null
+    @OptionKey("leftButtons") @JvmField var left: List<ButtonOptions>? = null
     /** `topBar.rightButtons`; null when the options don't give them. */
-    @JvmField var right: List<ButtonOptions>? = null
+    @OptionKey("rightButtons") @JvmField var right: List<ButtonOptions>? = null
     /** `topBar.centerButtons`; null when the options don't give them. */
-    @JvmField var center: List<ButtonOptions>? = null
+    @OptionKey("centerButtons") @JvmField var center: List<ButtonOptions>? = null
 
     fun hasValue(): Boolean = back.hasValue() || left != null || right != null || center != null
 
@@ -263,7 +272,7 @@ class BackButtonOptions {
     @JvmField var showTitle: Bool = NullBool()
     @JvmField var color: ThemeColour = NullThemeColour()
     @JvmField var fontSize: Fraction = NullFraction()
-    @JvmField var font = FontOptions()
+    @ReadFromParent @JvmField var font = FontOptions()
     @JvmField var iconBackground = IconBackgroundOptions()
     @JvmField var testID: Text = NullText()
     @JvmField var enableMenu: Bool = NullBool()

package/android/src/main/java/dev/apexnative/navigation/options/UserChoices.kt

@@ -0,0 +1,159 @@
+package dev.apexnative.navigation.options
+
+import dev.apexnative.navigation.options.params.Text
+
+/**
+ * The user layer of a node: what the user chose in the native UI, kept apart from the node's own options so that the
+ * app's next `mergeOptions` or `setDefaultOptions` doesn't wipe it. The choices are the check of a single-selection
+ * menu (a bar button's `menu`, by the button's id; `topBar.overflowMenu`) and the search scope
+ * (`topBar.searchBar.selectedScope`).
+ *
+ * It goes over everything else as the node's options resolve (defaults < parents < own < user), by identity rather
+ * than as a tree merged over: a menu's check by the button's id and the item's id, the scope by its id. A choice whose
+ * button, item or scope is gone is not applied, and leaves at the node's next merge; a merge that gives a chosen field
+ * a value other than the one the app had there before takes the choice away ([yieldTo]). `setDefaultOptions` never
+ * clears it. The node owns it and writes it through `ViewController.changeChoices`, which moves [OptionsCache]. Main
+ * thread only.
+ */
+internal class UserChoices {
+    // The menus' checks: per menu (a button's id, OVERFLOW for `overflowMenu`) the item picked in each of its levels,
+    // in the order of the picks.
+    private val checks = LinkedHashMap<String, MutableList<String>>()
+    private var scope: String? = null
+
+    /** The user chose nothing that stays. */
+    val isEmpty: Boolean
+        get() = checks.isEmpty() && scope == null
+
+    /**
+     * The user picked [itemId] in [menu], the menu of the button [buttonId] or `overflowMenu` (null), as it showed: it
+     * takes the place of an earlier pick in the same level.
+     */
+    fun check(buttonId: String?, menu: ButtonMenuOptions, itemId: String) {
+        val picks = checks.getOrPut(keyOf(buttonId)) { mutableListOf() }
+        val level = levelItems(menu.items, itemId)?.map { it.id }.orEmpty()
+        picks.removeAll { it == itemId || it in level }
+        picks += itemId
+    }
+
+    /** The user picked the search scope [scopeId]. */
+    fun pickScope(scopeId: String) {
+        scope = scopeId
+    }
+
+    /**
+     * Writes the choices into [resolved], a result of resolution nobody else holds yet; the menus it changes are copied
+     * first, as a resolved result shares its menus with the layers they come from. Returns [resolved].
+     */
+    fun applyTo(resolved: Options): Options {
+        if (isEmpty) return resolved
+        val topBar = resolved.topBar
+        for ((key, picks) in checks) {
+            if (key == OVERFLOW) {
+                val menu = topBar.overflowMenu ?: continue
+                topBar.overflowMenu = menu.copyMenu().also { copy -> picks.forEach { mark(copy, it) } }
+                continue
+            }
+            val button = buttonIn(topBar.buttons, key) ?: continue
+            val menu = button.menu ?: continue
+            button.menu = menu.copyMenu().also { copy -> picks.forEach { mark(copy, it) } }
+        }
+        scope?.let { picked ->
+            val searchBar = topBar.searchBar
+            if (searchBar.scopes?.any { it.id == picked } == true) searchBar.selectedScope = Text(picked)
+        }
+        return resolved
+    }
+
+    /**
+     * The app merged [delta] into the node. A choice leaves when what it was made in is gone from [after] (the node's
+     * options as they resolve after the merge, without this layer), or when [delta] gives its field a value other than
+     * the one the node's own options had before the merge ([own]; where they had none, the app's resolution before the
+     * merge, [before]). The same value sent again (a re-render) keeps the choice. Returns whether a choice left.
+     */
+    fun yieldTo(delta: Options, own: Options, before: Options, after: Options): Boolean {
+        var changed = false
+        val entries = checks.entries.iterator()
+        while (entries.hasNext()) {
+            val (key, picks) = entries.next()
+            val now = menuIn(after, key)
+            val given = menuIn(delta, key)
+            val was = menuIn(own, key) ?: menuIn(before, key)
+            val left = picks.removeAll { itemId ->
+                val gone = now == null || levelItems(now.items, itemId) == null
+                gone || (given != null && checkedInLevel(given, itemId) != was?.let { checkedInLevel(it, itemId) })
+            }
+            if (left) changed = true
+            if (picks.isEmpty()) entries.remove()
+        }
+        scope?.let { picked ->
+            val given = delta.topBar.searchBar.selectedScope
+            val ownScope = own.topBar.searchBar.selectedScope
+            val was = (if (ownScope.hasValue()) ownScope else before.topBar.searchBar.selectedScope).get(null)
+            val changedByApp = given.hasValue() && given.get(null) != was
+            val gone = after.topBar.searchBar.scopes?.any { it.id == picked } != true
+            if (changedByApp || gone) {
+                scope = null
+                changed = true
+            }
+        }
+        return changed
+    }
+
+    companion object {
+        // The key of `overflowMenu`, which has no button; no placed button has an empty id.
+        private const val OVERFLOW = ""
+
+        private fun keyOf(buttonId: String?): String = buttonId ?: OVERFLOW
+
+        /** Whether picking [itemId] in [menu] 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; nothing in a level without single selection. */
+        fun mark(menu: ButtonMenuOptions, itemId: String) {
+            mark(menu.items, menu.singleSelection, itemId)
+        }
+
+        private fun buttonIn(buttons: TopBarButtons, id: String): ButtonOptions? =
+            buttons.left?.firstOrNull { it.id.get(null) == id } ?: buttons.right?.firstOrNull { it.id.get(null) == id }
+
+        // The menu the key names in [options]: `overflowMenu`, or the menu of the button with that id.
+        private fun menuIn(options: Options, key: String): ButtonMenuOptions? =
+            if (key == OVERFLOW) options.topBar.overflowMenu else buttonIn(options.topBar.buttons, key)?.menu
+
+        // The checked items of the level that holds [itemId] in [menu]: the field a merge gives that level.
+        private fun checkedInLevel(menu: ButtonMenuOptions, itemId: String): Set<String>? =
+            levelItems(menu.items, itemId)?.filter { it.checked }?.map { it.id }?.toSet()
+
+        // The items of the level that holds [itemId]; null when it isn't in [elements].
+        private fun levelItems(
+            elements: List<ButtonMenuOptions.Element>,
+            itemId: String,
+        ): List<ButtonMenuOptions.Item>? {
+            val items = elements.filterIsInstance<ButtonMenuOptions.Item>()
+            if (items.any { it.id == itemId }) return items
+            return elements.filterIsInstance<ButtonMenuOptions.Submenu>().firstNotNullOfOrNull {
+                levelItems(it.items, 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) }
+        }
+    }
+}