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

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/splitview/SplitViewController.kt

@@ -15,6 +15,7 @@ import dev.apexnative.navigation.options.SplitViewGroupOptions
 import dev.apexnative.navigation.options.SplitViewOptions
 import dev.apexnative.navigation.react.CommandListener
 import dev.apexnative.navigation.react.CommandListenerAdapter
+import dev.apexnative.navigation.react.ErrorTexts
 import dev.apexnative.navigation.react.events.EventEmitter
 import dev.apexnative.navigation.system.SystemUiOwner
 import dev.apexnative.navigation.utils.TestIds
@@ -24,10 +25,11 @@ import dev.apexnative.navigation.viewcontrollers.child.ChildControllersRegistry
 import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackState
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.parent.ChildOffsetFromRest
+import dev.apexnative.navigation.viewcontrollers.parent.OptionsScreen
 import dev.apexnative.navigation.viewcontrollers.parent.ParentController
 import dev.apexnative.navigation.viewcontrollers.parent.ReturnsScreenFromColumn
-import dev.apexnative.navigation.viewcontrollers.parent.ShowsColumns
 import dev.apexnative.navigation.viewcontrollers.parent.ShownChildren
+import dev.apexnative.navigation.viewcontrollers.parent.ShowsColumns
 import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
@@ -45,8 +47,9 @@ class SplitViewController(
     presenter: Presenter,
     initialOptions: Options,
     private var split: SplitViewOptions,
-    private val primary: ViewController<*>,
-    private val secondary: ViewController<*>,
+    // The panes' content; `showInColumn` may give a pane a new one.
+    private var primary: ViewController<*>,
+    private var secondary: ViewController<*>,
     private val compact: ViewController<*>?,
     private val eventEmitter: EventEmitter,
 ) : ParentController<SplitViewLayout>(activity, childRegistry, id, presenter, initialOptions),
@@ -366,6 +369,19 @@ class SplitViewController(
         return can || super.canHandleBack()
     }
 
+    // As handleBack: the pane whose back goes first decides; an open sliding pane that would close previews nothing.
+    override fun stackPoppedByBack(): StackController? {
+        if (!isViewCreated) return super.stackPoppedByBack()
+        val layout = getView()
+        return when {
+            layout.isCompact -> compact?.stackPoppedByBack()
+            isSliding && !layout.panes.isOpen -> primary.stackPoppedByBack()
+            isSliding -> if (secondary.canHandleBack()) secondary.stackPoppedByBack() else null
+            secondary.canHandleBack() -> secondary.stackPoppedByBack()
+            else -> primary.stackPoppedByBack()
+        }
+    }
+
     /**
      * How far the pane of [child] is from where it rests: the secondary pane sliding over the primary one rests over
      * it, closed or on its way. Zero for the other children.
@@ -408,27 +424,67 @@ class SplitViewController(
     }
 
     /**
-     * Shows [screen] in the secondary pane in place of what it shows and brings the pane into view. False with the
-     * compact layout on screen: the screen goes over [from], the screen the command comes from.
+     * Shows [screen] in [column] (`primary` or `secondary`; Android has no other) in place of what the pane shows, and
+     * brings the pane into view. A stack pane's screens are replaced by it, unless it is a container
+     * (![goesInStack]): `columnIsStack`. Any other pane is taken by it, and its content goes. A column the split view
+     * doesn't have: `noSuchColumn`. False with the compact layout on screen: the screen goes over [from], the screen
+     * the command comes from.
      */
