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

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

@@ -0,0 +1,95 @@
+package dev.apexnative.navigation.viewcontrollers.stack.topbar
+
+import dev.apexnative.navigation.options.Options
+
+/**
+ * The room the bar takes, counted from a screen's own resolved options, never from where the bar is now (a large title
+ * collapsed, a search open, the bar moved by a scroll): a screen not on top keeps its room through a push and a pop.
+ * Pixels. A pure function.
+ */
+internal object TopBarRoom {
+    /** What the window gives the bar: the status bar's height (shown or not) and the cutout's at the top. */
+    class Insets(val statusBar: Int, val cutout: Int)
+
+    /** The parts of the bar as [Options] set them, in pixels. */
+    class Bar(
+        /** The strip under the status bar, at the top of the bar ([strip]). */
+        val strip: Int,
+        /** The room over the bar ([margin]). */
+        val margin: Int,
+        /** `topBar.topMargin` alone, in pixels. */
+        val topMargin: Int,
+        /** `topBar.height`: the bar without the strip, the large title and the search. */
+        val height: Int,
+    )
+
+    /**
+     * A screen with [options] lies under the bar, the bar keeping no room over it: `topBar.drawBehind`,
+     * `topBar.visible: false`, `topBar.hideOnScroll` or `topBar.searchBar.hideOnScroll`, or a large title shown
+     * ([largeTitleShown]).
+     */
+    fun isUnderBar(options: Options, largeTitleShown: Boolean): Boolean {
+        val topBar = options.topBar
+        return topBar.drawBehind.isTrue || topBar.visible.isFalse || topBar.hideOnScroll.isTrue ||
+            topBar.searchBar.hideOnScroll.isTrue || largeTitleShown
+    }
+
+    /**
+     * The safe area of a screen with [options] leaves its top edge free: the bar or the search hides on scroll, or a
+     * large title shows; the list pads itself then.
+     */
+    fun leavesTopEdgeFree(options: Options, largeTitleShown: Boolean): Boolean {
+        val topBar = options.topBar
+        if (topBar.visible.isFalse) return false
+        return topBar.hideOnScroll.isTrue || topBar.searchBar.hideOnScroll.isTrue || largeTitleShown
+    }
+
+    /**
+     * Whether a merge of [options] changes the room of the screen on top: the bar's visibility, `drawBehind`, the
+     * hide on scroll of the bar or the search, the large title, the search, `topBar.height` or `topBar.topMargin`
+     * (counted again at those merges).
+     */
+    fun isTouchedBy(options: Options): Boolean {
+        val topBar = options.topBar
+        return topBar.visible.hasValue() || topBar.drawBehind.hasValue() || topBar.hideOnScroll.hasValue() ||
+            topBar.searchBar.hideOnScroll.hasValue() || topBar.largeTitle.hasValue() || topBar.height.hasValue() ||
+            topBar.topMargin.hasValue() || topBar.searchBar.visible.hasValue() || topBar.searchBar.placement.hasValue()
+    }
+
+    /**
+     * The strip of the bar under the status bar: the status bar's height, at least the cutout's, while it shows and
+     * `statusBar.drawBehind` isn't `false`; with the status bar hidden only the cutout's (a merge of `drawBehind` adds
+     * nothing then); none in a sheet, and none with `drawBehind: false`, the bar below the status bar.
+     */
+    fun strip(options: Options, insets: Insets, inSheet: Boolean): Int {
+        if (inSheet) return 0
+        val statusBar = options.statusBar
+        if (statusBar.visible.isFalse) return insets.cutout
+        if (statusBar.drawBehind.isFalse) return 0
+        return maxOf(insets.statusBar, insets.cutout)
+    }
+
+    /**
+     * The room over the bar: `topBar.topMargin` ([topMargin] pixels), and the status bar's height when the bar isn't
+     * under it and it shows.
+     */
+    fun margin(options: Options, insets: Insets, inSheet: Boolean, topMargin: Int): Int {
+        val belowStatusBar = !inSheet && !options.statusBar.visible.isFalse && options.statusBar.drawBehind.isFalse
+        return topMargin + if (belowStatusBar) insets.statusBar else 0
+    }
+
+    /**
+     * Whether the bar keeps the room of the status bar for a screen: the bar shows and is drawn under the status bar,
+     * so the screen keeps none of its own (`ParentController.keepsStatusBarRoomOf`).
+     */
+    fun keepsStatusBarRoom(options: Options, bar: Bar): Boolean = !options.topBar.visible.isFalse && bar.strip > 0
+
+    /**
+     * The room the bar takes at the top of a screen, besides the layouts' around: none under the bar; else the strip,
+     * `topBar.topMargin` and the height as the options set them (without the large title), and [searchHeight] for a
+     * search under the row. The status bar's height over a bar below it is the screen's own room (it counts it itself
+     * then).
+     */
+    fun topInset(underBar: Boolean, bar: Bar, searchHeight: Int): Int =
+        if (underBar) 0 else bar.strip + bar.topMargin + bar.height + searchHeight
+}

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

