feat(ui5-segmented-button-item): introduce new component to serve as child of SegmentedButton (#3258)

Introduce new component SegmentedButtonItem (ui5-segmentedbutton-item), meant to be used within the SegmentedButton (ui5-segmented-button) as a child, in order to implement a11y compliant DOM structure and attributes. The SegmentedButtonItem replaces the ToggleButton, previously used in the SegmentedButton.

Fixes: #3191
Closes: #3191

BREAKING_CHANGE: `selectedButton` event detail of "selection-change" has been renamed to `selectedItem`
BREAKING_CHANGE: SegmentedButton no longer accepts ToggleButton, you have to use the newly created component, called SegmentedButtonItem as follows:
<ui5-segmentedbutton>
   <ui5-segmentedbutton-item pressed>One</ui5-segmentedbutton-item>
   <ui5-segmentedbutton-item>Two</ui5-segmentedbutton-item>
   <ui5-segmentedbutton-item>Three</ui5-segmentedbutton-item>
</ui5-segmentedbutton>

Author: terezamch

docs/Public Module Imports.md

@@ -59,6 +59,7 @@ For API documentation and samples, please check the [UI5 Web Components Playgrou
 | Select                   | `ui5-select`             | `import "@ui5/webcomponents/dist/Select.js";`              |
 | Select Option            | `ui5-option`             | comes with `ui5-select `                                   |
 | Segmented Button         | `ui5-segmented-button`    | `import "@ui5/webcomponents/dist/SegmentedButton.js";`     |
+| Segmented Button Item    | `ui5-segmented-button-item`| comes with `ui5-segmented-button `                         |
 | Suggestion Item          | `ui5-suggestion-item`    | comes with `InputSuggestions.js` feature - see below       |
 | Slider                   | `ui5-slider`             | `import "@ui5/webcomponents/dist/Slider.js";`              |
 | Step Input               | `ui5-step-input`         | `import "@ui5/webcomponents/dist/StepInput.js";`           |

packages/main/bundle.common.js

@@ -58,6 +58,7 @@ import Panel from "./dist/Panel.js";
 import RadioButton from "./dist/RadioButton.js";
 import ResponsivePopover from "./dist/ResponsivePopover.js";
 import SegmentedButton from "./dist/SegmentedButton.js";
+import SegmentedButtonItem from "./dist/SegmentedButtonItem.js";
 import Select from "./dist/Select.js";
 import Slider from "./dist/Slider.js";
 import StepInput from "./dist/StepInput.js";

packages/main/src/SegmentedButton.hbs

@@ -1,10 +1,17 @@
-<div
+<ul
 	@click="{{_onclick}}"
+	@keydown="{{_onkeydown}}"
+	@keyup="{{_onkeyup}}"
 	@focusin="{{_onfocusin}}"
 	class="ui5-segmented-button-root"
-	role="group"
+	role="listbox"
 	dir="{{effectiveDir}}"
-	aria-roledescription="{{ariaDescription}}"
+	aria-multiselectable="true"
+	aria-describedby="{{_id}}-invisibleText"
+	aria-roledescription={{ariaDescription}}
 >
 	<slot></slot>
-</div>
+
+	<span id="{{_id}}-invisibleText" class="ui5-hidden-text">{{ariaDescribedBy}}</span>
+
+</ul>

packages/main/src/SegmentedButton.js

@@ -5,8 +5,9 @@ import { fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18
 import ResizeHandler from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
 import { renderFinished } from "@ui5/webcomponents-base/dist/Render.js";
 import { isIE } from "@ui5/webcomponents-base/dist/Device.js";
-import { SEGMENTEDBUTTON_ARIA_DESCRIPTION } from "./generated/i18n/i18n-defaults.js";
-import ToggleButton from "./ToggleButton.js";
+import { isSpace, isEnter } from "@ui5/webcomponents-base/dist/Keys.js";
+import { SEGMENTEDBUTTON_ARIA_DESCRIPTION, SEGMENTEDBUTTON_ARIA_DESCRIBEDBY } from "./generated/i18n/i18n-defaults.js";
+import SegmentedButtonItem from "./SegmentedButtonItem.js";
 
 // Template
 import SegmentedButtonTemplate from "./generated/templates/SegmentedButtonTemplate.lit.js";
@@ -26,32 +27,32 @@ const metadata = {
 	slots: /** @lends sap.ui.webcomponents.main.SegmentedButton.prototype */ {
 
 		/**
-		 * Defines the buttons of component.
+		 * Defines the items of <code>ui5-segmented-button</code>.
 		 * <br><br>
-		 * <b>Note:</b> Multiple buttons are allowed.
+		 * <b>Note:</b> Multiple items are allowed.
 		 * <br><br>
-		 * <b>Note:</b> Use the <code>ui5-toggle-button</code> for the intended design.
+		 * <b>Note:</b> Use the <code>ui5-segmented-button-item</code> for the intended design.
 		 * @type {sap.ui.webcomponents.main.IButton[]}
-		 * @slot buttons
+		 * @slot items
 		 * @public
 		 */
 		"default": {
-			propertyName: "buttons",
+			propertyName: "items",
 			type: HTMLElement,
 		},
 	},
 	events: /** @lends sap.ui.webcomponents.main.SegmentedButton.prototype */ {
 
 		/**
-		 * Fired when the selected button changes.
+		 * Fired when the selected item changes.
 		 *
 		 * @event sap.ui.webcomponents.main.SegmentedButton#selection-change
-		 * @param {HTMLElement} selectedButton the pressed button.
+		 * @param {HTMLElement} selectedItem the pressed item.
 		 * @public
 		 */
 		"selection-change": {
 			detail: {
-				selectedButton: { type: HTMLElement },
+				selectedItem: { type: HTMLElement },
 			},
 		},
 	},
@@ -62,11 +63,11 @@ const metadata = {
  *
  * <h3 class="comment-api-title">Overview</h3>
  *
- * The <code>ui5-segmented-button</code> shows a group of buttons. When the user clicks or taps
- * one of the buttons, it stays in a pressed state. It automatically resizes the buttons
+ * The <code>ui5-segmented-button</code> shows a group of items. When the user clicks or taps
+ * one of the items, it stays in a pressed state. It automatically resizes the items
  * to fit proportionally within the component. When no width is set, the component uses the available width.
  * <br><br>
- * <b>Note:</b> There can be just one selected <code>button</code> at a time.
+ * <b>Note:</b> There can be just one selected <code>item</code> at a time.
  *
  * <h3>ES6 Module Import</h3>
  *
@@ -78,6 +79,7 @@ const metadata = {
  * @extends sap.ui.webcomponents.base.UI5Element
  * @tagname ui5-segmented-button
  * @since 1.0.0-rc.6
+ * @appenddocs SegmentedButtonItem
  * @public
  */
 class SegmentedButton extends UI5Element {
@@ -98,7 +100,7 @@ class SegmentedButton extends UI5Element {
 	}
 
 	static get dependencies() {
-		return [ToggleButton];
+		return [SegmentedButtonItem];
 	}
 
 	static async onDefine() {
@@ -109,7 +111,7 @@ class SegmentedButton extends UI5Element {
 		super();
 
 		this._itemNavigation = new ItemNavigation(this, {
-			getItemsCallback: () => this.getSlottedNodes("buttons"),
+			getItemsCallback: () => this.getSlottedNodes("items"),
 		});
 
 		this.absoluteWidthSet = false; // set to true whenever we set absolute width to the component
@@ -129,31 +131,38 @@ class SegmentedButton extends UI5Element {
 	}
 
 	onBeforeRendering() {
+		const items = this.getSlottedNodes("items");
+
+		items.forEach((item, index, arr) => {
+			item.posInSet = index + 1;
+			item.sizeOfSet = arr.length;
+		});
+
 		this.normalizeSelection();
 	}
 
 	async onAfterRendering() {
 		await this._doLayout();
 	}
 
-	prepareToMeasureButtons() {
+	prepareToMeasureItems() {
 		this.style.width = "";
-		this.buttons.forEach(button => {
-			button.style.width = "";
+		this.items.forEach(item => {
+			item.style.width = "";
 		});
 	}
 
-	async measureButtonsWidth() {
+	async measureItemsWidth() {
 		await renderFinished();
-		this.prepareToMeasureButtons();
+		this.prepareToMeasureItems();
 
-		this.widths = this.buttons.map(button => {
+		this.widths = this.items.map(item => {
 			// +1 is added because for width 100.44px the offsetWidth property returns 100px and not 101px
-			let width = button.offsetWidth + 1;
+			let width = item.offsetWidth + 1;
 
 			if (isIE()) {
-				// in IE we are adding 1 one px beacause the width of the border on a button in the middle is not calculated and if the
-				// longest button is in the middle, it truncates
+				// in IE we are adding 1 one px beacause the width of the border on an item in the middle is not calculated and if the
+				// longest item is in the middle, it truncates
 				width += 1;
 			}
 
@@ -162,37 +171,55 @@ class SegmentedButton extends UI5Element {
 	}
 
 	normalizeSelection() {
-		this._selectedButton = this.buttons.filter(button => button.pressed).pop();
+		this._selectedItem = this.items.filter(item => item.pressed).pop();
 
-		if (this._selectedButton) {
-			this.buttons.forEach(button => {
-				button.pressed = false;
+		if (this._selectedItem) {
+			this.items.forEach(item => {
+				item.pressed = false;
 			});
-			this._selectedButton.pressed = true;
+			this._selectedItem.pressed = true;
 		}
 	}
 
-	_onclick(event) {
+	_selectItem(event) {
 		if (event.target.disabled || event.target === this.getDomRef()) {
 			return;
 		}
 
-		if (event.target !== this._selectedButton) {
-			if (this._selectedButton) {
-				this._selectedButton.pressed = false;
+		if (event.target !== this._selectedItem) {
+			if (this._selectedItem) {
+				this._selectedItem.pressed = false;
 			}
-			this._selectedButton = event.target;
+			this._selectedItem = event.target;
 			this.fireEvent("selection-change", {
-				selectedButton: this._selectedButton,
+				selectedItem: this._selectedItem,
 			});
 		}
 
-		this._selectedButton.pressed = true;
-		this._itemNavigation.setCurrentItem(this._selectedButton);
+		this._selectedItem.pressed = true;
+		this._itemNavigation.setCurrentItem(this._selectedItem);
 
 		return this;
 	}
 
+	_onclick(event) {
+		this._selectItem(event);
+	}
+
+	_onkeydown(event) {
+		if (isEnter(event)) {
+			this._selectItem(event);
+		} else if (isSpace(event)) {
+			event.preventDefault();
+		}
+	}
+
+	_onkeyup(event) {
+		if (isSpace(event)) {
+			this._selectItem(event);
+		}
+	}
+
 	_onfocusin(event) {
 		// If the component was previously focused,
 		// update the ItemNavigation to sync butons` tabindex values
@@ -203,28 +230,28 @@ class SegmentedButton extends UI5Element {
 
 		// If the component is focused for the first time
 		// focus the selected item if such present
-		if (this.selectedButton) {
-			this.selectedButton.focus();
-			this._itemNavigation.setCurrentItem(this._selectedButton);
+		if (this.selectedItem) {
+			this.selectedItem.focus();
+			this._itemNavigation.setCurrentItem(this._selectedItem);
 			this.hasPreviouslyFocusedItem = true;
 		}
 	}
 
 	async _doLayout() {
-		const buttonsHaveWidth = this.widths && this.widths.some(button => button.offsetWidth > 2); // 2 are the pixel's added for rounding & IE
-		if (!buttonsHaveWidth) {
-			await this.measureButtonsWidth();
+		const itemsHaveWidth = this.widths && this.widths.some(item => item.offsetWidth > 2); // 2 are the pixel's added for rounding & IE
+		if (!itemsHaveWidth) {
+			await this.measureItemsWidth();
 		}
 
 		const parentWidth = this.parentNode.offsetWidth;
 
 		if (!this.style.width || this.percentageWidthSet) {
-			this.style.width = `${Math.max(...this.widths) * this.buttons.length}px`;
+			this.style.width = `${Math.max(...this.widths) * this.items.length}px`;
 			this.absoluteWidthSet = true;
 		}
 
-		this.buttons.forEach(button => {
-			button.style.width = "100%";
+		this.items.forEach(item => {
+			item.style.width = "100%";
 		});
 
 		if (parentWidth <= this.offsetWidth && this.absoluteWidthSet) {
@@ -234,14 +261,18 @@ class SegmentedButton extends UI5Element {
 	}
 
 	/**
-	 * Currently selected button.
+	 * Currently selected item.
 	 *
 	 * @readonly
-	 * @type { ui5-toggle-button }
+	 * @type { ui5-segmented-button-item }
 	 * @public
 	 */
-	get selectedButton() {
-		return this._selectedButton;
+	get selectedItem() {
+		return this._selectedItem;
+	}
+
+	get ariaDescribedBy() {
+		return this.i18nBundle.getText(SEGMENTEDBUTTON_ARIA_DESCRIBEDBY);
 	}
 
 	get ariaDescription() {

packages/main/src/SegmentedButtonItem.hbs

@@ -0,0 +1,42 @@
+<li
+		role="option"
+		aria-roledescription="{{ariaDescription}}"
+		aria-posinset="{{posInSet}}"
+		aria-setsize="{{sizeOfSet}}"
+		aria-selected="{{pressed}}"
+		class="ui5-button-root"
+		aria-disabled="{{disabled}}"
+		data-sap-focus-ref
+	{{> ariaPressed}}
+		dir="{{effectiveDir}}"
+		@focusout={{_onfocusout}}
+		@focusin={{_onfocusin}}
+		@click={{_onclick}}
+		@mousedown={{_onmousedown}}
+		@mouseup={{_onmouseup}}
+		@keydown={{_onkeydown}}
+		@keyup={{_onkeyup}}
+		@touchstart="{{_ontouchstart}}"
+		@touchend="{{_ontouchend}}"
+		tabindex={{tabIndexValue}}
+		aria-label="{{ariaLabelText}}"
+		title="{{accInfo.title}}"
+>
+	{{#if icon}}
+		<ui5-icon
+			class="ui5-button-icon"
+			name="{{icon}}"
+			part="icon"
+			?show-tooltip={{showIconTooltip}}
+		></ui5-icon>
+	{{/if}}
+
+	<span id="{{_id}}-content" class="ui5-button-text">
+		<bdi>
+			<slot></slot>
+		</bdi>
+	</span>
+
+</li>
+
+{{#*inline "ariaPressed"}}{{/inline}}