feat(ui5-avatar-group): new slot overflowButton (#3037)

Added new slot which allows to add custom overflow button and "overflow" event to let you know when avatars
hide/show in order to update the overflow button text. If not provided, the AvatarGroup will display the built-in overflow button. The slot is provided to allow you defining the text of the overflow button and let you set additional aria attributes, such as aria-label.

Fixes: #2912

Author: nnaydenow

packages/main/src/AvatarGroup.hbs

@@ -10,8 +10,12 @@
 	>
 		<slot></slot>
 
-		<ui5-button ?hidden="{{_overflowBtnHidden}}" tabindex="{{_overflowButtonTabIndex}}" class="ui5-avatar-group-overflow-btn">
-			{{_overflowButtonText}}
-		</ui5-button>
+		{{#if _customOverflowButton}}
+			<slot name="overflowButton"></slot>
+		{{else}}
+			<ui5-button ?hidden="{{_overflowBtnHidden}}" ?non-interactive={{_isGroup}} class="ui5-avatar-group-overflow-btn">
+				{{_overflowButtonText}}
+			</ui5-button>
+		{{/if}}
 	</div>
 </div>

packages/main/src/AvatarGroup.js

@@ -113,6 +113,20 @@ const metadata = {
 			type: HTMLElement,
 			propertyName: "items",
 		},
+		/**
+		 * Defines the overflow button of <code>ui5-avatar-group</code>.
+		 * <b>Note:</b> We recommend using the <code>ui5-button</code> component.
+		 * <br><br>
+		 * <b>Note:</b> If this slot is not used, the <code>ui5-avatar-group</code> will
+		 * display the built-in overflow button.
+		 * @type {HTMLElement}
+		 * @slot overflowButton
+		 * @public
+		 * @since 1.0.0-rc.13
+		 */
+		 overflowButton: {
+			type: HTMLElement,
+		},
 	},
 	events: /** @lends sap.ui.webcomponents.main.AvatarGroup.prototype */ {
 		/**
@@ -130,6 +144,14 @@ const metadata = {
 				overflowButtonClicked: { type: Boolean },
 			},
 		},
+		/**
+		* Fired when the count of visible <code>ui5-avatar</code> elements in the
+		* <code>ui5-avatar-group</code> has changed
+		* @event
+		* @public
+		* @since 1.0.0-rc.13
+		*/
+		overflow: {},
 	},
 };
 
@@ -241,6 +263,10 @@ class AvatarGroup extends UI5Element {
 		return this.items.map(avatar => avatar._effectiveBackgroundColor);
 	}
 
+	get _customOverflowButton() {
+		return this.overflowButton.length ? this.overflowButton[0] : undefined;
+	}
+
 	get _hiddenStartIndex() {
 		return this._itemsCount - this._hiddenItems;
 	}
@@ -261,10 +287,6 @@ class AvatarGroup extends UI5Element {
 		return this._isGroup ? "0" : "-1";
 	}
 
-	get _overflowButtonTabIndex() {
-		return this._isGroup ? "-1" : false;
-	}
-
 	get _overflowButton() {
 		return this.shadowRoot.querySelector(AVATAR_GROUP_OVERFLOW_BTN_SELECTOR);
 	}
@@ -278,26 +300,31 @@ class AvatarGroup extends UI5Element {
 	 * @private
 	 */
 	get _overflowButtonEffectiveWidth() {
+		const button = this._customOverflowButton ? this._customOverflowButton : this._overflowButton;
 		// if in "Group" mode overflow button size is equal to the offset from second item
 		if (this._isGroup) {
 			let item = this.items[1];
 
 			// in some cases when second avatar is overflowed the offset of the button is the right one
 			if (!item || item.hidden) {
-				item = this._overflowButton;
+				item = button;
 			}
 
 			return this.effectiveDir === "rtl" ? this._getWidthToItem(item) : item.offsetLeft;
 		}
 
-		return this._overflowButton.offsetWidth;
+		return button.offsetWidth;
 	}
 
 	onAfterRendering() {
 		this._overflowItems();
 	}
 
 	onBeforeRendering() {
+		if (this._customOverflowButton) {
+			this._customOverflowButton.nonInteractive = this._isGroup;
+		}
+
 		this._prepareAvatars();
 	}
 
@@ -332,7 +359,7 @@ class AvatarGroup extends UI5Element {
 	}
 
 	_fireGroupEvent(targetRef) {
-		const isOverflowButtonClicked = targetRef.classList.contains(OVERFLOW_BTN_CLASS);
+		const isOverflowButtonClicked = targetRef.classList.contains(OVERFLOW_BTN_CLASS) || targetRef === this._customOverflowButton;
 
 		this.fireEvent("click", {
 			targetRef,
@@ -384,7 +411,7 @@ class AvatarGroup extends UI5Element {
 			}
 
 			// last avatar should not be offset as it breaks the container width and focus styles are no set correctly
-			if (index !== this._itemsCount - 1) {
+			if (index !== this._itemsCount - 1 || this._customOverflowButton) {
 				// based on RTL margin left or right is set to avatars
 				avatar.style[`margin-${RTL ? "left" : "right"}`] = offsets[avatar._effectiveSize][this.type];
 			}
@@ -437,7 +464,7 @@ class AvatarGroup extends UI5Element {
 			// used to determine whether the following items will fit the container or not
 			let totalWidth = this._getWidthToItem(item) + item.offsetWidth;
 
-			if (index !== this._itemsCount - 1) {
+			if (index !== this._itemsCount - 1 || this._customOverflowButton) {
 				totalWidth += this._overflowButtonEffectiveWidth;
 			}
 
@@ -460,13 +487,19 @@ class AvatarGroup extends UI5Element {
 	}
 
 	_setHiddenItems(hiddenItems) {
+		const shouldFireEvent = this._hiddenItems !== hiddenItems;
+
 		this._hiddenItems = hiddenItems;
 
 		this.items.forEach((item, index) => {
 			item.hidden = index >= this._hiddenStartIndex;
 		});
 
 		this._overflowButtonText = `+${hiddenItems > 99 ? 99 : hiddenItems}`;
+
+		if (shouldFireEvent) {
+			this.fireEvent("overflow");
+		}
 	}
 }
 

packages/main/src/themes/AvatarGroup.css

@@ -26,49 +26,58 @@
 	cursor: pointer;
 }
 
+:host([type="Group"]) ::slotted([ui5-button]),
 :host([type="Group"]) ::slotted([ui5-avatar]) {
 	pointer-events: none;
 }
 
+::slotted([ui5-button]:not([hidden])),
 .ui5-avatar-group-overflow-btn:not([hidden]) {
 	border-radius: 50%;
 	display: inline-flex;
-	text-overflow: unset;
+	text-overflow: initial;
 }
 
+::slotted([ui5-button][focused]),
 .ui5-avatar-group-overflow-btn[focused] {
 	outline: var(--_ui5_button_outline);
 	outline-offset: var(--_ui5_avatar_group_overflow_button_focus_offset);
 }
 
+:host([avatar-size="XS"]) ::slotted([ui5-button]),
 :host([avatar-size="XS"]) .ui5-avatar-group-overflow-btn {
 	height: 2rem;
 	width: 2rem;
 	min-width: 2rem;
 	font-size: .75rem;
 }
 
+::slotted([ui5-button]),
+:host([avatar-size="S"]) ::slotted([ui5-button]),
 :host([avatar-size="S"]) .ui5-avatar-group-overflow-btn {
 	height: 3rem;
 	width: 3rem;
 	min-width: 3rem;
 	font-size: 1.125rem;
 }
 
+:host([avatar-size="M"]) ::slotted([ui5-button]),
 :host([avatar-size="M"]) .ui5-avatar-group-overflow-btn {
 	height: 4rem;
 	width: 4rem;
 	min-width: 4rem;
 	font-size: 1.625rem;
 }
 
+:host([avatar-size="L"]) ::slotted([ui5-button]),
 :host([avatar-size="L"]) .ui5-avatar-group-overflow-btn {
 	height: 5rem;
 	width: 5rem;
 	min-width: 5rem;
 	font-size: 2rem;
 }
 
+:host([avatar-size="XL"]) ::slotted([ui5-button]),
 :host([avatar-size="XL"]) .ui5-avatar-group-overflow-btn {
 	height: 7rem;
 	width: 7rem;

packages/main/test/pages/AvatarGroup.html

@@ -213,6 +213,21 @@ <h3>Unordinary group</h3>
 			<ui5-avatar size="L" interactive initials="L"></ui5-avatar>
 			<ui5-avatar size="XL" interactive initials="XL"></ui5-avatar>
 		</ui5-avatar-group>
+
+		<h3>AvatarGroup with user defined overflow button</h3>
+		<ui5-avatar-group type="Individual" id="group-with-overflow-btn">
+			<ui5-avatar size="XS" interactive initials="XS"></ui5-avatar>
+			<ui5-avatar size="S" interactive initials="S"></ui5-avatar>
+			<ui5-avatar size="M" interactive initials="M"></ui5-avatar>
+			<ui5-avatar size="L" interactive initials="L"></ui5-avatar>
+			<ui5-avatar size="XL" interactive initials="XL"></ui5-avatar>
+			<ui5-avatar size="XS" interactive initials="XS"></ui5-avatar>
+			<ui5-avatar size="S" interactive initials="S"></ui5-avatar>
+			<ui5-avatar size="M" interactive initials="M"></ui5-avatar>
+			<ui5-avatar size="L" interactive initials="L"></ui5-avatar>
+			<ui5-avatar size="XL" interactive initials="XL"></ui5-avatar>
+			<ui5-button slot="overflowButton" id="overflowButton" aria-label="+99 avatars">+99</ui5-button>
+		</ui5-avatar-group>
 	</div>
 
 <script>
@@ -230,6 +245,8 @@ <h3>Unordinary group</h3>
 	var resetBtn = document.getElementById("reset-btn")
 	var slider = document.getElementById("slider");
 	var avGrWrapper = document.getElementById("avatar-group-wrapper");
+	var groupWithBtn = document.getElementById("group-with-overflow-btn");
+	var customOBtn = document.getElementById("overflowButton");
 
 	slider.style.width = '100%';
 	avGrWrapper.style.width = slider.getAttribute("value") + '%';
@@ -300,6 +317,17 @@ <h3>Unordinary group</h3>
 		eventTargetRef.value = "";
 		eventOverflowButtonClicked.value = "";
 	});
+
+	function formatBtnText(group) {
+		var totalAvatars = 90 - group.items.length + group.hiddenItems.length;
+
+		customOBtn.innerHTML = totalAvatars > 99 ? "+99" : "+" + totalAvatars;
+		customOBtn.ariaLabel = totalAvatars > 99 ? "+99 avatars" : "+" + totalAvatars + " avatars";
+	};
+
+	groupWithBtn.addEventListener("ui5-overflow", function (event) {
+		formatBtnText(event.target);
+	});
 </script>
 
 </body>