@@ -0,0 +1,122 @@
+package dev.apexnative.navigation.viewcontrollers.stack.topbar
+
+import dev.apexnative.navigation.options.TopBarAnimationOptions
+import dev.apexnative.navigation.options.TopBarEnterExitAnimationOptions
+import dev.apexnative.navigation.views.animations.AnimationRules
+
+/**
+ * Showing and hiding the bar (`topBar.visible`, `.animate`): a hide moves the bar up by its height and the room over it
+ * in 300 ms (`FastOutSlowInInterpolator`) and makes it `GONE` at the end; a show moves it back. In a transition of the
+ * stack its side (`animations.*.topBar`) plays instead — its `exit` hides, its `enter` shows; `enabled: false` shows or
+ * hides at once. A show cancels a running hide and a hide a running show, each with its own token, so `visible: false`
+ * then `true` leaves the bar shown; a motion cancelled leaves the bar at rest; a bar shown again stands in its place
+ * with its row seen (the hide on scroll's shift and fade reset). Main thread only.
+ */
+internal class TopBarVisibility(private val target: Target) {
+    /** What moves: the bar's view, or the unit tests' fake. */
+    interface Target {
+        /** How far up the bar goes to hide: its height and the room over it, in pixels. */
+        val hiddenOffset: Float
+
+        var translationY: Float
+
+        /** The bar takes no room and draws nothing (`GONE`). */
+        var isGone: Boolean
+
+        /** Moves the bar to [to] in [duration] ms; [onEnd] at its end, not when the function returned stops it. */
+        fun slide(to: Float, duration: Long, onEnd: () -> Unit): () -> Unit
+
+        /**
+         * Plays [side] on the bar; [onEnd] at its end, not when the function returned stops it. Either way the bar is
+         * left at rest (no shift, opaque, full size, not turned).
+         */
+        fun play(side: TopBarAnimationOptions, onEnd: () -> Unit): () -> Unit
+
+        /** The hide on scroll lets go of the bar: where the rows took it no longer counts. */
+        fun resetCollapse()
+    }
+
+    private var stop: (() -> Unit)? = null
+    // The motion running now: a motion's end does something only while it is still this one.
+    private var sliding: Any? = null
+    private var hidden = false
+
+    /** The bar is hidden, or hides. */
+    val isHidden: Boolean
+        get() = hidden
+
+    /** Shows the bar: by [side] when it plays, sliding down when [animated], else at once. */
+    fun show(animated: Boolean, side: TopBarAnimationOptions? = null) {
+        val wasHidden = hidden
+        hidden = false
+        val wasSliding = sliding != null
+        cancel()
+        if (!wasHidden && !wasSliding) return
+        target.resetCollapse()
+        val moves = animated && !AnimationRules.isTurnedOff(side)
+        val own = side?.takeIf { moves && AnimationRules.sidePlays(it) }
+        if (target.isGone) {
+            target.isGone = false
+            if (moves && own == null) target.translationY = -target.hiddenOffset
+        }
+        if (!moves) {
+            target.translationY = 0f
+            return
+        }
+        val token = Any()
+        sliding = token
+        val end = if (own != null) {
+            target.play(own) { if (sliding === token) settle() }
+        } else {
+            target.slide(0f, DURATION) { if (sliding === token) settle() }
+        }
+        if (sliding === token) stop = end
+    }
+
+    /** Hides the bar: by [side] when it plays, sliding up when [animated], else at once. */
+    fun hide(animated: Boolean, side: TopBarAnimationOptions? = null) {
+        val wasHidden = hidden
+        hidden = true
+        val wasSliding = sliding != null
+        cancel()
+        if (wasHidden && !wasSliding) return
+        val moves = animated && !AnimationRules.isTurnedOff(side)
+        if (!moves || target.isGone) {
+            target.translationY = 0f
+            target.isGone = true
+            return
+        }
+        val token = Any()
+        sliding = token
+        val gone = {
+            if (sliding === token) {
+                settle()
+                target.isGone = true
+                target.translationY = 0f
+            }
+        }
+        val own = side?.takeIf { AnimationRules.sidePlays(it) }
+        val end = if (own != null) target.play(own, gone) else target.slide(-target.hiddenOffset, DURATION, gone)
+        if (sliding === token) stop = end
+    }
+
+    /** As the options say: shown unless `visible: false`; in a transition by its [side] (`enter` or `exit`). */
+    fun apply(visible: Boolean, animated: Boolean, side: TopBarEnterExitAnimationOptions? = null) =
+        if (visible) show(animated, side?.enter) else hide(animated, side?.exit)
+
+    // A running motion stops where it is, without its end.
+    private fun cancel() {
+        val running = stop
+        settle()
+        running?.invoke()
+    }
+
+    private fun settle() {
+        sliding = null
+        stop = null
+    }
+
+    private companion object {
+        const val DURATION = 300L
+    }
+}

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

