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

package/android/src/main/java/dev/apexnative/navigation/layout/LayoutNode.kt

@@ -0,0 +1,118 @@
+package dev.apexnative.navigation.layout
+
+import com.facebook.react.bridge.ReadableMap
+import dev.apexnative.navigation.options.Options
+
+/**
+ * A node of a layout as a command brings it, read and checked whole by [LayoutReader] on the module thread before
+ * anything is queued, then read on the main thread. It doesn't change after it is read; its options are read into
+ * [Options] on the module thread too, and `passProps` stays as React Native gave it.
+ */
+internal data class LayoutNode(
+    /** The node's id, as JavaScript gave it. */
+    val id: String,
+    /** The node's type. */
+    val type: LayoutType,
+    /** `data.name`: the screen's module, `slot:<Name>`, the native screen's registration, the pair's name. */
+    val name: String?,
+    /**
+     * `data.options`, read: the node's own options as the layout gives them, one-shot options included; empty when the
+     * node has none.
+     */
+    val options: Options,
+    /** `data.key` of a screen. */
+    val key: String?,
+    /** `data.passProps` of a native screen; a React screen's props stay in JavaScript. */
+    val passProps: ReadableMap?,
+    /** `data.functions` of a native screen: the names of the functions among its props. */
+    val functions: List<String>,
+    /** `data.columns` of a split view as given: the column of each child, in order; empty when missing. */
+    val columns: List<String>,
+    /** The data of a pair; none for other nodes. */
+    val arrangement: ArrangementData?,
+    /** The children; empty for a screen, whose children aren't read. */
+    val children: List<LayoutNode>,
+) {
+    /** A screen: `Component` or `ExternalComponent`. */
+    val isScreen: Boolean
+        get() = type.isScreen
+
+    /** A side of a side menu: commands don't find it by its id. */
+    val isSideMenuSide: Boolean
+        get() = type.isSideMenuSide
+
+    /** The screen of a single React tree: its name is `slot:<Name>`. */
+    val isSlot: Boolean
+        get() = type == LayoutType.Component && name?.startsWith(SLOT_PREFIX) == true
+
+    /** The name in events and in the navigation state: [name] without `slot:`. */
+    val screenName: String?
+        get() = if (isSlot) name?.removePrefix(SLOT_PREFIX) else name
+
+    /** This node and every node under it, depth first. */
+    fun allNodes(): List<LayoutNode> = mutableListOf<LayoutNode>().also(::collect)
+
+    /**
+     * The children of a split view by column: child i is the column `columns[i]`; without `columns` the first two
+     * children are `primary` and `secondary`. Names that aren't columns, and children without a name, are left out; of
+     * two children with one column the first counts.
+     */
+    fun columnChildren(): Map<String, LayoutNode> {
+        val result = LinkedHashMap<String, LayoutNode>()
+        children.forEachIndexed { index, child ->
+            columnName(columns, index)?.let { result.putIfAbsent(it, child) }
+        }
+        return result
+    }
+
+    private fun collect(into: MutableList<LayoutNode>) {
+        into += this
+        children.forEach { it.collect(into) }
+    }
+
+    companion object {
+        const val SLOT_PREFIX = "slot:"
+
+        const val PRIMARY = "primary"
+        const val SECONDARY = "secondary"
+        const val SUPPLEMENTARY = "supplementary"
+        const val COMPACT = "compact"
+        const val INSPECTOR = "inspector"
+
+        private val COLUMN_NAMES = setOf(PRIMARY, SECONDARY, SUPPLEMENTARY, COMPACT, INSPECTOR)
+        private val COLUMNS_WITHOUT_NAMES = listOf(PRIMARY, SECONDARY)
+
+        /** The column of the child at [index] of a split view with [columns]; none for a child without one. */
+        internal fun columnName(columns: List<String>, index: Int): String? {
+            val names = columns.ifEmpty { COLUMNS_WITHOUT_NAMES }
+            return names.getOrNull(index)?.takeIf { it in COLUMN_NAMES }
+        }
+    }
+}
+
+/** The root, the modals and the overlays of `setRoot`. */
+internal data class RootLayout(
+    /** The new root of the app. */
+    val root: LayoutNode,
+    /** Shown after the root, in order, each over the one before. */
+    val modals: List<LayoutNode>,
+    /** Shown after the modals, one by one. */
+    val overlays: List<LayoutNode>,
+)
+
+/**
+ * The data of a pair as JavaScript gave it: a value of the wrong kind is none. The pair's defaults are applied where
+ * the pair is made.
+ */
+internal data class ArrangementData(
+    /** `split` or `overlay`. */
+    val style: String?,
+    /** `horizontal`, `vertical` or `both`. */
+    val axes: String?,
+    /** The share of the primary screen along the division, 0–1. */
+    val fraction: Double?,
+    /** `leading`, `trailing`, `top` or `bottom`: the primary's edge in `overlay`. */
+    val primaryEdge: String?,
+    /** `primary` or `pair`: what a window too small for the pair shows. */
+    val compact: String?,
+)