-    override fun showScreen(screen: ViewController<*>, from: ViewController<*>, listener: CommandListener): Boolean {
+    override fun showScreen(
+        screen: ViewController<*>,
+        column: String,
+        goesInStack: Boolean,
+        from: ViewController<*>,
+        listener: CommandListener,
+    ): Boolean {
         if (isViewCreated && getView().isCompact) return false
-        val stack = secondary as? StackController
-        if (stack == null) {
-            listener.onError("the 'secondary' column of the split view of the screen '${from.id}' is not a stack")
-            return true
+        val pane = when (column) {
+            PRIMARY -> primary
+            SECONDARY -> secondary
+            else -> null
         }
-        stack.setRoot(listOf(screen), false, object : CommandListenerAdapter() {
-            override fun onSuccess(childId: String) {
+        when {
+            pane == null -> listener.onError(ErrorTexts.noSuchColumn(from.id, column))
+            pane is StackController && !goesInStack -> listener.onError(ErrorTexts.columnIsStack(from.id, column))
+            pane is StackController -> pane.setRoot(listOf(screen), false, object : CommandListenerAdapter() {
+                override fun onSuccess(childId: String) {
+                    updateBackButton()
+                    bringIntoView(column) { listener.onSuccess(childId) }
+                }
+
+                override fun onError(message: String) = listener.onError(message)
+            })
+            else -> {
+                replacePane(pane, screen)
                 updateBackButton()
-                showSecondary { listener.onSuccess(childId) }
+                val shownId = ((screen as? OptionsScreen)?.optionsScreen ?: screen).id
+                bringIntoView(column) { listener.onSuccess(shownId) }
             }
-
-            override fun onError(message: String) = listener.onError(message)
-        })
+        }
         return true
     }
 
+    // [next] takes the pane of [old], a screen alone or a container, as iOS puts a screen in place of a column's: its
+    // view goes where the old one's was, the children shown are told as a move of the panes tells them (DidDisappear
+    // of what left, DidAppear of what came), and [old] goes with its screens.
+    private fun replacePane(old: ViewController<*>, next: ViewController<*>) {
+        next.setParentController(this)
+        if (old === primary) primary = next else secondary = next
+        peekView()?.let { layout ->
+            layout.panes.replacePane(old.getView(), next.getView())
+            applyTestIds(primary.getView(), secondary.getView())
+            hideCoveredPane()
+            shownChildren.moved()
+            tellShownChanged()
+        }
+        old.destroy()
+    }
+
+    // The pane of [column] comes into view; [done] once the panes stopped.
+    private fun bringIntoView(column: String, done: Runnable) {
+        if (column == PRIMARY) setColumnShown(PRIMARY, true, done) else showSecondary(done)
+    }
+
     private fun showSecondary(done: Runnable) {
         if (!isSliding || getView().panes.isOpen) {
             done.run()

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/BackPreview.kt

@@ -0,0 +1,287 @@
+package dev.apexnative.navigation.viewcontrollers.stack
+
+import android.animation.Animator
+import android.animation.AnimatorListenerAdapter
+import android.animation.ValueAnimator
+import android.content.res.Configuration
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Outline
+import android.graphics.Rect
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.view.PixelCopy
+import android.view.View
+import android.view.ViewGroup
+import android.view.ViewOutlineProvider
+import android.view.Window
+import android.view.animation.DecelerateInterpolator
+import android.view.animation.LinearInterpolator
+import android.view.animation.PathInterpolator
+import android.widget.ImageView
+import androidx.coordinatorlayout.widget.CoordinatorLayout
+import dev.apexnative.navigation.views.animations.SystemTransition
+import dev.apexnative.navigation.views.stack.StackLayout
+
+/**
+ * The preview of a pop while the user's back gesture runs (predictive back), as the system shows the activity under
+ * the one that closes: the screen on top with its bar, a picture taken as the gesture starts, shrinks toward the
+ * gesture's side with rounded corners and follows the finger up and down; the screen under it shows behind it with
+ * its own bar, smaller and dimmed. Released, the pop plays its end ([commit]); cancelled, everything goes back
+ * ([cancel]). The values are those of the system's cross-activity back animation (WMShell
+ * `DefaultCrossActivityBackAnimation` of Android 15 and 16, the smallest scale as Android 17 shows it), also on Android
+ * 14, whose own preview differs. Main thread only.
+ */
+internal class BackPreview(
+    private val layout: StackLayout,
+    private val top: View,
+    private val target: View,
+    /** The gesture started at the left edge: the screen moves right; from the right edge it stays centered. */
+    private val fromLeft: Boolean,
+    private val startY: Float,
+    /**
+     * The room the tabs take at the bottom of the top screen: the card is the stack above them, rounded on all four
+     * corners, while the tab bar stays, as Gmail shows it.
+     */
+    private val bottomRoom: Int,
+    /** The picture is there: the stack shows the screen under the top, with its bar, before the preview draws. */
+    private val onReveal: () -> Unit,
+) {
+    private val density = layout.resources.displayMetrics.density
+    private val bar = layout.topBar
+    private val scrim = View(layout.context)
+    private var card: ImageView? = null
+    private var progress = 0f
+    private var touchY = startY
+    private var animator: Animator? = null
+    private var ended = false
+    private var topAlpha = 1f
+    // What puts the stack as it was after a cancel: once, as the preview ends.
+    private var onCancelled: (() -> Unit)? = null
+    // Forward is to the end of the line: right to left, the screens move the other way, as the stack's pop does.
+    private val forward = if (layout.layoutDirection == View.LAYOUT_DIRECTION_RTL) -1f else 1f
+
+    /** The picture of the top is there and the screen under it shows: the preview draws. */
+    val isReady: Boolean
+        get() = card != null && !ended
+
+    /**
+     * Takes the picture of the stack as it shows now, drawn from its views (what lies over the stack, an overlay or a
+     * tab bar drawn over it, stays out of it); with a hardware bitmap in it, copied from the window a frame later. The
+     * preview draws once it is there.
+     */
+    fun start(window: Window) {
+        val width = layout.width
+        val height = areaHeight
+        if (width <= 0 || height <= 0) return
+        val picture = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+        try {
+            layout.draw(Canvas(picture))
+            show(picture)
+            return
+        } catch (e: IllegalArgumentException) {
+            picture.eraseColor(Color.TRANSPARENT)
+        }
+        val place = IntArray(2)
+        layout.getLocationInWindow(place)
+        val area = Rect(place[0], place[1], place[0] + width, place[1] + height)
+        PixelCopy.request(window, area, picture, { result ->
+            if (result == PixelCopy.SUCCESS && !ended) show(picture)
+        }, Handler(Looper.getMainLooper()))
+    }
+
+    /** The gesture moved: [value] is its progress, 0 … 1, and [y] the finger's height in the window. */
+    fun progress(value: Float, y: Float) {
+        progress = value
+        touchY = y
+        if (isReady) drawGesture(GESTURE_CURVE.getInterpolation(value))
+    }
+
+    /**
+     * The gesture was cancelled: the preview springs back, then [restore] puts the stack as it was; at once when the
+     * preview ends earlier (a new gesture, a command).
+     */
+    fun cancel(restore: () -> Unit) {
+        onCancelled = restore
+        if (!isReady) return endAtOnce()
+        val from = progress
+        animator?.cancel()
+        animator = ValueAnimator.ofFloat(from, 0f).apply {
+            duration = CANCEL_MILLIS
+            interpolator = DecelerateInterpolator()
+            addUpdateListener { drawGesture(GESTURE_CURVE.getInterpolation(it.animatedValue as Float)) }
+            addListener(object : AnimatorListenerAdapter() {
+                override fun onAnimationEnd(animation: Animator) {
+                    if (animator === animation) endAtOnce()
+                }
+            })
+            start()
+        }
+    }
+
+    /**
+     * The gesture was released and the pop runs: the top goes back to its size while it moves away by 96 dp and fades
+     * in the first fifth, the screen under it grows to its place, the dim fades; [done] once at the end, after the
+     * preview took its views away.
+     */
+    fun commit(done: () -> Unit) {
+        val card = card ?: return done()
+        val distance = SystemTransition.DISTANCE_DP * density
+        val q = GESTURE_CURVE.getInterpolation(progress)
+        val scale = scaleAt(q)
+        val cardX = card.translationX
+        val cardY = card.translationY
+        val dim = scrim.alpha
+        animator?.cancel()
+        animator = ValueAnimator.ofFloat(0f, 1f).apply {
+            duration = SystemTransition.DURATION
+            interpolator = LinearInterpolator()
+            addUpdateListener {
+                val t = it.animatedValue as Float
+                val e = SystemTransition.CURVE.getInterpolation(t)
+                card.scaleX = lerp(scale, 1f, e)
+                card.scaleY = card.scaleX
+                card.translationX = lerp(cardX, distance * forward, e)
+                card.translationY = lerp(cardY, 0f, e)
+                card.alpha = (1f - 5f * t).coerceAtLeast(0f)
+                entering(lerp(scale, 1f, e), lerp(-distance * forward, 0f, e))
+                scrim.alpha = lerp(dim, 0f, t)
+            }
+            addListener(object : AnimatorListenerAdapter() {
+                override fun onAnimationEnd(animation: Animator) {
+                    if (animator !== animation) return
+                    endAtOnce()
+                    done()
+                }
+            })
+            start()
+        }
+    }
+
+    /**
+     * The preview ends where it is: its views go, the screens and the bar take their own values again, and a cancel's
+     * restore runs.
+     */
+    fun endAtOnce() {
+        if (ended) return
+        ended = true
+        animator?.let {
+            animator = null
+            it.cancel()
+        }
+        card?.let { (it.parent as? ViewGroup)?.removeView(it) }
+        card = null
+        (scrim.parent as? ViewGroup)?.removeView(scrim)
+        top.alpha = topAlpha
+        entering(1f, 0f)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+            target.resetPivot()
+            bar.resetPivot()
+        }
+        onCancelled?.let {
+            onCancelled = null
+            it()
+        }
+    }
+
+    // The picture came: the screen under the top shows with its bar, dimmed, and the picture lies over everything in
+    // the top's place, cut to rounded corners.
+    private fun show(picture: Bitmap) {
+        onReveal()
+        val dark = layout.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK ==
+            Configuration.UI_MODE_NIGHT_YES
+        scrim.setBackgroundColor(Color.BLACK)
+        scrim.alpha = if (dark) SCRIM_DARK else SCRIM_LIGHT
+        scrim.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
+        layout.addOverAll(scrim, fill())
+        val radius = CORNER_DP * density
+        val area = CoordinatorLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, areaHeight)
+        card = ImageView(layout.context).apply {
+            setImageBitmap(picture)
+            scaleType = ImageView.ScaleType.FIT_XY
+            importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
+            outlineProvider = object : ViewOutlineProvider() {
+                override fun getOutline(view: View, outline: Outline) =
+                    outline.setRoundRect(0, 0, view.width, view.height, radius)
+            }
+            clipToOutline = true
+            layout.addOverAll(this, area)
+        }
+        // Transparent, not invisible: a surface in it (a video, a map) stays, and so does the focus.
+        topAlpha = top.alpha
+        top.alpha = 0f
+        drawGesture(GESTURE_CURVE.getInterpolation(progress))
+    }
+
+    // The values of the gesture at [q], its progress on the system's curve.
+    private fun drawGesture(q: Float) {
+        val card = card ?: return
+        val width = layout.width.toFloat()
+        val height = areaHeight.toFloat()
+        val margin = MARGIN_DP * density
+        val scale = scaleAt(q)
+        card.scaleX = scale
+        card.scaleY = scale
+        // From the left edge the screen's right side ends 8 dp from the window's right edge; from the right edge it stays
+        // centered.
+        card.translationX = if (fromLeft) (width - width * scale) / 2f - margin * q else 0f
+        // Up and down with the finger, never closer than 8 dp to the window's edges.
+        val moved = touchY - startY
+        val ratio = FOLLOW_CURVE.getInterpolation((kotlin.math.abs(moved) / (height / 2f)).coerceAtMost(1f))
+        card.translationY = ((height - height * scale) / 2f - margin).coerceAtLeast(0f) * ratio *
+            Math.signum(moved)
+        entering(scale, -SystemTransition.DISTANCE_DP * density * forward)
+    }
+
+    // The screen under the top and its bar at [scale] around the stack's center, [x] along the line.
+    private fun entering(scale: Float, x: Float) {
+        for (view in listOf(target, bar)) {
+            view.pivotX = layout.width / 2f - view.left
+            view.pivotY = areaHeight / 2f - view.top
+            view.scaleX = scale
+            view.scaleY = scale
+            view.translationX = x
+        }
+    }
+
+    // The stack above the tabs' room: what the card shows and what the screens shrink around.
+    private val areaHeight: Int
+        get() = (layout.height - bottomRoom).coerceAtLeast(0)
+
+    private fun scaleAt(q: Float): Float = 1f - (1f - minScale()) * q
+
+    private fun fill() = CoordinatorLayout.LayoutParams(
+        ViewGroup.LayoutParams.MATCH_PARENT,
+        ViewGroup.LayoutParams.MATCH_PARENT,
+    )
+
+    private fun lerp(from: Float, to: Float, fraction: Float): Float = from + (to - from) * fraction
+
+    private companion object {
+        /** The system's curve of the back gesture's progress (`BackGestureInterpolator`). */
+        val GESTURE_CURVE = PathInterpolator(0.1f, 0.1f, 0f, 1f)
+
+        /** How the screen follows the finger up and down. */
+        val FOLLOW_CURVE = DecelerateInterpolator()
+
+        /** The room the shrunk screen keeps from the window's edges. */
+        const val MARGIN_DP = 8f
+
+        /** The corners of the shrunk screen, as Android 17 draws them on a Pixel (6.5 dp at its smallest). */
+        const val CORNER_DP = 7.5f
+
+        const val SCRIM_LIGHT = 0.2f
+        const val SCRIM_DARK = 0.8f
+
+        /** The cancel springs back about as fast as the system's (`BackProgressAnimator`'s spring, no bounce). */
+        const val CANCEL_MILLIS = 350L
+
+        /**
+         * The smallest scale of the screens: 0.9 in WMShell of Android 15 and 16 (and here on Android 14); Android 17
+         * shrinks the window further (0.86, measured on a Pixel 6).
+         */
+        fun minScale(): Float = if (android.os.Build.VERSION.SDK_INT >= 37) 0.86f else 0.9f
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/StackCommands.kt

@@ -105,33 +105,42 @@ internal class StackCommands(
     }
 
     /**
-     * `showInColumn` (Android): [layout] in the secondary pane of the split view of the screen [componentId], or over
-     * that screen in its stack. Before any node: the screen is there, else `the screen '<id>' is not shown`; the push's
-     * checks of the layout (an id that shows already; a container, which the stack of the screen, else its split view,
-     * doesn't take); a screen prepared with the id goes. The screen is made at once, a native screen's view too. The
-     * split view takes it (the answer once its pane stopped, or the rejection of the pane); with the compact layout on
-     * screen, or without a split view, it is pushed over [componentId] in its stack, with the push's answer and errors;
-     * neither: `the screen '<id>' is neither in a split view nor in a stack`. Every rejection after the screen was made
-     * destroys it. Two calls in a row each make their screen the root of the pane in turn, and each answers its own id.
+     * `showInColumn` (Android): [layout] in [column] of the split view of the screen [componentId], or over that screen
+     * in its stack. Before any node: the screen is there, else `the screen '<id>' is not shown`; the layout has no id
+     * that shows already; out of a split view, the push's check of the layout (a container, which the stack doesn't
+     * take); a screen prepared with the id goes. The screen is made at once, a native screen's view too. The split view
+     * takes it — in place of a stack column's screens or of a column's content — with the answer once its pane
+     * stopped, or rejects (a column it doesn't have, a container for a stack column); with the compact layout on
+     * screen, or without a split view, it is pushed over [componentId] in its stack, with the push's checks, answer and
+     * errors; neither: `the screen '<id>' is neither in a split view nor in a stack`. Every rejection after the screen
+     * was made destroys it. Two calls in a row each make their screen the column's content in turn, and each answers
+     * its own id.
      */
-    fun showInColumn(componentId: String, layout: LayoutNode, answer: CommandAnswer, what: String) {
+    fun showInColumn(componentId: String, column: String, layout: LayoutNode, answer: CommandAnswer, what: String) {
         val source = find(componentId)?.takeIf { !prepared.isPrepared(it) }
             ?: return answer.reject(ErrorTexts.screenNotShown(componentId))
         val shown = LayoutChecks.firstShownId(listOf(layout), ::isShown) { false }
         if (shown != null) return answer.reject(ErrorTexts.alreadyShown(shown))
         val columns = nodeWith<ShowsColumns>(source)
         val stack = source as? StackController ?: source.findParentStack()
-        val placeId = stack?.id ?: (columns as? ViewController<*>)?.id
-        placeId?.let { id -> LayoutChecks.checkStackChild(layout, id)?.let { return answer.reject(it) } }
+        // Out of a split view it can only be a push: the stack's check comes before any node.
+        if (columns == null && stack != null) {
+            LayoutChecks.checkStackChild(layout, stack.id)?.let { return answer.reject(it) }
+        }
         if (!factory.canMake(layout)) return answer.reject(ErrorTexts.notDoneYet("showInColumn"))
         prepared.discard(layout.id)
         val node = make(layout)
         try {
-            if (columns?.showScreen(node, source, destroyingOnError(node, answer)) == true) return
+            val goesInStack = LayoutChecks.isStackChild(layout)
+            if (columns?.showScreen(node, column, goesInStack, source, destroyingOnError(node, answer)) == true) return
             if (stack == null) {
                 node.destroy()
                 return answer.reject(ErrorTexts.neitherSplitViewNorStack(componentId))
             }
+            LayoutChecks.checkStackChild(layout, stack.id)?.let {
+                node.destroy()
+                return answer.reject(it)
+            }
             pushMade(stack, source, node, layout, answer, what)
         } catch (e: Throwable) {
             node.destroy()
@@ -225,8 +234,9 @@ internal class StackCommands(
     fun setStackRoot(componentId: String, layouts: List<LayoutNode>, answer: CommandAnswer, what: String) {
         if (layouts.isEmpty()) return answer.reject(ErrorTexts.noScreensForStack(componentId))
         val stack = stackOf(componentId, answer) ?: return
-        // An id of this stack may come again: the new screen replaces it (`setStackRoot` step 3).
-        val shown = LayoutChecks.firstShownId(layouts, { isShown(it) && !isOf(stack, it) }) { false }
+        // An id of an entry of this stack may come again: the new screen replaces it (`setStackRoot` step 3). The
+        // stack's own id, and a screen an accepted cut or replace took away, show elsewhere or still go: as on iOS.
+        val shown = LayoutChecks.firstShownId(layouts, ::isShown) { isInEntryOf(stack, it.id) }
         if (shown != null) return answer.reject(ErrorTexts.alreadyShown(shown))
         for (layout in layouts) LayoutChecks.checkStackChild(layout, stack.id)?.let { return answer.reject(it) }
         if (!layouts.all(factory::canMake)) return answer.reject(ErrorTexts.notDoneYet("setStackRoot"))
@@ -357,10 +367,10 @@ internal class StackCommands(
     // A node of the registry has [id], and it isn't only prepared for a push (`push` step 1, `preparePush`).
     private fun isShown(id: String): Boolean = registry.find(id)?.let { !prepared.isPrepared(it) } == true
 
-    // The node with [id] is [stack] or in it.
-    private fun isOf(stack: StackController, id: String): Boolean {
-        val node = find(id) ?: return false
-        return node === stack || node.findParentStack() === stack
+    // The node with [id] is in an entry of [stack] as JavaScript sees it (`StackQueue.entries`), not the stack itself.
+    private fun isInEntryOf(stack: StackController, id: String): Boolean {
+        val node = find(id)?.takeIf { it !== stack } ?: return false
+        return stack.entryOf(node)?.let { it in stack.queue.entries } == true
     }
 
     // A node of [layout], with its view made now when it has a native screen: its creator's failure rejects the