@@ -0,0 +1,89 @@
+package dev.apexnative.navigation.viewcontrollers.viewcontroller
+
+import android.util.Size
+import android.view.MotionEvent
+import android.view.ViewGroup
+import dev.apexnative.navigation.react.events.ComponentType
+
+/**
+ * What a screen shows: the core's React view (`ReactView`), the slot screen of the slots module (`SlotScreenView`, for
+ * names starting with `slot:`), or a view that stands for another screen's content (the view of a pair stands for its
+ * primary). The core asks it only these: its id, the appearance of its component (with the component's type), whether
+ * it is ready and when it gets so, the content mounted, the stop, touches, the size of its content. The answers with a
+ * body are those of a view that only stands for content: it is ready, and has nothing of its own to tell.
+ */
+interface IReactView {
+    /** The view to put where the screen's content goes. */
+    fun asView(): ViewGroup
+
+    /** The content has rendered once: the screen can show. */
+    fun isReady(): Boolean
+
+    /** The content is drawn as it is now: what a transition into the screen waits for. */
+    fun isRendered(): Boolean
+
+    /** Stops the content: its React surface goes, once. Main thread. */
+    fun destroy()
+
+    /** A button of the bar over the screen was pressed: `ANN.NavigationButtonPressed` with the screen's id. */
+    fun sendOnNavigationButtonPressed(buttonId: String)
+
+    /** The scroll of the content, which the bars follow; none for content that doesn't scroll. */
+    fun getScrollEventListener(): ScrollEventListener?
+
+    /** A touch that began outside the content (a bar's view over it) goes to its JavaScript. */
+    fun dispatchTouchEventToJs(event: MotionEvent)
+
+    /** The id of the screen the content belongs to; none for a view that stands for another screen's content. */
+    val componentId: String?
+        get() = null
+
+    /** The name the screen was registered with, without `slot:`. */
+    val componentName: String?
+        get() = null
+
+    /**
+     * The content's component starts to appear, as a component of [type]: the content tells its appearance record to
+     * the dispatcher of the appearance events (`AppearanceDispatcher`), which sends `ANN.ComponentWillAppear` once per
+     * appearance, when the content is ready or the hold limit passed. A view that stands for another screen's
+     * content tells nothing.
+     */
+    fun sendComponentWillStart(type: ComponentType) = Unit
+
+    /**
+     * The content's component has appeared: `ANN.ComponentDidAppear` through the dispatcher, after its WillAppear
+     * (asked first when it wasn't), once per appearance.
+     */
+    fun sendComponentStart(type: ComponentType) = Unit
+
+    /**
+     * The content's component has disappeared: `ANN.ComponentDidDisappear` through the dispatcher, only after its
+     * WillAppear went; when that is still held, nothing goes for the appearance.
+     */
+    fun sendComponentStop(type: ComponentType) = Unit
+
+    /** Runs [listener] once the content is ready ([isReady]); at once when it is. */
+    fun whenReady(listener: Runnable) = listener.run()
+
+    /** Runs [listener] once the content has mounted into its container; at once for content that mounts by itself. */
+    fun whenSlotContentMounted(listener: Runnable) = listener.run()
+
+    /**
+     * Calls [handler] after each mount of the content while the screen is in the window, under [key]; null removes
+     * the handler of [key].
+     */
+    fun setOnContentMounted(key: String, handler: Runnable?) = Unit
+
+    /** Touches outside the content go to what is under the screen (an overlay). */
+    fun setPassThroughTouches(passThrough: Boolean) = Unit
+
+    /** The size of the content as it lays out for [maxWidth] pixels, for a sheet as tall as its content; null without. */
+    fun contentSize(maxWidth: Int): Size? = null
+
+    /**
+     * The root view of the React content, where React Native's own touch target search starts (an overlay's touches): a
+     * React surface's view, a slot's content; none without content to search.
+     */
+    val touchRoot: ViewGroup?
+        get() = null
+}

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

