@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.1

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

@@ -0,0 +1,243 @@
+package dev.apexnative.navigation.viewcontrollers.stack.search
+
+import android.app.Activity
+import android.content.Context
+import android.graphics.drawable.Drawable
+import android.view.Menu
+import android.view.MenuItem
+import android.view.View
+import android.view.ViewGroup
+import androidx.appcompat.R as AppCompatR
+import androidx.appcompat.content.res.AppCompatResources
+import androidx.coordinatorlayout.widget.CoordinatorLayout
+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
+import dev.apexnative.navigation.viewcontrollers.parent.OptionsScreen
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import dev.apexnative.navigation.views.stack.topbar.TopBar
+import dev.apexnative.navigation.views.stack.topbar.TopBarDefaults
+import dev.apexnative.navigation.views.stack.topbar.search.SearchStyle
+
+/**
+ * The search of the screens of a stack (`topBar.searchBar`): each screen has its own while it is in the stack, and the
+ * top bar shows the one of the screen on top; a screen's search view (with a results component) shows only while the
+ * screen is on top.
+ */
+class StackSearchPresenter(
+    private val activity: Activity,
+    private val loadIcon: (String) -> Drawable?,
+) : ScreenSearch.Host {
+    private var topBar: TopBar? = null
+    private val searches = HashMap<View, ScreenSearch>()
+    private var shown: ScreenSearch? = null
+    private var scrim: View? = null
+    private var suggestions: View? = null
+    private var wasActive = false
+    private var onActiveChanged: Runnable? = null
+
+    /** The search of the screen on top opened or closed: the bar's hideOnScroll stops or goes on. */
+    fun setOnActiveChanged(listener: Runnable?) {
+        onActiveChanged = listener
+    }
+
+    /** The search of the screen on top is open. */
+    fun isActive(): Boolean = shown?.isActive == true
+
+    fun bindTopBar(topBar: TopBar) {
+        this.topBar = topBar
+        // The suggestions hang from the bar: they follow its height as the search opens and its scopes show.
+        topBar.addOnLayoutChangeListener { _, _, _, _, _, _, _, _, _ -> topBar.post { positionSuggestions(topBar) } }
+    }
+
+    /** The options of the screen on top of the stack, resolved: its search shows in the bar, or none. */
+    fun apply(screen: ViewController<*>, resolved: SearchBarOptions) {
+        val view = screen.view
+        if (!resolved.visible.isTrue) {
+            remove(view)
+            show(null)
+            return
+        }
+        val search = searchOf(screen)
+        search.apply(resolved)
+        show(search)
+    }
+
+    /** mergeOptions of the screen on top: only what it gives changes; visible: false removes the search. */
+    fun merge(screen: ViewController<*>, toMerge: SearchBarOptions, resolved: SearchBarOptions) {
+        if (!resolved.visible.isTrue) {
+            if (toMerge.visible.isFalse) {
+                remove(screen.view)
+                show(null)
+            }
+            return
+        }
+        val search = searchOf(screen)
+        search.merge(toMerge, resolved)
+        show(search)
+    }
+
+    fun onScreenDestroyed(view: View) {
+        remove(view)
+    }
+
+    /** The back key: an open search closes first. */
+    fun closeSearch(): Boolean {
+        val search = shown?.takeIf { it.isActive } ?: return false
+        search.cancel()
+        return true
+    }
+
+    /** After the right buttons change: the magnifier of an integrated search goes back among them, last. */
+    fun applyMagnifier() {
+        val bar = topBar ?: return
+        val menu = bar.rightButtonBar.menu
+        val item = menu.findItem(MAGNIFIER_ID)
+        if (shown?.showsMagnifier != true) {
+            if (item != null) menu.removeItem(MAGNIFIER_ID)
+            return
+        }
+        if (item != null) return
+        val context = styleContext()
+        val label = context.getString(AppCompatR.string.abc_searchview_description_search)
+        menu.add(Menu.NONE, MAGNIFIER_ID, MAGNIFIER_ORDER, label).apply {
+            icon = AppCompatResources.getDrawable(context, AppCompatR.drawable.abc_ic_search_api_material)?.mutate()?.also {
+                it.setTint(TopBarDefaults.overflowIconColor(context))
+            }
+            setShowAsAction(MenuItem.SHOW_AS_ACTION_ALWAYS)
+            setOnMenuItemClickListener {
+                shown?.activate()
+                true
+            }
+        }
+    }
+
+    override fun refresh(search: ScreenSearch) {
+        if (search === shown) refresh()
+    }
+
+    override fun isShown(search: ScreenSearch): Boolean = search === shown
+
+    override fun stackView(): ViewGroup? = topBar?.parent as? ViewGroup
+
+    override fun styleContext(): Context = SearchStyle.materialContext(activity)
+
+    /**
+     * Light or dark changed, or the default options (`navigation.setTheme`): the searches take the theme's colors
+     * again, the magnifier too. The shown one takes [tint], from its screen's options as they resolve now.
+     */
+    fun onConfigurationChanged(tint: ThemeColour) {
+        shown?.takeTint(tint)
+        searches.values.forEach { it.restyle() }
+        topBar?.rightButtonBar?.menu?.removeItem(MAGNIFIER_ID)
+        refresh()
+    }
+
+    override fun emitter(): EventEmitter? =
+        (activity.application as? ReactApplication)?.reactHost?.currentReactContext?.let { EventEmitter(it) }
+
+    override fun keyboard(view: View, show: Boolean) {
+        val controller = WindowCompat.getInsetsController(activity.window, view)
+        if (show) controller.show(WindowInsetsCompat.Type.ime()) else controller.hide(WindowInsetsCompat.Type.ime())
+    }
+
+    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.
+            val owner = (screen as? OptionsScreen)?.optionsScreen ?: screen
+            ScreenSearch(this, owner.id, styleContext(), loadIcon) { scope ->
+                owner.changeOptions { it.topBar.searchBar.selectedScope = Text(scope) }
+            }
+        }
+
+    private fun remove(view: View) {
+        val search = searches.remove(view) ?: return
+        if (search === shown) show(null)
+        search.destroy()
+    }
+
+    private fun show(search: ScreenSearch?) {
+        if (shown !== search) {
+            shown?.onHidden()
+            shown = search
+            search?.onShown()
+        }
+        refresh()
+    }
+
+    private fun refresh() {
+        val bar = topBar ?: return
+        val search = shown
+        bar.setSearchArea(search?.barArea, search?.barAreaHeight ?: 0, search?.takesBar == true)
+        applyMagnifier()
+        applyScrim(bar)
+        applySuggestions(bar)
+        if (isActive() != wasActive) {
+            wasActive = isActive()
+            onActiveChanged?.run()
+        }
+    }
+
+    // Over the screens and under the bar: a tap on it closes the search.
+    private fun applyScrim(bar: TopBar) {
+        if (shown?.dimsScreen != true) {
+            scrim?.visibility = View.GONE
+            return
+        }
+        val stack = bar.parent as? ViewGroup ?: return
+        val view = scrim ?: View(activity).apply {
+            setBackgroundColor(SearchStyle.scrimColor())
+            isClickable = true
+            setOnClickListener { shown?.cancel() }
+        }.also { scrim = it }
+        if (view.parent !== stack) {
+            (view.parent as? ViewGroup)?.removeView(view)
+            stack.addView(view, stack.indexOfChild(bar), CoordinatorLayout.LayoutParams(
+                ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT
+            ))
+        }
+        view.visibility = View.VISIBLE
+    }
+
+    // Under the bar, over the screen and its dimming.
+    private fun applySuggestions(bar: TopBar) {
+        val card = shown?.suggestionsOverlay
+        if (card !== suggestions) {
+            (suggestions?.parent as? ViewGroup)?.removeView(suggestions)
+            suggestions = card
+        }
+        if (card == null) return
+        val stack = bar.parent as? ViewGroup ?: return
+        val scrimIndex = scrim?.takeIf { it.parent === stack }?.let { stack.indexOfChild(it) } ?: -1
+        if (card.parent !== stack || stack.indexOfChild(card) < scrimIndex) {
+            (card.parent as? ViewGroup)?.removeView(card)
+            stack.addView(card, stack.indexOfChild(bar), CoordinatorLayout.LayoutParams(
+                ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT
+            ).apply {
+                leftMargin = 16.dp
+                rightMargin = 16.dp
+            })
+        }
+        positionSuggestions(bar)
+    }
+
+    private fun positionSuggestions(bar: TopBar) {
+        val card = suggestions ?: return
+        val lp = card.layoutParams as? ViewGroup.MarginLayoutParams ?: return
+        val top = bar.bottom + 4.dp
+        if (lp.topMargin == top) return
+        lp.topMargin = top
+        card.layoutParams = lp
+    }
+
+    private companion object {
+        val MAGNIFIER_ID = View.generateViewId()
+        // The highest a menu order goes: after the screen's own buttons.
+        const val MAGNIFIER_ORDER = 0xFFFF
+    }
+}

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

