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

package/android/src/main/java/dev/apexnative/navigation/system/AppDirection.kt

@@ -0,0 +1,92 @@
+package dev.apexnative.navigation.system
+
+import android.content.Context
+import android.text.TextUtils
+import android.view.View
+import com.facebook.react.modules.i18nmanager.I18nUtil
+import dev.apexnative.navigation.options.Options
+import java.util.Locale
+
+/**
+ * The direction of the app on Android: `layout.direction` of the default options — and of the root's own options at
+ * `setRoot` — set on the activity's views and on React Native. Each activity's owner applies it
+ * ([SystemUiOwner.applyDirection]) and remembers what it applied; this object keeps only the direction the last default
+ * options brought, a value with no views, so that `setDefaultOptions` acts only when that direction changed. Without
+ * the key nothing changes, and the bars and the tabs follow React Native's direction ([isReactNativeRtl]). Main thread
+ * only.
+ */
+internal object AppDirection {
+    private const val LTR = "ltr"
+    private const val RTL = "rtl"
+    private const val LOCALE = "locale"
+
+    /** The direction of the last default options, to tell a change from the same value sent again. */
+    class Defaults {
+        private var last: String? = null
+
+        /** New default options with [direction]: it when it differs from the previous defaults' and is set. */
+        fun changed(direction: String?): String? {
+            val changed = direction != last
+            last = direction
+            return direction.takeIf { changed }
+        }
+    }
+
+    private val defaults = Defaults()
+
+    /**
+     * New default options came (`setDefaultOptions`): their `layout.direction` when it changed from the one the
+     * previous defaults brought; none when it is the same or unset (a root's own direction stays then).
+     */
+    fun defaultsChanged(options: Options): String? = defaults.changed(options.layout.direction.get(null))
+
+    /** The direction `setRoot` applies: the root's own `layout.direction` over the defaults'. */
+    fun ofRoot(root: Options, defaults: Options): String? =
+        root.layout.direction.get(null) ?: defaults.layout.direction.get(null)
+
+    /**
+     * Whether [direction] is right to left now: `rtl` yes, `ltr` no, `locale` as the device's language now
+     * ([localeIsRtl]) — React Native's own check doesn't read the current language.
+     */
+    fun rtlNow(direction: String, localeIsRtl: Boolean): Boolean = when (direction) {
+        RTL -> true
+        LOCALE -> localeIsRtl
+        else -> false
+    }
+
+    /** [direction] as a view takes it; none for a value that is no direction. */
+    fun viewDirectionOf(direction: String): Int? = when (direction) {
+        LTR -> View.LAYOUT_DIRECTION_LTR
+        RTL -> View.LAYOUT_DIRECTION_RTL
+        LOCALE -> View.LAYOUT_DIRECTION_LOCALE
+        else -> null
+    }
+
+    /** The device's language now is written right to left. */
+    fun isLocaleRtl(): Boolean =
+        TextUtils.getLayoutDirectionFromLocale(Locale.getDefault()) == View.LAYOUT_DIRECTION_RTL
+
+    /**
+     * [viewDirection] (`View.LAYOUT_DIRECTION_*`) as a view resolves it, for a drawable, which resolves nothing itself:
+     * right to left only where the app supports it ([rtlSupported], `android:supportsRtl`), `LOCALE` as the device's
+     * language now ([localeIsRtl]), anything else left to right.
+     */
+    fun resolvedViewDirection(viewDirection: Int, localeIsRtl: Boolean, rtlSupported: Boolean): Int {
+        val rtl = when (viewDirection) {
+            View.LAYOUT_DIRECTION_RTL -> true
+            View.LAYOUT_DIRECTION_LOCALE -> localeIsRtl
+            else -> false
+        }
+        return if (rtl && rtlSupported) View.LAYOUT_DIRECTION_RTL else View.LAYOUT_DIRECTION_LTR
+    }
+
+    /**
+     * React Native's direction: right to left when forced, or allowed and the device's language is, with `supportsRtl`.
+     * The bars and the tabs follow it without `layout.direction`.
+     */
+    fun isReactNativeRtl(context: Context): Boolean {
+        // A context without an application (the unit tests' stubs) has no React Native settings to read.
+        if (context.applicationInfo == null) return false
+        return I18nUtil.instance.isRTL(context)
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/system/SystemUiLayers.kt

@@ -0,0 +1,126 @@
+package dev.apexnative.navigation.system
+
+import dev.apexnative.navigation.options.DefaultOptions
+import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.viewcontrollers.bottomtabs.BottomTabsController
+import dev.apexnative.navigation.viewcontrollers.modal.ModalRecord
+import dev.apexnative.navigation.viewcontrollers.parent.OptionsScreen
+import dev.apexnative.navigation.viewcontrollers.parent.ParentController
+import dev.apexnative.navigation.viewcontrollers.parent.nodeWith
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+/**
+ * Which layer of an activity decides each group of the system UI. The layers that show, bottom to top: the root, the
+ * modals that show or come in, the overlays that show. The top modal (any style) or else the root decides every group,
+ * but a sheet leaves the status bar to the first layer under it that isn't a sheet. An overlay decides a group only
+ * when its own and its parents' options name a key of it — never the app's defaults —, the topmost such overlay; the
+ * groups it doesn't name stay with the layers under it. [pick] is pure; [layerOf] and [overlayOf] read a layer's nodes.
+ * Main thread only.
+ */
+internal object SystemUiLayers {
+    /**
+     * The groups of the system UI a layer may decide on Android. [Keyboard] is whether the window resizes for the
+     * keyboard without edge to edge; the top layer that isn't an overlay decides it (overlays don't name it).
+     */
+    enum class Group { StatusBar, NavigationBar, Orientation, Keyboard }
+
+    /** What a layer is in the activity. */
+    enum class Kind { Root, Modal, Overlay }
+
+    /**
+     * A layer that shows: its [kind], whether it is a sheet, the groups its options name (counted for overlays), and
+     * the screen that decides for it, read only when asked.
+     */
+    class Layer(
+        val kind: Kind,
+        val isSheet: Boolean,
+        val named: Set<Group>,
+        read: () -> SystemUiRules.Screen,
+    ) {
+        /** The screen that decides for the layer: the end of its shown chain, with its resolved options. */
+        val screen: SystemUiRules.Screen by lazy(LazyThreadSafetyMode.NONE, read)
+    }
+
+    /** The layer that decides each group; none for a group no layer decides: the window keeps it as it is. */
+    class Picked(
+        val statusBar: Layer?,
+        val navigationBar: Layer?,
+        val orientation: Layer?,
+        val keyboard: Layer?,
+    )
+
+    /** Who decides each group among [layers], bottom to top; none when no layer shows. */
+    fun pick(layers: List<Layer>): Picked? {
+        if (layers.isEmpty()) return null
+        val under = layers.filter { it.kind != Kind.Overlay }
+        val overlays = layers.filter { it.kind == Kind.Overlay }
+        fun overlayFor(group: Group): Layer? = overlays.lastOrNull { group in it.named }
+        val top = under.lastOrNull()
+        // A sheet keeps the status bar of the layer under it; with sheets only (no root yet) nothing decides it.
+        val statusBar = under.lastOrNull { !it.isSheet }
+        return Picked(
+            statusBar = overlayFor(Group.StatusBar) ?: statusBar,
+            navigationBar = overlayFor(Group.NavigationBar) ?: top,
+            orientation = overlayFor(Group.Orientation) ?: top,
+            keyboard = top,
+        )
+    }
+
+    /**
+     * Whether a modal in [state] counts as a layer: it shows or comes in; not one that waits, goes, or went with an
+     * old root (its effective state, `ModalRecord.effective`).
+     */
+    fun modalCounts(state: ModalRecord.State): Boolean =
+        state == ModalRecord.State.Presenting || state == ModalRecord.State.Shown
+
+    /** The groups [options] name: a key of the status bar, of the navigation bar, `layout.orientation`. */
+    fun namedGroups(options: Options): Set<Group> {
+        val named = HashSet<Group>()
+        val statusBar = options.statusBar
+        // Only the keys Android reads: `animate`, `hideWithTopBar` and `blur` are iOS's.
+        val androidStatusBar = statusBar.visible.hasValue() || statusBar.style.hasValue() ||
+            statusBar.backgroundColor.hasValue() || statusBar.drawBehind.hasValue() || statusBar.translucent.hasValue()
+        if (androidStatusBar) named += Group.StatusBar
+        if (options.navigationBar.hasValue()) named += Group.NavigationBar
+        if (options.layout.orientation != null) named += Group.Orientation
+        return named
+    }
+
+    /** The root or a modal ([kind]) whose top node is [node]: its shown options with the app's defaults. */
+    fun layerOf(node: ViewController<*>, kind: Kind, isSheet: Boolean): Layer =
+        Layer(kind, isSheet, emptySet()) { screenOf(node, node.resolveShownOptions(DefaultOptions.current)) }
+
+    /**
+     * An overlay whose top node is [node]: what its own and its parents' options name, and its values from those
+     * options only, without the app's defaults.
+     */
+    fun overlayOf(node: ViewController<*>): Layer {
+        val options = node.resolveShownOptions(Options())
+        return Layer(Kind.Overlay, isSheet = false, named = namedGroups(options)) { screenOf(node, options) }
+    }
+
+    // The screen at the end of the chain [node] shows with (as `ParentController.resolveShownOptions` walks: a pair's
+    // options screen, else the current child), and where it is.
+    private fun screenOf(node: ViewController<*>, options: Options): SystemUiRules.Screen {
+        val screen = shownEnd(node)
+        return SystemUiRules.Screen(
+            options = options,
+            inStack = screen.findParentStack() != null,
+            inTabs = screen.parentController?.let { nodeWith<BottomTabsController>(it) } != null,
+            inSheet = screen.isInSheet,
+        )
+    }
+
+    private fun shownEnd(node: ViewController<*>): ViewController<*> {
+        var current = node
+        while (true) {
+            val parent = current as? ParentController<*> ?: return current
+            val optionsScreen = (parent as? OptionsScreen)?.optionsScreen
+            current = if (optionsScreen != null && optionsScreen !== parent) {
+                optionsScreen
+            } else {
+                parent.currentChild ?: return parent
+            }
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/system/SystemUiOwner.kt

@@ -0,0 +1,229 @@
+package dev.apexnative.navigation.system
+
+import android.app.Activity
+import android.view.ViewGroup
+import dev.apexnative.navigation.NavigationActivity
+import dev.apexnative.navigation.options.Options
+
+/**
+ * The one owner of the system UI of an activity: the status bar, the navigation bar, the requested orientation and
+ * (without edge to edge) the window's resize for the keyboard follow the screen on top of the layer that decides each
+ * group ([SystemUiLayers]). Every change — a screen appears or disappears, a side menu comes to rest, a merge, new
+ * default options, a light/dark switch, a configuration change, a new mode of the navigation bar — only marks it
+ * ([invalidate]); once before the next frame it resolves the deciding screens, computes the state ([SystemUiRules]) and
+ * writes to the window only the fields that differ from the state it applied last, the first time all of them; a group
+ * no layer decides (only sheets, or overlays that don't name it) stays as the window has it. Nothing is applied inside
+ * the caller's call, and nothing waits.
+ *
+ * Each activity's navigator has its own, made with it; it does nothing before [start] and after [release], so an old
+ * activity's owner never touches a new one's window, and nothing process-wide holds it. It also applies the app's
+ * direction to its activity ([applyDirection]). [layers] gives the layers that show, bottom to top. Main thread only.
+ */
+internal class SystemUiOwner(private val layers: () -> List<SystemUiLayers.Layer>) {
+    private var window: SystemUiWindow? = null
+    private var remembered: SystemUiWindow.Remembered? = null
+    private var released = false
+    private var applied: SystemUiState? = null
+    // The groups [applied] holds written values of; a group no layer decided yet was never written.
+    private val appliedGroups = HashSet<SystemUiLayers.Group>()
+    private var pending = false
+    // A change other than new default options asked in this frame: the orientation applies.
+    private var orientationAsked = false
+    private var mode = SystemUiRules.initialMode(0)
+    private var appliedDirection: String? = null
+    // The window was told the keyboard covers the screen and wasn't told back yet.
+    private var keyboardCovered = false
+    // One instance, so the post can be taken back.
+    private val applyTask = Runnable { applyNow() }
+
+    /**
+     * The activity was created ([window]): what its theme and manifest give is remembered before anything changes
+     * them. Once.
+     */
+    fun start(window: SystemUiWindow) {
+        if (released || this.window != null) return
+        this.window = window
+        remembered = window.start()
+        mode = SystemUiRules.initialMode(window.sdk)
+    }
+
+    /** The layers joined [content]: the bars' views go over them, and the owner watches the window's insets. */
+    fun attach(content: ViewGroup) {
+        window?.attach(content, ::barsChanged)
+    }
+
+    /** Something the system UI depends on changed: it applies once before the next frame. */
+    fun invalidate() {
+        if (window == null) return
+        orientationAsked = true
+        schedule()
+    }
+
+    /**
+     * New default options (`Navigator.repaint`): the bars apply again, the orientation as it is applied unless another
+     * change of the same frame asks for it.
+     */
+    fun invalidateKeepingOrientation() {
+        if (window == null) return
+        schedule()
+    }
+
+    /** The configuration changed: the next apply writes every field again, once. */
+    fun configurationChanged() {
+        if (window == null) return
+        applied = null
+        appliedGroups.clear()
+        invalidate()
+    }
+
+    /**
+     * The app's [direction] for this activity (`setRoot` step 1, `setDefaultOptions`): the activity's views and React
+     * Native take it, unless it is the one applied already. None: nothing changes.
+     */
+    fun applyDirection(direction: String?) {
+        val window = window ?: return
+        if (direction == null || direction == appliedDirection) return
+        val layoutDirection = AppDirection.viewDirectionOf(direction) ?: return
+        appliedDirection = direction
+        window.setDirection(layoutDirection, AppDirection.rtlNow(direction, window.isLocaleRtl()))
+    }
+
+    /** The activity is destroyed: the pending apply, the views and the listeners go; the owner does nothing after. */
+    fun release() {
+        val window = window ?: return
+        window.cancel(applyTask)
+        window.release()
+        this.window = null
+        released = true
+        pending = false
+        applied = null
+        appliedGroups.clear()
+        remembered = null
+    }
+
+    private fun schedule() {
+        val window = window ?: return
+        if (pending) return
+        pending = true
+        window.post(applyTask)
+    }
+
+    // The window's insets changed: a new mode or side of the navigation bar applies again.
+    private fun barsChanged() {
+        val window = window ?: return
+        val now = SystemUiRules.navigationMode(window.sdk, window.bars(), mode)
+        if (now == mode) return
+        mode = now
+        invalidate()
+    }
+
+    private fun applyNow() {
+        pending = false
+        val window = window ?: return
+        val remembered = remembered ?: return
+        val orientation = orientationAsked
+        orientationAsked = false
+        // With no layer showing (before the first root, after a reload) the window keeps what it has.
+        val picked = SystemUiLayers.pick(layers()) ?: return
+        mode = SystemUiRules.navigationMode(window.sdk, window.bars(), mode)
+        val environment = SystemUiRules.Environment(
+            edgeToEdge = window.isEdgeToEdge,
+            night = window.isNight(),
+            threeButtons = mode.threeButtons,
+            themeStatusBarColor = remembered.statusBarColor,
+            themeNavigationBarColor = remembered.navigationBarColor,
+            manifestOrientation = remembered.orientation,
+            windowBackground = window.windowBackground(),
+            topBarDefaultColor = window.topBarDefaultColor(),
+            tabsDefaultColor = window.tabsDefaultColor(),
+            colour = window::colourOf,
+        )
+        val deciders = mapOf(
+            SystemUiLayers.Group.StatusBar to picked.statusBar,
+            SystemUiLayers.Group.NavigationBar to picked.navigationBar,
+            SystemUiLayers.Group.Orientation to picked.orientation,
+            SystemUiLayers.Group.Keyboard to picked.keyboard,
+        )
+        // A group no layer decides (only sheets, or overlays that don't name it) stays as the window has it.
+        val decided = deciders.filterValues { it != null }.keys
+        if (decided.isEmpty()) return
+        var state = SystemUiRules.state(
+            statusBar = picked.statusBar?.screen ?: UNDECIDED,
+            navigationBar = picked.navigationBar?.screen ?: UNDECIDED,
+            orientation = picked.orientation?.screen ?: UNDECIDED,
+            keyboard = picked.keyboard?.screen ?: UNDECIDED,
+            environment = environment,
+        )
+        val last = applied
+        if (last != null) {
+            for (group in SystemUiLayers.Group.entries) {
+                val kept = group !in decided ||
+                    (group == SystemUiLayers.Group.Orientation && !orientation && group in appliedGroups)
+                if (kept) state = state.keeping(last, group)
+            }
+        }
+        val fields = state.changedFrom(last).toMutableSet()
+        // A group decided for the first time is written whole.
+        for (group in decided - appliedGroups) fields += SystemUiState.Field.entries.filter { groupOf(it) == group }
+        // The window's soft input mode stays the app's unless a screen asks the keyboard to cover it: never with edge
+        // to edge, where the window doesn't resize; and "resize again" only after "cover".
+        if (window.isEdgeToEdge || state.keyboardCovers == keyboardCovered) fields -= SystemUiState.Field.KeyboardCovers
+        for (field in SystemUiState.Field.entries) {
+            if (field in fields && groupOf(field) in decided) write(window, state, field)
+        }
+        applied = state
+        appliedGroups += decided
+    }
+
+    private fun write(window: SystemUiWindow, state: SystemUiState, field: SystemUiState.Field) = when (field) {
+        SystemUiState.Field.StatusBarShown -> window.setStatusBarShown(state.statusBarShown)
+        SystemUiState.Field.StatusBarColor -> window.setStatusBarColor(state.statusBarColor)
+        SystemUiState.Field.StatusBarIcons -> window.setStatusBarLightIcons(state.statusBarLightIcons)
+        SystemUiState.Field.NavigationBarShown -> window.setNavigationBarShown(state.navigationBarShown)
+        SystemUiState.Field.NavigationBarColor -> window.setNavigationBarColor(state.navigationBarColor)
+        SystemUiState.Field.NavigationBarButtons -> window.setNavigationBarLightButtons(state.navigationBarLightButtons)
+        SystemUiState.Field.Orientation -> window.setOrientation(state.orientation)
+        SystemUiState.Field.KeyboardCovers -> {
+            keyboardCovered = state.keyboardCovers
+            window.setKeyboardCovers(state.keyboardCovers)
+        }
+    }
+
+    companion object {
+        // Stands for a group no layer decides; its values are never written.
+        private val UNDECIDED = SystemUiRules.Screen(Options())
+
+        private fun groupOf(field: SystemUiState.Field): SystemUiLayers.Group = when (field) {
+            SystemUiState.Field.StatusBarShown,
+            SystemUiState.Field.StatusBarColor,
+            SystemUiState.Field.StatusBarIcons,
+            -> SystemUiLayers.Group.StatusBar
+            SystemUiState.Field.NavigationBarShown,
+            SystemUiState.Field.NavigationBarColor,
+            SystemUiState.Field.NavigationBarButtons,
+            -> SystemUiLayers.Group.NavigationBar
+            SystemUiState.Field.Orientation -> SystemUiLayers.Group.Orientation
+            SystemUiState.Field.KeyboardCovers -> SystemUiLayers.Group.Keyboard
+        }
+
+        // [this] with the values of [group] from [last].
+        private fun SystemUiState.keeping(last: SystemUiState, group: SystemUiLayers.Group): SystemUiState =
+            when (group) {
+                SystemUiLayers.Group.StatusBar -> copy(
+                    statusBarShown = last.statusBarShown,
+                    statusBarColor = last.statusBarColor,
+                    statusBarLightIcons = last.statusBarLightIcons,
+                )
+                SystemUiLayers.Group.NavigationBar -> copy(
+                    navigationBarShown = last.navigationBarShown,
+                    navigationBarColor = last.navigationBarColor,
+                    navigationBarLightButtons = last.navigationBarLightButtons,
+                )
+                SystemUiLayers.Group.Orientation -> copy(orientation = last.orientation)
+                SystemUiLayers.Group.Keyboard -> copy(keyboardCovers = last.keyboardCovers)
+            }
+
+        /** The owner of [activity]'s system UI; none for an activity that isn't the navigation's (unit tests). */
+        fun of(activity: Activity): SystemUiOwner? = (activity as? NavigationActivity)?.navigator?.systemUi
+    }
+}