@@ -0,0 +1,51 @@
+package dev.apexnative.navigation.viewcontrollers.viewcontroller
+
+import android.app.Activity
+import android.graphics.Color
+import dev.apexnative.navigation.options.DefaultOptions
+import dev.apexnative.navigation.options.Options
+
+/**
+ * Applies a layout's resolved options to the layout's own view (its background, its bars). Each layout has one. The
+ * system UI of the activity (the status bar, the navigation bar, the orientation) is its owner's (`SystemUiOwner`),
+ * which a presenter only tells that something changed. The options it gets are read-only (the node keeps them,
+ * `ViewController.resolveCurrentOptions`): code that changes them copies them first.
+ */
+open class Presenter(
+    @JvmField protected val activity: Activity,
+    // Kept for the modules that pass it: the defaults are the app's one tree, read from DefaultOptions.
+    @Suppress("UNUSED_PARAMETER") defaultOptions: Options,
+) {
+    /**
+     * The default options of the app (`setDefaultOptions`), which every layout's options take what they lack from:
+     * always the current ones ([DefaultOptions.current]).
+     */
+    val defaultOptions: Options
+        get() = DefaultOptions.current
+
+    /** The layout shows with [options], resolved: everything they give applies. */
+    open fun applyOptions(view: ViewController<*>, options: Options) = Unit
+
+    /** `mergeOptions` of the layout: what [options] give applies over what shows. */
+    open fun mergeOptions(viewController: ViewController<*>, options: Options) = Unit
+
+    /** The layout comes to the front again (a pop, a dismissed modal): what it set for the activity applies again. */
+    open fun onViewBroughtToFront(viewController: ViewController<*>, options: Options) = Unit
+
+    /**
+     * Light or dark changed (the activity takes `uiMode` itself), or new default options came (`setDefaultOptions`):
+     * what depends on colors and looks applies again with [options], resolved with the new defaults
+     * (`Navigator.repaint`).
+     */
+    open fun onConfigurationChanged(controller: ViewController<*>, options: Options) = Unit
+
+    /**
+     * The background of the layout's view: `layout.backgroundColor` of [options], platform colors with the activity's
+     * theme; `'NoColor'` (or a side the options don't give) is no background.
+     */
+    fun applyBackgroundColor(view: ViewController<*>, options: Options) {
+        val color = options.layout.backgroundColor
+        if (!color.hasValue()) return
+        view.peekView()?.setBackgroundColor(color.get(activity, Color.TRANSPARENT) ?: Color.TRANSPARENT)
+    }
+}

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

