feat(AvatarGroup): add overflow slot for custom tooltip on hidden avatars

Author: Mathu-lmn

docs/app/components/content/examples/avatar-group/AvatarGroupOverflowTooltipExample.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+const getOverflowTooltip = (hiddenCount: number) => `${hiddenCount} more teammates`
+</script>
+
+<template>
+  <UAvatarGroup :max="2">
+    <UAvatar
+      src="https://github.com/benjamincanac.png"
+      alt="Benjamin Canac"
+      loading="lazy"
+    />
+
+    <UAvatar
+      src="https://github.com/romhml.png"
+      alt="Romain Hamel"
+      loading="lazy"
+    />
+
+    <UAvatar
+      src="https://github.com/noook.png"
+      alt="Neil Richter"
+      loading="lazy"
+    />
+
+    <template #overflow="{ hiddenCount, avatarProps }">
+      <UTooltip :text="getOverflowTooltip(hiddenCount)">
+        <UAvatar v-bind="avatarProps" />
+      </UTooltip>
+    </template>
+  </UAvatarGroup>
+</template>

docs/content/docs/2.components/avatar-group.md

@@ -69,6 +69,12 @@ slots:
 :u-avatar{src="https://github.com/noook.png" alt="Neil Richter" loading="lazy"}
 ::
 
+### Overflow tooltip
+
+Use the `overflow` slot to customize the `+X` avatar. The slot receives the hidden count and the default avatar props, so you can wrap the overflow avatar with a [Tooltip](/docs/components/tooltip) and provide either a static string or a helper function that derives the label from the count.
+
+:component-example{name="avatar-group-overflow-tooltip-example"}
+
 ## Examples
 
 ### With tooltip

src/runtime/components/AvatarGroup.vue

@@ -26,6 +26,7 @@ export interface AvatarGroupProps {
 
 export interface AvatarGroupSlots {
   default?(props?: {}): VNode[]
+  overflow?(props: { hiddenCount: number, avatarProps: { text: string, class: any } }): VNode[]
 }
 </script>
 
@@ -90,14 +91,21 @@ const hiddenCount = computed(() => {
   return children.value.length - visibleAvatars.value.length
 })
 
+const overflowAvatarProps = computed(() => ({
+  text: `+${hiddenCount.value}`,
+  class: ui.value.base({ class: uiProp.value?.base })
+}))
+
 provide(avatarGroupInjectionKey, computed(() => ({
   size: props.size
 })))
 </script>
 
 <template>
   <Primitive :as="as" data-slot="root" :class="ui.root({ class: [uiProp?.root, props.class] })">
-    <UAvatar v-if="hiddenCount > 0" :text="`+${hiddenCount}`" data-slot="base" :class="ui.base({ class: uiProp?.base })" />
+    <slot v-if="hiddenCount > 0" name="overflow" :hidden-count="hiddenCount" :avatar-props="overflowAvatarProps">
+      <UAvatar v-bind="overflowAvatarProps" data-slot="base" />
+    </slot>
     <component :is="avatar" v-for="(avatar, count) in visibleAvatars" :key="count" data-slot="base" :class="ui.base({ class: uiProp?.base })" />
   </Primitive>
 </template>

test/components/AvatarGroup.spec.ts

@@ -5,6 +5,7 @@ import { mountSuspended } from '@nuxt/test-utils/runtime'
 import { renderEach } from '../component-render'
 import AvatarGroup from '../../src/runtime/components/AvatarGroup.vue'
 import Avatar from '../../src/runtime/components/Avatar.vue'
+import Tooltip from '../../src/runtime/components/Tooltip.vue'
 import theme from '#build/ui/avatar-group'
 
 const AvatarGroupWrapper = defineComponent({
@@ -19,6 +20,26 @@ const AvatarGroupWrapper = defineComponent({
 </UAvatarGroup>`
 })
 
+const AvatarGroupOverflowTooltipWrapper = defineComponent({
+  components: {
+    UAvatar: Avatar,
+    UAvatarGroup: AvatarGroup,
+    UTooltip: Tooltip
+  },
+  template: `<UAvatarGroup :max="2">
+  <UAvatar src="https://github.com/benjamincanac.png" alt="Benjamin Canac" />
+  <UAvatar src="https://github.com/romhml.png" alt="Romain Hamel" />
+  <UAvatar src="https://github.com/noook.png" alt="Neil Richter" />
+  <template #overflow="{ hiddenCount, avatarProps }">
+    <span :data-hidden-count="hiddenCount">
+      <UTooltip :text="'+' + hiddenCount + ' hidden avatars'">
+        <UAvatar v-bind="avatarProps" />
+      </UTooltip>
+    </span>
+  </template>
+</UAvatarGroup>`
+})
+
 describe('AvatarGroup', () => {
   const sizes = Object.keys(theme.variants.size) as any
 
@@ -33,6 +54,12 @@ describe('AvatarGroup', () => {
     ['with default slot', {}]
   ])
 
+  it('exposes the hidden count to the overflow slot', async () => {
+    const wrapper = await mountSuspended(AvatarGroupOverflowTooltipWrapper)
+
+    expect(wrapper.find('[data-hidden-count="1"]').exists()).toBe(true)
+  })
+
   it('passes accessibility tests', async () => {
     const wrapper = await mountSuspended(AvatarGroupWrapper, {
       props: {