@@ -0,0 +1,211 @@
+package dev.apexnative.navigation.viewcontrollers.stack.topbar
+
+import dev.apexnative.navigation.options.ButtonOptions
+import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.options.TitleComponentOptions
+import dev.apexnative.navigation.options.TopBarBackgroundComponentOptions
+import dev.apexnative.navigation.options.params.Text
+import dev.apexnative.navigation.viewcontrollers.component.ScreenReadiness
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.IReactView
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+/**
+ * The React components of the bar of one stack, by screen: each screen of the stack keeps its title, its background and
+ * its buttons (by `componentId`) while it is in the stack. The same `name` and `componentId` at the same screen is the
+ * same root, never made again; another replaces it, and the old one stops at once. A background with the same `name`
+ * and `componentId` on several screens is one root, shared; it stops when no screen of the stack names it any more. The
+ * roots go with their screen ([screenDestroyed]) or the stack ([destroyAll]). Each root renders at once, without
+ * waiting for its layout: [makeRoot] marks its id so before its surface starts. Main thread only.
+ */
+internal class BarComponents(private val makeRoot: (componentId: String, name: String) -> IReactView) {
+    /** A root of the bar: what it renders, and its content. */
+    class Root(val name: String, val componentId: String, val view: IReactView)
+
+    private data class Key(val name: String, val componentId: String)
+
+    private class ScreenRoots {
+        var title: Root? = null
+        var background: Key? = null
+        val buttons = LinkedHashMap<String, Root>()
+    }
+
+    private val screens = HashMap<ViewController<*>, ScreenRoots>()
+    private val backgrounds = HashMap<Key, Root>()
+
+    /** The title of [screen] for [options] (`topBar.title.component`): kept, made, or none without a `name`. */
+    fun title(screen: ViewController<*>, options: TitleComponentOptions): Root? {
+        val roots = rootsOf(screen)
+        val key = keyOf(options.name, options.componentId, options.id)
+        val current = roots.title
+        if (key == null) {
+            roots.title = null
+            current?.let(::stop)
+            return null
+        }
+        if (current != null && current.name == key.name && current.componentId == key.componentId) return current
+        current?.let(::stop)
+        return make(key).also { roots.title = it }
+    }
+
+    /** The background of [screen] for [options] (`topBar.background.component`): shared by `name` + `componentId`. */
+    fun background(screen: ViewController<*>, options: TopBarBackgroundComponentOptions): Root? {
+        val roots = rootsOf(screen)
+        val key = keyOf(options.name, options.componentId, options.id)
+        val old = roots.background
+        roots.background = key
+        if (old != null && old != key) release(old)
+        if (key == null) return null
+        return backgrounds.getOrPut(key) { make(key) }
+    }
+
+    /**
+     * The React buttons of [screen] for [buttons] (all the sides at once), by `componentId`: those kept, those made;
+     * the roots no button names any more stop (one map, a merge makes no extra one).
+     */
+    fun buttons(screen: ViewController<*>, buttons: List<ButtonOptions>): Map<String, Root> {
+        val roots = rootsOf(screen)
+        val wanted = LinkedHashMap<String, Key>()
+        for (button in buttons) {
+            val key = keyOf(button.component.name, button.component.componentId, button.component.id) ?: continue
+            wanted[key.componentId] = key
+        }
+        val iterator = roots.buttons.entries.iterator()
+        while (iterator.hasNext()) {
+            val (componentId, root) = iterator.next()
+            val key = wanted[componentId]
+            if (key == null || key.name != root.name) {
+                iterator.remove()
+                stop(root)
+            }
+        }
+        for ((componentId, key) in wanted) roots.buttons.getOrPut(componentId) { make(key) }
+        return roots.buttons
+    }
+
+    /** The title of [screen] now; none. */
+    fun titleOf(screen: ViewController<*>): Root? = screens[screen]?.title
+
+    /** The background of [screen] now; none. */
+    fun backgroundOf(screen: ViewController<*>): Root? = screens[screen]?.background?.let(backgrounds::get)
+
+    /** The screens that have components here. */
+    fun screens(): List<ViewController<*>> = screens.keys.toList()
+
+    /** Whether [root] is a background still alive here. */
+    fun holds(root: Root): Boolean = backgrounds.values.any { it === root }
+
+    /** The React buttons of [screen] now. */
+    fun buttonsOf(screen: ViewController<*>): Collection<Root> = screens[screen]?.buttons?.values.orEmpty()
+
+    /**
+     * Whether the components of the bar [screen] shows with [options] have drawn: its title unless its `waitForRender`
+     * is `false`, and its background unless its own is `false`. Its React buttons don't count: they render during the
+     * transition.
+     */
+    fun isDrawn(screen: ViewController<*>, options: Options): Boolean = waited(screen, options).all { it.isReady() }
+
+    /** Calls [listener] once [isDrawn]; at once when it is. It can't be taken back: the caller guards it. */
+    fun whenDrawn(screen: ViewController<*>, options: Options, listener: () -> Unit) {
+        val waited = waited(screen, options)
+        if (waited.all { it.isReady() }) return listener()
+        var told = false
+        for (view in waited) {
+            view.whenReady {
+                if (!told && waited.all { it.isReady() }) {
+                    told = true
+                    listener()
+                }
+            }
+        }
+    }
+
+    /** [screen] is destroyed: its roots stop, its background when no other screen names it. */
+    fun screenDestroyed(screen: ViewController<*>) {
+        val roots = screens.remove(screen) ?: return
+        roots.title?.let(::stop)
+        roots.buttons.values.forEach(::stop)
+        roots.background?.let(::release)
+    }
+
+    /** The stack is destroyed: every root stops. */
+    fun destroyAll() {
+        screens.keys.toList().forEach(::screenDestroyed)
+        backgrounds.values.toList().forEach(::stop)
+        backgrounds.clear()
+    }
+
+    private fun waited(screen: ViewController<*>, options: Options): List<IReactView> {
+        val waited = ArrayList<IReactView>(2)
+        val title = options.topBar.title.component
+        if (!title.waitForRender.isFalse) titleOf(screen)?.let { waited += it.view }
+        val background = options.topBar.background.component
+        if (!background.waitForRender.isFalse) backgroundOf(screen)?.let { waited += it.view }
+        return waited
+    }
+
+    private fun rootsOf(screen: ViewController<*>): ScreenRoots = screens.getOrPut(screen, ::ScreenRoots)
+
+    // A shared background no screen names any more stops.
+    private fun release(key: Key) {
+        if (screens.values.any { it.background == key }) return
+        backgrounds.remove(key)?.let(::stop)
+    }
+
+    // Made first, counted after: the maker asks whether another root with the id lives.
+    private fun make(key: Key): Root {
+        val root = Root(key.name, key.componentId, makeRoot(key.componentId, key.name))
+        LiveIds.add(key.componentId)
+        return root
+    }
+
+    // Stops a root once; what the readiness store kept of its id goes unless another live root holds the id.
+    private fun stop(root: Root) {
+        root.view.destroy()
+        if (LiveIds.remove(root.componentId)) ScreenReadiness.remove(root.componentId)
+    }
+
+    private fun keyOf(name: Text, componentId: Text, id: Text): Key? {
+        val componentName = name.get(null)?.takeIf { it.isNotEmpty() } ?: return null
+        val rootId = componentId.get(null)?.takeIf { it.isNotEmpty() } ?: id.get(null)?.takeIf { it.isNotEmpty() }
+            ?: return null
+        return Key(componentName, rootId)
+    }
+
+    companion object {
+        /** Whether a bar root with [id] is alive now, in any stack. */
+        fun isLive(id: String): Boolean = LiveIds.has(id)
+
+        /**
+         * Another root that renders at once lives with [id] (a cell of the tabs' custom row): it counts as the bar's
+         * roots do, so a root that stops clears the id's readiness only when it was the last one with it.
+         */
+        internal fun rootMade(id: String) = LiveIds.add(id)
+
+        /** A root of [rootMade] stopped; true when no live root has [id] any more. */
+        internal fun rootStopped(id: String): Boolean = LiveIds.remove(id)
+
+        /** The JavaScript went (a reload): no id counts as held by a live root any more, as `ScreenReadiness.reset`. */
+        fun reset() = LiveIds.clear()
+    }
+
+    // The ids of the bar roots alive now, in every stack: a root that stops clears its id's readiness only when it was
+    // the last one with it.
+    private object LiveIds {
+        private val counts = HashMap<String, Int>()
+
+        fun has(id: String): Boolean = (counts[id] ?: 0) > 0
+
+        fun clear() = counts.clear()
+
+        fun add(id: String) {
+            counts[id] = (counts[id] ?: 0) + 1
+        }
+
+        // True when no root with the id is left.
+        fun remove(id: String): Boolean {
+            val count = (counts[id] ?: return true) - 1
+            if (count <= 0) counts.remove(id) else counts[id] = count
+            return count <= 0
+        }
+    }
+}

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

