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

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

@@ -0,0 +1,186 @@
+package dev.apexnative.navigation.viewcontrollers.modal
+
+import dev.apexnative.navigation.options.ModalAnimationOptions
+import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.react.CommandAnswer
+import dev.apexnative.navigation.viewcontrollers.component.RenderWait
+import dev.apexnative.navigation.viewcontrollers.navigator.WaitingLayer
+import dev.apexnative.navigation.viewcontrollers.parent.ParentController
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+/**
+ * One modal of an activity: its layout's top node, its state, and what waits for its transitions. Every rule about
+ * modals is a move of one record ([ModalCoordinator]); nothing else keeps a list of modals. While it waits to show it
+ * is a [WaitingLayer] of its activity: a stack in it runs its commands at once and tells it when its top changes. Main
+ * thread only.
+ */
+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. */
+    val isSheet: Boolean,
+) : WaitingLayer {
+    /** Where the modal is. */
+    enum class State {
+        /** Made and findable; waits for its screens, unseen. No appearance event went. */
+        Waiting,
+
+        /** Its show runs; its screens' `ComponentWillAppear` went. */
+        Presenting,
+
+        /** On screen; its show answered. */
+        Shown,
+
+        /** Its dismissal runs (a command, back, the user, a `dismissAllModals`). */
+        Dismissing,
+
+        /** Dismissed while a modal above it stays: reported and destroyed, its exit plays unseen. */
+        ClosedBelow,
+
+        /** A `setRoot` was accepted: commands don't find it; it goes with the old root. */
+        WithOldRoot,
+
+        /** Out of the list. */
+        Gone,
+    }
+
+    /** The id `showModal` answers with, which `dismissModal` takes. */
+    val rootId: String = root.id
+
+    /** The state; the coordinator moves it. */
+    var state = State.Waiting
+
+    /** The state the record had when a `setRoot` took it ([State.WithOldRoot]). */
+    var before = State.Waiting
+
+    /**
+     * The state for everything that isn't a command (the user, back, its own transitions, the layers): the one it
+     * had before a `setRoot` took it, else its own.
+     */
+    val effective: State
+        get() = if (state == State.WithOldRoot) before else state
+
+    /** The answer of its `showModal`; none in a `setRoot`'s chain, or once answered. */
+    var showAnswer: CommandAnswer? = null
+
+    /** The step of a `setRoot`'s chain that waits for its show; none otherwise, or once told. */
+    var chain: Chain? = null
+
+    /** `ANN.ModalDismissed` went for it: never twice. */
+    var reported = false
+
+    /** It covers the layer under it once shown: not a sheet, not `overFullScreen` / `overCurrentContext`. */
+    var coversUnder = false
+
+    /** Its container is out of the modals layer: a modal over it covers it. */
+    var isOut = false
+
+    /** Its wait ended: it shows once every older waiting modal showed or went (N1). */
+    var isReady = false
+
+    /** The wait for its screens while it waits. */
+    var wait: RenderWait? = null
+
+    /** Stops its running show or dismissal where it is, without its end; none while nothing runs. */
+    var stopAnimation: (() -> Unit)? = null
+
+    /** The dismissals asked while it presents: the first runs at the end of the show. */
+    val waitingDismissals = mutableListOf<Dismissal>()
+
+    /** The commands that resolve with [rootId] at the end of its dismissal or its batch. */
+    val answers = mutableListOf<CommandAnswer>()
+
+    /** What its running dismissal reveals and who asked; none while it isn't dismissed on its own. */
+    var ending: Ending? = null
+
+    /** The `dismissAllModals` it goes with; none. */
+    var batch: Any? = null
+
+    /** The ids of its nodes, taken when they may go before the record does (closed below, a new root, the user). */
+    var ids: Set<String> = emptySet()
+
+    /** Its wait for the targets of its elements, after its content: what stops it. */
+    var stopTargets: (() -> Unit)? = null
+
+    /** That wait was asked: the next end of a wait shows the modal. */
+    var targetsAwaited = false
+
+    /** The 0.5 s of a wait without `waitForRender` passed: the targets get nothing of it any more. */
+    var overLimit = false
+
+    /** Cancels that limit. */
+    var cancelLimit: () -> Unit = {}
+
+    /** A stack in it changed its top while it waits: the coordinator's handler. */
+    var screensChanged: () -> Unit = {}
+
+    override val waitingNode: ViewController<*>?
+        get() = root.takeIf { state == State.Waiting }
+
+    override fun shownScreensChanged() = screensChanged()
+
+    /** The ids of every node of the modal now. */
+    fun takeIds() {
+        ids = idsOf(root)
+    }
+
+    /**
+     * A dismissal asked of the record: the command's answer (none for back and the user), whether it animates, and
+     * its `animations.dismissModal` (none: the default one).
+     */
+    class Dismissal(
+        val answer: CommandAnswer?,
+        val animated: Boolean,
+        val byUser: Boolean,
+        val animation: ModalAnimationOptions? = null,
+    )
+
+    /**
+     * A running dismissal: the layer it reveals when that had disappeared (its screens appear at the end), and whether
+     * the user (or back) closed it — its ids stay answerable then.
+     */
+    class Ending(val revealed: ViewController<*>?, val byUser: Boolean)
+
+    /** The step of a `setRoot`'s chain: [animated] for its last modal; [done] once the modal showed or went. */
+    class Chain(val animated: Boolean, val done: () -> Unit)
+
+    companion object {
+        /** The ids of [node] and every node under it. */
+        fun idsOf(node: ViewController<*>): Set<String> {
+            val ids = LinkedHashSet<String>()
+            collect(node, ids)
+            return ids
+        }
+
+        private fun collect(node: ViewController<*>, into: MutableSet<String>) {
+            into += node.id
+            (node as? ParentController<*>)?.childControllers?.forEach { collect(it, into) }
+        }
+
+        /** `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")
+
+        /**
+         * 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`.
+         */
+        fun isSheet(options: Options): Boolean = options.modal.sheet.hasValue && styleOf(options) in SHEET_STYLES
+
+        /**
+         * Whether a modal covers the layer under it at the end of its show: full screen, unless it is a sheet or
+         * `overFullScreen` / `overCurrentContext`; an unknown style is unset.
+         */
+        fun coversUnder(isSheet: Boolean, options: Options): Boolean = !isSheet && styleOf(options) !in OVER_STYLES
+
+        /** The styles `modalPresentationStyle` takes (`modalPresentationStyle`). */
+        private val STYLES = setOf(
+            "pageSheet", "formSheet", "fullScreen", "overFullScreen", "overCurrentContext", "currentContext", "popover",
+        )
+
+        // The style the options give; `null` and an unknown string (`'none'` too) read as unset.
+        private fun styleOf(options: Options): String? = options.modalPresentationStyle.value?.takeIf { it in STYLES }
+    }
+}

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

