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

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/overlay/OverlayCoordinator.kt

@@ -0,0 +1,383 @@
+package dev.apexnative.navigation.viewcontrollers.overlay
+
+import dev.apexnative.navigation.options.DefaultOptions
+import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.react.CommandAnswer
+import dev.apexnative.navigation.react.ErrorTexts
+import dev.apexnative.navigation.react.events.AppearanceDispatcher
+import dev.apexnative.navigation.viewcontrollers.component.Readiness
+import dev.apexnative.navigation.viewcontrollers.component.RenderWait
+import dev.apexnative.navigation.viewcontrollers.modal.ModalCoordinator
+import dev.apexnative.navigation.viewcontrollers.modal.ModalRecord
+import dev.apexnative.navigation.viewcontrollers.navigator.WaitingLayer
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+/**
+ * The overlays of one activity (`showOverlay`, `dismissOverlay`, `dismissAllOverlays`): in the order they showed, later
+ * above, each waiting for its screens first (the core's one wait, at most [WAIT_LIMIT_MILLIS]) unseen and without
+ * touches, then shown at once — no animation, no part of the navigation state, untouched by `setRoot`, modals and the
+ * rest. An overlay with the root id of a shown one replaces it after its wait. `overlay.interceptTouchOutside` is read
+ * at the show and after each merge and kept ([OverlayRecord.intercepts]): the touches never resolve options. The views,
+ * the readiness and the clock are given, so it runs in unit tests. Main thread only.
+ *
+ * The steps that come later (the wait's timers and readiness signals, and the show at its end with the removal of the
+ * overlay it replaces) run under no runner: each goes through one guard, and a failure there ends the show as one
+ * that couldn't be made, rejecting it with its error text (ARCHITECTURE.md section 5).
+ */
+internal class OverlayCoordinator(
+    private val views: Views,
+    private val readiness: Readiness,
+    private val scheduler: AppearanceDispatcher.Scheduler,
+    private val host: Host,
+) {
+    /** What the overlays ask of their activity's navigation. */
+    interface Host {
+        /** The node with [id] in the activity's registry, as the commands find it; none. */
+        fun find(id: String): ViewController<*>?
+
+        /** [layer] waits to show from now on (`Navigator.addWaitingLayer`). */
+        fun addWaitingLayer(layer: WaitingLayer)
+
+        /** [layer] no longer waits to show. */
+        fun removeWaitingLayer(layer: WaitingLayer)
+
+        /** Writes [text] to the log. */
+        fun log(text: String)
+    }
+
+    /** The views of the overlays layer. Main thread only. */
+    interface Views {
+        /**
+         * The overlay's container joins the overlays layer at the top, waiting: transparent, without touches, unseen by
+         * accessibility, with its root's view in it. It may throw: nothing of it stays then.
+         */
+        fun place(record: OverlayRecord)
+
+        /** The overlay shows: on top, opaque, its touches by [OverlayTouches] with [OverlayRecord.intercepts]. */
+        fun show(record: OverlayRecord)
+
+        /** The overlay's view leaves; the layer hides when it holds none. */
+        fun remove(record: OverlayRecord)
+
+        /** New [options] (resolved) of the overlay: its `testID` (`overlay.testID`). */
+        fun update(record: OverlayRecord, options: Options)
+
+        /** The overlay's views lay out again (the activity resumed). */
+        fun requestLayout(record: OverlayRecord) = Unit
+    }
+
+    private val records = mutableListOf<OverlayRecord>()
+
+    /** Every overlay that waits or shows, bottom to top. */
+    val overlays: List<OverlayRecord>
+        get() = records.toList()
+
+    /** The tops of the overlays, bottom to top: the last layers the repaint walks. */
+    fun layers(): List<ViewController<*>> = records.map { it.root }
+
+    /**
+     * Whether [node] is in an overlay: what the system UI of the top layer asks.
+     */
+    fun isInOverlay(node: ViewController<*>): Boolean = recordOf(node) != null
+
+    /** The overlay [node] is in; none. */
+    fun recordOf(node: ViewController<*>): OverlayRecord? {
+        val top = topOf(node)
+        return records.firstOrNull { it.root === top }
+    }
+
+    /**
+     * The trees of the overlays a new one with the root id [id] replaces: their ids are no other screen's for its
+     * "shows already".
+     */
+    fun isReplacedBy(id: String, node: ViewController<*>): Boolean {
+        val top = topOf(node)
+        return records.any { it.rootId == id && it.root === top }
+    }
+
+    /**
+     * `showOverlay` after its checks: [make] makes the tree, a waiting overlay with the same root id is cancelled (its
+     * show resolves), and [answer] resolves with the overlay's id once it shows. A failure to make or place it goes to
+     * the caller, which rejects.
+     */
+    fun show(make: () -> ViewController<*>, answer: CommandAnswer) {
+        start(make, answer, null)
+    }
+
+    /**
+     * An overlay of a `setRoot`'s layout: made now; [done] once it showed or went. A failure is logged and skipped. The
+     * function returned stops it while it waits (a newer `setRoot`): it goes without a word.
+     */
+    fun showInChain(id: String, make: () -> ViewController<*>, done: () -> Unit): () -> Unit {
+        val record = try {
+            start(make, null, done)
+        } catch (e: Throwable) {
+            val reason = ErrorTexts.reasonOf(e)
+            host.log("[ApexNavigation] setRoot: ${ErrorTexts.couldNot("show the screen '$id'", reason)}")
+            done()
+            return {}
+        }
+        return {
+            record.chainDone = null
+            if (record.state == OverlayRecord.State.Waiting) cancel(record)
+        }
+    }
+
+    /**
+     * `dismissOverlay`: the overlays with the root id [componentId] go — one that waits is cancelled, one that shows
+     * goes with its events (both, when a replacement of a shown one waits) — and [answer] resolves with the id. An id
+     * no node has: `not shown`; a node that is no overlay's root (Android takes only the root's id): `not in an
+     * overlay`.
+     */
+    fun dismiss(componentId: String, answer: CommandAnswer) {
+        if (host.find(componentId) == null) return answer.reject(ErrorTexts.screenNotShown(componentId))
+        val matches = records.filter { it.rootId == componentId }
+        if (matches.isEmpty()) return answer.reject(ErrorTexts.notInOverlay(componentId))
+        matches.filter { it.state == OverlayRecord.State.Waiting }.forEach(::cancel)
+        val shown = matches.filter { it.state == OverlayRecord.State.Shown }
+        if (shown.isEmpty()) return answer.resolve(componentId)
+        shown.dropLast(1).forEach { remove(it, null) }
+        remove(shown.last(), answer)
+    }
+
+    /** `dismissAllOverlays`: every overlay, last to first, as [dismiss] does; `''`. */
+    fun dismissAll(answer: CommandAnswer) {
+        for (record in records.reversed()) {
+            if (record.state == OverlayRecord.State.Waiting) cancel(record) else remove(record, null)
+        }
+        answer.resolve("")
+    }
+
+    /** A `mergeOptions` went into [node]: when it is in an overlay, its options are read again. */
+    fun optionsMergedInto(node: ViewController<*>) {
+        recordOf(node)?.let(::readOptions)
+    }
+
+    /** New default options reach the overlays without their own. */
+    fun defaultOptionsChanged() {
+        records.forEach(::readOptions)
+    }
+
+    /** The activity resumed: the overlays lay out again; nothing is sent. */
+    fun onResume() {
+        records.forEach(views::requestLayout)
+    }
+
+    /**
+     * The activity's layers go: JavaScript reloads (nothing sent, nothing answered) or the activity is destroyed (the
+     * destroy events; a show that waits resolves with its id).
+     */
+    fun destroyAll() {
+        val all = records.toList()
+        records.clear()
+        for (record in all) {
+            record.wait?.cancel()
+            record.wait = null
+            host.removeWaitingLayer(record)
+            record.state = OverlayRecord.State.Gone
+            record.chainDone = null
+            views.remove(record)
+            if (!record.root.isDestroyed) record.root.destroy()
+            record.answer?.resolve(record.rootId)
+            record.answer = null
+        }
+    }
+
+    private fun start(make: () -> ViewController<*>, answer: CommandAnswer?, chainDone: (() -> Unit)?): OverlayRecord {
+        val root = make()
+        val record = OverlayRecord(root)
+        // A waiting layer before its views join the window: what is in it isn't on screen from its first layout.
+        record.screensChanged = { screensChanged(record) }
+        host.addWaitingLayer(record)
+        try {
+            views.place(record)
+        } catch (e: Throwable) {
+            host.removeWaitingLayer(record)
+            root.destroy()
+            throw e
+        }
+        record.answer = answer
+        record.chainDone = chainDone
+        // From here the record is placed: a failure ends its show (failed), so it doesn't stay in the window.
+        guarded(record) {
+            // A waiting overlay of the same id never shows: the new one comes instead.
+            records.filter { it.rootId == record.rootId && it.state == OverlayRecord.State.Waiting }.forEach(::cancel)
+            records += record
+            val wait = RenderWait(
+                readiness = readiness,
+                scheduler = scheduler,
+                limitMillis = WAIT_LIMIT_MILLIS,
+                bar = RenderWait.Bar.WithinLimit,
+                countsUnknownContent = false,
+                step = { work -> guarded(record, work) },
+                onEnd = { guarded(record) { ready(record) } },
+            )
+            record.wait = wait
+            wait.start(RenderWait.waitedScreens(root), RenderWait.unseenScreens(root))
+        }
+        return record
+    }
+
+    private fun screensChanged(record: OverlayRecord) {
+        if (record.state != OverlayRecord.State.Waiting) return
+        val wait = record.wait ?: return
+        guarded(record) { wait.retake(RenderWait.waitedScreens(record.root), RenderWait.unseenScreens(record.root)) }
+    }
+
+    // The wait ended: a shown overlay of the same id goes first, as `dismissOverlay` without an answer of its own; then
+    // this one shows on top, with WillAppear and DidAppear at once and its answer.
+    private fun ready(record: OverlayRecord) {
+        if (record.state != OverlayRecord.State.Waiting) return
+        record.wait = null
+        host.removeWaitingLayer(record)
+        records.filter { it !== record && it.rootId == record.rootId && it.state == OverlayRecord.State.Shown }
+            .forEach { remove(it, null) }
+        record.state = OverlayRecord.State.Shown
+        try {
+            readOptions(record)
+            views.show(record)
+        } catch (e: Throwable) {
+            return failed(record, e)
+        }
+        // The answer and the chain's step stay on the record until the events went: a failure among them still answers.
+        val answer = record.answer
+        val done = record.chainDone
+        AppearanceDispatcher.beginTransition(listOf(record.root))
+        // In a `setRoot`'s chain the state goes once, before its answer.
+        AppearanceDispatcher.endTransition(
+            hiding = emptyList(),
+            showing = listOf(record.root),
+            events = null,
+            answer = answer,
+            value = record.rootId,
+            reportsState = done == null,
+        )
+        record.answer = null
+        record.chainDone = null
+        done?.invoke()
+    }
+
+    // The show couldn't be made, or a later step of it failed: the overlay goes, its show rejects (the chain logs and
+    // goes on). Its views and its root go each on their own: a part that fails again doesn't keep the rest from
+    // running.
+    private fun failed(record: OverlayRecord, e: Throwable) {
+        val text = ErrorTexts.couldNot("show the screen '${record.rootId}'", ErrorTexts.reasonOf(e))
+        record.wait?.cancel()
+        record.wait = null
+        host.removeWaitingLayer(record)
+        record.state = OverlayRecord.State.Gone
+        records.remove(record)
+        runCatching { views.remove(record) }
+        runCatching { if (!record.root.isDestroyed) record.root.destroy() }
+        if (record.answer == null && record.chainDone == null) host.log("[ApexNavigation] $text")
+        record.answer?.reject(text)
+        record.answer = null
+        record.chainDone?.let {
+            record.chainDone = null
+            host.log("[ApexNavigation] setRoot: $text")
+            it()
+        }
+    }
+
+    // A waiting overlay goes: nothing was sent for it; its show resolves with its id.
+    private fun cancel(record: OverlayRecord) {
+        record.wait?.cancel()
+        record.wait = null
+        host.removeWaitingLayer(record)
+        record.state = OverlayRecord.State.Gone
+        records.remove(record)
+        views.remove(record)
+        if (!record.root.isDestroyed) record.root.destroy()
+        record.answer?.resolve(record.rootId)
+        record.answer = null
+        record.chainDone?.let {
+            record.chainDone = null
+            it()
+        }
+    }
+
+    // A shown overlay goes at once: DidDisappear of its screens, then its content stops, then [answer] with its id. Its
+    // view leaves whatever happens to its events: the record is gone, nothing would remove it later.
+    private fun remove(record: OverlayRecord, answer: CommandAnswer?) {
+        record.state = OverlayRecord.State.Gone
+        records.remove(record)
+        try {
+            AppearanceDispatcher.endTransition(
+                hiding = listOf(record.root),
+                showing = emptyList(),
+                events = { if (!record.root.isDestroyed) record.root.destroy() },
+                answer = answer,
+                value = record.rootId,
+            )
+        } finally {
+            views.remove(record)
+        }
+    }
+
+    // A step of [record]'s show that comes later, under no runner: a failure ends the show ([failed]).
+    private inline fun guarded(record: OverlayRecord, work: () -> Unit) {
+        try {
+            work()
+        } catch (e: Throwable) {
+            failed(record, e)
+        }
+    }
+
+    private fun readOptions(record: OverlayRecord) {
+        if (record.root.isDestroyed) return
+        val options = record.root.resolveShownOptions(DefaultOptions.current)
+        record.intercepts = options.overlay.interceptTouchOutside.isTrue
+        views.update(record, options)
+    }
+
+    private fun topOf(node: ViewController<*>): ViewController<*> {
+        var current = node
+        while (true) current = current.parentController ?: return current
+    }
+
+    companion object {
+        /** How long an overlay waits for its screens at most: the unset rule of the modals. */
+        const val WAIT_LIMIT_MILLIS = ModalCoordinator.WAIT_LIMIT_MILLIS
+    }
+}
+
+/**
+ * One overlay of an activity: its layout's top node, whether it waits or shows, and what it keeps for the touches.
+ * While it waits it is a [WaitingLayer] of its activity. Main thread only.
+ */
+internal class OverlayRecord(
+    /** The top node of the overlay's layout. */
+    val root: ViewController<*>,
+) : WaitingLayer {
+    /** Where the overlay is. */
+    enum class State { Waiting, Shown, Gone }
+
+    /** The id `showOverlay` answers with, which `dismissOverlay` takes. */
+    val rootId: String = root.id
+
+    /** The state; the coordinator moves it. */
+    var state = State.Waiting
+
+    /** `overlay.interceptTouchOutside` of its options, read at the show and after each merge. */
+    var intercepts = false
+
+    /** The answer of its `showOverlay`; none in a `setRoot`'s chain, or once answered. */
+    var answer: CommandAnswer? = null
+
+    /** The step of a `setRoot`'s chain that waits for its show; none. */
+    var chainDone: (() -> Unit)? = null
+
+    /** The wait for its screens while it waits. */
+    var wait: RenderWait? = null
+
+    /** A stack in it changed its top while it waits: the coordinator's handler. */
+    var screensChanged: () -> Unit = {}
+
+    override val waitingNode: ViewController<*>?
+        get() = root.takeIf { state == State.Waiting }
+
+    override fun shownScreensChanged() = screensChanged()
+
+    /** The ids of every node of the overlay now. */
+    fun ids(): Set<String> = ModalRecord.idsOf(root)
+}

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/overlay/OverlayTouches.kt

