Shared transitions

circuit-foundation/build.gradle.kts

@@ -59,6 +59,7 @@ kotlin {
         api(projects.circuitRuntimePresenter)
         api(projects.circuitRuntimeUi)
         api(projects.circuitRetained)
+        api(projects.circuitSharedElements)
         api(libs.compose.ui)
       }
     }

circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/ModifierExt.kt

@@ -0,0 +1,38 @@
+// Copyright (C) 2024 Slack Technologies, LLC
+// SPDX-License-Identifier: Apache-2.0
+package com.slack.circuit.foundation
+
+import androidx.compose.ui.Modifier
+
+/**
+ * Conditionally applies the [transform] modifier based on the [predicate].
+ *
+ * Note: This is useful in cases where you want to apply a modifier like clickable in certain
+ * situations but in others you don't want the View to react (ripple) to tap events.
+ */
+public inline fun Modifier.thenIf(
+  predicate: Boolean,
+  transform: Modifier.() -> Modifier,
+): Modifier =
+  if (predicate) {
+    then(transform(Modifier))
+  } else {
+    this
+  }
+
+/**
+ * Conditionally applies the [transform] modifier if the [value] is not null.
+ *
+ * Note: This is useful in cases where you want to apply a modifier like clickable in certain
+ * situations but in others you don't want the View to react (ripple) to tap events.
+ */
+public inline fun <T> Modifier.thenIfNotNull(
+  value: T?,
+  transform: Modifier.(T) -> Modifier,
+): Modifier {
+  return if (value != null) {
+    then(transform(Modifier, value))
+  } else {
+    this
+  }
+}

circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/NavigableCircuitContent.kt

@@ -2,14 +2,17 @@
 // SPDX-License-Identifier: Apache-2.0
 package com.slack.circuit.foundation
 
-import androidx.compose.animation.AnimatedContent
+import androidx.compose.animation.AnimatedContentScope
+import androidx.compose.animation.AnimatedContentTransitionScope
 import androidx.compose.animation.ContentTransform
 import androidx.compose.animation.EnterTransition
 import androidx.compose.animation.ExitTransition
 import androidx.compose.animation.SizeTransform
 import androidx.compose.animation.core.CubicBezierEasing
 import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.Transition
 import androidx.compose.animation.core.tween
+import androidx.compose.animation.core.updateTransition
 import androidx.compose.animation.expandHorizontally
 import androidx.compose.animation.fadeIn
 import androidx.compose.animation.fadeOut
@@ -36,6 +39,8 @@ import com.slack.circuit.backstack.NavDecoration
 import com.slack.circuit.backstack.ProvidedValues
 import com.slack.circuit.backstack.isEmpty
 import com.slack.circuit.backstack.providedValuesForBackStack
+import com.slack.circuit.foundation.NavigatorDefaults.DefaultDecoration.backward
+import com.slack.circuit.foundation.NavigatorDefaults.DefaultDecoration.forward
 import com.slack.circuit.retained.CanRetainChecker
 import com.slack.circuit.retained.LocalCanRetainChecker
 import com.slack.circuit.retained.LocalRetainedStateRegistry
