@apexnative/navigation 1.0.0-alpha.0 → 1.0.0-alpha.10

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalCoordinator.kt

@@ -147,14 +147,20 @@ internal class ModalCoordinator(
          */
         fun carry(record: ModalRecord, oldRoot: ViewController<*>?)
 
-        /** New [options] (resolved) of the record: its `testID`s, its sheet's `update` ([move]: to its selection). */
-        fun update(record: ModalRecord, options: Options, move: Boolean)
+        /**
+         * New [options] (resolved) of the record: its `testID`s, its sheet's `update`; [merge] is the `mergeOptions`
+         * that brought them, which alone may move the sheet, or null when the shown screen changed.
+         */
+        fun update(record: ModalRecord, options: Options, merge: Options?)
 
         /** The colors of the record's own views again (a light/dark switch). */
         fun repaint(record: ModalRecord) = Unit
 
         /** The record's views lay out again (the activity resumed). */
         fun requestLayout(record: ModalRecord) = Unit
+
+        /** The record's sheet as back sees it; none before its show and for a modal that isn't a sheet. */
+        fun sheetBack(record: ModalRecord): SheetBack? = null
     }
 
     /**
@@ -258,6 +264,54 @@ internal class ModalCoordinator(
         }
     }
 
+    /**
+     * A modal of a `setRoot`'s layout made with the root, before its turn: it joins the modals layer and renders
+     * unseen while the root waits and comes in, held — it doesn't show, and commands and back don't count it — until
+     * [release]; [animated] as in [showInChain]. A failure is logged, and nothing is made (null).
+     */
+    fun hold(id: String, make: () -> ViewController<*>, animated: Boolean): ModalRecord? = try {
+        start(make, null, ModalRecord.Chain(animated) {}, held = true)
+    } catch (e: Throwable) {
+        val reason = ErrorTexts.reasonOf(e)
+        host.log("[ApexNavigation] setRoot: ${ErrorTexts.couldNot("show the screen '$id'", reason)}")
+        null
+    }
+
+    /**
+     * The turn of a [hold]'s modal in its `setRoot`'s chain: it shows as soon as it rendered, as [showInChain]'s
+     * would, with [done] once it showed or went; at once when it went meanwhile. The function returned stops it while
+     * it waits.
+     */
+    fun release(record: ModalRecord, done: () -> Unit): () -> Unit {
+        if (!record.held || record.state != State.Waiting) {
+            done()
+            return {}
+        }
+        record.chain = ModalRecord.Chain(record.chain?.animated ?: true, done)
+        record.held = false
+        guarded(record) {
+            host.backChanged()
+            // Rendered while held: the targets of its elements are in the layer under it only now.
+            if (record.isReady && !record.targetsAwaited && awaitsTargets(record)) {
+                record.isReady = false
+                awaitTargets(record)
+            } else {
+                presentReady()
+            }
+        }
+        return {
+            record.chain = null
+            if (record.state == State.Waiting) cancel(record, null, reports = false)
+        }
+    }
+
+    /** A [hold]'s modal whose `setRoot` ended before its turn: it goes without a word. */
+    fun drop(record: ModalRecord) {
+        if (!record.held) return
+        record.chain = null
+        if (record.state == State.Waiting) cancel(record, null, reports = false)
+    }
+
     /**
      * `dismissModal` after its shared steps: the record of [componentId], Android's rule of the last modal without a
      * root, [options] merged into the modal's visible screen, the animation of the command's screen with its parents
@@ -276,6 +330,7 @@ internal class ModalCoordinator(
             State.ClosedBelow -> return answer.resolve(record.rootId)
             else -> Unit
         }
+        if (record.held) return answer.reject(ErrorTexts.screenNotShown(componentId))
         if (isLastWithoutRoot(record)) return answer.reject(ErrorTexts.modalWithoutRoot(componentId))
         options?.let { mergeInto(record, it) }
         val from = node?.takeUnless { it.isDestroyed } ?: record.root
@@ -290,7 +345,7 @@ internal class ModalCoordinator(
      * before anything changes, with the id of the top modal's visible screen.
      */
     fun dismissAll(options: Options?, unreadablePath: String?, answer: CommandAnswer) {
-        val members = records.filter { it.batch == null && it.state in BATCHED }
+        val members = records.filter { it.batch == null && !it.held && it.state in BATCHED }
         if (members.isEmpty()) {
             // Nothing else to take: the second one answers with the running batch (N6), else at once.
             val running = batches.lastOrNull()
@@ -344,6 +399,27 @@ internal class ModalCoordinator(
         return true
     }
 
+    /**
+     * The root of the modal that back goes to first; none without one. A back gesture previews a pop in it, or the
+     * modal's dismissal when it is a sheet ([backTargetSheet]).
+     */
+    fun backTargetRoot(): ViewController<*>? = backTarget()?.root
+
+    /**
+     * The sheet back would dismiss now, as [handleBack] would, and as a drag down of the user would: the top modal is
+     * a sheet that shows, its content can't go back (else back goes there, and a pop in it has its own preview),
+     * `modal.swipeToDismiss` isn't false, `hardwareBackButton.dismissModalOnPress` doesn't hold back, it isn't the only
+     * modal over no root, and its sheet would hide, not collapse, and isn't closing already ([SheetBack.hidesOnBack]).
+     * None otherwise. The back gesture previews its hide on Android 14+, and its release closes it as the user does.
+     */
+    fun backTargetSheet(): SheetBack? {
+        val record = backTarget()?.takeIf { it.isSheet && it.state == State.Shown } ?: return null
+        if (record.root.canHandleBack() || holdsBack(record) || isLastWithoutRoot(record)) return null
+        val options = record.root.resolveShownOptions(DefaultOptions.current)
+        if (options.modal.swipeToDismiss.isFalse) return null
+        return views.sheetBack(record)?.takeIf { it.hidesOnBack }
+    }
+
     /** The mirror of [handleBack], without acting; null without a modal to ask. */
     fun canHandleBack(): Boolean? {
         val record = backTarget() ?: return null
@@ -353,13 +429,14 @@ internal class ModalCoordinator(
     // Options.
 
     /**
-     * A `mergeOptions` went into [node] (`mergeOptions` step 5): when it is in a modal, the modal's sheet takes its
-     * options again (it re-reads the resolved ones at any merge) and its `testID`s apply again.
+     * A `mergeOptions` of [merge] went into [node] (`mergeOptions` step 5): when it is in a modal, the modal's sheet
+     * takes its resolved options again, moving only to a `selectedDetent` that [merge] names, and its `testID`s apply
+     * again.
      */
-    fun optionsMergedInto(node: ViewController<*>) {
+    fun optionsMergedInto(node: ViewController<*>, merge: Options) {
         val record = recordOf(node) ?: return
         if (record.root.isDestroyed) return
-        views.update(record, record.root.resolveShownOptions(DefaultOptions.current), move = true)
+        views.update(record, record.root.resolveShownOptions(DefaultOptions.current), merge)
     }
 
     /**
@@ -369,7 +446,7 @@ internal class ModalCoordinator(
     fun visibleScreenChanged(node: ViewController<*>) {
         val record = recordOf(node) ?: return
         if (record.state == State.Waiting || record.root.isDestroyed) return
-        views.update(record, record.root.resolveShownOptions(DefaultOptions.current), move = false)
+        views.update(record, record.root.resolveShownOptions(DefaultOptions.current), merge = null)
     }
 
     /** The colors of the modals' own views again, after a light/dark switch. */
@@ -418,6 +495,8 @@ internal class ModalCoordinator(
         }
         batches.clear()
         for (record in records.toList()) {
+            // A modal of the new root's layout, made with it, stays: it shows over the new root in its turn.
+            if (record.held) continue
             if (record.state == State.Waiting) {
                 cancel(record, null, reports = false)
                 continue
@@ -428,7 +507,7 @@ internal class ModalCoordinator(
             views.carry(record, old)
             carried += record
         }
-        records.clear()
+        records.retainAll { it.held }
         host.backChanged()
     }
 
@@ -478,7 +557,12 @@ internal class ModalCoordinator(
 
     // The show (3, 4).
 
-    private fun start(make: () -> ViewController<*>, answer: CommandAnswer?, chain: ModalRecord.Chain?): ModalRecord {
+    private fun start(
+        make: () -> ViewController<*>,
+        answer: CommandAnswer?,
+        chain: ModalRecord.Chain?,
+        held: Boolean = false,
+    ): ModalRecord {
         val root = make()
         val record: ModalRecord
         val options: Options
@@ -488,6 +572,7 @@ internal class ModalCoordinator(
             val sheet = ModalRecord.isSheet(options)
             root.shownAsSheet = sheet
             record = ModalRecord(root, sheet)
+            record.held = held
         } catch (e: Throwable) {
             root.destroy()
             throw e
@@ -551,7 +636,7 @@ internal class ModalCoordinator(
     private fun ready(record: ModalRecord) {
         if (record.state != State.Waiting) return
         record.wait = null
-        if (!record.targetsAwaited && awaitsTargets(record)) return awaitTargets(record)
+        if (!record.targetsAwaited && !record.held && awaitsTargets(record)) return awaitTargets(record)
         record.cancelLimit()
         record.isReady = true
         presentReady()
@@ -603,7 +688,7 @@ internal class ModalCoordinator(
         if (taking) return
         for (record in records.toList()) {
             if (record.state != State.Waiting) continue
-            if (!record.isReady) return
+            if (record.held || !record.isReady) return
             present(record)
         }
     }
@@ -664,7 +749,7 @@ internal class ModalCoordinator(
     // without the events not sent yet; what waits for it rejects, the layer it took out comes back, and the modals that
     // wait go on.
     private fun dismissFailed(record: ModalRecord, e: Throwable) {
-        val text = ErrorTexts.couldNot("dismiss the modal of the screen '${record.rootId}'", ErrorTexts.reasonOf(e))
+        val text = ErrorTexts.couldNot("dismiss the modal '${record.rootId}'", ErrorTexts.reasonOf(e))
         val listed = record in records
         val under = layerUnder(record)
         runCatching { record.stopAnimation?.invoke() }
@@ -768,8 +853,8 @@ internal class ModalCoordinator(
             State.Presenting -> record.waitingDismissals += dismissal
             State.Shown -> if (isTop(record)) beginDismissal(record, dismissal) else closeBelow(record, dismissal)
             State.Dismissing -> dismissal.answer?.let(record.answers::add)
-            State.ClosedBelow -> dismissal.answer?.resolve(record.rootId)
-            State.WithOldRoot, State.Gone -> dismissal.answer?.reject(ErrorTexts.screenNotShown(record.rootId))
+            // It went already, or goes with the old root: the dismissal just completes, as on iOS.
+            State.ClosedBelow, State.WithOldRoot, State.Gone -> dismissal.answer?.resolve(record.rootId)
         }
     }
 
@@ -783,7 +868,7 @@ internal class ModalCoordinator(
         record.state = State.Gone
         records.remove(record)
         views.remove(record)
-        val screen = AppearanceDispatcher.visibleNode(record.root)
+        val screen = AppearanceDispatcher.modalScreen(record.root)
         record.showAnswer?.resolve(record.rootId)
         record.showAnswer = null
         record.chain?.let {
@@ -945,7 +1030,7 @@ internal class ModalCoordinator(
         val wasOut = isOut(revealed)
         val counted = members.filter { it.state != State.ClosedBelow && !it.reported }
         batch.count = counted.size
-        batch.screen = counted.lastOrNull()?.let { AppearanceDispatcher.visibleNode(it.root) }
+        batch.screen = counted.lastOrNull()?.let { AppearanceDispatcher.modalScreen(it.root) }
         // The top that leaves with its animation: one already leaving keeps its own.
         val top = members.lastOrNull { it.state in ANIMATED_IN_BATCH }
         batch.top = top
@@ -1152,13 +1237,16 @@ internal class ModalCoordinator(
 
     // A record is the top when no record above it waits, comes in or shows; one that leaves doesn't count.
     private fun isTop(record: ModalRecord): Boolean =
-        records.drop(records.indexOf(record) + 1).none { it.effective in TOP_STATES }
+        records.drop(records.indexOf(record) + 1).none(::countsAsTop)
 
     // The top record, as the commands see it; none.
-    private fun topRecord(): ModalRecord? = records.lastOrNull { it.effective in TOP_STATES }
+    private fun topRecord(): ModalRecord? = records.lastOrNull(::countsAsTop)
 
     // Back goes to the top modal that waits, comes in or shows.
-    private fun backTarget(): ModalRecord? = records.lastOrNull { it.effective in TOP_STATES }
+    private fun backTarget(): ModalRecord? = records.lastOrNull(::countsAsTop)
+
+    // A record that waits, comes in or shows; a held one doesn't count before its turn.
+    private fun countsAsTop(record: ModalRecord): Boolean = !record.held && record.effective in TOP_STATES
 
     // `hardwareBackButton.dismissModalOnPress: false` of the modal's options now.
     private fun holdsBack(record: ModalRecord): Boolean =
@@ -1230,7 +1318,7 @@ internal class ModalCoordinator(
         val screen = AppearanceDispatcher.visibleNode(record.root)
         if (screen.isDestroyed) return
         screen.mergeOptions(options)
-        optionsMergedInto(screen)
+        optionsMergedInto(screen, options)
     }
 
     private inline fun whileTaking(work: () -> Unit) {

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalRecord.kt

@@ -17,7 +17,10 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 internal class ModalRecord(
     /** The top node of the modal's layout. */
     val root: ViewController<*>,
-    /** The modal shows as a Material sheet (`modal.sheet`), decided before its root's view is made. */
+    /**
+     * The modal shows as a Material sheet (`pageSheet`, `formSheet`, `popover`, or `modal.sheet` without a style),
+     * decided before its root's view is made.
+     */
     val isSheet: Boolean,
 ) : WaitingLayer {
     /** Where the modal is. */
@@ -78,6 +81,12 @@ internal class ModalRecord(
     /** Its wait ended: it shows once every older waiting modal showed or went (N1). */
     var isReady = false
 
+    /**
+     * A modal of a `setRoot`'s layout made with the root, before its turn: it renders unseen while the root waits and
+     * comes in, and neither shows nor counts for commands or back until its step of the chain lets it go.
+     */
+    var held = false
+
     /** The wait for its screens while it waits. */
     var wait: RenderWait? = null
 
@@ -160,14 +169,20 @@ internal class ModalRecord(
         /** `modalPresentationStyle` values that keep the layer under in place. */
         private val OVER_STYLES = setOf("overFullScreen", "overCurrentContext")
 
-        /** The styles a sheet shows with: unset, `pageSheet`, `formSheet`. */
-        private val SHEET_STYLES = setOf(null, "pageSheet", "formSheet")
+        /**
+         * The styles that always show as a sheet: the sheets of iOS, and the popover, which an iPhone shows as a sheet
+         * too.
+         */
+        private val SHEET_STYLES = setOf("pageSheet", "formSheet", "popover")
 
         /**
-         * Whether a modal with [options] (resolved, with the defaults) shows as a sheet: any `modal.sheet` field set,
-         * and the style unset, `pageSheet` or `formSheet`.
+         * Whether a modal with [options] (resolved, with the defaults) shows as a sheet: its style is `pageSheet`,
+         * `formSheet` or `popover`, or it has none and any `modal.sheet` field is set.
          */
-        fun isSheet(options: Options): Boolean = options.modal.sheet.hasValue && styleOf(options) in SHEET_STYLES
+        fun isSheet(options: Options): Boolean {
+            val style = styleOf(options)
+            return style in SHEET_STYLES || (style == null && options.modal.sheet.hasValue)
+        }
 
         /**
          * Whether a modal covers the layer under it at the end of its show: full screen, unless it is a sheet or