@@ -0,0 +1,342 @@
+package dev.apexnative.navigation.viewcontrollers.modal
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.graphics.Color
+import android.graphics.Outline
+import android.view.GestureDetector
+import android.view.Gravity
+import android.view.MotionEvent
+import android.view.View
+import android.view.ViewGroup
+import android.view.ViewGroup.LayoutParams.MATCH_PARENT
+import android.view.ViewGroup.LayoutParams.WRAP_CONTENT
+import android.view.ViewOutlineProvider
+import android.view.ViewTreeObserver
+import android.widget.FrameLayout
+import android.widget.ScrollView
+import androidx.coordinatorlayout.widget.CoordinatorLayout
+import androidx.core.graphics.Insets
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowInsetsCompat
+import com.google.android.material.bottomsheet.BottomSheetBehavior
+import com.google.android.material.bottomsheet.BottomSheetDragHandleView
+import dev.apexnative.navigation.options.SheetDetent
+import dev.apexnative.navigation.options.SheetOptions
+import dev.apexnative.navigation.utils.MaterialTheme
+import dev.apexnative.navigation.utils.TestIds
+import dev.apexnative.navigation.utils.dp
+import kotlin.math.roundToInt
+
+/**
+ * A modal shown as a Material bottom sheet (`modal.sheet`): the modal's view in a container with a
+ * [BottomSheetBehavior], in the modals' CoordinatorLayout, over a scrim. It stops at the detents of its options —
+ * `medium` at half the height, `large` at the full height under the status bar, a number at that height in dp — and the
+ * user drags it between them. A drag down past the smallest one closes it, unless `swipeToDismiss` is false: then the
+ * sheet stays, and the try is told. The screen under it stays in place.
+ */
+internal class ModalSheet(
+    private val layout: CoordinatorLayout,
+    private val content: View,
+    private val events: Events,
+) {
+    interface Events {
+        /** The user dragged the sheet to another detent. */
+        fun onDetentChanged(detent: SheetDetent)
+
+        /** The user closed the sheet: dragged it down or tapped the scrim. The modal goes. */
+        fun onClosedByUser()
+
+        /** The user tried to close a sheet that keeps them (`swipeToDismiss: false`). */
+        fun onCloseAttempted()
+    }
+
+    // Material 3 views: the app's Material 3 theme, or the navigation's neutral one.
+    private val context: Context = MaterialTheme.context(layout.context)
+    private val scrim = View(context)
+    private val container = SheetContainer(context)
+    private val grabber = BottomSheetDragHandleView(context)
+    private val behavior = SheetBehavior()
+    private var options = SheetOptions()
+    private var swipeToDismiss = true
+    private var detents: List<SheetDetent> = listOf(SheetDetent.Large)
+    private var selected: SheetDetent? = null
+    private var topGap = 0
+    private var dragged = false
+    private var shown: (() -> Unit)? = null
+    private var closing: (() -> Unit)? = null
+
+    // A list inside the sheet scrolls with it, as the Material behavior expects: up at half height the sheet goes up
+    // first, down at the top of the list the sheet comes down. The behavior follows views that scroll nested.
+    private val scrollViews = ViewTreeObserver.OnGlobalLayoutListener {
+        if (behavior.dragAnywhere) enableNestedScrolling(container)
+    }
+
+    /** The sheet is down, out of sight: the modal can go at once. */
+    val isClosed: Boolean
+        get() = behavior.state == BottomSheetBehavior.STATE_HIDDEN
+
+    init {
+        scrim.setBackgroundColor(Color.BLACK)
+        scrim.alpha = 0f
+        // A tap on the dimmed screen closes the sheet, as on iOS; a drag on it does nothing.
+        val taps = GestureDetector(context, object : GestureDetector.SimpleOnGestureListener() {
+            override fun onDown(e: MotionEvent) = dims()
+            override fun onSingleTapUp(e: MotionEvent): Boolean {
+                closeByUser()
+                return true
+            }
+        })
+        scrim.setOnTouchListener { _, event -> taps.onTouchEvent(event) }
+        container.clipToOutline = true
+        container.outlineProvider = object : ViewOutlineProvider() {
+            // The bottom corners are under the screen's bottom: only the top ones round.
+            override fun getOutline(view: View, outline: Outline) {
+                val radius = cornerRadius().toFloat()
+                outline.setRoundRect(0, 0, view.width, view.height + radius.roundToInt(), radius)
+            }
+        }
+        // The sheet is under the status bar: its screens leave no room for it at their top.
+        ViewCompat.setOnApplyWindowInsetsListener(container) { _, insets ->
+            val types = WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout()
+            val bars = insets.getInsets(types)
+            WindowInsetsCompat.Builder(insets).setInsets(types, Insets.of(bars.left, 0, bars.right, bars.bottom)).build()
+        }
+        container.addView(content, FrameLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT))
+        container.addView(grabber, FrameLayout.LayoutParams(WRAP_CONTENT, WRAP_CONTENT, Gravity.TOP or Gravity.CENTER_HORIZONTAL))
+        behavior.isHideable = true
+        behavior.state = BottomSheetBehavior.STATE_HIDDEN
+        behavior.halfExpandedRatio = 0.5f
+        behavior.addBottomSheetCallback(object : BottomSheetBehavior.BottomSheetCallback() {
+            override fun onStateChanged(sheet: View, newState: Int) = onState(newState)
+            override fun onSlide(sheet: View, slideOffset: Float) = updateScrim()
+        })
+        container.viewTreeObserver.addOnGlobalLayoutListener(scrollViews)
+    }
+
+    /** Slides the sheet up to its selected detent; [onShown] once it is there. */
+    fun show(sheetOptions: SheetOptions, swipeToDismiss: Boolean, onShown: () -> Unit) {
+        topGap = ViewCompat.getRootWindowInsets(layout)?.getInsets(WindowInsetsCompat.Type.systemBars())?.top ?: 0
+        layout.addView(scrim, CoordinatorLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT))
+        // As tall as its largest detent (maxHeight), not moved down by a margin: the behavior counts its states from
+        // where the sheet is laid out.
+        layout.addView(container, CoordinatorLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT).also { it.behavior = behavior })
+        shown = onShown
+        update(sheetOptions, swipeToDismiss, move = false)
+        // Laid out hidden first, so it slides up from the bottom.
+        container.post { if (closing == null) behavior.state = stateOf(selected ?: detents.first()) }
+    }
+
+    /** New options from mergeOptions: the detents, the look, and the selected detent, which the sheet moves to. */
+    fun update(sheetOptions: SheetOptions, swipeToDismiss: Boolean, move: Boolean = true) {
+        val previous = selected
+        options = sheetOptions
+        this.swipeToDismiss = swipeToDismiss
+        detents = sheetOptions.detents?.takeIf { it.isNotEmpty() }?.sortedBy { heightOf(it) } ?: listOf(SheetDetent.Large)
+        selected = sheetOptions.selectedDetent?.takeIf { it in detents }
+        grabber.visibility = if (sheetOptions.grabber.isTrue) View.VISIBLE else View.GONE
+        behavior.dragAnywhere = sheetOptions.expandsOnScroll.get(true)
+        container.invalidateOutline()
+        configure()
+        if (!move || closing != null) return
+        val settled = detentOf(behavior.state)
+        if (settled != null) behavior.isHideable = swipeToDismiss && settled == detents.first()
+        val target = when {
+            selected != null && selected != previous -> selected
+            settled != null && settled !in detents -> selected ?: detents.first()
+            else -> null
+        }
+        if (target != null) behavior.state = stateOf(target)
+        updateScrim()
+    }
+
+    /** Slides the sheet down; [onClosed] once it is out of sight. */
+    fun close(onClosed: () -> Unit) {
+        closing = onClosed
+        if (isClosed) {
+            finishClosing()
+            return
+        }
+        behavior.isHideable = true
+        behavior.state = BottomSheetBehavior.STATE_HIDDEN
+    }
+
+    /** Takes the sheet's views away; the modal's view is the caller's. */
+    fun remove() {
+        container.viewTreeObserver.removeOnGlobalLayoutListener(scrollViews)
+        container.removeView(content)
+        layout.removeView(container)
+        layout.removeView(scrim)
+    }
+
+    /** The sheet's `testID`: its container, and `<id>.grabber`, `<id>.scrim`; none takes them away. */
+    fun setTestIds(testId: String?) {
+        TestIds.apply(container, testId)
+        TestIds.applyOver(grabber, testId?.let { "$it.grabber" })
+        TestIds.apply(scrim, testId?.let { "$it.scrim" })
+    }
+
+    private fun closeByUser() {
+        if (!swipeToDismiss) {
+            events.onCloseAttempted()
+            return
+        }
+        behavior.isHideable = true
+        behavior.state = BottomSheetBehavior.STATE_HIDDEN
+    }
+
+    // How the Material behavior stops at the detents: with half and full height both, at its three states (the
+    // smallest at the collapsed one); otherwise at the collapsed state (the smaller detent) and the expanded one, which
+    // is only as tall as the largest detent.
+    private fun configure() {
+        val height = detents.filterIsInstance<SheetDetent.Height>().firstOrNull()
+        val halfAndFull = SheetDetent.Medium in detents && SheetDetent.Large in detents
+        behavior.isFitToContents = !halfAndFull
+        behavior.expandedOffset = topGap
+        behavior.maxHeight = heightOf(detents.last())
+        val collapsed = if (halfAndFull) height else detents.takeIf { it.size > 1 }?.first()
+        behavior.skipCollapsed = collapsed == null
+        // Without a detent of its own the collapsed state is the smallest detent: a sheet that isn't hideable settles
+        // there, not at Material's peek height.
+        behavior.peekHeight = heightOf(collapsed ?: detents.first())
+    }
+
+    private fun stateOf(detent: SheetDetent): Int = when {
+        detent == detents.last() -> BottomSheetBehavior.STATE_EXPANDED
+        detent == SheetDetent.Medium && !behavior.isFitToContents -> BottomSheetBehavior.STATE_HALF_EXPANDED
+        else -> BottomSheetBehavior.STATE_COLLAPSED
+    }
+
+    private fun detentOf(state: Int): SheetDetent? = when (state) {
+        BottomSheetBehavior.STATE_EXPANDED -> detents.last()
+        BottomSheetBehavior.STATE_HALF_EXPANDED -> SheetDetent.Medium
+        BottomSheetBehavior.STATE_COLLAPSED -> detents.first()
+        else -> null
+    }
+
+    /** The height of the sheet at the detent, in px. */
+    private fun heightOf(detent: SheetDetent): Int {
+        val full = (if (layout.height > 0) layout.height else layout.rootView.height) - topGap
+        return when (detent) {
+            SheetDetent.Large -> full
+            SheetDetent.Medium -> (full + topGap) / 2
+            is SheetDetent.Height -> detent.dp.toFloat().dp.coerceAtMost(full)
+        }
+    }
+
+    private fun onState(state: Int) {
+        when (state) {
+            BottomSheetBehavior.STATE_DRAGGING -> dragged = true
+            BottomSheetBehavior.STATE_HIDDEN -> {
+                when {
+                    closing != null -> finishClosing()
+                    else -> {
+                        // Dragged down or the scrim tapped: the modal goes.
+                        closing = {}
+                        events.onClosedByUser()
+                    }
+                }
+            }
+            BottomSheetBehavior.STATE_EXPANDED, BottomSheetBehavior.STATE_HALF_EXPANDED, BottomSheetBehavior.STATE_COLLAPSED -> {
+                if (closing != null) return
+                val detent = detentOf(state)
+                // A drag down closes the sheet from its smallest detent only; from a larger one it stops at the next.
+                behavior.isHideable = swipeToDismiss && detent == detents.first()
+                shown?.let {
+                    shown = null
+                    it()
+                }
+                if (dragged && detent != null && detent != selected) {
+                    selected = detent
+                    events.onDetentChanged(detent)
+                }
+                dragged = false
+            }
+        }
+        updateScrim()
+    }
+
+    private fun finishClosing() {
+        val done = closing ?: return
+        closing = {}
+        done()
+    }
+
+    // The screen under the sheet dims as the sheet goes up past `largestUndimmedDetent` (from the bottom without
+    // one), to the dim of a Material modal sheet at the next detent; while it isn't dimmed, it takes touches.
+    private fun updateScrim() {
+        val height = layout.height - container.top
+        val undimmed = options.largestUndimmedDetent?.takeIf { it in detents }
+        val from = undimmed?.let { heightOf(it) } ?: 0
+        val to = detents.firstOrNull { heightOf(it) > from }?.let { heightOf(it) } ?: return run { setDim(0f) }
+        setDim(((height - from).toFloat() / (to - from)).coerceIn(0f, 1f))
+    }
+
+    private fun setDim(fraction: Float) {
+        scrim.alpha = fraction * SCRIM_ALPHA
+    }
+
+    private fun dims() = scrim.alpha > 0f
+
+    private fun cornerRadius(): Int = if (options.cornerRadius.hasValue()) options.cornerRadius.get().toFloat().dp else 28.dp
+
+    private fun enableNestedScrolling(view: View) {
+        if (view is ScrollView && !view.isNestedScrollingEnabled) view.isNestedScrollingEnabled = true
+        if (view is ViewGroup) for (i in 0 until view.childCount) enableNestedScrolling(view.getChildAt(i))
+    }
+
+    /** With `expandsOnScroll: false` only the top of the sheet, around the grabber, drags it; the rest scrolls. */
+    private inner class SheetBehavior : BottomSheetBehavior<FrameLayout>() {
+        var dragAnywhere = true
+        private var ignoring = false
+        private var downY = 0f
+        private var downAtSmallest = false
+
+        // A sheet that keeps the user doesn't go down (it isn't hideable): a drag down from its smallest detent is a
+        // try to close it, told when the finger lifts.
+        private fun watchCloseAttempt(event: MotionEvent) {
+            when (event.actionMasked) {
+                MotionEvent.ACTION_DOWN -> {
+                    downY = event.rawY
+                    downAtSmallest = detentOf(state) == detents.first()
+                }
+                MotionEvent.ACTION_UP -> {
+                    if (!swipeToDismiss && closing == null && downAtSmallest && event.rawY - downY > ATTEMPT_DISTANCE_DP.dp) {
+                        events.onCloseAttempted()
+                    }
+                }
+            }
+        }
+
+        override fun onInterceptTouchEvent(parent: CoordinatorLayout, child: FrameLayout, event: MotionEvent): Boolean {
+            if (ignores(child, event)) return false
+            return super.onInterceptTouchEvent(parent, child, event)
+        }
+
+        @SuppressLint("ClickableViewAccessibility")
+        override fun onTouchEvent(parent: CoordinatorLayout, child: FrameLayout, event: MotionEvent): Boolean {
+            if (ignores(child, event)) return false
+            return super.onTouchEvent(parent, child, event)
+        }
+
+        override fun onStartNestedScroll(
+            coordinatorLayout: CoordinatorLayout, child: FrameLayout, directTargetChild: View, target: View, axes: Int, type: Int
+        ): Boolean = dragAnywhere && super.onStartNestedScroll(coordinatorLayout, child, directTargetChild, target, axes, type)
+
+        private fun ignores(child: View, event: MotionEvent): Boolean {
+            watchCloseAttempt(event)
+            if (dragAnywhere) return false
+            if (event.actionMasked == MotionEvent.ACTION_DOWN) ignoring = event.y - child.top > GRAB_AREA_DP.dp
+            val ignore = ignoring
+            if (event.actionMasked == MotionEvent.ACTION_UP || event.actionMasked == MotionEvent.ACTION_CANCEL) ignoring = false
+            return ignore
+        }
+    }
+
+    private companion object {
+        /** The dim of a Material modal bottom sheet's scrim. */
+        const val SCRIM_ALPHA = 0.32f
+        const val GRAB_AREA_DP = 48
+        const val ATTEMPT_DISTANCE_DP = 48
+    }
+}