@@ -0,0 +1,194 @@
+package dev.apexnative.navigation.viewcontrollers.viewcontroller
+
+import android.view.View
+import android.view.ViewGroup
+import android.widget.ScrollView
+import dev.apexnative.navigation.react.ScrollEvents
+import java.lang.ref.WeakReference
+
+/**
+ * The scroll of a React screen's content, which the bars follow (`topBar.hideOnScroll`, `bottomTabs.hideOnScroll`, the
+ * large title, the FAB): one per screen's view, with several followers at once, each registered once however often it
+ * registers again. It hears only the vertical lists inside the screen's view — a list whose view (its id is its Fabric
+ * tag) is in the screen, found once per tag —, not the horizontal ones, nor those of a modal, an overlay or another
+ * screen; a slot screen's lists are in its container too. While a list is dragged, each follower gets the drag as a
+ * translation to follow; when the drag ends, the way to settle; at every scroll event, the drags' and the inertia's,
+ * the offset. It listens to React Native's events only while it has followers; without React Native's event dispatcher
+ * (around a reload) it waits and listens once there is one. Released with the screen. Main thread only.
+ */
+class ScrollEventListener() {
+    /** Follows the content while it is dragged. */
+    interface OnScrollListener {
+        /** The content went up; [nextTranslation] is where the follower would be, from its place of rest. */
+        fun onScrollUp(nextTranslation: Float)
+
+        /** The content went down; as [onScrollUp]. */
+        fun onScrollDown(nextTranslation: Float)
+
+        /**
+         * The vertical offset of the list that scrolled, in pixels: at each of its scroll events, while it is dragged
+         * and while it goes on by itself.
+         */
+        fun onScrollOffset(offsetY: Float) = Unit
+    }
+
+    /** Settles when a drag ends: the finger went down (show) or up (hide). */
+    interface OnDragListener {
+        fun onShow()
+
+        fun onHide()
+    }
+
+    private class Registration(val view: View?, val onScroll: OnScrollListener, val onDrag: OnDragListener)
+
+    private val registrations = mutableListOf<Registration>()
+
+    // Whether the list of a tag is one of the screen's own vertical lists; a test gives its own answer.
+    private var ownLists: ((Int) -> Boolean)? = null
+    private var scope: WeakReference<ViewGroup>? = null
+    private val ownByTag = HashMap<Int, Boolean>()
+    private var stopListening: (() -> Unit)? = null
+    private var released = false
+    // The list being dragged, its last offset by tag, and the way the drag went last.
+    private var dragged: Int? = null
+    private val offsets = HashMap<Int, Float>()
+    private var lastStep = 0f
+
+    /** A listener for the unit tests: [ownLists] tells which tags are the screen's own vertical lists. */
+    internal constructor(ownLists: (Int) -> Boolean) : this() {
+        this.ownLists = ownLists
+    }
+
+    /**
+     * The vertical offset of the screen's own list heard last, in pixels; 0 until one scrolls. It stays while no
+     * follower listens (the screen is covered), so a follower that comes back starts where the list is.
+     */
+    var lastOffset = 0f
+        private set
+
+    /**
+     * The offset heard last no longer stands, when nothing listens to the lists any more while the screen shows: they
+     * may scroll unheard from now on. A screen that gets covered keeps it.
+     */
+    fun forgetOffset() {
+        if (registrations.isEmpty()) lastOffset = 0f
+    }
+
+    /** Whether a listener follows the screen. */
+    val hasListeners: Boolean
+        get() = registrations.isNotEmpty()
+
+    /**
+     * Adds a follower: [view] is what moves (up from rest, as far as the follower lets it; none for a follower that
+     * only hears the way), [onScroll] and [onDrag] hear the scroll. A follower registered again replaces itself.
+     */
+    fun register(view: View?, onScroll: OnScrollListener, onDrag: OnDragListener) {
+        if (released) return
+        // In its place: followers register again at every apply of the options, and a drag in progress, the offsets and
+        // the listening to React Native stay as they are.
+        val registration = Registration(view, onScroll, onDrag)
+        val index = registrations.indexOfFirst { it.onScroll === onScroll }
+        if (index >= 0) registrations[index] = registration else registrations += registration
+        attachIfNeeded()
+    }
+
+    /** Removes the follower whose scroll listener is [listener]. */
+    fun unregister(listener: OnScrollListener) {
+        registrations.removeAll { it.onScroll === listener }
+        if (registrations.isEmpty()) detach()
+    }
+
+    /** The lists inside [screenView] are the screen's. */
+    internal fun watch(screenView: ViewGroup) {
+        scope = WeakReference(screenView)
+        ownByTag.clear()
+    }
+
+    /**
+     * Listens to React Native's scroll events when followers wait for them and it doesn't yet: after a reload there may
+     * be no event dispatcher at first: then it is asked again once React Native has one, and as the screen joins a
+     * window.
+     */
+    internal fun attachIfNeeded() {
+        if (released || stopListening != null || registrations.isEmpty()) return
+        val context = scope?.get()?.context ?: return
+        stopListening = ScrollEvents.listen(context, ::onScrollEvent)
+        if (stopListening == null) ScrollEvents.waitForDispatcher(this)
+    }
+
+    /** The screen is destroyed: no follower hears it any more. */
+    internal fun release() {
+        released = true
+        registrations.clear()
+        detach()
+        scope = null
+        ownByTag.clear()
+    }
+
+    /** One scroll event of a list of the app; only the screen's own vertical lists count. */
+    internal fun onScrollEvent(event: ScrollEvents.Reading) {
+        if (released || registrations.isEmpty() || !isOwnVerticalList(event.viewTag)) return
+        val tag = event.viewTag
+        lastOffset = event.offsetY
+        val step = event.offsetY - (offsets[tag] ?: event.offsetY)
+        offsets[tag] = event.offsetY
+        when (event.kind) {
+            ScrollEvents.Kind.BeginDrag -> {
+                dragged = tag
+                lastStep = 0f
+            }
+            ScrollEvents.Kind.EndDrag -> if (dragged == tag) endDrag(event.velocityY)
+            ScrollEvents.Kind.Scroll -> if (dragged == tag && step != 0f) follow(step)
+            ScrollEvents.Kind.MomentumBegin, ScrollEvents.Kind.MomentumEnd -> Unit
+        }
+        registrations.toList().forEach { it.onScroll.onScrollOffset(event.offsetY) }
+    }
+
+    // The rows moved by [step] pixels while dragged: up when the offset grows.
+    private fun follow(step: Float) {
+        lastStep = step
+        for (registration in registrations.toList()) {
+            val view = registration.view
+            // The view's follower bounds how far it goes: the top bar below the status bar goes by its margin too.
+            val next = if (view == null) -step else (view.translationY - step).coerceAtMost(0f)
+            if (step > 0) registration.onScroll.onScrollUp(next) else registration.onScroll.onScrollDown(next)
+        }
+    }
+
+    // The finger went up (a negative speed: the offset grows) or down; without speed, the way the drag went last.
+    private fun endDrag(velocityY: Float) {
+        dragged = null
+        val hide = if (velocityY != 0f) velocityY < 0f else lastStep > 0f
+        for (registration in registrations.toList()) {
+            if (hide) registration.onDrag.onHide() else registration.onDrag.onShow()
+        }
+    }
+
+    private fun isOwnVerticalList(tag: Int): Boolean {
+        ownLists?.let { return it(tag) }
+        ownByTag[tag]?.let { return it }
+        val screenView = scope?.get() ?: return false
+        val own = isVerticalList(screenView.findViewById(tag))
+        if (ownByTag.size >= TAG_CACHE_LIMIT) ownByTag.clear()
+        ownByTag[tag] = own
+        return own
+    }
+
+    private fun detach() {
+        stopListening?.invoke()
+        stopListening = null
+        dragged = null
+        offsets.clear()
+    }
+
+    internal companion object {
+        // The tags remembered at most: the lists of a screen, and those of the other screens it saw.
+        private const val TAG_CACHE_LIMIT = 256
+
+        /**
+         * Whether [view] is a vertical list: a scroll view (React Native's `ReactScrollView`). Horizontal lists and
+         * the other views that send scroll events (a multiline text input) don't count.
+         */
+        fun isVerticalList(view: View?): Boolean = view is ScrollView
+    }
+}