@@ -0,0 +1,122 @@
+package dev.apexnative.navigation.viewcontrollers.stack.topbar
+
+import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.BarMotion
+
+/**
+ * The bar's row in a default transition of its stack: as the bar takes the incoming screen's options, a picture of the
+ * row and the large title lies over them and the real row turns transparent; then the picture goes with the old screen
+ * and the row comes with the new one ([RowTimeline]). Each change of the stack's current child owns the bar: a newer
+ * one takes it over (the older picture goes, its animator stops), and only the end of the transition that owns it puts
+ * the row back at rest. Without a picture (a `HARDWARE` bitmap in the bar) the old row just hides. Main thread only.
+ */
+internal class BarRowTransition(private val target: Target) {
+    /** What the transition moves: the bar's views, or the unit tests' fake. */
+    interface Target {
+        /**
+         * Lays a picture of the row and the large title over them, laid out at once and taking the touches; false when
+         * the bar can't be drawn in software (a `HARDWARE` bitmap): no picture then.
+         */
+        fun takeSnapshot(): Boolean
+
+        /** The picture goes. */
+        fun dropSnapshot()
+
+        /** The row and the large title as [frame] says; the picture too while it is there. Pixels from dp here. */
+        fun show(frame: RowTimeline.Frame, rtl: Boolean)
+
+        /** The row and the large title at rest: opaque, in their place, without the picture. */
+        fun rest()
+
+        /** The bar's row reads right to left. */
+        val isRtl: Boolean
+
+        /** The slide's curve (`fast_out_extra_slow_in`); the unit tests give a straight line. */
+        val curve: (Float) -> Float
+
+        /** Plays [onFrame] with the time since the start, in milliseconds, for [duration]; the function stops it. */
+        fun play(duration: Long, onFrame: (elapsed: Long) -> Unit): () -> Unit
+    }
+
+    private class Run(val motion: BarMotion)
+
+    private var owner: Run? = null
+    private var stop: (() -> Unit)? = null
+
+    /** A transition owns the bar now. */
+    val isRunning: Boolean
+        get() = owner != null
+
+    /**
+     * The stack's current child changes ([BarMotion], or none for a change at once): what a running transition did to
+     * the row goes, and a default transition takes the picture before the bar takes the new screen's options.
+     */
+    fun begin(motion: BarMotion?) {
+        release()
+        if (motion == null) return
+        val run = Run(motion)
+        owner = run
+        if (!target.takeSnapshot()) target.dropSnapshot()
+        val rtl = target.isRtl
+        val curve = target.curve
+        target.show(RowTimeline.frame(motion, 0L, curve), rtl)
+        stop = target.play(RowTimeline.duration(motion)) { elapsed ->
+            if (owner === run) target.show(RowTimeline.frame(motion, elapsed, curve), rtl)
+        }
+    }
+
+    /**
+     * The transition that brought the current child ended (`operationEnded` with the top settled), or the stack's
+     * animations were all cancelled: the row at rest, the picture gone.
+     */
+    fun end() {
+        if (owner == null) return
+        release()
+    }
+
+    private fun release() {
+        stop?.invoke()
+        stop = null
+        val had = owner != null
+        owner = null
+        if (had) target.rest()
+    }
+}
+
+/**
+ * The timeline of the row in the default transitions: push and pop slide both 96 dp in 450 ms on
+ * `fast_out_extra_slow_in` (the system's transition), the picture fades out linearly in 100 ms and the new row fades in
+ * linearly in 150 ms after 50 ms (push) or 35 ms (pop); fade through (`setStackRoot`): the picture fades out in 105 ms,
+ * the new row is transparent for the first 35 % of 300 ms, then fades in. No scale.
+ */
+internal object RowTimeline {
+    /** The values at one moment: alphas, and shifts along the line in dp (forward is to the end of the line). */
+    class Frame(val snapshotAlpha: Float, val snapshotShift: Float, val rowAlpha: Float, val rowShift: Float)
+
+    const val DISTANCE_DP = 96f
+    private const val SLIDE = 450L
+    private const val SNAPSHOT_FADE = 100L
+    private const val ROW_FADE = 150L
+    private const val PUSH_DELAY = 50L
+    private const val POP_DELAY = 35L
+    private const val FADE_THROUGH = 300L
+    private const val FADE_THROUGH_OUT = 105L
+
+    fun duration(motion: BarMotion): Long = if (motion == BarMotion.FadeThrough) FADE_THROUGH else SLIDE
+
+    fun frame(motion: BarMotion, elapsed: Long, curve: (Float) -> Float): Frame {
+        val slide = curve((elapsed.toFloat() / SLIDE).coerceIn(0f, 1f))
+        val out = 1f - fraction(elapsed, 0L, SNAPSHOT_FADE)
+        return when (motion) {
+            BarMotion.Push -> Frame(out, -DISTANCE_DP * slide, fraction(elapsed, PUSH_DELAY, ROW_FADE),
+                DISTANCE_DP * (1f - slide))
+            BarMotion.Pop -> Frame(out, DISTANCE_DP * slide, fraction(elapsed, POP_DELAY, ROW_FADE),
+                -DISTANCE_DP * (1f - slide))
+            BarMotion.FadeThrough -> Frame(1f - fraction(elapsed, 0L, FADE_THROUGH_OUT), 0f,
+                fraction(elapsed, FADE_THROUGH_OUT, FADE_THROUGH - FADE_THROUGH_OUT), 0f)
+        }
+    }
+
+    // 0 until [delay], then linear to 1 over [duration].
+    private fun fraction(elapsed: Long, delay: Long, duration: Long): Float =
+        ((elapsed - delay).toFloat() / duration).coerceIn(0f, 1f)
+}

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

