@apexnative/navigation 1.0.0-alpha.3 → 1.0.0-alpha.4

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

@@ -211,7 +211,7 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
         layout: ReadableMap,
         promise: Promise,
     ) {
-        // Android has one column to show screens in: the secondary pane (`showInColumn`).
+        // Android's split view has the primary and the secondary pane; another column rejects (`showInColumn`).
         val what = "show the screen '${LayoutReader.idOf(layout)}' in the '$column' column"
         runner.run(
             name = "showInColumn",
@@ -219,7 +219,7 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
             what = what,
             promise = promise,
             check = { LayoutReader.node(layout, context = appContext()) },
-        ) { node, answer -> navigator().stackCommands.showInColumn(componentId, node, answer, what) }
+        ) { node, answer -> navigator().stackCommands.showInColumn(componentId, column, node, answer, what) }
     }
 
     override fun setColumnShown(
@@ -295,9 +295,10 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
         })
     }
 
-    // The navigation of the activity the command runs in; the runner checked there is one.
+    // The navigation of the activity the command runs in; the runner checked there is an activity. One without its
+    // navigation yet (or any more) has nowhere to show screens either: the command rejects with the runner's own text.
     private fun navigator(): Navigator =
-        requireNotNull(Navigators.current()?.navigator) { "the activity has no navigation" }
+        Navigators.current()?.navigator ?: throw LayoutException(ErrorTexts.nowhereToShow())
 
     // The app's context, which the colors of the options resolve platform colors with.
     private fun appContext(): Context = reactApplicationContext.applicationContext

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

@@ -0,0 +1,48 @@
+package dev.apexnative.navigation.react
+
+import dev.apexnative.navigation.NavigationApplication
+import dev.apexnative.navigation.utils.UiThread
+
+/**
+ * The calls JavaScript made to the module that may not have reached the main thread yet: [after] runs a task on the
+ * main thread behind every one of them. A screen's first mount reaches the main thread from Fabric while a
+ * `mergeOptions` of the same React commit (its layout effects: `useScreenOptions`) may still be on its way: an
+ * asynchronous method goes from the JavaScript thread to the module's thread (`BridgelessNativeMethodCallInvoker`),
+ * which reads its options there and posts its body to the main thread ([CommandRunner]). The task goes the same way: a
+ * turn of the JavaScript thread, which comes after the task of the commit with its layout effects; then the module's
+ * thread, behind the calls that task made; then the main thread, behind their bodies. Each of the three runs its queue
+ * in order, so every call JavaScript made before the mount has applied when the task runs.
+ *
+ * Without JavaScript (none yet, a reload, a queue that ended) the task is posted to the main thread at once: nothing is
+ * on its way. A queue that ends while the task is on it drops it, and a wait with no limit of its own (a push with
+ * `waitForRender: true` whose content has mounted: the task is its only end) would not end; a queue ends only as the
+ * JavaScript goes (a reload, the host destroyed), and then the layouts go with it (`ReloadCoordinator`), the stack
+ * and its waiting push too. Main thread.
+ */
+internal object PendingCalls {
+    /** A queue the task goes through: it runs what it takes in order, and says false when it ended and took nothing. */
+    fun interface Queue {
+        fun run(task: Runnable): Boolean
+    }
+
+    /** Runs [task] on the main thread, on a later turn, after every call JavaScript made so far has applied there. */
+    fun after(task: () -> Unit) {
+        val context = NavigationApplication.instanceOrNull?.reactGatewayOrNull?.currentReactContext
+            ?.takeIf { it.hasActiveReactInstance() }
+        val js = context?.jsMessageQueueThread?.let { Queue(it::runOnQueue) }
+        val module = context?.nativeModulesMessageQueueThread?.let { Queue(it::runOnQueue) }
+        after(js, module, UiThread::post, task)
+    }
+
+    /**
+     * The way of [after] over the queues given: [js], then [module], then [main]; straight to [main] without one of
+     * them, or from where a queue refused it. The unit tests run it over their own queues.
+     */
+    fun after(js: Queue?, module: Queue?, main: (Runnable) -> Unit, task: () -> Unit) {
+        val onMain = Runnable(task)
+        if (js == null || module == null) return main(onMain)
+        val toMain = Runnable { main(onMain) }
+        val toModule = Runnable { if (!module.run(toMain)) main(onMain) }
+        if (!js.run(toModule)) main(onMain)
+    }
+}

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

