Improve avatar components (#1072)

* Make avatar initials font size auto
Similar to autoSizeTextType in xml

* Clean parameter lists

* Improve text sizing logic

* Clean parameter lists again

* Improve and add KDocs

* Move ParticipantAvatars out of "internal" package

* Make Avatar component internal and change KDocs accordingly

* Clean up

demo-app/src/main/kotlin/io/getstream/video/android/ui/call/CallStats.kt

@@ -74,7 +74,6 @@ import androidx.compose.ui.window.DialogProperties
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import io.getstream.video.android.compose.theme.VideoTheme
 import io.getstream.video.android.compose.ui.components.avatar.UserAvatar
-import io.getstream.video.android.compose.ui.components.base.styling.StyleSize
 import io.getstream.video.android.core.Call
 import io.getstream.video.android.mock.StreamPreviewDataUtils
 import io.getstream.video.android.mock.previewCall
@@ -342,10 +341,9 @@ fun UserAndCallId(call: Call, clipboardManager: ClipboardManager?) {
                 verticalAlignment = Alignment.CenterVertically,
             ) {
                 UserAvatar(
-                    textSize = StyleSize.S,
                     modifier = Modifier.size(44.dp),
-                    userName = call.user.userNameOrId,
                     userImage = call.user.image,
+                    userName = call.user.userNameOrId,
                 )
                 Column(modifier = Modifier.padding(start = 8.dp)) {
                     Text(

demo-app/src/main/kotlin/io/getstream/video/android/ui/call/ParticipantsDialog.kt

@@ -55,7 +55,6 @@ import androidx.compose.ui.window.DialogProperties
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import io.getstream.video.android.compose.theme.VideoTheme
 import io.getstream.video.android.compose.ui.components.avatar.UserAvatar
-import io.getstream.video.android.compose.ui.components.base.styling.StyleSize
 import io.getstream.video.android.core.Call
 import io.getstream.video.android.core.ParticipantState
 import io.getstream.video.android.mock.StreamPreviewDataUtils
@@ -146,10 +145,9 @@ fun ParticipantsListContent(
                     val userName by participant.userNameOrId.collectAsStateWithLifecycle()
                     val userImage by participant.image.collectAsStateWithLifecycle()
                     UserAvatar(
-                        textSize = StyleSize.S,
                         modifier = Modifier.size(VideoTheme.dimens.genericXxl),
-                        userName = userName,
                         userImage = userImage,
+                        userName = userName,
                         isShowingOnlineIndicator = false,
                     )
                     Spacer(modifier = Modifier.size(VideoTheme.dimens.spacingM))

demo-app/src/main/kotlin/io/getstream/video/android/ui/join/CallJoinScreen.kt

@@ -96,7 +96,6 @@ import io.getstream.video.android.compose.ui.components.base.StreamButton
 import io.getstream.video.android.compose.ui.components.base.StreamDialogPositiveNegative
 import io.getstream.video.android.compose.ui.components.base.StreamIconToggleButton
 import io.getstream.video.android.compose.ui.components.base.StreamTextField
-import io.getstream.video.android.compose.ui.components.base.styling.StyleSize
 import io.getstream.video.android.mock.StreamPreviewDataUtils
 import io.getstream.video.android.mock.previewUsers
 import io.getstream.video.android.model.User
@@ -224,9 +223,8 @@ private fun CallJoinHeader(
             ) {
                 UserAvatar(
                     modifier = Modifier.size(VideoTheme.dimens.componentHeightL),
-                    textSize = StyleSize.S,
-                    userName = it.userNameOrId,
                     userImage = it.image,
+                    userName = it.userNameOrId,
                 )
             }
 

demo-app/src/main/kotlin/io/getstream/video/android/ui/lobby/CallLobbyScreen.kt

@@ -68,7 +68,6 @@ import io.getstream.video.android.R
 import io.getstream.video.android.compose.theme.VideoTheme
 import io.getstream.video.android.compose.ui.components.avatar.UserAvatar
 import io.getstream.video.android.compose.ui.components.base.StreamButton
-import io.getstream.video.android.compose.ui.components.base.styling.StyleSize
 import io.getstream.video.android.compose.ui.components.call.lobby.CallLobby
 import io.getstream.video.android.core.Call
 import io.getstream.video.android.core.call.state.ToggleCamera
@@ -173,10 +172,9 @@ private fun CallLobbyHeaderContent(
         val userValue = user.value
         if (userValue != null) {
             UserAvatar(
-                textSize = StyleSize.S,
                 modifier = Modifier.size(32.dp),
-                userName = userValue.userNameOrId,
                 userImage = userValue.image,
+                userName = userValue.userNameOrId,
             )
 
             Spacer(modifier = Modifier.width(4.dp))

demo-app/src/main/kotlin/io/getstream/video/android/ui/outgoing/DirectCallJoinScreen.kt

@@ -52,7 +52,6 @@ import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import io.getstream.video.android.compose.theme.VideoTheme
 import io.getstream.video.android.compose.ui.components.avatar.UserAvatar
 import io.getstream.video.android.compose.ui.components.base.StreamButton
-import io.getstream.video.android.compose.ui.components.base.styling.StyleSize
 import io.getstream.video.android.mock.previewUsers
 import io.getstream.video.android.model.User
 import io.getstream.video.android.models.GoogleAccount
@@ -96,10 +95,9 @@ private fun Header(user: User?) {
         Row {
             user?.let {
                 UserAvatar(
-                    textSize = StyleSize.XS,
                     modifier = Modifier.size(24.dp),
-                    userName = it.userNameOrId,
                     userImage = it.image,
+                    userName = it.userNameOrId,
                 )
                 Spacer(modifier = Modifier.width(8.dp))
             }
@@ -213,10 +211,9 @@ private fun UserRow(
     ) {
         Row(verticalAlignment = Alignment.CenterVertically) {
             UserAvatar(
-                textSize = StyleSize.M,
                 modifier = Modifier.size(50.dp),
-                userName = name,
                 userImage = avatarUrl,
+                userName = name,
             )
             Spacer(modifier = Modifier.width(10.dp))
             Text(

stream-video-android-ui-compose/api/stream-video-android-ui-compose.api

@@ -496,10 +496,6 @@ public final class io/getstream/video/android/compose/ui/components/audio/Regula
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class io/getstream/video/android/compose/ui/components/avatar/AvatarKt {
-	public static final fun Avatar-zf1_rLo (Landroidx/compose/ui/Modifier;Ljava/lang/String;Ljava/lang/String;Landroidx/compose/ui/graphics/Shape;Lio/getstream/video/android/compose/ui/components/base/styling/StyleSize;Landroidx/compose/ui/text/TextStyle;Landroidx/compose/ui/layout/ContentScale;Ljava/lang/String;JILjava/lang/Integer;JLkotlin/jvm/functions/Function0;Landroidx/compose/runtime/Composer;III)V
-}
-
 public final class io/getstream/video/android/compose/ui/components/avatar/ComposableSingletons$AvatarKt {
 	public static final field INSTANCE Lio/getstream/video/android/compose/ui/components/avatar/ComposableSingletons$AvatarKt;
 	public static field lambda-1 Lkotlin/jvm/functions/Function2;
@@ -551,11 +547,11 @@ public final class io/getstream/video/android/compose/ui/components/avatar/Onlin
 }
 
 public final class io/getstream/video/android/compose/ui/components/avatar/UserAvatarBackgroundKt {
-	public static final fun UserAvatarBackground-xr0SGnQ (Ljava/lang/String;Ljava/lang/String;Landroidx/compose/ui/Modifier;Landroidx/compose/ui/graphics/Shape;FLandroidx/compose/ui/layout/ContentScale;Ljava/lang/String;JJILjava/lang/Integer;Landroidx/compose/runtime/Composer;III)V
+	public static final fun UserAvatarBackground-1UyhGxE (Landroidx/compose/ui/Modifier;Ljava/lang/String;Ljava/lang/String;Landroidx/compose/ui/graphics/Shape;FLandroidx/compose/ui/layout/ContentScale;Ljava/lang/String;JLjava/lang/Integer;ILandroidx/compose/ui/text/TextStyle;JLandroidx/compose/runtime/Composer;III)V
 }
 
 public final class io/getstream/video/android/compose/ui/components/avatar/UserAvatarKt {
-	public static final fun UserAvatar-8W8krDU (Ljava/lang/String;Ljava/lang/String;Landroidx/compose/ui/Modifier;Landroidx/compose/ui/graphics/Shape;Landroidx/compose/ui/layout/ContentScale;Ljava/lang/String;Lio/getstream/video/android/compose/ui/components/base/styling/StyleSize;JILjava/lang/Integer;JZLio/getstream/video/android/compose/ui/components/avatar/OnlineIndicatorAlignment;Lkotlin/jvm/functions/Function3;Lkotlin/jvm/functions/Function0;Landroidx/compose/runtime/Composer;III)V
+	public static final fun UserAvatar-S9GcbaY (Landroidx/compose/ui/Modifier;Ljava/lang/String;Ljava/lang/String;Landroidx/compose/ui/graphics/Shape;Landroidx/compose/ui/layout/ContentScale;Ljava/lang/String;JLjava/lang/Integer;ILandroidx/compose/ui/text/TextStyle;JZLio/getstream/video/android/compose/ui/components/avatar/OnlineIndicatorAlignment;Lkotlin/jvm/functions/Function3;Lkotlin/jvm/functions/Function0;Landroidx/compose/runtime/Composer;III)V
 }
 
 public final class io/getstream/video/android/compose/ui/components/background/CallBackgroundKt {
@@ -1782,6 +1778,17 @@ public final class io/getstream/video/android/compose/ui/components/participants
 	public final fun getLambda-1$stream_video_android_ui_compose_release ()Lkotlin/jvm/functions/Function2;
 }
 
+public final class io/getstream/video/android/compose/ui/components/participants/ComposableSingletons$ParticipantAvatarsKt {
+	public static final field INSTANCE Lio/getstream/video/android/compose/ui/components/participants/ComposableSingletons$ParticipantAvatarsKt;
+	public static field lambda-1 Lkotlin/jvm/functions/Function2;
+	public fun <init> ()V
+	public final fun getLambda-1$stream_video_android_ui_compose_release ()Lkotlin/jvm/functions/Function2;
+}
+
+public final class io/getstream/video/android/compose/ui/components/participants/ParticipantAvatarsKt {
+	public static final fun ParticipantAvatars (Ljava/util/List;Landroidx/compose/runtime/Composer;I)V
+}
+
 public final class io/getstream/video/android/compose/ui/components/participants/internal/ComposableSingletons$CallParticipantListAppBarKt {
 	public static final field INSTANCE Lio/getstream/video/android/compose/ui/components/participants/internal/ComposableSingletons$CallParticipantListAppBarKt;
 	public static field lambda-1 Lkotlin/jvm/functions/Function2;
@@ -1810,13 +1817,6 @@ public final class io/getstream/video/android/compose/ui/components/participants
 	public final fun getLambda-1$stream_video_android_ui_compose_release ()Lkotlin/jvm/functions/Function2;
 }
 
-public final class io/getstream/video/android/compose/ui/components/participants/internal/ComposableSingletons$ParticipantAvatarsKt {
-	public static final field INSTANCE Lio/getstream/video/android/compose/ui/components/participants/internal/ComposableSingletons$ParticipantAvatarsKt;
-	public static field lambda-1 Lkotlin/jvm/functions/Function2;
-	public fun <init> ()V
-	public final fun getLambda-1$stream_video_android_ui_compose_release ()Lkotlin/jvm/functions/Function2;
-}
-
 public final class io/getstream/video/android/compose/ui/components/participants/internal/ComposableSingletons$ParticipantInformationKt {
 	public static final field INSTANCE Lio/getstream/video/android/compose/ui/components/participants/internal/ComposableSingletons$ParticipantInformationKt;
 	public static field lambda-1 Lkotlin/jvm/functions/Function2;
@@ -1828,10 +1828,6 @@ public final class io/getstream/video/android/compose/ui/components/participants
 	public final fun getLambda-3$stream_video_android_ui_compose_release ()Lkotlin/jvm/functions/Function2;
 }
 
-public final class io/getstream/video/android/compose/ui/components/participants/internal/ParticipantAvatarsKt {
-	public static final fun ParticipantAvatars (Ljava/util/List;Landroidx/compose/runtime/Composer;I)V
-}
-
 public final class io/getstream/video/android/compose/ui/components/participants/internal/ParticipantInformationKt {
 	public static final fun ParticipantInformation (Lio/getstream/video/android/core/model/CallStatus;Ljava/util/List;ZLandroidx/compose/runtime/Composer;II)V
 }

stream-video-android-ui-compose/src/main/kotlin/io/getstream/video/android/compose/ui/components/audio/ParticipantAudio.kt

@@ -86,11 +86,11 @@ public fun ParticipantAudio(
     ) {
         Box(modifier = Modifier.fillMaxSize()) {
             UserAvatar(
-                userName = nameOrId,
-                userImage = userImage,
                 modifier = Modifier
                     .fillMaxSize()
                     .padding(VideoTheme.dimens.spacingM),
+                userImage = userImage,
+                userName = nameOrId,
             )
 
             if (isSpeaking && style.isShowingSpeakingBorder) {

stream-video-android-ui-compose/src/main/kotlin/io/getstream/video/android/compose/ui/components/avatar/Avatar.kt

@@ -44,45 +44,40 @@ import com.skydoves.landscapist.coil.CoilImage
 import com.skydoves.landscapist.components.rememberImageComponent
 import com.skydoves.landscapist.placeholder.placeholder.PlaceholderPlugin
 import io.getstream.video.android.compose.theme.VideoTheme
-import io.getstream.video.android.compose.ui.components.base.styling.StyleSize
 import io.getstream.video.android.ui.common.R
 
 /**
- * An avatar that renders an image from the provided image URL. In case the image URL
- * was empty or there was an error loading the image, it falls back to the initials avatar.
+ * An avatar that renders an image or a fallback text. In case the image URL
+ * is empty or there was an error loading the image, it falls back to showing initials.
+ * If needed, the initials font size is gradually decreased automatically until the text fits within the avatar boundaries.
  *
- * @param modifier Modifier for styling.
- * @param imageUrl The URL of the image to load.
- * @param initials The fallback text.
+ * @param modifier Modifier used for styling.
+ * @param imageUrl The URL of the image to be displayed.
+ * @param fallbackText The fallback text to be used for the initials avatar.
  * @param shape The shape of the avatar.
- * @param textStyle The text style of the [initials] text.
- * @param contentScale The scale option used for the content.
- * @param contentDescription Description of the image.
- * @param requestSize The actual request size.
- * @param previewPlaceholder A placeholder that will be displayed on the Compose preview (IDE).
- * @param loadingPlaceholder A placeholder that will be displayed while loading an image.
- * @param initialsAvatarOffset The initials offset to apply to the avatar.
- * @param onClick OnClick action, that can be nullable.
+ * @param imageScale The scale rule used for the image.
+ * @param imageDescription Accessibility description for the image.
+ * @param imageRequestSize The image size to be requested.
+ * @param loadingPlaceholder Placeholder image to be displayed while loading the remote image.
+ * @param previewModePlaceholder Placeholder image to be displayed in Compose previews (IDE).
+ * @param textStyle The text style of the [fallbackText] text. The `fontSize`, `fontFamily` and `fontWeight` properties are used.
+ * If the font size is too large, it will be gradually decreased automatically.
+ * @param textOffset Offset to be applied to the initials text.
+ * @param onClick Handler to be called when the user clicks on the avatar.
  */
 @Composable
-public fun Avatar(
+internal fun Avatar(
     modifier: Modifier = Modifier,
     imageUrl: String? = null,
-    initials: String? = null,
+    fallbackText: String? = null,
     shape: Shape = VideoTheme.shapes.circle,
-    textSize: StyleSize = StyleSize.XL,
+    imageScale: ContentScale = ContentScale.Crop,
+    imageDescription: String? = null,
+    imageRequestSize: IntSize = IntSize(DEFAULT_IMAGE_SIZE, DEFAULT_IMAGE_SIZE),
+    @DrawableRes loadingPlaceholder: Int? = LocalAvatarPreviewProvider.getLocalAvatarLoadingPlaceholder(),
+    @DrawableRes previewModePlaceholder: Int = LocalAvatarPreviewProvider.getLocalAvatarPreviewPlaceholder(),
     textStyle: TextStyle = VideoTheme.typography.titleM,
-    contentScale: ContentScale = ContentScale.Crop,
-    contentDescription: String? = null,
-    requestSize: IntSize = IntSize(
-        DEFAULT_IMAGE_SIZE,
-        DEFAULT_IMAGE_SIZE,
-    ),
-    @DrawableRes previewPlaceholder: Int =
-        LocalAvatarPreviewProvider.getLocalAvatarPreviewPlaceholder(),
-    @DrawableRes loadingPlaceholder: Int? =
-        LocalAvatarPreviewProvider.getLocalAvatarLoadingPlaceholder(),
-    initialsAvatarOffset: DpOffset = DpOffset(0.dp, 0.dp),
+    textOffset: DpOffset = DpOffset(0.dp, 0.dp),
     onClick: (() -> Unit)? = null,
 ) {
     if (LocalInspectionMode.current && !imageUrl.isNullOrEmpty()) {
@@ -91,20 +86,20 @@ public fun Avatar(
                 .fillMaxSize()
                 .clip(CircleShape)
                 .testTag("avatar"),
-            painter = painterResource(id = previewPlaceholder),
+            painter = painterResource(id = previewModePlaceholder),
             contentScale = ContentScale.Crop,
             contentDescription = null,
         )
         return
     }
 
-    if (imageUrl.isNullOrEmpty() && !initials.isNullOrBlank()) {
+    if (imageUrl.isNullOrEmpty() && !fallbackText.isNullOrBlank()) {
         InitialsAvatar(
             modifier = modifier,
-            initials = initials,
-            textSize = textSize,
-            shape = shape,
+            text = fallbackText,
             textStyle = textStyle,
+            textOffset = textOffset,
+            shape = shape,
         )
         return
     }
@@ -123,11 +118,11 @@ public fun Avatar(
         modifier = clickableModifier.clip(shape),
         imageModel = { imageUrl },
         imageOptions = ImageOptions(
-            contentDescription = contentDescription,
-            contentScale = contentScale,
-            requestSize = requestSize,
+            contentDescription = imageDescription,
+            contentScale = imageScale,
+            requestSize = imageRequestSize,
         ),
-        previewPlaceholder = painterResource(id = previewPlaceholder),
+        previewPlaceholder = painterResource(id = previewModePlaceholder),
         component = rememberImageComponent {
             +CrossfadePlugin()
             loadingPlaceholder?.let {
@@ -137,10 +132,10 @@ public fun Avatar(
         failure = {
             InitialsAvatar(
                 modifier = modifier,
-                initials = initials.orEmpty(),
-                shape = shape,
+                text = fallbackText.orEmpty(),
                 textStyle = textStyle,
-                avatarOffset = initialsAvatarOffset,
+                textOffset = textOffset,
+                shape = shape,
             )
         },
     )
@@ -152,7 +147,7 @@ private fun AvatarInitialPreview() {
     VideoTheme {
         Avatar(
             modifier = Modifier.size(72.dp),
-            initials = "Thierry",
+            fallbackText = "Thierry",
         )
     }
 }
@@ -163,8 +158,8 @@ internal fun AvatarImagePreview() {
     VideoTheme {
         Avatar(
             modifier = Modifier.size(72.dp),
-            initials = null,
-            previewPlaceholder = R.drawable.stream_video_call_sample,
+            fallbackText = null,
+            previewModePlaceholder = R.drawable.stream_video_call_sample,
         )
     }
 }