package/android/src/main/java/dev/apexnative/navigation/layout/LayoutReader.kt

@@ -0,0 +1,274 @@
+package dev.apexnative.navigation.layout
+
+import android.content.Context
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
+import dev.apexnative.navigation.NavigationApplication
+import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.options.OptionsReader
+import dev.apexnative.navigation.react.ErrorTexts
+
+/**
+ * Reads the layout of a command straight from React Native's data, once, into [LayoutNode]s, and checks it whole
+ * before any view is made: the type and the id of every node, the name of every screen, the registration of every
+ * native screen, the nesting of the layouts, and one id per node of the layout. The first error found throws a
+ * [LayoutException] with the command's rejection. Fields the layout doesn't define are ignored. Once the whole layout
+ * passed its checks, the options of every node are read ([OptionsReader]), depth first in layout order, so the first
+ * error is the same on iOS: a value that can't be read rejects with `unreadableOption`. Runs on the module thread;
+ * [isNativeScreen] reads the app's registry under its own lock; [Context] is the app's, which platform colors resolve
+ * with (none in unit tests).
+ */
+internal object LayoutReader {
+    /** One node: the layout of `push`, `preparePush`, `showModal`, `showOverlay`, `showInColumn`. */
+    @JvmStatic
+    fun node(map: ReadableMap?, isNativeScreen: (String) -> Boolean = ::isRegistered): LayoutNode =
+        node(map, null, isNativeScreen)
+
+    /** As [node], its options read with the app's [context]. */
+    @JvmStatic
+    fun node(map: ReadableMap?, context: Context?, isNativeScreen: (String) -> Boolean = ::isRegistered): LayoutNode {
+        val reading = Reading(isNativeScreen, context)
+        val node = reading.top(map)
+        reading.readOptions()
+        return reading.withOptions(node)
+    }
+
+    /** The layout of `setRoot`: a root, and the modals and overlays, none when missing. */
+    @JvmStatic
+    fun root(map: ReadableMap?, isNativeScreen: (String) -> Boolean = ::isRegistered): RootLayout =
+        root(map, null, isNativeScreen)
+
+    /** As [root], its options read with the app's [context]. */
+    @JvmStatic
+    fun root(map: ReadableMap?, context: Context?, isNativeScreen: (String) -> Boolean = ::isRegistered): RootLayout {
+        val root = map?.mapOrNull("root")
+        if (map == null || root == null) throw LayoutException(ErrorTexts.rootMissing())
+        val reading = Reading(isNativeScreen, context)
+        val layout = RootLayout(
+            root = reading.top(root),
+            modals = map.arrayOrNull("modals")?.let(reading::tops).orEmpty(),
+            overlays = map.arrayOrNull("overlays")?.let(reading::tops).orEmpty(),
+        )
+        reading.readOptions()
+        return RootLayout(
+            root = reading.withOptions(layout.root),
+            modals = layout.modals.map(reading::withOptions),
+            overlays = layout.overlays.map(reading::withOptions),
+        )
+    }
+
+    /** The screens of `setStackRoot`, bottom to top; ids count once across all of them. */
+    @JvmStatic
+    fun nodes(array: ReadableArray?, isNativeScreen: (String) -> Boolean = ::isRegistered): List<LayoutNode> =
+        nodes(array, null, isNativeScreen)
+
+    /** As [nodes], their options read with the app's [context]. */
+    @JvmStatic
+    fun nodes(
+        array: ReadableArray?,
+        context: Context?,
+        isNativeScreen: (String) -> Boolean = ::isRegistered,
+    ): List<LayoutNode> {
+        val reading = Reading(isNativeScreen, context)
+        val nodes = array?.let(reading::tops).orEmpty()
+        reading.readOptions()
+        return nodes.map(reading::withOptions)
+    }
+
+    /** The id of the node [map], read without failing: the texts of failures that come before the layout is read. */
+    @JvmStatic
+    fun idOf(map: ReadableMap?): String = try {
+        map?.stringOrNull("id").orEmpty()
+    } catch (e: RuntimeException) {
+        ""
+    }
+
+    private fun isRegistered(name: String): Boolean =
+        NavigationApplication.instanceOrNull?.isNativeScreenRegistered(name) == true
+
+    // Where a node stands: the parent it is checked against, the menu of a side, the column of a split view's child.
+    private class Place(
+        val parent: LayoutType? = null,
+        val parentId: String = "",
+        val menuId: String = "",
+        val column: String? = null,
+    )
+
+    // One reading of one command's layout: the ids it has met so far, and the options of each node, in layout order.
+    private class Reading(private val isNativeScreen: (String) -> Boolean, private val context: Context?) {
+        private val ids = HashSet<String>()
+        private val rawOptions = LinkedHashMap<String, ReadableMap?>()
+        private val options = HashMap<String, Options>()
+
+        // The options of every node met, once the whole layout passed its checks; the first value that can't be
+        // read rejects the command.
+        fun readOptions() {
+            rawOptions.forEach { (id, map) ->
+                val read = OptionsReader.read(map, context)
+                read.unreadablePath?.let { throw LayoutException(ErrorTexts.unreadableOption(it, id)) }
+                options[id] = read.options
+            }
+        }
+
+        // [node] and the nodes under it with the options read for them.
+        fun withOptions(node: LayoutNode): LayoutNode = node.copy(
+            options = options[node.id] ?: Options(),
+            children = node.children.map(::withOptions),
+        )
+
+        fun top(map: ReadableMap?): LayoutNode = read(map, Place())
+
+        fun tops(array: ReadableArray): List<LayoutNode> = (0 until array.size()).map { top(array.mapAt(it)) }
+
+        private fun read(map: ReadableMap?, place: Place): LayoutNode {
+            val typeName = map?.stringOrNull("type")
+            val type = LayoutType.fromName(typeName)
+            if (map == null || type == null) throw LayoutException(ErrorTexts.unknownNodeType(typeName.orEmpty()))
+            val id = map.stringOrNull("id")?.takeIf { it.isNotEmpty() }
+                ?: throw LayoutException(ErrorTexts.nodeWithoutId(type.jsName))
+            checkPlace(type, id, place)
+            if (!ids.add(id)) throw LayoutException(ErrorTexts.idGivenTwice(id))
+
+            val data = map.mapOrNull("data")
+            rawOptions[id] = data?.mapOrNull("options")
+            val name = data?.stringOrNull("name")
+            if (type.isScreen && name.isNullOrEmpty()) {
+                throw LayoutException(ErrorTexts.nodeWithoutName(type.jsName, id))
+            }
+            if (type == LayoutType.ExternalComponent && name != null && !isNativeScreen(name)) {
+                throw LayoutException(ErrorTexts.nativeScreenNotRegistered(name))
+            }
+
+            // A screen's children aren't read.
+            val childMaps = if (type.isScreen) null else map.arrayOrNull("children")
+            val count = childMaps?.size() ?: 0
+            checkCount(type, id, count, place)
+            val isNative = type == LayoutType.ExternalComponent
+            val columns = if (type == LayoutType.SplitView) data?.arrayOrNull("columns").strings() else emptyList()
+            val children = (0 until count).map { index ->
+                val column = if (type == LayoutType.SplitView) LayoutNode.columnName(columns, index) else null
+                read(childMaps?.mapAt(index), Place(type, id, place.parentId, column))
+            }
+            val node = LayoutNode(
+                id = id,
+                type = type,
+                name = name,
+                options = Options(),
+                key = data?.stringOrNull("key"),
+                passProps = if (isNative) data?.mapOrNull("passProps") else null,
+                functions = if (isNative) data?.arrayOrNull("functions").strings() else emptyList(),
+                columns = columns,
+                arrangement = if (type == LayoutType.Arrangement) arrangementOf(data) else null,
+                children = children,
+            )
+            checkChildren(node)
+            return node
+        }
+
+        // The node where its parent put it, from the parent's point of view.
+        private fun checkPlace(type: LayoutType, id: String, place: Place) {
+            val text = when (place.parent) {
+                LayoutType.Stack ->
+                    if (type !in stackChildren) ErrorTexts.stackTakesScreens(place.parentId, type.jsName) else null
+                LayoutType.BottomTabs ->
+                    if (type == LayoutType.BottomTabs) ErrorTexts.tabsInTabs(place.parentId) else null
+                LayoutType.SideMenuRoot ->
+                    if (!type.isSideMenuSide) ErrorTexts.sideMenuChild(place.parentId, type.jsName) else null
+                LayoutType.SideMenuLeft, LayoutType.SideMenuCenter, LayoutType.SideMenuRight ->
+                    if (type == LayoutType.SideMenuRoot) ErrorTexts.sideMenuInSide(place.menuId) else null
+                LayoutType.SplitView ->
+                    if (place.column != null && type == LayoutType.SplitView) {
+                        ErrorTexts.splitViewInColumn(place.parentId)
+                    } else {
+                        null
+                    }
+                LayoutType.Arrangement ->
+                    if (!type.isScreen) ErrorTexts.pairNeedsTwoScreens(place.parentId) else null
+                else -> null
+            }
+            text?.let { throw LayoutException(it) }
+            if (type.isSideMenuSide && place.parent != LayoutType.SideMenuRoot) {
+                throw LayoutException(ErrorTexts.sideOutsideMenu(id, type.jsName))
+            }
+        }
+
+        // What the number of children decides, before the children are read.
+        private fun checkCount(type: LayoutType, id: String, count: Int, place: Place) {
+            val text = when (type) {
+                LayoutType.Stack -> if (count == 0) ErrorTexts.emptyStack(id) else null
+                LayoutType.BottomTabs -> when {
+                    count == 0 -> ErrorTexts.emptyTabs(id)
+                    count > MAX_TABS -> ErrorTexts.tooManyTabs(id, count)
+                    else -> null
+                }
+                LayoutType.Arrangement -> if (count != 2) ErrorTexts.pairNeedsTwoScreens(id) else null
+                LayoutType.SideMenuLeft, LayoutType.SideMenuCenter, LayoutType.SideMenuRight ->
+                    if (count != 1) ErrorTexts.sideChildCount(id, place.parentId) else null
+                else -> null
+            }
+            text?.let { throw LayoutException(it) }
+        }
+
+        // What the types of the children decide, once they are read.
+        private fun checkChildren(node: LayoutNode) {
+            when (node.type) {
+                LayoutType.SideMenuRoot -> {
+                    val sides = node.children.groupingBy { it.type }.eachCount()
+                    val center = sides[LayoutType.SideMenuCenter] ?: 0
+                    val left = sides[LayoutType.SideMenuLeft] ?: 0
+                    val right = sides[LayoutType.SideMenuRight] ?: 0
+                    if (center != 1 || left > 1 || right > 1) {
+                        throw LayoutException(ErrorTexts.sideMenuSides(node.id))
+                    }
+                }
+                LayoutType.SplitView -> {
+                    val columns = node.columnChildren()
+                    if (LayoutNode.PRIMARY !in columns || LayoutNode.SECONDARY !in columns) {
+                        throw LayoutException(ErrorTexts.splitViewColumns(node.id))
+                    }
+                }
+                else -> Unit
+            }
+        }
+
+        private fun arrangementOf(data: ReadableMap?) = ArrangementData(
+            style = data?.stringOrNull("style"),
+            axes = data?.stringOrNull("axes"),
+            fraction = data?.doubleOrNull("fraction"),
+            primaryEdge = data?.stringOrNull("primaryEdge"),
+            compact = data?.stringOrNull("compact"),
+        )
+    }
+}
+
+// The most tabs Android shows.
+private const val MAX_TABS = 5
+
+// What a stack takes.
+private val stackChildren = setOf(LayoutType.Component, LayoutType.ExternalComponent, LayoutType.Arrangement)
+
+// A field of the wrong JSON kind counts as missing. `getType` is asked only for a key the map has: a native map
+// throws for one it hasn't.
+private fun ReadableMap.typeOf(key: String): ReadableType? = if (hasKey(key)) getType(key) else null
+
+private fun ReadableMap.stringOrNull(key: String): String? =
+    if (typeOf(key) == ReadableType.String) getString(key) else null
+
+private fun ReadableMap.mapOrNull(key: String): ReadableMap? =
+    if (typeOf(key) == ReadableType.Map) getMap(key) else null
+
+private fun ReadableMap.arrayOrNull(key: String): ReadableArray? =
+    if (typeOf(key) == ReadableType.Array) getArray(key) else null
+
+private fun ReadableMap.doubleOrNull(key: String): Double? =
+    if (typeOf(key) == ReadableType.Number) getDouble(key) else null
+
+private fun ReadableArray.mapAt(index: Int): ReadableMap? =
+    if (getType(index) == ReadableType.Map) getMap(index) else null
+
+// The strings of an array; an entry of another kind is an empty name, which names nothing.
+private fun ReadableArray?.strings(): List<String> {
+    if (this == null) return emptyList()
+    return (0 until size()).map { if (getType(it) == ReadableType.String) getString(it).orEmpty() else "" }
+}