@@ -391,12 +391,14 @@ internal object AppearanceDispatcher {
 
     /**
      * [modal] went with [count] modals (EVT-ModalDismissed): `ANN.ModalDismissed` with the id and the name of the
-     * screen the modal shows, down its current children.
+     * screen the modal shows, down its current children ([modalScreen]); a modal that shows no screen gives its own id
+     * and no name.
      */
     fun modalDismissed(modal: ViewController<*>, count: Int) {
         if (!ReloadCoordinator.isCurrent(modal.jsGeneration)) return
-        val screen = visibleNode(modal)
-        sender.modalDismissed(screen.id, screen.currentComponentName.orEmpty(), count)
+        val named = modalScreen(modal)
+        val name = if (named is ParentController<*>) "" else named.currentComponentName.orEmpty()
+        sender.modalDismissed(named.id, name, count)
     }
 
     /**
@@ -449,7 +451,7 @@ internal object AppearanceDispatcher {
      * modal shows. Nothing for a JavaScript that went.
      */
     fun modalAttemptedToDismiss(modal: ViewController<*>) {
-        val screen = visibleNode(modal)
+        val screen = modalScreen(modal)
         if (ReloadCoordinator.isCurrent(screen.jsGeneration)) sender.modalAttemptedToDismiss(screen.id)
     }
 
@@ -458,18 +460,26 @@ internal object AppearanceDispatcher {
      * Nothing for a JavaScript that went.
      */
     fun sheetDetentChanged(modal: ViewController<*>, detent: Any) {
-        val screen = visibleNode(modal)
+        val screen = modalScreen(modal)
         if (ReloadCoordinator.isCurrent(screen.jsGeneration)) sender.sheetDetentChanged(screen.id, detent)
     }
 
     /**
      * The screen [node] shows: the node at the end of its current children (the one "visible screen" of the core): what
-     * `ANN.ModalDismissed`, `ANN.ModalAttemptedToDismiss`, `ANN.SheetDetentChanged` and back's
-     * `ANN.NavigationButtonPressed` of a modal name. A layout without a child answers itself.
+     * back's `ANN.NavigationButtonPressed` of a modal names, and, through [modalScreen], its `ANN.ModalDismissed`,
+     * `ANN.ModalAttemptedToDismiss` and `ANN.SheetDetentChanged`. A layout without a child answers itself.
      */
     fun visibleNode(node: ViewController<*>): ViewController<*> {
         var current = node
         while (current is ParentController<*>) current = current.currentChild ?: break
         return current
     }
+
+    /**
+     * The node the events of the modal [modal] (its root) name: its [visibleNode] when that is a screen; the root
+     * itself when the chain ends in a layout without a child, as on iOS. Asked again of what it gave, it gives the
+     * same.
+     */
+    fun modalScreen(modal: ViewController<*>): ViewController<*> =
+        visibleNode(modal).takeUnless { it is ParentController<*> } ?: modal
 }

package/android/src/main/java/dev/apexnative/navigation/slots/SlotContainers.kt

@@ -9,14 +9,15 @@ interface SlotContainer {
 }
 
 /**
- * The native containers the slots of the app's React tree show their children in, by slot id. A destroyed container
- * drops out on its own.
+ * The native containers the slots of the app's React tree show their children in, by slot id, and the slot views by
+ * the same id: a change of a container goes straight to the views of its id. A destroyed container and a collected
+ * view drop out on their own.
  */
 object SlotContainers {
     private class Entry(val view: WeakReference<ViewGroup>, val passThrough: Boolean)
 
     private val containers = HashMap<String, Entry>()
-    private val slots = LinkedHashSet<SlotView>()
+    private val slots = SlotViews<SlotView>()
 
     /** `passThrough`: touches outside the slot's content go to the screens below, as in an overlay for a toast. */
     fun put(slotId: String, container: ViewGroup, passThrough: Boolean = false) {
@@ -33,12 +34,14 @@ object SlotContainers {
         changed(slotId)
     }
 
-    /** The container of a slot appeared or changed its size. */
+    /** The container of a slot appeared or changed its size: the slot views under its id, and only they, hear it. */
     fun changed(slotId: String) {
-        slots.toList().forEach { it.containerChanged(slotId) }
+        slots.views(slotId).forEach { it.containerChanged(slotId) }
     }
 
-    internal fun listen(slot: SlotView) = slots.add(slot)
+    /** The slot view goes under its slot id, and out from under the id it had. Main thread only. */
+    internal fun register(slotId: String, slot: SlotView) = slots.register(slotId, slot)
 
-    internal fun stopListening(slot: SlotView) = slots.remove(slot)
+    /** The slot view unmounted or lost its slot id: no container change reaches it. Main thread only. */
+    internal fun unregister(slot: SlotView) = slots.unregister(slot)
 }

package/android/src/main/java/dev/apexnative/navigation/slots/SlotView.kt

@@ -86,7 +86,6 @@ class SlotView(reactContext: ThemedReactContext) : ReactViewGroup(reactContext)
     init {
         content.visibility = INVISIBLE
         addView(content)
-        SlotContainers.listen(this)
     }
 
     override fun setId(id: Int) {
@@ -100,7 +99,9 @@ class SlotView(reactContext: ThemedReactContext) : ReactViewGroup(reactContext)
     }
 
     fun attachContent() {
-        val id = slotId ?: return
+        // The view hears the changes of the container under the id it has now, and no other.
+        val id = slotId ?: return SlotContainers.unregister(this)
+        SlotContainers.register(id, this)
         val container = SlotContainers.get(id)
         val target: ViewGroup = container ?: this
         if (content.parent !== target) {
@@ -135,7 +136,7 @@ class SlotView(reactContext: ThemedReactContext) : ReactViewGroup(reactContext)
     }
 
     fun drop() {
-        SlotContainers.stopListening(this)
+        SlotContainers.unregister(this)
         (content.parent as? ViewGroup)?.removeView(content)
     }
 }

package/android/src/main/java/dev/apexnative/navigation/slots/SlotViews.kt

@@ -0,0 +1,40 @@
+package dev.apexnative.navigation.slots
+
+import java.lang.ref.WeakReference
+import java.util.WeakHashMap
+
+/**
+ * The slot views by their slot id, held weakly, so a change of a container reaches only the views of its id. A view is
+ * under one id at a time: registering it under a new one (its `nativeID` changed, or Fabric reused it) takes it out
+ * from under the old one. Two live views under one id both stay, in the order they came, and both hear the change, as
+ * every view with that id did when the change went to all of them. Main thread only.
+ */
+internal class SlotViews<T : Any> {
+    private val byId = HashMap<String, MutableList<WeakReference<T>>>()
+    private val idOf = WeakHashMap<T, String>()
+
+    fun register(slotId: String, view: T) {
+        if (idOf[view] == slotId) return
+        unregister(view)
+        idOf[view] = slotId
+        byId.getOrPut(slotId) { ArrayList(1) }.add(WeakReference(view))
+    }
+
+    fun unregister(view: T) {
+        val slotId = idOf.remove(view) ?: return
+        prune(slotId) { it === view }
+    }
+
+    /** The live views under [slotId], a copy: a view may register or leave while it hears the change. */
+    fun views(slotId: String): List<T> {
+        prune(slotId) { false }
+        return byId[slotId]?.mapNotNull { it.get() }.orEmpty()
+    }
+
+    // Drops the collected views under the id and the ones `drop` picks; an id with no views left goes.
+    private fun prune(slotId: String, drop: (T) -> Boolean) {
+        val views = byId[slotId] ?: return
+        views.removeAll { reference -> reference.get()?.let(drop) ?: true }
+        if (views.isEmpty()) byId.remove(slotId)
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/utils/ImageKey.kt

@@ -0,0 +1,66 @@
+package dev.apexnative.navigation.utils
+
+import android.content.Context
+import android.content.res.Configuration
+import android.view.View
+import java.io.File
+import java.net.URI
+import java.net.URISyntaxException
+
+/**
+ * What an image of the options is cached by: its [uri] and what changes the decoded result for the same uri, the
+ * screen's density (a drawable of the app picks its density's file, a decoded file is scaled to it), light or dark
+ * (`drawable-night`) and the layout direction (`drawable-ldrtl`, auto-mirrored drawables). For a `file:` uri also the
+ * file's [modified] time and [size]: a file the app writes again at the same path is another image. The loader bakes
+ * no tint and no size into an image, so neither is part of it.
+ */
+internal data class ImageKey(
+    val uri: String,
+    val densityDpi: Int,
+    val night: Boolean,
+    val rightToLeft: Boolean,
+    /** When the file of a `file:` uri last changed, in milliseconds; 0 for any other uri or a file that isn't there. */
+    val modified: Long = 0,
+    /** The bytes of the file of a `file:` uri; 0 for any other uri or a file that isn't there. */
+    val size: Long = 0,
+) {
+    companion object {
+        private const val FILE_SCHEME = "file:"
+        private const val FILE_PREFIX = "file://"
+
+        /** The key of [uri] in the current configuration of [context]. Any thread. */
+        fun of(context: Context, uri: String): ImageKey {
+            val configuration = context.resources.configuration
+            return of(uri, configuration.densityDpi, configuration.uiMode, configuration.layoutDirection)
+        }
+
+        /**
+         * The key of [uri] for a configuration's density, `uiMode` (only its night bits count) and layout direction;
+         * a `file:` uri reads its file's modification time and size. Any thread.
+         */
+        fun of(uri: String, densityDpi: Int, uiMode: Int, layoutDirection: Int): ImageKey {
+            val file = filePath(uri)?.let(::File)
+            return ImageKey(
+                uri = uri,
+                densityDpi = densityDpi,
+                night = uiMode and Configuration.UI_MODE_NIGHT_MASK == Configuration.UI_MODE_NIGHT_YES,
+                rightToLeft = layoutDirection == View.LAYOUT_DIRECTION_RTL,
+                // Both 0 when the file isn't there or can't be read.
+                modified = file?.lastModified() ?: 0,
+                size = file?.length() ?: 0,
+            )
+        }
+
+        // The path of a `file:` uri, decoded as the loader's `Uri.getPath` decodes it; none for any other uri. A uri
+        // that `URI` can't parse (an unescaped space) is taken as it is after its scheme.
+        private fun filePath(uri: String): String? {
+            if (!uri.startsWith(FILE_SCHEME)) return null
+            val path = try {
+                URI(uri).path
+            } catch (e: URISyntaxException) {
+                null
+            }
+            return path ?: uri.removePrefix(FILE_PREFIX).removePrefix(FILE_SCHEME).ifEmpty { null }
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/utils/ImageLoader.kt

@@ -1,19 +1,8 @@
 package dev.apexnative.navigation.utils
 
 import android.content.Context
-import android.content.res.Resources
-import android.graphics.BitmapFactory
-import android.graphics.drawable.BitmapDrawable
 import android.graphics.drawable.Drawable
-import android.net.Uri
-import android.os.StrictMode
-import androidx.core.content.ContextCompat
-import com.facebook.react.views.imagehelper.ResourceDrawableIdHelper
-import java.io.FileInputStream
-import java.io.FileNotFoundException
 import java.io.IOException
-import java.io.InputStream
-import java.net.URL
 
 /** What an image loads into: [onComplete] with the image, or [onError] when it can't load. Main thread. */
 open class ImageLoadingListenerAdapter {
@@ -23,90 +12,19 @@ open class ImageLoadingListenerAdapter {
 }
 
 /**
- * Loads the images and icons of the options when they apply: synchronously on the main thread, without a cache, each
- * image its own mutable copy. A `file:` address is a file; anything else first a drawable of the app by name (as React
- * Native's images by resource name: release builds' assets, `{ android }` icons). Not found while the app is in
- * development: the address is read as a stream, Metro's asset over the network (network on the main thread allowed for
- * that read only) or through the content resolver. A remote address that is not Metro's asset is never loaded. A
- * failure never ends the app: the listener's [ImageLoadingListenerAdapter.onError], the log, and React Native's red
- * screen in development.
+ * Loads an image or an icon of the options at once, through the shared cache of [OptionImages]: each image its own
+ * mutable copy. For the places whose first frame needs the image (the top bar's buttons, the back button, menus, search
+ * suggestions); a place that can show it when ready asks through [ImageRequests]. A failure never ends the app: the
+ * listener's [ImageLoadingListenerAdapter.onError], and one warning per address.
  */
 class ImageLoader {
     /** Loads [uri] and gives it to [listener] before returning. Main thread. */
     fun loadIcon(context: Context, uri: String, listener: ImageLoadingListenerAdapter) {
-        val drawable = try {
-            load(context, uri)
-        } catch (e: Exception) {
-            val reason = if (e is LoadFailure) "" else ": ${e.message ?: e.javaClass.simpleName}"
-            DevelopmentLog.error("Could not load image $uri$reason${(e as? LoadFailure)?.why.orEmpty()}", e)
-            listener.onError(e)
+        val drawable = OptionImages.load(context, uri)
+        if (drawable == null) {
+            listener.onError(IOException("Could not load image $uri"))
             return
         }
         listener.onComplete(drawable)
     }
-
-    private fun load(context: Context, uri: String): Drawable {
-        if (uri.startsWith(FILE_SCHEME)) return decode(context) { FileInputStream(Uri.parse(uri).path) }
-        resourceDrawable(context, uri)?.let { return it }
-        if (!DevelopmentLog.isDevelopment) throw LoadFailure("")
-        val address = Uri.parse(uri)
-        return when (address.scheme) {
-            "http", "https" -> {
-                if (!isMetroAsset(address)) throw LoadFailure(": remote images are not supported in options")
-                withNetworkOnMainThread { decode(context) { URL(uri).openStream() } }
-            }
-            else -> decode(context) {
-                context.contentResolver.openInputStream(address) ?: throw FileNotFoundException(uri)
-            }
-        }
-    }
-
-    // A drawable of the app by name, its own copy; none when the app has none by that name.
-    private fun resourceDrawable(context: Context, name: String): Drawable? {
-        val id = ResourceDrawableIdHelper.getResourceDrawableId(context, name)
-        if (id <= 0) return null
-        return try {
-            ContextCompat.getDrawable(context, id)?.mutate()
-        } catch (e: Resources.NotFoundException) {
-            null
-        }
-    }
-
-    // The image of the stream [open] gives, closed after the read, also on an error; one it can't decode fails, and so
-    // does one too large for the memory: that is a load error too, never the end of the app.
-    private fun decode(context: Context, open: () -> InputStream): Drawable {
-        val decoded = try {
-            open().use { BitmapFactory.decodeStream(it) }
-        } catch (e: OutOfMemoryError) {
-            throw LoadFailure(": it is too large to decode")
-        }
-        val bitmap = decoded ?: throw LoadFailure(": it can't be decoded")
-        return BitmapDrawable(context.resources, bitmap)
-    }
-
-    // A failure the loader names itself: `Could not load image <source>`, then [why].
-    private class LoadFailure(val why: String) : IOException("Could not load image$why")
-
-    // Metro's asset: an address of the server the JavaScript bundle came from, under `/assets/`.
-    private fun isMetroAsset(address: Uri): Boolean {
-        val bundle = DevelopmentLog.bundleUrl?.let(Uri::parse) ?: return false
-        return address.host == bundle.host && address.port == bundle.port &&
-            address.path.orEmpty().startsWith(ASSETS_PATH)
-    }
-
-    // Reading from the network on the main thread for [read] only; the thread's policy comes back, also on an error.
-    private fun <T> withNetworkOnMainThread(read: () -> T): T {
-        val policy = StrictMode.getThreadPolicy()
-        StrictMode.setThreadPolicy(StrictMode.ThreadPolicy.Builder(policy).permitNetwork().build())
-        try {
-            return read()
-        } finally {
-            StrictMode.setThreadPolicy(policy)
-        }
-    }
-
-    private companion object {
-        const val FILE_SCHEME = "file:"
-        const val ASSETS_PATH = "/assets/"
-    }
 }

package/android/src/main/java/dev/apexnative/navigation/utils/ImageRequests.kt

@@ -0,0 +1,76 @@
+package dev.apexnative.navigation.utils
+
+import android.graphics.drawable.Drawable
+
+/** Where the images of the options come from, for one context: [OptionImages.source], or a fake in the tests. */
+internal interface ImageSource {
+    /** The key of [uri] in the context's configuration now; for a `file:` uri it reads the file's version. */
+    fun key(uri: String): ImageKey
+
+    /** A copy of the image of [key] when the cache has it, none otherwise; never loads. */
+    fun cached(key: ImageKey): Drawable?
+
+    /** A copy of the image of [key], from the cache or loaded on the caller's thread; none on a failure. */
+    fun now(key: ImageKey): Drawable?
+
+    /** Whether [uri] can load off the main thread: a file or a drawable of the app. */
+    fun loadsLater(uri: String): Boolean
+
+    /** Loads [key] off the main thread and gives a copy of it, or none on a failure, to [done] on the main thread. */
+    fun later(key: ImageKey, done: (Drawable?) -> Unit)
+}
+
+/**
+ * The images that the places of a view asked for (an item's icon, a button's icon), by place [P]: what the cache has
+ * comes at once; what it doesn't, when the place can show it later, loads off the main thread and comes when ready;
+ * everything else loads at once. The last request of a place wins: a load that arrives after the place asked again,
+ * or after [forget] or [clear], is dropped. A load that fails gives the place no image, as an option without one:
+ * the image it showed before doesn't stay. A request builds the key of its image once (a file's version is read once).
+ * Main thread only.
+ */
+internal class ImageRequests<P : Any>(private val source: ImageSource) {
+    // The open load of each place: its number, which a later request of the place replaces.
+    private val waiting = HashMap<P, Long>()
+    private var last = 0L
+
+    /** The key of [uri] now, for a caller that compares it before it asks ([request] with the key). */
+    fun key(uri: String): ImageKey = source.key(uri)
+
+    /** [request] for the image of [uri], its key built here. */
+    fun request(place: P, uri: String, mayWait: Boolean, show: (Drawable?) -> Unit) =
+        request(place, source.key(uri), mayWait, show)
+
+    /**
+     * Gives [show] the image of [key] for [place]: now when the cache has it, or when the place can't wait for it
+     * ([mayWait] false: the first frame needs it) or the uri can't load off the main thread (Metro's address, a content
+     * uri); otherwise later, unless [place] asks again first. Null when it doesn't load: the place shows none.
+     */
+    fun request(place: P, key: ImageKey, mayWait: Boolean, show: (Drawable?) -> Unit) {
+        waiting.remove(place)
+        source.cached(key)?.let {
+            show(it)
+            return
+        }
+        if (!mayWait || !source.loadsLater(key.uri)) {
+            show(source.now(key))
+            return
+        }
+        val number = ++last
+        waiting[place] = number
+        source.later(key) { image ->
+            if (waiting[place] != number) return@later
+            waiting.remove(place)
+            show(image)
+        }
+    }
+
+    /** The place shows no image of the options now: a load it asked for earlier is dropped. */
+    fun forget(place: P) {
+        waiting.remove(place)
+    }
+
+    /** The view goes: every open load is dropped. */
+    fun clear() {
+        waiting.clear()
+    }
+}