Deprecate LocalImageLoader.

coil-compose-singleton/api/coil-compose-singleton.api

@@ -8,7 +8,6 @@ public final class coil/compose/ImageLoaderProvidableCompositionLocal {
 	public fun hashCode ()I
 	public static fun hashCode-impl (Landroidx/compose/runtime/ProvidableCompositionLocal;)I
 	public static final fun provides-impl (Landroidx/compose/runtime/ProvidableCompositionLocal;Lcoil/ImageLoader;)Landroidx/compose/runtime/ProvidedValue;
-	public static final fun providesDefault-impl (Landroidx/compose/runtime/ProvidableCompositionLocal;Lcoil/ImageLoader;)Landroidx/compose/runtime/ProvidedValue;
 	public fun toString ()Ljava/lang/String;
 	public static fun toString-impl (Landroidx/compose/runtime/ProvidableCompositionLocal;)Ljava/lang/String;
 	public final synthetic fun unbox-impl ()Landroidx/compose/runtime/ProvidableCompositionLocal;

coil-compose-singleton/src/main/java/coil/compose/LocalImageLoader.kt

@@ -1,34 +1,60 @@
-@file:Suppress("unused")
+@file:Suppress("DEPRECATION", "unused")
 
 package coil.compose
 
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.CompositionLocal
 import androidx.compose.runtime.ProvidableCompositionLocal
 import androidx.compose.runtime.ReadOnlyComposable
 import androidx.compose.runtime.staticCompositionLocalOf
 import androidx.compose.ui.platform.LocalContext
 import coil.ImageLoader
 import coil.imageLoader
 
-/**
- * A pseudo-[CompositionLocal] that returns the current [ImageLoader] for the composition.
- * If a local [ImageLoader] has not been provided, it returns the singleton [ImageLoader].
- */
+private const val DEPRECATION_MESSAGE = "" +
+    "LocalImageLoader was intended to provide a method to overwrite the singleton ImageLoader " +
+    "in local compositions. In practice, it's not clear that `LocalImageLoader.provide` " +
+    "**does not** set the singleton ImageLoader. This can result in accidentally creating " +
+    "multiple ImageLoader instances if you use a combination of `LocalImageLoader.current` and " +
+    "`context.imageLoader`. To maximize performance, apps should create one ImageLoader or use " +
+    "`ImageLoader.newBuilder` to create new ImageLoaders that share the same resources.\n" +
+    "\n" +
+    "Additionally, as a composition is at most scoped to an Activity, `LocalImageLoader.provide` " +
+    "encourages creating multiple ImageLoaders if the user creates multiple activities that use " +
+    "Compose.\n" +
+    "\n" +
+    "You should migrate to `ImageLoaderFactory` to set the singleton ImageLoader and " +
+    "`LocalContext.current.imageLoader` to access the singleton ImageLoader in Compose. If you " +
+    "need to use a locally scoped ImageLoader it's recommended to use the `AsyncImage` and " +
+    "`rememberAsyncImagePainter` overloads that have an ImageLoader argument and pass the local " +
+    "ImageLoader as input."
+
+@Deprecated(message = DEPRECATION_MESSAGE)
 val LocalImageLoader = ImageLoaderProvidableCompositionLocal()
 
-/** @see LocalImageLoader */
+@Deprecated(message = DEPRECATION_MESSAGE)
 @JvmInline
 value class ImageLoaderProvidableCompositionLocal internal constructor(
     private val delegate: ProvidableCompositionLocal<ImageLoader?> = staticCompositionLocalOf { null }
 ) {
 
+    @Deprecated(
+        message = DEPRECATION_MESSAGE,
+        replaceWith = ReplaceWith(
+            expression = "LocalContext.current.imageLoader",
+            imports = ["androidx.compose.ui.platform.LocalContext", "coil.imageLoader"]
+        )
+    )
     val current: ImageLoader
         @Composable
         @ReadOnlyComposable
         get() = delegate.current ?: LocalContext.current.imageLoader
 
+    @Deprecated(
+        message = DEPRECATION_MESSAGE,
+        replaceWith = ReplaceWith(
+            expression = "Coil.setImageLoader(value)",
+            imports = ["coil.Coil"]
+        )
+    )
     infix fun provides(value: ImageLoader) = delegate provides value
-
-    infix fun providesDefault(value: ImageLoader) = delegate providesDefault value
 }

coil-compose-singleton/src/main/java/coil/compose/SingletonAsyncImage.kt

@@ -1,4 +1,4 @@
-@file:Suppress("unused")
+@file:Suppress("DEPRECATION", "unused")
 
 package coil.compose
 

coil-compose-singleton/src/main/java/coil/compose/SingletonAsyncImagePainter.kt

@@ -1,4 +1,4 @@
-@file:Suppress("unused")
+@file:Suppress("DEPRECATION", "unused")
 
 package coil.compose