@apexnative/navigation 1.0.0-alpha.5 → 1.0.0-alpha.6

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

@@ -158,6 +158,9 @@ internal class ModalCoordinator(
 
         /** 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
     }
 
     /**
@@ -397,11 +400,26 @@ internal class ModalCoordinator(
     }
 
     /**
-     * The root of the modal that back goes to first; none without one. A back gesture previews only a pop in it: its
-     * dismissal has a preview of its own nowhere yet.
+     * 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

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

@@ -15,6 +15,7 @@ import android.view.ViewOutlineProvider
 import android.view.ViewTreeObserver
 import android.widget.FrameLayout
 import android.widget.ScrollView
+import androidx.activity.BackEventCompat
 import androidx.coordinatorlayout.widget.CoordinatorLayout
 import androidx.core.graphics.Insets
 import androidx.core.view.ViewCompat
@@ -34,13 +35,14 @@ import kotlin.math.roundToInt
  * 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. In a window wider than [MAX_WIDTH_DP] it stands in the
  * middle at that width. 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.
+ * stays, and the try is told. The screen under it stays in place. On Android 14+ the back gesture previews its hide
+ * ([SheetBack]): the Material behavior shrinks it with the progress and slides it down at the release.
  */
 internal class ModalSheet(
     private val layout: CoordinatorLayout,
     private val content: View,
     private val events: Events,
-) {
+) : SheetBack {
     interface Events {
         /** The user dragged the sheet to another detent. */
         fun onDetentChanged(detent: SheetDetent)
@@ -66,6 +68,28 @@ internal class ModalSheet(
     private var dragged = false
     private var shown: (() -> Unit)? = null
     private var closing: (() -> Unit)? = null
+    // The back gesture whose preview runs now; none.
+    private var backPreview: BackPreview? = null
+    // Released: the behavior slides the sheet down from where the preview left it, and hides it at the end.
+    private var backFinishing = false
+    // The window's observer the scrim follows the preview's frames through, from its start until the sheet is back
+    // in place or gone; none otherwise.
+    private var backFramesObserver: ViewTreeObserver? = null
+
+    // The behavior tells no slide while back's preview scales the sheet and its release slides it down (they move it by
+    // its transform, not its offset): the scrim follows what is drawn, frame by frame, until the sheet stands again.
+    private val backFrames = ViewTreeObserver.OnPreDrawListener {
+        updateScrim()
+        if (backPreview == null && !backFinishing && container.scaleY == 1f && container.translationY == 0f) {
+            stopBackFrames()
+        }
+        true
+    }
+
+    private val sheetCallback = object : BottomSheetBehavior.BottomSheetCallback() {
+        override fun onStateChanged(sheet: View, newState: Int) = onState(newState)
+        override fun onSlide(sheet: View, slideOffset: Float) = updateScrim()
+    }
 
     // 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.
@@ -89,6 +113,13 @@ internal class ModalSheet(
             }
         })
         scrim.setOnTouchListener { _, event -> taps.onTouchEvent(event) }
+        // The sheet keeps a touch that lands on it and no view in it takes (its bar, an empty part), as Material's
+        // BottomSheetDialog does: else the touch falls to the scrim under it, and a tap there closes a dimmed sheet;
+        // past an undimmed scrim it reaches the behavior, which takes the sheet into its drag state at the touch's
+        // down, before any move. The back gesture starts with such a touch, and a sheet in the drag state has no
+        // preview. A drag that starts there still moves the sheet: the behavior takes it past the touch slop, as from
+        // the views in it.
+        container.setOnTouchListener { _, _ -> true }
         container.clipToOutline = true
         container.outlineProvider = object : ViewOutlineProvider() {
             // The bottom corners are under the screen's bottom: only the top ones round.
@@ -116,10 +147,7 @@ internal class ModalSheet(
         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()
-        })
+        behavior.addBottomSheetCallback(sheetCallback)
         container.viewTreeObserver.addOnGlobalLayoutListener(scrollViews)
     }
 
@@ -154,10 +182,12 @@ internal class ModalSheet(
         behavior.dragAnywhere = sheetOptions.expandsOnScroll.get(true)
         container.invalidateOutline()
         configure()
-        if (merge == null || closing != null) return
+        if (merge == null || closing != null || backFinishing) return
         val settled = detentOf(behavior.state)
         if (settled != null) behavior.isHideable = swipeToDismiss && settled == detents.first()
         val target = SheetStops.target(settled, detents, merge.selectedDetent, sheetOptions.selectedDetent)
+        // A merge that moves the sheet or keeps it from going down ends a preview of back on it.
+        if (target != null || !behavior.isHideable) stopBackPreview()
         if (target != null) {
             selected = target
             behavior.state = stateOf(target)
@@ -172,12 +202,19 @@ internal class ModalSheet(
             finishClosing()
             return
         }
+        // Released by back, it goes down already: it is closed at the end of that slide.
+        if (backFinishing) return
+        stopBackPreview()
         behavior.isHideable = true
         behavior.state = BottomSheetBehavior.STATE_HIDDEN
     }
 
     /** Takes the sheet's views away; the modal's view is the caller's. */
     fun remove() {
+        // A slide down of back's release that ends after this tells nothing: the modal went already.
+        behavior.removeBottomSheetCallback(sheetCallback)
+        stopBackPreview()
+        stopBackFrames()
         container.viewTreeObserver.removeOnGlobalLayoutListener(scrollViews)
         container.removeView(content)
         layout.removeView(container)
@@ -191,6 +228,69 @@ internal class ModalSheet(
         TestIds.apply(scrim, testId?.let { "$it.scrim" })
     }
 
+    override val hidesOnBack: Boolean
+        get() = closing == null && !backFinishing && behavior.isHideable && container.isLaidOut &&
+            detentOf(behavior.state) != null
+
+    override fun startBackPreview(event: BackEventCompat): SheetBack.Gesture? {
+        if (!hidesOnBack || backPreview != null) return null
+        val preview = BackPreview()
+        backPreview = preview
+        startBackFrames()
+        behavior.startBackProgress(event)
+        return preview
+    }
+
+    // A command closed or moved the sheet, or it goes, while back's preview runs: the sheet grows back where it stands
+    // (the behavior's cancel), and the gesture's release does the usual back.
+    private fun stopBackPreview() {
+        if (backPreview == null) return
+        backPreview = null
+        behavior.cancelBackProgress()
+    }
+
+    private fun startBackFrames() {
+        if (backFramesObserver != null) return
+        backFramesObserver = container.viewTreeObserver.also { it.addOnPreDrawListener(backFrames) }
+    }
+
+    // The listener leaves the observer it joined: a container out of the window has another one.
+    private fun stopBackFrames() {
+        val observer = backFramesObserver ?: return
+        backFramesObserver = null
+        if (observer.isAlive) observer.removeOnPreDrawListener(backFrames)
+    }
+
+    /** The back gesture over this sheet: the Material behavior previews its hide (`MaterialBackHandler`). */
+    private inner class BackPreview : SheetBack.Gesture {
+        override val sheet: SheetBack
+            get() = this@ModalSheet
+
+        override fun progress(event: BackEventCompat) {
+            if (backPreview !== this) return
+            behavior.updateBackProgress(event)
+            updateScrim()
+        }
+
+        override fun cancel() {
+            if (backPreview === this) stopBackPreview()
+        }
+
+        // The behavior slides the sheet down from the preview and sets its hidden state at the end: `onState` closes
+        // it there as a drag down does (`onClosedByUser`), so the modal goes through the user's path once.
+        override fun commit(): Boolean {
+            if (backPreview !== this) return false
+            backPreview = null
+            if (!hidesOnBack) {
+                behavior.cancelBackProgress()
+                return false
+            }
+            backFinishing = true
+            behavior.handleBackInvoked()
+            return true
+        }
+    }
+
     private fun closeByUser() {
         if (!swipeToDismiss) {
             events.onCloseAttempted()
@@ -243,6 +343,7 @@ internal class ModalSheet(
         when (state) {
             BottomSheetBehavior.STATE_DRAGGING -> dragged = true
             BottomSheetBehavior.STATE_HIDDEN -> {
+                backFinishing = false
                 when {
                     closing != null -> finishClosing()
                     else -> {
@@ -280,13 +381,23 @@ internal class ModalSheet(
     // 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
+        // Hidden at the end of back's slide, it still stands at its detent until the next layout.
+        if (behavior.state == BottomSheetBehavior.STATE_HIDDEN) return setDim(0f)
+        val height = layout.height - sheetTop()
         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))
     }
 
+    // The top of the sheet as drawn: its offset, and while back's preview moves it, its slide and its scale toward
+    // the bottom (the behavior's pivot).
+    private fun sheetTop(): Int {
+        if (backFramesObserver == null) return container.top
+        val scaled = container.pivotY * (1f - container.scaleY)
+        return (container.top + container.translationY + scaled).roundToInt()
+    }
+
     private fun setDim(fraction: Float) {
         scrim.alpha = fraction * SCRIM_ALPHA
     }

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

@@ -19,6 +19,7 @@ import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.utils.TestIds
 import dev.apexnative.navigation.utils.dp
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import dev.apexnative.navigation.views.animations.AnimationLayer
 import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
 import dev.apexnative.navigation.views.element.ElementTransition
@@ -263,6 +264,8 @@ internal class ModalViews(
         parts[record]?.container?.requestLayout()
     }
 
+    override fun sheetBack(record: ModalRecord): SheetBack? = parts[record]?.sheet
+
     // `modal.testID` on the modal's view; a sheet's on the sheet's container, `modal.sheet.testID` first, and its
     // grabber and scrim after it.
     private fun applyTestIds(record: ModalRecord, parts: Parts, options: Options) {
@@ -293,7 +296,11 @@ internal class ModalViews(
         val under = motion.underSide?.let { side -> underView?.let { SideAnimator.build(it, side, underBase) } }
         if (under != null && underView != null) {
             if (showing) moved[underView] = record else moved.remove(underView)
+            AnimationLayer.during(underView, under)
         }
+        // A fade of the modal or of the layer under it draws it through a hardware layer, given back at its end and at
+        // any stop (the set's cancel cancels it).
+        for (animator in listOfNotNull(side, fade)) AnimationLayer.during(container, animator)
         val fadeLength = motion.side?.takeIf(AnimationRules::isSingleAlpha)?.let(AnimationRules::lengthOf)
         val elements = motion.elements?.let { animation ->
             val content = modalsLayer.parent as? ViewGroup ?: return@let null

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

@@ -0,0 +1,42 @@
+package dev.apexnative.navigation.viewcontrollers.modal
+
+import androidx.activity.BackEventCompat
+
+/**
+ * A modal's sheet as back sees it ([ModalSheet]): whether a release of back would hide it, and the preview of that
+ * hide during the back gesture (Android 14+). [ModalCoordinator.backTargetSheet] gives the one back would dismiss now.
+ * Main thread only.
+ */
+internal interface SheetBack {
+    /**
+     * Back's release would hide the sheet, as a drag down does: it stands at a detent from which it goes down (its
+     * smallest, while it lets the user close it), laid out, and it isn't closing already. False at a larger detent:
+     * the Material behavior would only collapse it there.
+     */
+    val hidesOnBack: Boolean
+
+    /**
+     * Starts the preview of back on the sheet with the gesture's first [event]: the sheet shrinks a little toward the
+     * bottom with the progress, the scrim following it. None when [hidesOnBack] doesn't hold or a preview runs.
+     */
+    fun startBackPreview(event: BackEventCompat): Gesture?
+
+    /** A back gesture over the sheet ([startBackPreview]). */
+    interface Gesture {
+        /** The sheet the gesture previews. */
+        val sheet: SheetBack
+
+        /** The gesture moved. */
+        fun progress(event: BackEventCompat)
+
+        /** Cancelled, or back went elsewhere: the sheet grows back to where it stood, the scrim with it. */
+        fun cancel()
+
+        /**
+         * Released: the sheet slides down from where the preview left it and goes as one the user dragged down (its
+         * events, its dismissal). False when the preview stopped since it started (a command closed or moved the
+         * sheet): back goes the usual way.
+         */
+        fun commit(): Boolean
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/navigator/Navigator.kt

@@ -33,6 +33,7 @@ import dev.apexnative.navigation.viewcontrollers.externalcomponent.ExternalCompo
 import dev.apexnative.navigation.viewcontrollers.modal.ModalCoordinator
 import dev.apexnative.navigation.viewcontrollers.modal.ModalRecord
 import dev.apexnative.navigation.viewcontrollers.modal.ModalViews
+import dev.apexnative.navigation.viewcontrollers.modal.SheetBack
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayCoordinator
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayRecord
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayViews
@@ -177,6 +178,9 @@ class Navigator(
         return if (modalRoot != null) modalRoot.stackPoppedByBack() else root?.stackPoppedByBack()
     }
 
+    /** The sheet [handleBack] would dismiss, as a drag down of the user would; none when back would do anything else. */
+    internal fun sheetDismissedByBack(): SheetBack? = modals.backTargetSheet()
+
     /**
      * [layer] may wait to show from now on ([WaitingLayer]): the nodes in it ask it through [isInWaitingLayer] and
      * [shownScreensChanged]. The root's layer is there from the start.

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/parent/ParentController.kt

@@ -129,12 +129,9 @@ abstract class ParentController<V : ViewGroup>(
     open fun leavesTopEdgeFree(child: ViewController<*>): Boolean =
         parentController?.leavesTopEdgeFree(this) ?: false
 
-    /**
-     * Whether the safe area of [child] leaves its bottom edge free by default: the tabs show with
-     * `bottomTabs.hideOnScroll` of [screen], the screen that asks.
-     */
-    open fun leavesBottomEdgeFree(child: ViewController<*>, screen: ViewController<*> = child): Boolean =
-        parentController?.leavesBottomEdgeFree(this, screen) ?: false
+    /** Whether a large title shows over [child]: its stack shows the bar with one. No by default. */
+    open fun showsLargeTitleOver(child: ViewController<*>): Boolean =
+        parentController?.showsLargeTitleOver(this) ?: false
 
     /**
      * The tab bar at rest under [child]: where a stack's FAB keeps clear of it, by the options of [screen], the stack's

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

@@ -2,18 +2,18 @@ package dev.apexnative.navigation.viewcontrollers.stack
 
 import android.view.View
 import com.facebook.react.uimanager.PixelUtil.pxToDp
-import dev.apexnative.navigation.react.ScreenInsets
+import dev.apexnative.navigation.react.ScreenEnvironment
 
 /**
  * Where a screen prepared for a push (`preparePush`) shows, in dp: the size of the container its slot fills and the
  * padding of its safe area view, as the push lays it out. JavaScript renders the screen with them before the push, and
  * the slot and the safe area view start their states with them.
  */
-internal data class PreparedFrame(val width: Float, val height: Float, val padding: ScreenInsets.Insets) {
+internal data class PreparedFrame(val width: Float, val height: Float, val padding: ScreenEnvironment.Insets) {
     companion object {
         /** The size of [container] as its slot measures it (`SlotView`), so the slot finds it equal. */
         @JvmStatic
-        fun of(container: View, padding: ScreenInsets.Insets) =
+        fun of(container: View, padding: ScreenEnvironment.Insets) =
             PreparedFrame(container.width.toFloat().pxToDp(), container.height.toFloat().pxToDp(), padding)
     }
 }

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

@@ -11,7 +11,7 @@ import dev.apexnative.navigation.options.DefaultOptions
 import dev.apexnative.navigation.react.CommandAnswer
 import dev.apexnative.navigation.react.CommandListener
 import dev.apexnative.navigation.react.ErrorTexts
-import dev.apexnative.navigation.react.ScreenInsets
+import dev.apexnative.navigation.react.ScreenEnvironment
 import dev.apexnative.navigation.slots.SlotScreenView
 import dev.apexnative.navigation.utils.NavigationLog
 import dev.apexnative.navigation.viewcontrollers.child.ChildControllersRegistry
@@ -318,7 +318,7 @@ internal class StackCommands(
         layoutNow(stackView, screenView)
         node.updateSafeArea()
         val content = node.content?.asView()
-        val padding = ScreenInsets.padding(node.id)
+        val padding = ScreenEnvironment.padding(node.id)
         val noInsets = content == null || ViewCompat.getRootWindowInsets(content) == null
         if (noInsets || padding == null || content.width <= 0 || content.height <= 0) {
             prepared.discard(node.id)

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

@@ -594,6 +594,10 @@ class StackController(
     override fun leavesTopEdgeFree(child: ViewController<*>): Boolean =
         TopBarRoom.leavesTopEdgeFree(resolvedOf(child), largeTitleShown(child)) || super.leavesTopEdgeFree(child)
 
+    /** A large title shows over [child] in this stack's bar. */
+    override fun showsLargeTitleOver(child: ViewController<*>): Boolean =
+        largeTitleShown(child) || super.showsLargeTitleOver(child)
+
     /** A screen under another doesn't compute its safe area again; the prepared and waiting do. */
     override fun isTopOfStack(child: ViewController<*>): Boolean =
         child === queue.currentChild || child === queue.waitingScreen || isPrepared(child)

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

@@ -15,6 +15,7 @@ import dev.apexnative.navigation.viewcontrollers.component.ComponentViewControll
 import dev.apexnative.navigation.viewcontrollers.externalcomponent.ExternalComponentViewController
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.Motion
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import dev.apexnative.navigation.views.animations.AnimationLayer
 import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
 import dev.apexnative.navigation.views.animations.SystemTransition
@@ -157,6 +158,8 @@ internal class StackViews(private val stack: StackController) : StackDisplay {
         custom.alpha?.let { view.alpha = it }
         val own = custom.side?.let { SideAnimator.build(view, it, SideAnimator.Base(alpha = custom.alpha)) }
         val fade = if (own == null) StackTransitions.fade(view, custom.fade) else null
+        // A fade of the whole screen draws it through a hardware layer, as the default transition does ([dress]).
+        for (animator in listOfNotNull(own, fade)) AnimationLayer.during(view, animator)
         val elements = custom.elements?.let { elements ->
             val layout = layout ?: return@let null
             val fadeLength = custom.side?.takeIf(AnimationRules::isSingleAlpha)?.let(AnimationRules::lengthOf)

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/viewcontroller/ScrollEventListener.kt

@@ -13,8 +13,8 @@ import java.lang.ref.WeakReference
  * tag) is in the screen, found once per tag —, not the horizontal ones, nor those of a modal, an overlay or another
  * screen; a slot screen's lists are in its container too. While a list is dragged, each follower gets the drag as a
  * translation to follow; when the drag ends, the way to settle; at every scroll event, the drags' and the inertia's,
- * the offset. It listens to React Native's events only while it has followers; without React Native's event dispatcher
- * (around a reload) it waits and listens once there is one. Released with the screen. Main thread only.
+ * the offset. It listens to React Native's scroll views ([ScrollEvents]) only while it has followers and its screen's
+ * view. Released with the screen. Main thread only.
  */
 class ScrollEventListener() {
     /** Follows the content while it is dragged. */
@@ -105,15 +105,12 @@ class ScrollEventListener() {
     }
 
     /**
-     * Listens to React Native's scroll events when followers wait for them and it doesn't yet: after a reload there may
-     * be no event dispatcher at first: then it is asked again once React Native has one, and as the screen joins a
-     * window.
+     * Listens to React Native's scroll views when followers wait for them and it doesn't yet, once it has the screen's
+     * view to tell its own lists by; asked again as the screen joins a window.
      */
     internal fun attachIfNeeded() {
-        if (released || stopListening != null || registrations.isEmpty()) return
-        val context = scope?.get()?.context ?: return
-        stopListening = ScrollEvents.listen(context, ::onScrollEvent)
-        if (stopListening == null) ScrollEvents.waitForDispatcher(this)
+        if (released || stopListening != null || registrations.isEmpty() || scope?.get() == null) return
+        stopListening = ScrollEvents.listen(::onScrollEvent)
     }
 
     /** The screen is destroyed: no follower hears it any more. */

package/android/src/main/java/dev/apexnative/navigation/views/animations/AnimationLayer.kt

@@ -0,0 +1,73 @@
+package dev.apexnative.navigation.views.animations
+
+import android.animation.Animator
+import android.animation.AnimatorListenerAdapter
+import android.animation.AnimatorSet
+import android.animation.ObjectAnimator
+import android.view.View
+
+/**
+ * A hardware layer on a view for the time of an animator that fades it. A view whose `alpha` is below 1 and whose
+ * rendering overlaps (any `ViewGroup` by default) is drawn into an offscreen buffer at every frame; through a layer it
+ * is drawn once and the GPU only composites it. The layer is taken as the animator starts and only from
+ * `LAYER_TYPE_NONE` (a layer someone else set stays theirs), and given back as it ends or is cancelled. A pure
+ * translation or scale needs none: RenderThread draws it. The stack's default transition has its own
+ * (`StackViews.dress`). Main thread only.
+ */
+internal object AnimationLayer {
+    private const val ALPHA = "alpha"
+
+    /**
+     * [view] draws through a hardware layer while [animator] plays, when [animator] changes the `alpha` of [view] and
+     * the view's rendering overlaps; [animator] itself, for chaining.
+     */
+    fun during(view: View, animator: Animator): Animator {
+        if (!changesAlpha(animator, view)) return animator
+        val hold = Hold({ view.layerType }, { view.setLayerType(it, null) })
+        animator.addListener(object : AnimatorListenerAdapter() {
+            override fun onAnimationStart(animation: Animator) {
+                hold.take(changesAlpha = true, overlapping = view.hasOverlappingRendering())
+            }
+
+            override fun onAnimationCancel(animation: Animator) = hold.release()
+
+            override fun onAnimationEnd(animation: Animator) = hold.release()
+        })
+        return animator
+    }
+
+    /** Whether an animation takes a layer: it fades, its view's rendering overlaps, and the view has no layer. */
+    fun takes(changesAlpha: Boolean, overlapping: Boolean, layerType: Int): Boolean =
+        changesAlpha && overlapping && layerType == View.LAYER_TYPE_NONE
+
+    /**
+     * The layer one animation took on one view, through [layerType] and [setLayerType]: taken at most once at a time,
+     * given back once, and only while it is still the hardware layer it set.
+     */
+    class Hold(private val layerType: () -> Int, private val setLayerType: (Int) -> Unit) {
+        /** Whether the animation holds the view's layer now. */
+        var isTaken = false
+            private set
+
+        /** The animation starts: the layer, when [takes] says so. */
+        fun take(changesAlpha: Boolean, overlapping: Boolean) {
+            if (isTaken || !takes(changesAlpha, overlapping, layerType())) return
+            setLayerType(View.LAYER_TYPE_HARDWARE)
+            isTaken = true
+        }
+
+        /** The animation ended or stopped: the layer goes, unless someone changed it meanwhile. */
+        fun release() {
+            if (!isTaken) return
+            isTaken = false
+            if (layerType() == View.LAYER_TYPE_HARDWARE) setLayerType(View.LAYER_TYPE_NONE)
+        }
+    }
+
+    // Whether [animator], or an animator in it, writes the alpha of [view].
+    private fun changesAlpha(animator: Animator, view: View): Boolean = when (animator) {
+        is AnimatorSet -> animator.childAnimations.any { changesAlpha(it, view) }
+        is ObjectAnimator -> animator.target === view && animator.values.orEmpty().any { it.propertyName == ALPHA }
+        else -> false
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/views/animations/ValueInterpolation.kt

@@ -18,6 +18,18 @@ internal object ValueInterpolation {
         else -> from + fraction * (to - from)
     }
 
+    /**
+     * An angle in degrees at [fraction] of the way along the shorter arc, as iOS turns a shared element: 0 → 270 turns
+     * back by 90, 170 → −170 turns on by 20; half a turn goes on. At the end of the time exactly [to].
+     */
+    fun angle(from: Float, to: Float, fraction: Float, time: Float = fraction): Float {
+        if (time <= 0f) return from
+        if (time >= 1f) return to
+        val forward = ((to - from) % FULL_TURN + FULL_TURN) % FULL_TURN
+        val turn = if (forward > HALF_TURN) forward - FULL_TURN else forward
+        return from + fraction * turn
+    }
+
     /**
      * A color (an sRGB color int, as React Native keeps a background; none is transparent) at [fraction] of the way
      * from [from] to [to]: L, a and b in Lab (D65), the alpha linear, the result rounded; at the end of the time
@@ -90,4 +102,6 @@ internal object ValueInterpolation {
     private const val WHITE_Z = 108.883
     private const val EPSILON = 0.008856
     private const val KAPPA = 903.3
+    private const val FULL_TURN = 360f
+    private const val HALF_TURN = 180f
 }