package/android/src/main/java/dev/apexnative/navigation/layout/LayoutType.kt

@@ -0,0 +1,35 @@
+package dev.apexnative.navigation.layout
+
+/** The type of a node of the layout JSON, with the name JavaScript sends. */
+internal enum class LayoutType(
+    /** The name in the layout JSON. */
+    val jsName: String,
+) {
+    Component("Component"),
+    ExternalComponent("ExternalComponent"),
+    Stack("Stack"),
+    BottomTabs("BottomTabs"),
+    SideMenuRoot("SideMenuRoot"),
+    SideMenuLeft("SideMenuLeft"),
+    SideMenuCenter("SideMenuCenter"),
+    SideMenuRight("SideMenuRight"),
+    SplitView("SplitView"),
+    Arrangement("Arrangement"),
+    ;
+
+    /** A screen: a React screen or a native one. */
+    val isScreen: Boolean
+        get() = this == Component || this == ExternalComponent
+
+    /** A side of a side menu: a place in the menu, not a layout of its own. */
+    val isSideMenuSide: Boolean
+        get() = this == SideMenuLeft || this == SideMenuCenter || this == SideMenuRight
+
+    companion object {
+        private val byName = entries.associateBy { it.jsName }
+
+        /** The type JavaScript names [name]; none for a name the layout doesn't know. */
+        @JvmStatic
+        fun fromName(name: String?): LayoutType? = name?.let(byName::get)
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/nativescreen/NativeScreenCalls.kt

@@ -0,0 +1,61 @@
+package dev.apexnative.navigation.nativescreen
+
+import androidx.annotation.RestrictTo
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableArray
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** A call of a native screen failed in JS, or could not reach it. */
+class NativeScreenCallException(message: String) : Exception(message)
+
+/** The calls of native screens waiting for JS to answer, by their ids. Main thread only. */
+@RestrictTo(RestrictTo.Scope.LIBRARY)
+object NativeScreenCalls {
+    private class Call(val componentId: String, val name: String, val result: ((Result<Any?>) -> Unit)?)
+
+    private val calls = HashMap<String, Call>()
+    private var lastId = 0
+
+    /** Keeps the result of the call [name] of the screen; returns the id JS answers it with. */
+    fun add(componentId: String, name: String, result: ((Result<Any?>) -> Unit)?): String {
+        val callId = "NativeScreenCall${++lastId}"
+        calls[callId] = Call(componentId, name, result)
+        return callId
+    }
+
+    /** JS answered: `{ value }`, or `{ error }` with its message. */
+    @JvmStatic
+    fun resolve(callId: String, answer: JSONObject) {
+        if (answer.has("error")) {
+            finish(callId, Result.failure(NativeScreenCallException(answer.getString("error"))))
+        } else {
+            finish(callId, Result.success(answer.opt("value").takeUnless { it == JSONObject.NULL }))
+        }
+    }
+
+    /** The JavaScript that would answer is gone (a reload): every call fails with [reason] of its name and screen. */
+    @JvmStatic
+    fun failAll(reason: (name: String, componentId: String) -> String) =
+        calls.toList().forEach { (callId, call) -> fail(callId, reason(call.name, call.componentId)) }
+
+    /** The arguments of a call as JS reads them. */
+    @JvmStatic
+    fun toArguments(arguments: JSONArray): WritableArray = Arguments.makeNativeArray(toJava(arguments) as List<*>)
+
+    private fun fail(callId: String, reason: String) =
+        finish(callId, Result.failure(NativeScreenCallException(reason)))
+
+    private fun finish(callId: String, result: Result<Any?>) {
+        val call = calls.remove(callId) ?: return
+        call.result?.invoke(result)
+    }
+
+    // JSON as the lists and maps React Native converts; JSONObject.NULL as null.
+    private fun toJava(value: Any?): Any? = when (value) {
+        is JSONObject -> value.keys().asSequence().associateWith { toJava(value.opt(it)) }
+        is JSONArray -> (0 until value.length()).map { toJava(value.opt(it)) }
+        JSONObject.NULL -> null
+        else -> value
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/nativescreen/NativeScreenContext.kt

@@ -0,0 +1,84 @@
+package dev.apexnative.navigation.nativescreen
+
+import androidx.annotation.RestrictTo
+import dev.apexnative.navigation.react.ErrorTexts
+import dev.apexnative.navigation.react.ReloadCoordinator
+import dev.apexnative.navigation.react.events.EventEmitter
+import dev.apexnative.navigation.utils.UiThread
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** What a native screen gets when JS opens it, for as long as it is open. */
+class NativeScreenContext @RestrictTo(RestrictTo.Scope.LIBRARY) constructor(
+    /** The screen's layout id: `externalComponent.id`, or the one JS generated. */
+    val componentId: String,
+    props: JSONObject,
+    functions: Collection<String>,
+    private val eventEmitter: EventEmitter,
+) {
+    /**
+     * The props: those of the command that showed the screen, with what its `useProps` returns over them. Plain data;
+     * they change while the screen is open, and [onPropsChange] tells when.
+     */
+    var props: JSONObject = props
+        private set
+
+    /** The names of the functions in the props, which [call] runs in JS. */
+    var functions: Set<String> = functions.toSet()
+        private set
+
+    // The JavaScript the screen was made for: once it went, its emitter may reach the next one, which never showed
+    // this screen (bridgeless: an old context sends through the host's current instance).
+    private val generation = ReloadCoordinator.generation
+
+    /** Called on the main thread with the new props, each time they change. */
+    var onPropsChange: ((JSONObject) -> Unit)? = null
+
+    /**
+     * Runs a function of the props in JS. [result] gets, on the main thread, what it returned (for a promise, what it
+     * resolved with) as plain data, or the error: a function the props don't have, one that threw, a screen gone.
+     */
+    @JvmOverloads
+    fun call(function: String, arguments: JSONArray = JSONArray(), result: ((Result<Any?>) -> Unit)? = null) =
+        send("function", function, arguments, result)
+
+    /**
+     * Runs a command of the navigation from this screen in JS, as `useNavigation()` of a React screen does: push, pop,
+     * popTo, popToRoot, showInColumn, showModal, dismiss, showOverlay, dismissOverlay, setOptions, selectTab,
+     * setTabBadge. [arguments] are those of the JS command; [result] gets what it resolved with.
+     */
+    @JvmOverloads
+    fun navigate(command: String, arguments: JSONArray = JSONArray(), result: ((Result<Any?>) -> Unit)? = null) =
+        send("command", command, arguments, result)
+
+    /** New props from JS, on the main thread: `{ props, removed, functions }`, the changed ones and the names gone. */
+    @RestrictTo(RestrictTo.Scope.LIBRARY)
+    fun applyUpdate(update: JSONObject) {
+        val next = JSONObject(props, props.keys().asSequence().toList().toTypedArray())
+        update.optJSONObject("props")?.let { changed ->
+            changed.keys().forEach { key -> next.put(key, changed.get(key)) }
+        }
+        update.optJSONArray("removed")?.let { removed ->
+            for (i in 0 until removed.length()) next.remove(removed.getString(i))
+        }
+        props = next
+        update.optJSONArray("functions")?.let { names ->
+            functions = (0 until names.length()).map(names::getString).toSet()
+        }
+        onPropsChange?.invoke(next)
+    }
+
+    // The call waits for its answer under its id; the event takes it to JS. Without a sender for the JavaScript that
+    // runs (none yet, or the screen's went) nothing could answer it: it fails at once.
+    private fun send(kind: String, name: String, arguments: JSONArray, result: ((Result<Any?>) -> Unit)?) {
+        UiThread.post {
+            if (!eventEmitter.canSend || !ReloadCoordinator.isCurrent(generation)) {
+                val text = ErrorTexts.nativeCallNotRunning(name, componentId)
+                result?.invoke(Result.failure(NativeScreenCallException(text)))
+                return@post
+            }
+            val callId = NativeScreenCalls.add(componentId, name, result)
+            eventEmitter.emitNativeScreenCall(componentId, callId, kind, name, arguments)
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/nativescreen/NativeScreenCreator.kt

@@ -0,0 +1,17 @@
+package dev.apexnative.navigation.nativescreen
+
+import android.view.View
+import androidx.fragment.app.FragmentActivity
+import dev.apexnative.navigation.viewcontrollers.externalcomponent.ExternalComponentCreator
+
+/** Makes the view of a native screen: Android views, or a ComposeView. */
+fun interface NativeScreenCreator {
+    fun create(activity: FragmentActivity, context: NativeScreenContext): View
+
+    companion object {
+        /** A creator of the 8.x registration (`registerExternalComponent`): it gets the props the screen showed with. */
+        @JvmStatic
+        fun of(creator: ExternalComponentCreator) =
+            NativeScreenCreator { activity, context -> creator.create(activity, context.props).asView() }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/options/AnimationsOptions.kt

@@ -0,0 +1,54 @@
+package dev.apexnative.navigation.options
+
+import com.facebook.react.bridge.ReadableMap
+
+/**
+ * `animations` (`AnimationOptions`): the animations of the commands that change the hierarchy, each for the next time
+ * its command runs.
+ */
+class AnimationsOptions {
+    @JvmField var push = StackPushAnimationOptions()
+    @JvmField var pop = StackAnimationOptions()
+    @JvmField var setStackRoot = SetStackRootAnimationOptions()
+    @JvmField var setRoot = EnterExitAnimationOptions()
+    @JvmField var showModal = ModalAnimationOptions()
+    @JvmField var dismissModal = ModalAnimationOptions()
+
+    fun hasValue(): Boolean = push.hasValue() || pop.hasValue() || setStackRoot.hasValue() || setRoot.hasValue() ||
+        showModal.hasValue() || dismissModal.hasValue()
+
+    fun mergeWith(other: AnimationsOptions) {
+        push.mergeWith(other.push)
+        pop.mergeWith(other.pop)
+        setStackRoot.mergeWith(other.setStackRoot)
+        setRoot.mergeWith(other.setRoot)
+        showModal.mergeWith(other.showModal)
+        dismissModal.mergeWith(other.dismissModal)
+    }
+
+    fun mergeWithDefault(defaults: AnimationsOptions) {
+        push.mergeWithDefault(defaults.push)
+        pop.mergeWithDefault(defaults.pop)
+        setStackRoot.mergeWithDefault(defaults.setStackRoot)
+        setRoot.mergeWithDefault(defaults.setRoot)
+        showModal.mergeWithDefault(defaults.showModal)
+        dismissModal.mergeWithDefault(defaults.dismissModal)
+    }
+
+    fun copy() = AnimationsOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): AnimationsOptions {
+            val options = AnimationsOptions()
+            if (map == null) return options
+            options.push = map.group("push") { StackPushAnimationOptions.parse(it) }
+            options.pop = map.group("pop") { StackAnimationOptions.parse(it) }
+            options.setStackRoot = map.group("setStackRoot") { SetStackRootAnimationOptions.parse(it) }
+            options.setRoot = map.group("setRoot") { EnterExitAnimationOptions.parse(it) }
+            options.showModal = map.group("showModal") { ModalAnimationOptions.parse(it) }
+            options.dismissModal = map.group("dismissModal") { ModalAnimationOptions.parse(it) }
+            return options
+        }
+    }
+}