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

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/StackController.kt

@@ -2,6 +2,7 @@ package dev.apexnative.navigation.viewcontrollers.stack
 
 import android.app.Activity
 import android.util.Log
+import android.view.View
 import dev.apexnative.navigation.NavigationActivity
 import dev.apexnative.navigation.options.AnimationsOptions
 import dev.apexnative.navigation.options.BottomTabsEnterExitAnimationOptions
@@ -35,6 +36,7 @@ import dev.apexnative.navigation.viewcontrollers.stack.topbar.TopBarPresenter
 import dev.apexnative.navigation.viewcontrollers.stack.topbar.TopBarRoom
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.component.ComponentLayout
 import dev.apexnative.navigation.views.stack.StackLayout
 import dev.apexnative.navigation.views.stack.topbar.LargeTitleView
@@ -257,6 +259,136 @@ class StackController(
      */
     override fun canHandleBack(): Boolean = topBar.isSearchOpen() || queue.entries.size >= 2
 
+    /**
+     * The default pop of the top is what back does now and it can be previewed: two entries or more, nothing running
+     * or waiting, no open search, the top doesn't hold back and pops with the default transition, the screen under it
+     * has its view, and the stack shows.
+     */
+    override fun stackPoppedByBack(): StackController? {
+        if (topBar.isSearchOpen() || !queue.isAtRest) return null
+        val entries = queue.entries
+        val top = queue.currentChild ?: return null
+        val target = entries.getOrNull(entries.size - 2) ?: return null
+        if (top !== entries.last() || target !in queue.shown || target.peekView() == null) return null
+        if (!queue.isRendered(target) || backGesture != null) return null
+        val options = resolvedOf(top)
+        val pop = options.animations.pop
+        if (options.hardwareBackButton.popStackOnPress.isFalse || pop.enabled.isFalse || AnimationRules.stackIsOwn(pop)) {
+            return null
+        }
+        val display = queue.display
+        return this.takeIf { display.isOnScreen && display.canAnimate }
+    }
+
+    /**
+     * Starts the preview of the pop a back gesture would make ([stackPoppedByBack] said yes): the top shrinks toward
+     * the gesture's side ([fromLeft]) and follows the finger from [touchY]; the screen under it shows with its bar.
+     * None when it can't be shown.
+     */
+    internal fun startBackGesture(fromLeft: Boolean, touchY: Float): BackGesture? {
+        val views = queue.display as? StackViews ?: return null
+        val top = queue.currentChild ?: return null
+        val target = queue.entries.getOrNull(queue.entries.size - 2) ?: return null
+        val gesture = BackGesture(views, top, target)
+        val preview = views.startBackPreview(top, target, fromLeft, touchY, gesture::reveal) ?: return null
+        gesture.preview = preview
+        backGesture = gesture
+        return gesture
+    }
+
+    // The back gesture over this stack whose preview hasn't ended yet; none.
+    private var backGesture: BackGesture? = null
+
+    /**
+     * A back gesture over the top of this stack ([startBackGesture]): its progress, its cancel, and its release, which
+     * pops the top through the queue with the preview's end. A command accepted meanwhile, or the stack's destroy,
+     * ends the preview at once ([abort]).
+     */
+    internal inner class BackGesture(
+        private val views: StackViews,
+        private val top: ViewController<*>,
+        private val target: ViewController<*>,
+    ) {
+        lateinit var preview: BackPreview
+        // How the screen under the top was before the preview showed it: in the container and seen, its alpha and
+        // accessibility.
+        private var targetWasPlaced = false
+        private var targetAlpha = 1f
+        private var targetAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_AUTO
+        private var revealed = false
+        private var aborted = false
+
+        /** The gesture moved: [progress] 0 … 1, the finger at [touchY]. */
+        fun progress(progress: Float, touchY: Float) {
+            if (!aborted) preview.progress(progress, touchY)
+        }
+
+        /** Cancelled: the preview springs back, then the screen under the top and the bar are as they were. */
+        fun cancel() {
+            if (!aborted) preview.cancel(::restore)
+        }
+
+        /**
+         * Released: the top pops, the preview playing its end; the default pop when its picture isn't there yet. False
+         * when the stack changed since the gesture started (a command ran, the stack went): back goes the usual way.
+         */
+        fun commit(): Boolean {
+            if (aborted || isDestroyed) return false
+            if (!preview.isReady) {
+                abort()
+                queue.cut(target, null, id, "go back in the stack '$id'", null)
+                return true
+            }
+            if (backGesture === this) backGesture = null
+            queue.cut(target, null, id, "go back in the stack '$id'", null, gesture = true)
+            return true
+        }
+
+        /** The stack changed or goes: the preview ends at once and the stack is as it was. */
+        fun abort() {
+            if (aborted) return
+            aborted = true
+            preview.endAtOnce()
+            restore()
+        }
+
+        // The preview's picture is there: the screen under the top shows under it, and the bar shows that screen.
+        internal fun reveal() {
+            val view = target.peekView() ?: return
+            targetWasPlaced = view.parent === peekView() && view.visibility == View.VISIBLE
+            targetAlpha = view.alpha
+            targetAccessibility = view.importantForAccessibility
+            revealed = true
+            views.reveal(target, top)
+            view.alpha = 1f
+            topBar.apply(target)
+        }
+
+        private fun restore() {
+            views.previewEnded(preview)
+            if (backGesture === this) backGesture = null
+            if (!revealed || isDestroyed) return
+            revealed = false
+            if (target in queue.shown && target !== queue.currentChild) {
+                val view = target.peekView()
+                if (targetWasPlaced && view != null) {
+                    view.alpha = targetAlpha
+                    view.importantForAccessibility = targetAccessibility
+                } else {
+                    views.detach(target)
+                }
+            }
+            // The bar shows the top again, its components appeared again.
+            val shown = queue.currentChild
+            topBar.apply(shown)
+            shown?.let {
+                topBar.screenWillAppear(optionsScreen(it))
+                topBar.screenDidAppear(optionsScreen(it))
+            }
+            BackCallbackState.update()
+        }
+    }
+
     /**
      * The back arrow of the bar was pressed: the screen the user sees holds it (`topBar.backButton.popStackOnPress:
      * false`: `ANN.NavigationButtonPressed` with `topBar.backButton.id` or `ApexNavigation.back`); on the first screen
@@ -460,8 +592,9 @@ class StackController(
 
     /**
      * The bar's bottom in the window while [child] is under it and it shows, from the stack's place in the window: for
-     * the screen on top where the bar is laid out (a move of the bar doesn't count); for another child (a prepared one)
-     * as its own options set the bar.
+     * the screen on top that the bar shows, where the bar is laid out (a move of the bar doesn't count); for another
+     * child (a prepared one) and for a top the bar hasn't shown yet (in a tab not selected yet, which measures though
+     * invisible) as its own options set the bar, so its content doesn't move as the bar takes them.
      */
     override fun headerBottomOf(child: ViewController<*>): Int? {
         if (!isUnderBar(child)) return super.headerBottomOf(child)
@@ -471,7 +604,7 @@ class StackController(
         val layout = peekView() ?: return null
         // The stack's place at rest, as the screen's own: a modal sliding in or a sheet dragged doesn't move it.
         val top = RestPlace.topInWindow(layout)
-        if (entry === queue.currentChild) return topBar.barBottomInStack()?.let { top + it }
+        if (entry === queue.currentChild && topBar.shows(entry)) return topBar.barBottomInStack()?.let { top + it }
         val bar = topBar.barOf(entry, options)
         val large = if (largeTitleShown(child)) UiUtils.dpToPx(activity, LargeTitleView.HEIGHT).toInt() else 0
         return top + bar.margin + bar.strip + bar.height + large
@@ -506,6 +639,7 @@ class StackController(
 
     override fun destroy() {
         if (isDestroyed) return
+        backGesture?.abort()
         queue.destroy()
         preparedPushes()?.discardFor(this)
         fab.destroy()
@@ -552,15 +686,23 @@ class StackController(
         (node as? OptionsScreen)?.optionsScreen ?: node
 
     private inner class QueueHost : StackQueue.Host {
+        override fun operationAccepted() {
+            backGesture?.abort()
+        }
+
         // The bar takes the options of the new top at once, also without appearance events.
         override fun currentChildChanged() {
             updateBar()
             navigator?.shownScreensChanged(this@StackController)
         }
 
-        // Before the bar takes the new top's options: the row's picture, and how it shows or hides.
-        override fun barTransition(motion: StackDisplay.BarMotion?, visibility: StackDisplay.BarVisibility) {
-            if (peekView() != null) topBar.beginRowTransition(motion, queue.currentChild, visibility)
+        // Before the bar takes the new top's options: the row's picture or the bar's travel, and how it shows or hides.
+        override fun barTransition(
+            motion: StackDisplay.BarMotion?,
+            visibility: StackDisplay.BarVisibility,
+            travel: StackDisplay.BarTravel?,
+        ) {
+            if (peekView() != null) topBar.beginRowTransition(motion, queue.currentChild, visibility, travel)
         }
 
         // The tab bar of the tabs around goes with the transition; a takeover doesn't bring it to rest.

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

@@ -38,6 +38,12 @@ internal interface StackDisplay {
      */
     enum class BarMotion { Push, Pop, FadeThrough }
 
+    /**
+     * How the bar goes with a transition of the stack's own (`content`): with its screens. [Forward]: the screen that
+     * comes lies over the one that goes (a push, `setStackRoot`); [Back]: the one that goes lies over it (a pop).
+     */
+    enum class BarTravel { Forward, Back }
+
     /**
      * How the bar shows or hides when the new top's `topBar.visible` differs: at once (no animation, or a transition
      * with elements), or [animated] by the transition's [side] (`animations.push.topBar`, the leaving screen's
@@ -156,6 +162,24 @@ internal interface StackDisplay {
         done: () -> Unit,
     ): () -> Unit
 
+    /** The preview of a back gesture over [top], [target] under it, shows ([finishBackGesture] can end it). */
+    fun hasBackPreview(top: ViewController<*>, target: ViewController<*>): Boolean = false
+
+    /**
+     * The pop of a back gesture whose preview shows ([hasBackPreview]), released: the preview plays the end of [top]
+     * going and [target] coming. [topDone] and [targetDone] once each, as [animate]'s; [stop] of one screen ends the
+     * preview where it is and its other screen's part.
+     */
+    fun finishBackGesture(
+        top: ViewController<*>,
+        target: ViewController<*>,
+        topDone: () -> Unit,
+        targetDone: () -> Unit,
+    ) {
+        topDone()
+        targetDone()
+    }
+
     /** Stops the animator of [screen] where it is, without its end: a later transition takes the screen over. */
     fun stop(screen: ViewController<*>)