Add crossfade between subsequent image results in AsyncImage (#3141)

* Enable crossfade between images by remembering last success painter in AsyncImagePainter

* Add opt-in option for crossfade between images

* Update API dump

* Simplify if-condition

* Enable crossfade between images by remembering last success drawable in GenericViewTarget. Additionally, opt-in option is provided.

* Use crossfadeBetweenImages from target instead of ImageRequest

* Annotate crossfadeBetweenImages APIs as @ExperimentalCoilApi

* Expose crossfadeBetweenImages key

* Enable crossfadeBetweenImages option on ImageLoader.Builder

* Add documentation comment explaining crossfadeBetweenImages option

* Fix failing tests after adding crossfadeBetweenImages option

* Update API dump

* Revert "Enable crossfade between images by remembering last success drawable in GenericViewTarget. Additionally, opt-in option is provided."

This reverts commit 340a445.

* Revert "Use crossfadeBetweenImages from target instead of ImageRequest"

This reverts commit e887971.

* refactor: Move and rename crossfadeBetweenImages to Compose-only module

* Rename `crossfadeBetweenImages` to `useExistingImageAsPlaceholder` for clarity
* Move from `coil-core` to `coil-compose-core` to restrict to Compose usage only
* Update documentation to explicitly state Compose-only support
* Remove from core module to prevent incorrect usage in XML views

* Apply Spotless code formatting

* Revert "Fix failing tests after adding crossfadeBetweenImages option"

This reverts commit e17c262.

* Update API dump

---------

Co-authored-by: byungtak.lee <kyle.lee@travel-wallet.com>

Author: tak8997

coil-compose-core/api/android/coil-compose-core.api

@@ -161,6 +161,13 @@ public final class coil3/compose/ImagePainter_androidKt {
 	public static synthetic fun asPainter-55t9-rM$default (Lcoil3/Image;Landroid/content/Context;IILjava/lang/Object;)Landroidx/compose/ui/graphics/painter/Painter;
 }
 
+public final class coil3/compose/ImageRequestsKt {
+	public static final fun getUseExistingImageAsPlaceholder (Lcoil3/Extras$Key$Companion;)Lcoil3/Extras$Key;
+	public static final fun getUseExistingImageAsPlaceholder (Lcoil3/request/ImageRequest;)Z
+	public static final fun useExistingImageAsPlaceholder (Lcoil3/ImageLoader$Builder;Z)Lcoil3/ImageLoader$Builder;
+	public static final fun useExistingImageAsPlaceholder (Lcoil3/request/ImageRequest$Builder;Z)Lcoil3/request/ImageRequest$Builder;
+}
+
 public final class coil3/compose/LocalAsyncImageModelEqualityDelegateKt {
 	public static final fun getLocalAsyncImageModelEqualityDelegate ()Landroidx/compose/runtime/ProvidableCompositionLocal;
 }

coil-compose-core/api/coil-compose-core.klib.api

@@ -202,9 +202,15 @@ final val coil3.compose/coil3_compose_AsyncImagePainter_State_Success$stableprop
 final val coil3.compose/coil3_compose_ConstraintsSizeResolver$stableprop // coil3.compose/coil3_compose_ConstraintsSizeResolver$stableprop|#static{}coil3_compose_ConstraintsSizeResolver$stableprop[0]
 final val coil3.compose/coil3_compose_CrossfadePainter$stableprop // coil3.compose/coil3_compose_CrossfadePainter$stableprop|#static{}coil3_compose_CrossfadePainter$stableprop[0]
 final val coil3.compose/coil3_compose_ImagePainter$stableprop // coil3.compose/coil3_compose_ImagePainter$stableprop|#static{}coil3_compose_ImagePainter$stableprop[0]
+final val coil3.compose/useExistingImageAsPlaceholder // coil3.compose/useExistingImageAsPlaceholder|@coil3.Extras.Key.Companion{}useExistingImageAsPlaceholder[0]
+    final fun (coil3/Extras.Key.Companion).<get-useExistingImageAsPlaceholder>(): coil3/Extras.Key<kotlin/Boolean> // coil3.compose/useExistingImageAsPlaceholder.<get-useExistingImageAsPlaceholder>|<get-useExistingImageAsPlaceholder>@coil3.Extras.Key.Companion(){}[0]
+final val coil3.compose/useExistingImageAsPlaceholder // coil3.compose/useExistingImageAsPlaceholder|@coil3.request.ImageRequest{}useExistingImageAsPlaceholder[0]
+    final fun (coil3.request/ImageRequest).<get-useExistingImageAsPlaceholder>(): kotlin/Boolean // coil3.compose/useExistingImageAsPlaceholder.<get-useExistingImageAsPlaceholder>|<get-useExistingImageAsPlaceholder>@coil3.request.ImageRequest(){}[0]
 
 final fun (coil3.compose/SubcomposeAsyncImageScope).coil3.compose/SubcomposeAsyncImageContent(androidx.compose.ui/Modifier?, androidx.compose.ui.graphics.painter/Painter?, kotlin/String?, androidx.compose.ui/Alignment?, androidx.compose.ui.layout/ContentScale?, kotlin/Float, androidx.compose.ui.graphics/ColorFilter?, kotlin/Boolean, androidx.compose.runtime/Composer?, kotlin/Int, kotlin/Int) // coil3.compose/SubcomposeAsyncImageContent|SubcomposeAsyncImageContent@coil3.compose.SubcomposeAsyncImageScope(androidx.compose.ui.Modifier?;androidx.compose.ui.graphics.painter.Painter?;kotlin.String?;androidx.compose.ui.Alignment?;androidx.compose.ui.layout.ContentScale?;kotlin.Float;androidx.compose.ui.graphics.ColorFilter?;kotlin.Boolean;androidx.compose.runtime.Composer?;kotlin.Int;kotlin.Int){}[0]
+final fun (coil3.request/ImageRequest.Builder).coil3.compose/useExistingImageAsPlaceholder(kotlin/Boolean): coil3.request/ImageRequest.Builder // coil3.compose/useExistingImageAsPlaceholder|useExistingImageAsPlaceholder@coil3.request.ImageRequest.Builder(kotlin.Boolean){}[0]
 final fun (coil3/Image).coil3.compose/asPainter(coil3/PlatformContext, androidx.compose.ui.graphics/FilterQuality = ...): androidx.compose.ui.graphics.painter/Painter // coil3.compose/asPainter|asPainter@coil3.Image(coil3.PlatformContext;androidx.compose.ui.graphics.FilterQuality){}[0]
+final fun (coil3/ImageLoader.Builder).coil3.compose/useExistingImageAsPlaceholder(kotlin/Boolean): coil3/ImageLoader.Builder // coil3.compose/useExistingImageAsPlaceholder|useExistingImageAsPlaceholder@coil3.ImageLoader.Builder(kotlin.Boolean){}[0]
 final fun coil3.compose.internal/coil3_compose_internal_AbstractContentPainterNode$stableprop_getter(): kotlin/Int // coil3.compose.internal/coil3_compose_internal_AbstractContentPainterNode$stableprop_getter|coil3_compose_internal_AbstractContentPainterNode$stableprop_getter(){}[0]
 final fun coil3.compose.internal/coil3_compose_internal_AsyncImageState$stableprop_getter(): kotlin/Int // coil3.compose.internal/coil3_compose_internal_AsyncImageState$stableprop_getter|coil3_compose_internal_AsyncImageState$stableprop_getter(){}[0]
 final fun coil3.compose.internal/coil3_compose_internal_ContentPainterElement$stableprop_getter(): kotlin/Int // coil3.compose.internal/coil3_compose_internal_ContentPainterElement$stableprop_getter|coil3_compose_internal_ContentPainterElement$stableprop_getter(){}[0]

coil-compose-core/api/jvm/coil-compose-core.api

@@ -161,6 +161,13 @@ public final class coil3/compose/ImagePainter_nonAndroidKt {
 	public static synthetic fun asPainter-55t9-rM$default (Lcoil3/Image;Lcoil3/PlatformContext;IILjava/lang/Object;)Landroidx/compose/ui/graphics/painter/Painter;
 }
 
+public final class coil3/compose/ImageRequestsKt {
+	public static final fun getUseExistingImageAsPlaceholder (Lcoil3/Extras$Key$Companion;)Lcoil3/Extras$Key;
+	public static final fun getUseExistingImageAsPlaceholder (Lcoil3/request/ImageRequest;)Z
+	public static final fun useExistingImageAsPlaceholder (Lcoil3/ImageLoader$Builder;Z)Lcoil3/ImageLoader$Builder;
+	public static final fun useExistingImageAsPlaceholder (Lcoil3/request/ImageRequest$Builder;Z)Lcoil3/request/ImageRequest$Builder;
+}
+
 public final class coil3/compose/LocalAsyncImageModelEqualityDelegateKt {
 	public static final fun getLocalAsyncImageModelEqualityDelegate ()Landroidx/compose/runtime/ProvidableCompositionLocal;
 }

coil-compose-core/src/commonMain/kotlin/coil3/compose/AsyncImagePainter.kt

@@ -277,7 +277,10 @@ class AsyncImagePainter internal constructor(
         return request.newBuilder()
             .target(
                 onStart = { placeholder ->
-                    val painter = placeholder?.asPainter(request.context, filterQuality)
+                    var painter = placeholder?.asPainter(request.context, filterQuality)
+                    if (request.useExistingImageAsPlaceholder && painter == null && this.painter != null) {
+                        painter = this.painter
+                    }
                     updateState(State.Loading(painter))
                 },
             )

coil-compose-core/src/commonMain/kotlin/coil3/compose/ImageRequests.kt

@@ -0,0 +1,38 @@
+package coil3.compose
+
+import coil3.Extras
+import coil3.ImageLoader
+import coil3.annotation.ExperimentalCoilApi
+import coil3.getExtra
+import coil3.request.ImageRequest
+
+/**
+ * If enabled, crossfade animation will be applied not only between placeholder and the loaded image,
+ * but also between consecutive images (i.e., when a new image is requested after a previous one has been successfully loaded).
+ * This allows for smooth transitions between images, rather than an abrupt replacement or only placeholder→image crossfade.
+ *
+ * Note: The [coil3.request.crossfade] option must also be enabled for [useExistingImageAsPlaceholder] to take effect.
+ * If [coil3.request.crossfade] is not enabled, this option will have no effect.
+ *
+ * Also note: If a placeholder is set, the crossfade will always occur between the placeholder and the result,
+ * so consecutive image crossfading may not be observable in that scenario.
+ *
+ * Also note: This option is only supported in Jetpack Compose (AsyncImage, AsyncImagePainter).
+ * It does not apply to XML-based views.
+ */
+fun ImageRequest.Builder.useExistingImageAsPlaceholder(enable: Boolean) = apply {
+    extras[useExistingImageAsPlaceholderKey] = enable
+}
+
+fun ImageLoader.Builder.useExistingImageAsPlaceholder(enable: Boolean) = apply {
+    extras[useExistingImageAsPlaceholderKey] = enable
+}
+
+@ExperimentalCoilApi
+val ImageRequest.useExistingImageAsPlaceholder: Boolean
+    get() = getExtra(useExistingImageAsPlaceholderKey)
+
+val Extras.Key.Companion.useExistingImageAsPlaceholder: Extras.Key<Boolean>
+    get() = useExistingImageAsPlaceholderKey
+
+private val useExistingImageAsPlaceholderKey = Extras.Key(default = false)