@@ -0,0 +1,44 @@
+package dev.apexnative.navigation.viewcontrollers.overlay
+
+/**
+ * Whether an overlay takes a touch, decided at its down, for the whole gesture, before React Native's root sees it.
+ * With `overlay.interceptTouchOutside: true` the overlay takes every touch. Otherwise a touch on a screen's React
+ * content goes to the overlay only when React Native's own touch target search (honoring `pointerEvents`: `box-none`
+ * takes nothing) finds a view other than the content's root; a touch on the overlay's own native views (a bar) is the
+ * overlay's; every other touch goes to the layers under it. Pure.
+ */
+internal object OverlayTouches {
+    /** Where a touch landed in an overlay. */
+    enum class Place {
+        /** On a screen's React content: the target search decides. */
+        Content,
+
+        /** On a screen's view but outside its React content (what the system covers, kept as padding). */
+        Screen,
+
+        /** On the overlay's own native views: a bar, a native screen. */
+        OwnView,
+
+        /** Outside the overlay's views. */
+        Outside,
+    }
+
+    /**
+     * Whether the overlay takes the touch at [place]: [intercepts] (`interceptTouchOutside`); on the content, when the
+     * target search found [target] other than [contentRoot] (the tag of the content's root view, which the search
+     * answers with for the root alone and for nothing).
+     */
+    fun takes(intercepts: Boolean, place: Place, target: Int, contentRoot: Int): Boolean = when {
+        intercepts -> true
+        place == Place.Content -> target != contentRoot
+        place == Place.OwnView -> true
+        else -> false
+    }
+
+    /**
+     * Whether a touch at [y] (in the window) on a screen lands on the bars of its layouts over its content: above the
+     * bottom of its stack's header ([headerBottom]) or below the top of its tabs ([tabsTop]); none of them: no.
+     */
+    fun isOnBars(y: Float, headerBottom: Int?, tabsTop: Int?): Boolean =
+        (headerBottom != null && y < headerBottom) || (tabsTop != null && y >= tabsTop)
+}

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/overlay/OverlayViews.kt

