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

package/android/src/main/java/dev/apexnative/navigation/react/ReactView.kt

@@ -0,0 +1,197 @@
+package dev.apexnative.navigation.react
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.os.Bundle
+import android.view.MotionEvent
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import com.facebook.react.interfaces.fabric.ReactSurface
+import com.facebook.react.runtime.ReactSurfaceImpl
+import dev.apexnative.navigation.NavigationApplication
+import dev.apexnative.navigation.react.events.AppearanceDispatcher
+import dev.apexnative.navigation.react.events.ComponentType
+import dev.apexnative.navigation.react.events.ScreenAppearance
+import dev.apexnative.navigation.viewcontrollers.component.ScreenReadiness
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.IReactView
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ScrollEventListener
+
+/**
+ * A React root of its own: the content of a screen, or a component of a bar or a tab, rendered from the module
+ * registered as [componentName], with [componentId] as its initial prop (the props stay in JavaScript); a cell of the
+ * tabs' custom row gets its state from the native side as props too ([initialProps], [updateProps]). Its React surface
+ * is made with the view, from the app's React host, and fills it; it starts once, as the view joins a window, and stops
+ * once, on the main thread, as the view is destroyed.
+ *
+ * Ready once the safe area view of the screen told [ScreenReadiness] that the content rendered into it; a screen
+ * without a safe area view (no view ever told anything of its id) once the root view of its surface has children, read
+ * on this view's own layout passes. Ready once, ready for good; what waits for it ([whenReady]) runs then, once.
+ * Without either, the limits of what waits decide: the view has no timer of its own. It owns the record of its
+ * appearance, which the dispatcher of the appearance events holds until the content is ready (`AppearanceDispatcher`).
+ */
+@SuppressLint("ViewConstructor")
+class ReactView @JvmOverloads constructor(
+    context: Context,
+    override val componentId: String,
+    override val componentName: String,
+    /** Props given by the native side, over `componentId`: the state of a tab's cell. */
+    initialProps: Bundle? = null,
+) : FrameLayout(context), IReactView {
+    private val scrollEventListener = ScrollEventListener()
+    private var destroyed = false
+    private var started = false
+    private var ready = false
+    // What waited for the readiness was told; a question of isReady alone tells nothing, so nothing runs inside it.
+    private var readyTold = false
+    private val readyListeners = mutableListOf<Runnable>()
+    private var readinessListener: ScreenReadiness.Listener? = null
+
+    // None without the app's host (the unit tests).
+    private val surface: ReactSurface?
+
+    /** The appearance of the component; its type is the one of the first appearance call. */
+    internal val appearance = ScreenAppearance(componentId, componentName, ComponentType.Component, this)
+    private var typeTaken = false
+
+    /**
+     * How many children the root view of the surface has: only read, for a screen without a safe area view. The unit
+     * tests give their own count.
+     */
+    internal var contentChildCount: () -> Int = { (surface?.view as? ViewGroup)?.childCount ?: 0 }
+
+    init {
+        require(componentId.isNotEmpty()) { "a React root needs the id of its screen" }
+        val props = Bundle().apply {
+            initialProps?.let(::putAll)
+            putString(COMPONENT_ID, componentId)
+        }
+        surface = NavigationApplication.instanceOrNull?.reactGatewayOrNull?.host
+            ?.createSurface(context, componentName, props)
+        surface?.view?.let { addView(it, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)) }
+    }
+
+    override fun onAttachedToWindow() {
+        super.onAttachedToWindow()
+        if (started || destroyed) return
+        started = true
+        surface?.start()
+    }
+
+    // The children of the surface's root are read after each layout; what waits (a root's transition, which moves
+    // views of the root layer) runs on the next turn of the main loop, not inside the layout pass.
+    override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+        super.onLayout(changed, left, top, right, bottom)
+        if (!destroyed && !readyTold && isReady()) post { checkReadiness() }
+    }
+
+    override fun asView(): ViewGroup = this
+
+    // The surface's own view: React Native's touch target search starts there.
+    override val touchRoot: ViewGroup?
+        get() = surface?.view as? ViewGroup
+
+    override fun isReady(): Boolean {
+        if (!ready && hasRendered()) ready = true
+        return ready
+    }
+
+    override fun isRendered(): Boolean = isReady()
+
+    /** Runs [listener] once the content is ready ([isReady]); at once when it is. */
+    override fun whenReady(listener: Runnable) {
+        if (destroyed) return
+        if (readyTold) return listener.run()
+        readyListeners += listener
+        if (isReady()) return checkReadiness()
+        if (readinessListener != null) return
+        val readiness = object : ScreenReadiness.Listener {
+            override fun onLaidOut() = Unit
+
+            override fun onContentRendered() = checkReadiness()
+        }
+        readinessListener = readiness
+        ScreenReadiness.setListener(componentId, readiness)
+    }
+
+    /**
+     * The content may have become ready: the safe area view told it rendered, or the surface's root got its first
+     * children (a screen without a safe area view). What waits runs once.
+     */
+    internal fun checkReadiness() {
+        if (destroyed || readyTold || !isReady()) return
+        readyTold = true
+        stopListening()
+        val waiting = readyListeners.toList()
+        readyListeners.clear()
+        waiting.forEach(Runnable::run)
+    }
+
+    // The safe area view said so; without one, the root view of the surface has children.
+    private fun hasRendered(): Boolean = when (ScreenReadiness.isContentRendered(componentId)) {
+        true -> true
+        false -> false
+        null -> contentChildCount() > 0
+    }
+
+    private fun stopListening() {
+        val readiness = readinessListener ?: return
+        readinessListener = null
+        ScreenReadiness.removeListener(componentId, readiness)
+    }
+
+    /**
+     * Stops the content, once, on the main thread: its appearance ends first (DidDisappear if its WillAppear went,
+     * else what is held goes with it), then the surface stops and leaves the host, so a reload doesn't start it again
+     * in the new JavaScript.
+     */
+    override fun destroy() {
+        if (destroyed) return
+        AppearanceDispatcher.didDisappear(appearance)
+        destroyed = true
+        readyListeners.clear()
+        stopListening()
+        val surface = surface ?: return
+        if (started) surface.stop()
+        surface.detach()
+    }
+
+    // The screen sends ANN.NavigationButtonPressed itself (`ComponentViewController`): its content has nothing to do.
+    override fun sendOnNavigationButtonPressed(buttonId: String) = Unit
+
+    override fun getScrollEventListener(): ScrollEventListener = scrollEventListener
+
+    override fun dispatchTouchEventToJs(event: MotionEvent) = Unit
+
+    override fun sendComponentWillStart(type: ComponentType) = AppearanceDispatcher.willAppear(appearanceOf(type))
+
+    override fun sendComponentStart(type: ComponentType) = AppearanceDispatcher.didAppear(appearanceOf(type))
+
+    override fun sendComponentStop(type: ComponentType) = AppearanceDispatcher.didDisappear(appearanceOf(type))
+
+    private fun appearanceOf(type: ComponentType): ScreenAppearance {
+        if (!typeTaken) {
+            typeTaken = true
+            appearance.componentType = type
+        }
+        return appearance
+    }
+
+    /**
+     * The props the native side gives change: [props] replace them whole, `componentId` kept, as an update of the same
+     * root (the props JavaScript keeps by the id stay). Main thread.
+     */
+    fun updateProps(props: Bundle) {
+        if (destroyed) return
+        val all = Bundle(props).apply { putString(COMPONENT_ID, componentId) }
+        (surface as? ReactSurfaceImpl)?.updateInitProps(all)
+    }
+
+    /** The view was destroyed: its surface is stopped. */
+    val isDestroyed: Boolean
+        get() = destroyed
+
+    private companion object {
+        // The one initial prop of a React root: the props of the screen stay in JavaScript by this id.
+        const val COMPONENT_ID = "componentId"
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/react/ReadableJson.kt

@@ -0,0 +1,60 @@
+package dev.apexnative.navigation.react
+
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * What JavaScript sends a native screen (its props, an update of them, the answer of a call) as the JSON the native
+ * screen's context keeps (`NativeScreenContext`): maps, lists, strings, numbers, booleans, and `null` kept as a value
+ * (`JSONObject.NULL`, `updateNativeScreenProps`). Read on the thread the command comes on.
+ */
+internal object ReadableJson {
+    /** [map] as JSON. */
+    fun toJson(map: ReadableMap): JSONObject = jsonObject(plain(map))
+
+    /** [map] as plain values: nested maps and lists too, a `null` kept as an entry with no value. */
+    fun plain(map: ReadableMap): Map<String, Any?> {
+        val values = LinkedHashMap<String, Any?>()
+        val keys = map.keySetIterator()
+        while (keys.hasNextKey()) {
+            val key = keys.nextKey()
+            values[key] = when (map.getType(key)) {
+                ReadableType.Null -> null
+                ReadableType.Boolean -> map.getBoolean(key)
+                ReadableType.Number -> map.getDouble(key)
+                ReadableType.String -> map.getString(key)
+                ReadableType.Map -> map.getMap(key)?.let(::plain)
+                ReadableType.Array -> map.getArray(key)?.let(::plain)
+            }
+        }
+        return values
+    }
+
+    /** [array] as plain values, as [plain] of a map. */
+    fun plain(array: ReadableArray): List<Any?> = (0 until array.size()).map { index ->
+        when (array.getType(index)) {
+            ReadableType.Null -> null
+            ReadableType.Boolean -> array.getBoolean(index)
+            ReadableType.Number -> array.getDouble(index)
+            ReadableType.String -> array.getString(index)
+            ReadableType.Map -> array.getMap(index)?.let(::plain)
+            ReadableType.Array -> array.getArray(index)?.let(::plain)
+        }
+    }
+
+    private fun jsonObject(values: Map<String, Any?>): JSONObject {
+        val json = JSONObject()
+        for ((key, value) in values) json.put(key, jsonValue(value))
+        return json
+    }
+
+    private fun jsonValue(value: Any?): Any = when (value) {
+        null -> JSONObject.NULL
+        is Map<*, *> -> jsonObject(value.entries.associate { (key, item) -> key.toString() to item })
+        is List<*> -> JSONArray().also { array -> value.forEach { array.put(jsonValue(it)) } }
+        else -> value
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/react/ReloadCoordinator.kt

@@ -0,0 +1,130 @@
+package dev.apexnative.navigation.react
+
+import com.facebook.react.bridge.ReactContext
+import dev.apexnative.navigation.NavigationActivity
+import dev.apexnative.navigation.nativescreen.NativeScreenCalls
+import dev.apexnative.navigation.react.events.EventEmitter
+import dev.apexnative.navigation.react.events.NavigationStateReporter
+import dev.apexnative.navigation.utils.UiThread
+import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackState
+import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
+import dev.apexnative.navigation.viewcontrollers.navigator.Navigators
+import java.lang.ref.WeakReference
+import java.util.WeakHashMap
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * The JavaScript the navigation answers to. [generation] grows each time the JavaScript goes; every command takes it as
+ * it arrives, and its queued work and its answer do nothing once it has moved: the commands of the JavaScript that went
+ * get no answer. `ReactGateway` tells it when the JavaScript goes and when a new React context is ready; it resets the
+ * navigation for the new JavaScript and sends `ANN.AppLaunched` once per pair of a navigation activity and a React
+ * context (EVT-AppLaunched).
+ */
+internal object ReloadCoordinator {
+    private val counter = AtomicInteger()
+
+    // Which activity got AppLaunched from which React context. Main thread only.
+    private val launches = AppLaunches<NavigationActivity, ReactContext>()
+
+    /** The number of the JavaScript that runs now. Any thread. */
+    val generation: Int
+        get() = counter.get()
+
+    /** Whether [generation] is still the number of the JavaScript that runs now. Any thread. */
+    fun isCurrent(generation: Int): Boolean = generation == counter.get()
+
+    /** The JavaScript went: the number grows. Any thread. */
+    fun advance(): Int = counter.incrementAndGet()
+
+    /**
+     * The JavaScript goes (a reload, or the host is destroyed). Any thread: the number grows at once; the layouts of
+     * every navigation activity go on the main thread, with the "reloading" mark, and so do the listeners of the
+     * JavaScript that went (back, hinge).
+     */
+    fun onJavaScriptGoes() {
+        advance()
+        Navigator.setReloading(true)
+        UiThread.runOnMain {
+            launches.contextGone()
+            try {
+                Navigators.all().forEach { it.onReload() }
+                BackCallbackState.setJsListeners(false)
+                Hinge.setEnabled(Navigators.current(), false)
+            } finally {
+                Navigator.setReloading(false)
+            }
+        }
+    }
+
+    /**
+     * The developer tools of [activity] reload the JavaScript ("R R", the reload broadcast): the number grows first, so
+     * the navigation of the activity goes without a word to the JavaScript that goes, then its layers go
+     * ([NavigationActivity.onReload]). The host's own reset follows as the reload destroys it. Main thread.
+     */
+    fun resetForDeveloperReload(activity: NavigationActivity) {
+        advance()
+        Navigator.setReloading(true)
+        try {
+            activity.onReload()
+        } finally {
+            Navigator.setReloading(false)
+        }
+    }
+
+    /**
+     * A React context is ready, the first or one after a reload: the calls of native screens the JavaScript that went
+     * didn't answer fail, and every resumed navigation activity gets its `ANN.AppLaunched`.
+     */
+    fun onReactContextReady(context: ReactContext) {
+        UiThread.runOnMain {
+            launches.contextReady(context)
+            NativeScreenCalls.failAll { name, componentId -> ErrorTexts.nativeCallReloaded(name, componentId) }
+            // Scroll listeners that found no event dispatcher listen now.
+            ScrollEvents.dispatcherReady()
+            Navigators.all().filter { it.isNavigationResumed }.forEach(::launchIfDue)
+        }
+    }
+
+    /**
+     * Sends `ANN.AppLaunched` for [activity] when it is resumed, the React context is ready, and that context hasn't
+     * sent it for this activity yet. The navigation state forgets what it sent last, so the new JavaScript gets the
+     * next one whatever it is. Main thread only.
+     */
+    fun launchIfDue(activity: NavigationActivity) {
+        val context = launches.takeDue(activity, activity.isNavigationResumed) ?: return
+        NavigationStateReporter.reset()
+        EventEmitter(context).emitAppLaunched()
+    }
+}
+
+/**
+ * When `ANN.AppLaunched` is due (EVT-AppLaunched): once per pair of an activity and a React context, to a resumed
+ * activity once the context is ready; a paused activity gets it at its next resume. Both are held weakly. Main thread
+ * only.
+ */
+internal class AppLaunches<A : Any, C : Any> {
+    private var ready: WeakReference<C>? = null
+    private val launched = WeakHashMap<A, WeakReference<C>>()
+
+    /** [context] is ready for events. */
+    fun contextReady(context: C) {
+        ready = WeakReference(context)
+    }
+
+    /** The context went with its JavaScript: nothing is due until the next one is ready. */
+    fun contextGone() {
+        ready = null
+    }
+
+    /**
+     * The context to send `ANN.AppLaunched` with to [activity] now, marked as sent; none when [resumed] is false, no
+     * context is ready, or this context sent it to this activity already.
+     */
+    fun takeDue(activity: A, resumed: Boolean): C? {
+        if (!resumed) return null
+        val context = ready?.get() ?: return null
+        if (launched[activity]?.get() === context) return null
+        launched[activity] = WeakReference(context)
+        return context
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/react/ScreenInsets.kt

@@ -0,0 +1,69 @@
+package dev.apexnative.navigation.react
+
+import android.content.Context
+import com.facebook.react.ReactApplication
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import dev.apexnative.navigation.react.events.EventEmitter
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * The safe area of each screen, in dp: how much of its content the bars and the system cover on each side. The padding
+ * is the part of it the screen's safe area view keeps its content out of: the insets on the edges the screen's options
+ * give. JavaScript gets the rest, what still covers the content (0 on a padded edge): it reads it from its own thread
+ * for a screen's first render, and gets every change as `ANN.ScreenInsetsChanged`.
+ */
+object ScreenInsets {
+    data class Insets(val top: Double, val right: Double, val bottom: Double, val left: Double)
+
+    private val insets = ConcurrentHashMap<String, Insets>()
+    // Main thread only.
+    private val padding = HashMap<String, Insets>()
+    private val paddingListeners = HashMap<String, MutableSet<() -> Unit>>()
+
+    /** The padding of the screen's safe area view; none before the screen was laid out. */
+    fun padding(screenId: String): Insets? = padding[screenId]
+
+    /** Calls `listener` when the padding of the screen changes; returns the function that stops it. */
+    fun listenToPadding(screenId: String, listener: () -> Unit): () -> Unit {
+        paddingListeners.getOrPut(screenId) { LinkedHashSet() }.add(listener)
+        return {
+            paddingListeners[screenId]?.let {
+                it.remove(listener)
+                if (it.isEmpty()) paddingListeners.remove(screenId)
+            }
+        }
+    }
+
+    /** Keeps the screen's insets and padding, and tells when they changed. */
+    fun update(context: Context, screenId: String, value: Insets, paddingValue: Insets) {
+        if (padding.put(screenId, paddingValue) != paddingValue) {
+            paddingListeners[screenId]?.toList()?.forEach { it() }
+        }
+        // JavaScript gets what still covers the content: the edges the safe area view keeps it off are 0.
+        val uncovered = Insets(
+            top = (value.top - paddingValue.top).coerceAtLeast(0.0),
+            right = (value.right - paddingValue.right).coerceAtLeast(0.0),
+            bottom = (value.bottom - paddingValue.bottom).coerceAtLeast(0.0),
+            left = (value.left - paddingValue.left).coerceAtLeast(0.0),
+        )
+        if (insets.put(screenId, uncovered) == uncovered) return
+        val reactContext = (context.applicationContext as? ReactApplication)?.reactHost?.currentReactContext ?: return
+        EventEmitter(reactContext).emitScreenInsetsChanged(screenId, toMap(uncovered))
+    }
+
+    /** `{ top, right, bottom, left }`, empty before the screen was laid out. Any thread. */
+    fun get(screenId: String): WritableMap = insets[screenId]?.let(::toMap) ?: Arguments.createMap()
+
+    fun remove(screenId: String) {
+        insets.remove(screenId)
+        padding.remove(screenId)
+    }
+
+    private fun toMap(value: Insets): WritableMap = Arguments.createMap().apply {
+        putDouble("top", value.top)
+        putDouble("right", value.right)
+        putDouble("bottom", value.bottom)
+        putDouble("left", value.left)
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/react/ScreenRegions.kt

@@ -0,0 +1,87 @@
+package dev.apexnative.navigation.react
+
+import android.app.Activity
+import android.graphics.Rect
+import androidx.core.view.WindowInsetsCompat
+import com.facebook.react.ReactApplication
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.bridge.WritableMap
+import dev.apexnative.navigation.react.events.EventEmitter
+import dev.apexnative.navigation.utils.WindowFolds
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * The reserved regions of each screen (`useReservedRegions`), in dp from the top left of its content: where it divides
+ * (a fold the window is divided at, `division`) and where hardware covers it (a fold that hides what is under it, the
+ * camera cutout: `occlusion`). Only those on the screen, cut to it: a fold at the edge of a screen of a pair is not on
+ * it. Measured on the main thread as each screen lays out, and again after a change of the window's folds (which lays
+ * the window out); JavaScript reads them from its own thread for a screen's first render, and gets every change as
+ * `ANN.ScreenRegionsChanged`.
+ */
+internal object ScreenRegions {
+    data class Region(val x: Double, val y: Double, val width: Double, val height: Double)
+
+    data class Regions(val division: List<Region>, val occlusion: List<Region>) {
+        val isEmpty: Boolean get() = division.isEmpty() && occlusion.isEmpty()
+    }
+
+    private val NONE = Regions(emptyList(), emptyList())
+    private val regions = ConcurrentHashMap<String, Regions>()
+
+    /**
+     * Measures the regions of the screen whose content the layout puts at [content] in the window (pixels), with the
+     * window's [insets] (the camera cutout), and tells JavaScript when they changed. Main thread only.
+     */
+    fun update(activity: Activity, screenId: String, content: Rect, insets: WindowInsetsCompat?) {
+        val folds = WindowFolds.of(activity)?.folds.orEmpty()
+        val cutouts = insets?.displayCutout?.boundingRects.orEmpty()
+        val density = activity.resources.displayMetrics.density
+        val value = Regions(
+            division = folds.filter { it.separating }.mapNotNull { onScreen(it.bounds, content, density) },
+            occlusion = (folds.filter { it.occludes }.map { it.bounds } + cutouts)
+                .mapNotNull { onScreen(it, content, density) },
+        )
+        val previous = regions.put(screenId, value)
+        // None at first is what JavaScript reads before the first layout.
+        if (previous == value || (previous == null && value.isEmpty)) return
+        val reactContext = (activity.application as? ReactApplication)?.reactHost?.currentReactContext ?: return
+        EventEmitter(reactContext).emitScreenRegionsChanged(screenId, toMap(value))
+    }
+
+    /** `{ division, occlusion }`, empty lists for an unknown screen and before its first layout. Any thread. */
+    fun get(screenId: String): WritableMap = toMap(regions[screenId] ?: NONE)
+
+    fun remove(screenId: String) {
+        regions.remove(screenId)
+    }
+
+    // The part of [bounds] (window pixels) on the screen, in dp from its top left; null off it. A fold without width
+    // counts where it crosses the screen.
+    private fun onScreen(bounds: Rect, content: Rect, density: Float): Region? {
+        val part = Rect(bounds)
+        if (!part.intersect(content)) return null
+        return Region(
+            x = (part.left - content.left) / density.toDouble(),
+            y = (part.top - content.top) / density.toDouble(),
+            width = part.width() / density.toDouble(),
+            height = part.height() / density.toDouble(),
+        )
+    }
+
+    private fun toMap(value: Regions): WritableMap = Arguments.createMap().apply {
+        putArray("division", toArray(value.division))
+        putArray("occlusion", toArray(value.occlusion))
+    }
+
+    private fun toArray(regions: List<Region>): WritableArray = Arguments.createArray().apply {
+        for (region in regions) {
+            pushMap(Arguments.createMap().apply {
+                putDouble("x", region.x)
+                putDouble("y", region.y)
+                putDouble("width", region.width)
+                putDouble("height", region.height)
+            })
+        }
+    }
+}