@@ -233,10 +238,13 @@ public object NavigatorDefaults {
   private const val SHORT_DURATION = 83 * DEBUG_MULTIPLIER
   private const val NORMAL_DURATION = 450 * DEBUG_MULTIPLIER
 
-  /** The default [NavDecoration] used in navigation. */
-  // Mirrors the forward and backward transitions of activities in Android 34
-  public object DefaultDecoration : NavDecoration {
-
+  public object DefaultDecoration :
+    AnimatedNavDecoration(
+      decoratorFactory =
+        object : AnimatedNavDecorator.Factory {
+          override fun <T> create(): AnimatedNavDecorator<T, *> = DefaultDecorator()
+        }
+    ) {
     /**
      * The [ContentTransform] used for 'forward' navigation changes (i.e. items added to stack).
      * This isn't meant for public consumption, so be aware that this may be removed/changed at any
@@ -304,39 +312,48 @@ public object NavigatorDefaults {
 
       return enterTransition togetherWith exitTransition
     }
+  }
+
+  public class DefaultDecorator<T> : AnimatedNavDecorator<T, ImmutableList<T>> {
 
     @Composable
-    override fun <T> DecoratedContent(
+    public override fun Content(
       args: ImmutableList<T>,
       backStackDepth: Int,
       modifier: Modifier,
+      content: @Composable Transition<ImmutableList<T>>.(Modifier) -> Unit,
+    ) {
+      updateTransition(args).content(modifier)
+    }
+
+    @OptIn(InternalCircuitApi::class)
+    @Composable
+    override fun Transition<ImmutableList<T>>.transitionSpec():
+      AnimatedContentTransitionScope<ImmutableList<T>>.() -> ContentTransform = {
+      // A transitionSpec should only use values passed into the `AnimatedContent`, to
+      // minimize
+      // the transitionSpec recomposing. The states are available as `targetState` and
+      // `initialState`
+      val diff = targetState.size - initialState.size
+      val sameRoot = targetState.lastOrNull() == initialState.lastOrNull()
+
+      when {
+        sameRoot && diff > 0 -> forward
+        sameRoot && diff < 0 -> backward
+        else -> fadeIn() togetherWith fadeOut()
+      }.using(
+        // Disable clipping since the faded slide-in/out should
+        // be displayed out of bounds.
+        SizeTransform(clip = false)
+      )
+    }
+
+    @Composable
+    public override fun AnimatedContentScope.AnimatedNavContent(
+      targetState: ImmutableList<T>,
       content: @Composable (T) -> Unit,
     ) {
-      @OptIn(InternalCircuitApi::class)
-      AnimatedContent(
-        targetState = args,
-        modifier = modifier,
-        transitionSpec = {
-          // A transitionSpec should only use values passed into the `AnimatedContent`, to
-          // minimize
-          // the transitionSpec recomposing. The states are available as `targetState` and
-          // `initialState`
-          val diff = targetState.size - initialState.size
-          val sameRoot = targetState.lastOrNull() == initialState.lastOrNull()
-
-          when {
-            sameRoot && diff > 0 -> forward
-            sameRoot && diff < 0 -> backward
-            else -> fadeIn() togetherWith fadeOut()
-          }.using(
-            // Disable clipping since the faded slide-in/out should
-            // be displayed out of bounds.
-            SizeTransform(clip = false)
-          )
-        },
-      ) {
-        content(it.first())
-      }
+      content(targetState.first())
     }
   }
 

circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/NavigationDecoration.kt

@@ -0,0 +1,78 @@
+// Copyright (C) 2022 Slack Technologies, LLC
+// SPDX-License-Identifier: Apache-2.0
+package com.slack.circuit.foundation
+
+import androidx.compose.animation.AnimatedContent
+import androidx.compose.animation.AnimatedContentScope
+import androidx.compose.animation.AnimatedContentTransitionScope
+import androidx.compose.animation.ContentTransform
+import androidx.compose.animation.ExperimentalSharedTransitionApi
+import androidx.compose.animation.core.Transition
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.Stable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import com.slack.circuit.backstack.NavDecoration
+import com.slack.circuit.sharedelements.ProvideAnimatedTransitionScope
+import com.slack.circuit.sharedelements.SharedElementTransitionScope.AnimatedScope.Navigation
+import kotlinx.collections.immutable.ImmutableList
+
+@OptIn(ExperimentalSharedTransitionApi::class)
+public abstract class AnimatedNavDecoration(
+  private val decoratorFactory: AnimatedNavDecorator.Factory
+) : NavDecoration {
+
+  @Composable
+  public override fun <T> DecoratedContent(
+    args: ImmutableList<T>,
+    backStackDepth: Int,
+    modifier: Modifier,
+    content: @Composable (T) -> Unit,
+  ) {
+
+    val decorator = remember {
+      @Suppress("UNCHECKED_CAST")
+      decoratorFactory.create<T>() as AnimatedNavDecorator<T, Any>
+    }
+    with(decorator) {
+      Content(args, backStackDepth, modifier) { modifier ->
+        AnimatedContent(modifier = modifier, transitionSpec = transitionSpec()) { targetState ->
+          ProvideAnimatedTransitionScope(Navigation, this) {
+            AnimatedNavContent(targetState) { content(it) }
+          }
+        }
+      }
+    }
+  }
+}
+
+public class DefaultAnimatedNavDecoration(decoratorFactory: AnimatedNavDecorator.Factory) :
+  AnimatedNavDecoration(decoratorFactory)
+
+@Stable
+public interface AnimatedNavDecorator<T, S> {
+
+  @Composable
+  public fun Content(
+    args: ImmutableList<T>,
+    backStackDepth: Int,
+    modifier: Modifier,
+    content: @Composable Transition<S>.(Modifier) -> Unit,
+  )
+
+  @Composable
+  public fun Transition<S>.transitionSpec():
+    AnimatedContentTransitionScope<S>.() -> ContentTransform
+
+  @Composable
+  public fun AnimatedContentScope.AnimatedNavContent(
+    targetState: S,
+    content: @Composable (T) -> Unit,
+  )
+
+  @Stable
+  public interface Factory {
+
+    public fun <T> create(): AnimatedNavDecorator<T, *>
+  }
+}

circuit-overlay/build.gradle.kts

@@ -38,6 +38,7 @@ kotlin {
         api(libs.compose.runtime)
         api(libs.compose.foundation)
         implementation(libs.coroutines)
+        implementation(projects.circuitSharedElements)
       }
     }
     commonTest {

circuit-overlay/src/commonMain/kotlin/com/slack/circuit/overlay/ContentWithOverlays.kt

@@ -3,20 +3,34 @@
 package com.slack.circuit.overlay
 
 import androidx.compose.animation.AnimatedContent
+import androidx.compose.animation.AnimatedVisibilityScope
+import androidx.compose.animation.EnterExitState
+import androidx.compose.animation.EnterExitState.PostExit
+import androidx.compose.animation.EnterExitState.PreEnter
+import androidx.compose.animation.EnterExitState.Visible
 import androidx.compose.animation.EnterTransition
 import androidx.compose.animation.ExitTransition
+import androidx.compose.animation.ExperimentalSharedTransitionApi
 import androidx.compose.animation.SizeTransform
+import androidx.compose.animation.core.ExperimentalTransitionApi
+import androidx.compose.animation.core.Transition
+import androidx.compose.animation.core.createChildTransition
 import androidx.compose.animation.core.snap
+import androidx.compose.animation.core.updateTransition
 import androidx.compose.animation.togetherWith
 import androidx.compose.foundation.layout.Box
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.derivedStateOf
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.key
+import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberUpdatedState
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import com.slack.circuit.sharedelements.ProvideAnimatedTransitionScope
+import com.slack.circuit.sharedelements.SharedElementTransitionScope.AnimatedScope.Overlay
 
 /**
  * Renders the given [content] with the ability to show overlays on top of it. This works by
@@ -26,6 +40,7 @@ import androidx.compose.ui.Modifier
  * @param overlayHost the [OverlayHost] to use for managing overlays.
  * @param content The regular content to render. Any overlays will be rendered over them.
  */
+@OptIn(ExperimentalSharedTransitionApi::class)
 @Composable
 public fun ContentWithOverlays(
   modifier: Modifier = Modifier,
@@ -41,9 +56,12 @@ public fun ContentWithOverlays(
     LocalOverlayState provides overlayState,
   ) {
     Box(modifier) {
-      content()
-      AnimatedContent(
-        targetState = overlayHostData,
+      val transition =
+        updateTransition(targetState = overlayHostData, label = "OverlayHostData transition")
+      ProvideAnimatedTransitionScope(Overlay, transition.animatedVisibilityScope { it == null }) {
+        content()
+      }
+      transition.AnimatedContent(
         transitionSpec = {
           val enter =
             (targetState?.overlay as? AnimatedOverlay)?.enterTransition ?: EnterTransition.None
@@ -56,12 +74,67 @@ public fun ContentWithOverlays(
         },
         contentAlignment = Alignment.Center,
       ) { data ->
-        when (val overlay = data?.overlay) {
-          null -> Unit
-          is AnimatedOverlay -> with(overlay) { AnimatedContent(data::finish) }
-          else -> overlay.Content(data::finish)
+        ProvideAnimatedTransitionScope(Overlay, this) {
+          when (val overlay = data?.overlay) {
+            null -> Unit
+            is AnimatedOverlay -> with(overlay) { AnimatedContent(data::finish) }
+            else -> overlay.Content(data::finish)
+          }
         }
       }
     }
   }
 }
+
+/** Creates an [AnimatedVisibilityScope] for the given [OverlayState]. */
+@OptIn(ExperimentalTransitionApi::class)
+@Composable
+private fun Transition<OverlayHostData<Any>?>.animatedVisibilityScope(
+  visible: (OverlayHostData<Any>?) -> Boolean
+): AnimatedVisibilityScope {
+  val childTransition =
+    createChildTransition(label = "Overlay transition") { overlayState ->
+      targetEnterExit(visible, overlayState)
+    }
+  return remember(childTransition) { SimpleAnimatedVisibilityScope(childTransition) }
+}
+
+/** A [AnimatedVisibilityScope] that takes a [Transition]. */
+private data class SimpleAnimatedVisibilityScope(
+  override val transition: Transition<EnterExitState>
+) : AnimatedVisibilityScope
+
+// This converts Boolean visible to EnterExitState
+@Composable
+private fun <T> Transition<T>.targetEnterExit(
+  visible: (T) -> Boolean,
+  targetState: T,
+): EnterExitState =
+  key(this) {
+    if (this.isSeeking) {
+      if (visible(targetState)) {
+        Visible
+      } else {
+        if (visible(this.currentState)) {
+          PostExit
+        } else {
+          PreEnter
+        }
+      }
+    } else {
+      val hasBeenVisible = remember { mutableStateOf(false) }
+      if (visible(currentState)) {
+        hasBeenVisible.value = true
+      }
+      if (visible(targetState)) {
+        Visible
+      } else {
+        // If never been visible, visible = false means PreEnter, otherwise PostExit
+        if (hasBeenVisible.value) {
+          PostExit
+        } else {
+          PreEnter
+        }
+      }
+    }
+  }