@@ -0,0 +1,117 @@
+package dev.apexnative.navigation.viewcontrollers.overlay
+
+import android.content.Context
+import android.view.MotionEvent
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import com.facebook.react.uimanager.TouchTargetHelper
+import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.utils.TestIds
+import dev.apexnative.navigation.viewcontrollers.component.ComponentViewController
+import dev.apexnative.navigation.viewcontrollers.parent.ParentController
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+/**
+ * The views of the overlays of one activity ([OverlayCoordinator.Views]): an [OverlayContainer] per overlay in the
+ * overlays layer, later above earlier, the layer visible only while it holds one. An overlay's touches are decided by
+ * React Native's public touch target search over each screen's React content (`TouchTargetHelper`), never by the core
+ * walking React Native's views. Main thread only.
+ */
+internal class OverlayViews(
+    // The activity's context: the containers' views are made with it.
+    private val context: Context,
+    private val layer: FrameLayout,
+) : OverlayCoordinator.Views {
+    private val containers = HashMap<OverlayRecord, OverlayContainer>()
+
+    override fun place(record: OverlayRecord) {
+        val container = OverlayContainer(context)
+        container.isWaiting = true
+        container.alpha = 0f
+        container.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS
+        try {
+            val view = record.root.view
+            (view.parent as? ViewGroup)?.removeView(view)
+            container.addView(view, FrameLayout.LayoutParams(MATCH, MATCH))
+            layer.addView(container, FrameLayout.LayoutParams(MATCH, MATCH))
+        } catch (e: Throwable) {
+            (container.parent as? ViewGroup)?.removeView(container)
+            throw e
+        }
+        containers[record] = container
+        layer.visibility = View.VISIBLE
+    }
+
+    override fun show(record: OverlayRecord) {
+        val container = containers[record] ?: return
+        container.takesTouch = { takes(record, container, it) }
+        container.isWaiting = false
+        container.alpha = 1f
+        container.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_AUTO
+        container.bringToFront()
+    }
+
+    override fun remove(record: OverlayRecord) {
+        val container = containers.remove(record) ?: return
+        (container.parent as? ViewGroup)?.removeView(container)
+        if (layer.childCount == 0) layer.visibility = View.GONE
+    }
+
+    override fun update(record: OverlayRecord, options: Options) {
+        containers[record]?.let { TestIds.apply(it, options.overlay.testID.value?.ifEmpty { null }) }
+    }
+
+    override fun requestLayout(record: OverlayRecord) {
+        containers[record]?.requestLayout()
+    }
+
+    // Where the down of a gesture landed, and React Native's target there when it is on a screen's content.
+    private fun takes(record: OverlayRecord, container: OverlayContainer, event: MotionEvent): Boolean {
+        if (record.intercepts) return true
+        val origin = locationOf(container)
+        val x = origin[0] + event.x
+        val y = origin[1] + event.y
+        for (screen in shownScreens(record.root)) {
+            val screenView = screen.peekView() ?: continue
+            if (!contains(screenView, x, y)) continue
+            // The bar or the tabs over the screen's content (`drawBehind`) are the overlay's own views.
+            val layout = screen.parentController
+            if (OverlayTouches.isOnBars(y, layout?.headerBottomOf(screen), layout?.tabsTopOf(screen))) {
+                return OverlayTouches.takes(false, OverlayTouches.Place.OwnView, NO_TARGET, NO_TARGET)
+            }
+            // A native screen is the overlay's own view.
+            val content = (screen as? ComponentViewController)?.content ?: return true
+            val root = content.touchRoot
+            if (root == null || !contains(root, x, y)) {
+                return OverlayTouches.takes(false, OverlayTouches.Place.Screen, NO_TARGET, NO_TARGET)
+            }
+            val at = locationOf(root)
+            val target = TouchTargetHelper.findTargetTagForTouch(x - at[0], y - at[1], root)
+            return OverlayTouches.takes(false, OverlayTouches.Place.Content, target, root.id)
+        }
+        val place = if (record.root.peekView()?.let { contains(it, x, y) } == true) {
+            OverlayTouches.Place.OwnView
+        } else {
+            OverlayTouches.Place.Outside
+        }
+        return OverlayTouches.takes(false, place, NO_TARGET, NO_TARGET)
+    }
+
+    // The screens the overlay shows, down the visible children of its layouts.
+    private fun shownScreens(node: ViewController<*>): List<ViewController<*>> =
+        if (node is ParentController<*>) node.visibleChildren().flatMap(::shownScreens) else listOf(node)
+
+    private fun locationOf(view: View): IntArray = IntArray(2).also(view::getLocationInWindow)
+
+    private fun contains(view: View, x: Float, y: Float): Boolean {
+        if (!view.isShown) return false
+        val at = locationOf(view)
+        return x >= at[0] && x < at[0] + view.width && y >= at[1] && y < at[1] + view.height
+    }
+
+    private companion object {
+        const val MATCH = ViewGroup.LayoutParams.MATCH_PARENT
+        const val NO_TARGET = View.NO_ID
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/parent/Capabilities.kt

@@ -0,0 +1,62 @@
+package dev.apexnative.navigation.viewcontrollers.parent
+
+import dev.apexnative.navigation.react.CommandListener
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+// The capabilities of a node: what the core asks a layout for where it needs the behavior of a split view or a pair,
+// instead of checking its class. A node without one answers "no". The names are the same on iOS:
+// returnsScreenFromColumn, screensLeavingWithNode, childOffsetFromRest, optionsScreen, keepsStatusBarRoom.
+
+/** "Returns a screen from a column": the pop of the only screen of a column goes back to the column before. */
+interface ReturnsScreenFromColumn {
+    /**
+     * [screen], the only screen of its column, goes back: the column goes away, and [done] runs once it has stopped
+     * moving. False when this isn't the node's case: the core pops as in any stack, and [done] doesn't run.
+     */
+    fun returnsScreenFromColumn(screen: ViewController<*>, done: Runnable): Boolean
+}
+
+/** "Screens that leave with the node": a node taken off a stack takes these screens with it (`ANN.ScreenPopped`). */
+interface ScreensLeavingWithNode {
+    val screensLeavingWithNode: List<ViewController<*>>
+}
+
+/**
+ * "Child offset from rest": a child that moves (a side menu's drawer, a sliding pane) counts its safe area where it
+ * comes to rest; a screen adds what every layout on its way gives (`ComponentViewController.updateSafeArea`).
+ */
+interface ChildOffsetFromRest {
+    /** How far [child] is from where it rests, in pixels along the width; 0 for a child at rest. */
+    fun childOffsetFromRest(child: ViewController<*>): Int
+}
+
+/** "The screen whose options are the node's": the bar, the search, the status bar and the animations take its. */
+interface OptionsScreen {
+    val optionsScreen: ViewController<*>
+}
+
+/** "Keeps the status bar room for its screens": the node keeps it at its own top, its screens keep none. */
+interface KeepsStatusBarRoom
+
+/** A node that shows screens in its columns (the split view): `showInColumn` and `setColumnShown` go to it. */
+interface ShowsColumns {
+    /**
+     * Shows [screen] in the column after the first one, in place of what it shows; [listener] once it shows, or with
+     * the error reason, which names [from], the screen the command comes from. False when the node doesn't take it now
+     * (its compact layout shows): the core pushes the screen over [from] instead.
+     */
+    fun showScreen(screen: ViewController<*>, from: ViewController<*>, listener: CommandListener): Boolean
+
+    /** Shows or hides [column]; [done] once the columns have stopped moving. */
+    fun setColumnShown(column: String, shown: Boolean, done: Runnable)
+}
+
+/** The nearest node with the capability [T] from [node] up through the layouts around it; none without one. */
+inline fun <reified T : Any> nodeWith(node: ViewController<*>): T? {
+    var current: ViewController<*>? = node
+    while (current != null) {
+        if (current is T) return current
+        current = current.parentController
+    }
+    return null
+}

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/parent/ContainerBackground.kt

@@ -0,0 +1,43 @@
+package dev.apexnative.navigation.viewcontrollers.parent
+
+import android.graphics.Color
+import android.graphics.drawable.ColorDrawable
+import android.graphics.drawable.Drawable
+import android.graphics.drawable.LayerDrawable
+import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.utils.SystemUiUtils
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+/**
+ * The background of a stack's and of the tabs' view (`layout.backgroundColor`): `layout.backgroundColor` of the options
+ * the layout shows with (its visible screen's over its own over the defaults), kept out of the status bar's height as a
+ * screen's is (`ScreenSafeArea.backgroundBand`); it shows around the screens during transitions. Without the option no
+ * background (the window shows); `'NoColor'` transparent. The layers of the navigation never paint; the side menu
+ * paints its own. Main thread only.
+ */
+internal object ContainerBackground {
+    /** Whether a merge of [options] changes the background: its color, or the status bar's room. */
+    fun isTouchedBy(options: Options): Boolean = options.layout.backgroundColor.hasValue() ||
+        options.statusBar.visible.hasValue() || options.statusBar.drawBehind.hasValue()
+
+    /** [node]'s view takes the background of [options], resolved; nothing before the view is made. */
+    fun apply(node: ViewController<*>, options: Options) {
+        val view = node.peekView() ?: return
+        view.background = backgroundOf(node, options)
+    }
+
+    private fun backgroundOf(node: ViewController<*>, options: Options): Drawable? {
+        val colour = options.layout.backgroundColor
+        if (!colour.hasValue()) return null
+        val color = colour.get(node.activity, Color.TRANSPARENT) ?: Color.TRANSPARENT
+        // The screens' band rule (`ScreenSafeArea.backgroundBand`) for a layout, which keeps no room at its top: the
+        // status bar's height, but none when it is hidden or the layout is drawn under it, in a side menu, a sheet or
+        // a pair.
+        val full = options.statusBar.isHiddenOrDrawBehind || node.isInSideMenu || node.isInSheet ||
+            node.parentController is KeepsStatusBarRoom
+        val band = if (full) 0 else SystemUiUtils.getStatusBarHeight(node.activity)
+        if (band <= 0) return ColorDrawable(color)
+        // A layer inset reports no padding, so the view keeps its own.
+        return LayerDrawable(arrayOf<Drawable>(ColorDrawable(color))).apply { setLayerInset(0, 0, band, 0, 0) }
+    }
+}