@@ -0,0 +1,30 @@
+package dev.apexnative.navigation.viewcontrollers.stack.topbar
+
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+/**
+ * The cells of the bar's React buttons (BarButtonComponentCell), by screen and `componentId`: a button of the stack's
+ * or the defaults' options has one `componentId` on every screen, and each screen shows its own root in its own cell,
+ * so the destroy of one screen never empties the cell another shows. A cell lives while its screen names the button.
+ * [make] makes a cell, [empty] takes its content out. Main thread only.
+ */
+internal class ButtonCells<C : Any>(private val make: () -> C, private val empty: (C) -> Unit) {
+    private val cells = HashMap<Pair<ViewController<*>, String>, C>()
+
+    /** The cell of [screen]'s button [componentId]: kept, or made now. */
+    fun cellOf(screen: ViewController<*>, componentId: String): C = cells.getOrPut(screen to componentId, make)
+
+    /** [screen] names only [componentIds] now: the cells of the others go. */
+    fun retain(screen: ViewController<*>, componentIds: Set<String>) =
+        drop { it.first === screen && it.second !in componentIds }
+
+    /** [screen] is destroyed: its cells go, and no other's. */
+    fun screenDestroyed(screen: ViewController<*>) = drop { it.first === screen }
+
+    /** The stack is destroyed: every cell goes. */
+    fun clear() = drop { true }
+
+    private fun drop(which: (Pair<ViewController<*>, String>) -> Boolean) {
+        cells.keys.filter(which).forEach { key -> cells.remove(key)?.let(empty) }
+    }
+}

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

@@ -0,0 +1,65 @@
+package dev.apexnative.navigation.viewcontrollers.stack.topbar
+
+/**
+ * Where the right buttons of the bar go: the bar has as many places as AppCompat gives a toolbar for the window now
+ * ([maxActionButtons]), one less for "⋮" when it shows; the pinned buttons take theirs first, then the buttons with the
+ * highest `priority` (ties by the list's order); the rest go into "⋮". The core counts it, not AppCompat: AppCompat
+ * would share the places in the menu's order, where the first button of the list is the last, and keep the count of the
+ * orientation before a rotation. A pure function.
+ */
+internal object ButtonPlaces {
+    /** A right button as the count sees it: its `priority` ([HIGH], [STANDARD], [LOW]) and `pinned`. */
+    class Button(val priority: Int, val pinned: Boolean)
+
+    /** The plan: the indices of the list in the bar and in "⋮", each in the list's order, and whether "⋮" shows. */
+    class Plan(val inBar: List<Int>, val inOverflow: List<Int>, val showsOverflow: Boolean)
+
+    const val HIGH = 2
+    const val STANDARD = 1
+    const val LOW = 0
+
+    /** The `priority` of a button by its option's value: `high`, `low`, else standard. */
+    fun priorityOf(value: String?): Int = when (value) {
+        "high" -> HIGH
+        "low" -> LOW
+        else -> STANDARD
+    }
+
+    /**
+     * How many buttons AppCompat puts in a toolbar for a window [widthDp] × [heightDp] dp with the smallest width
+     * [smallestDp] (`ActionBarPolicy.getMaxActionButtons`, appcompat 1.7.0): "⋮" counts among them when it shows.
+     */
+    fun maxActionButtons(widthDp: Int, heightDp: Int, smallestDp: Int): Int = when {
+        smallestDp > 600 || widthDp > 600 || (widthDp > 960 && heightDp > 720) || (widthDp > 720 && heightDp > 960) -> 5
+        widthDp >= 500 || (widthDp > 640 && heightDp > 480) || (widthDp > 480 && heightDp > 640) -> 4
+        widthDp >= 360 -> 3
+        else -> 2
+    }
+
+    /**
+     * The plan for [buttons] with [maxPlaces] places, [taken] of them already used by what the core always puts in the
+     * bar (the search's magnifier), and [overflowItems] items of `overflowMenu`, which put "⋮" in the bar whatever
+     * the buttons are.
+     */
+    fun plan(buttons: List<Button>, maxPlaces: Int, taken: Int, overflowItems: Int): Plan {
+        val free = (maxPlaces - taken).coerceAtLeast(0)
+        val needsOverflow = overflowItems > 0 || buttons.size > free
+        var places = if (needsOverflow) (free - 1).coerceAtLeast(0) else free
+        val inBar = HashSet<Int>()
+        buttons.forEachIndexed { index, button ->
+            if (button.pinned) {
+                inBar += index
+                places--
+            }
+        }
+        val byPriority = buttons.indices.filter { !buttons[it].pinned }
+            .sortedWith(compareByDescending<Int> { buttons[it].priority }.thenBy { it })
+        for (index in byPriority) {
+            if (places <= 0) break
+            inBar += index
+            places--
+        }
+        val overflow = buttons.indices.filter { it !in inBar }
+        return Plan(buttons.indices.filter { it in inBar }, overflow, overflowItems > 0 || overflow.isNotEmpty())
+    }
+}