fix(ui5-timeline): apply correct accessibility semantics (#11774)

We've now set correct tree/list roles on the Timeline based on conditions:

If a ui5-timeline has ui5-timeline-group-item – the role is set to tree so we oblige with the latest accessibility standards.
When we have a ui5-timeline with only ui5-timeline-items – the role is set to list.
Depending on the role, the correct treeitem/listitem roles are set to the items within.
Using a Screen Reader now announces the counting information natively due to correct semantics (e.g Timeline item 2 of 4).

Added region="Timeline" to the root of the Component according to spec.

Author: hinzzx

packages/fiori/cypress/specs/Timeline.cy.tsx

@@ -86,7 +86,7 @@ describe("Timeline general interaction", () => {
 		cy.mount(<Sample />);
 		cy.get("[ui5-timeline]")
 			.shadow()
-			.find("ul")
+			.find(".ui5-timeline-list")
 			.should("have.attr", "aria-label", "Timeline vertical");
 	});
 

packages/fiori/src/Timeline.ts

@@ -51,6 +51,7 @@ interface ITimelineItem extends UI5Element, ITabbable {
 	lastItem: boolean;
 	isNextItemGroup?: boolean;
 	firstItemInTimeline?: boolean;
+	effectiveRole?: string;
 }
 
 const SHORT_LINE_WIDTH = "ShortLineWidth";
@@ -306,6 +307,12 @@ class Timeline extends UI5Element {
 
 		for (let i = 0; i < this.items.length; i++) {
 			this.items[i].layout = this.layout;
+			if (this.hasGroupItems) {
+				this.items[i].effectiveRole = "treeitem";
+			} else {
+				this.items[i].effectiveRole = "listitem";
+			}
+
 			if (this.items[i + 1] && !!this.items[i + 1].icon) {
 				this.items[i].forcedLineWidth = SHORT_LINE_WIDTH;
 			} else if (this.items[i].icon && this.items[i + 1] && !this.items[i + 1].icon) {
@@ -428,6 +435,10 @@ class Timeline extends UI5Element {
 		item.focus();
 	}
 
+	get hasGroupItems() {
+		return this.items.some(item => item.isGroupItem);
+	}
+
 	get _navigableItems() {
 		const navigatableItems: Array<ITimelineItem | ToggleButton> = [];
 

packages/fiori/src/TimelineGroupItem.ts

@@ -110,6 +110,10 @@ class TimelineGroupItem extends UI5Element implements ITimelineItem {
 			return;
 		}
 
+		this.items.forEach(item => {
+			item.effectiveRole = "treeitem";
+		});
+
 		this._setGroupItemProps();
 	}
 

packages/fiori/src/TimelineGroupItemTemplate.tsx

@@ -8,7 +8,7 @@ import slimArrowup from "@ui5/webcomponents-icons/dist/slim-arrow-up.js";
 
 export default function TimelineGroupItemTemplate(this: TimelineGroupItem) {
 	return (
-		<div class="ui5-tlgi-root">
+		<div class="ui5-tlgi-root" role="treeitem">
 			<div class="ui5-tlgi-btn-root">
 				<div class="ui5-tlgi-icon-placeholder">
 					<div class="ui5-tlgi-icon-dot"></div>
@@ -23,17 +23,18 @@ export default function TimelineGroupItemTemplate(this: TimelineGroupItem) {
 					icon={getEffectiveGroupIcon.call(this, this.layout, this.collapsed)}
 					pressed={this.collapsed}
 					onClick={this.onGroupItemClick}
+					accessibleName={`${this.groupName || "Group"}, ${this.collapsed ? "collapsed" : "expanded"}`}
 				>
 					{this.groupName}
 				</ToggleButton>
 			</div>
-			<ul class="ui5-tl-group-item">
+			<div class="ui5-tl-group-item" role="group" aria-label={`${this.groupName || "Group"} items`}>
 				{this.items.map(item =>
-					<li class="ui5-timeline-group-list-item">
+					<div class="ui5-timeline-group-list-item">
 						<slot name={item._individualSlot}></slot>
-					</li>
+					</div>
 				)}
-			</ul>
+			</div>
 		</div>
 	);
 }

packages/fiori/src/TimelineItem.ts

@@ -23,6 +23,8 @@ import {
 
 import TimelineItemCss from "./generated/themes/TimelineItem.css.js";
 
+type TimelineItemRole = "listitem" | "treeitem";
+
 /**
  * @class
  *
@@ -163,6 +165,12 @@ class TimelineItem extends UI5Element implements ITimelineItem {
 	@property({ type: Boolean })
 	hidden = false;
 
+	/**
+	 * @private
+	 */
+	@property({ noAttribute: true })
+	effectiveRole: `${TimelineItemRole}` = "listitem";
+
 	/**
 	 * Defines the position of the item in a group.
 	 * @private
@@ -204,6 +212,28 @@ class TimelineItem extends UI5Element implements ITimelineItem {
 	get isGroupItem() {
 		return false;
 	}
+
+	get _getAccessibleLabel() {
+		const parts = [];
+
+		if (this.name) {
+			parts.push(this.name);
+		}
+
+		if (this.titleText) {
+			parts.push(this.titleText);
+		}
+
+		if (this.subtitleText) {
+			parts.push(this.subtitleText);
+		}
+
+		if (this.timelineItemStateText) {
+			parts.push(this.timelineItemStateText);
+		}
+
+		return parts.join(", ");
+	}
 }
 
 TimelineItem.define();

packages/fiori/src/TimelineItemTemplate.tsx

@@ -4,6 +4,9 @@ import Icon from "@ui5/webcomponents/dist/Icon.js";
 import TimelineLayout from "./types/TimelineLayout.js";
 
 export default function TimelineItemTemplate(this: TimelineItem) {
+	// Create accessible label with status information
+	const accessibleLabel = this._getAccessibleLabel;
+
 	return (
 		<div class="ui5-tli-root">
 			<div
@@ -27,7 +30,9 @@ export default function TimelineItemTemplate(this: TimelineItem) {
 				<div
 					data-sap-focus-ref
 					class="ui5-tli-bubble"
+					role={this.effectiveRole}
 					tabindex={parseInt(this.forcedTabIndex)}
+					aria-label={accessibleLabel}
 					aria-description={this.timelineItemStateText}
 				>
 					<div class="ui5-tli-title">

packages/fiori/src/TimelineTemplate.tsx

@@ -2,9 +2,15 @@ import Button from "@ui5/webcomponents/dist/Button.js";
 import type Timeline from "./Timeline.js";
 import BusyIndicator from "@ui5/webcomponents/dist/BusyIndicator.js";
 
+type TimelineListRole = "list" | "tree";
+
 export default function TimelineTemplate(this: Timeline) {
+	const listRole: `${TimelineListRole}` = this.hasGroupItems ? "tree" : "list";
+
 	return (
 		<div class="ui5-timeline-root"
+			role="region"
+			aria-label="Timeline"
 			onFocusIn={this._onfocusin}
 			onKeyDown={this._onkeydown}
 		>
@@ -16,15 +22,19 @@ export default function TimelineTemplate(this: Timeline) {
 			>
 				<div class="ui5-timeline-scroll-container">
 
-					<ul class="ui5-timeline-list" aria-live="polite" aria-label={this.ariaLabel}>
+					<div class="ui5-timeline-list"
+						role={listRole}
+						aria-live="polite"
+						aria-label={this.ariaLabel}
+					>
 						{this.items.map(item =>
-							<li class="ui5-timeline-list-item">
+							<div class="ui5-timeline-list-item">
 								<slot name={item._individualSlot}></slot>
-							</li>
+							</div>
 						)}
 						{ this.growsWithButton && moreRow.call(this) }
 						{ this.growsOnScroll && endRow.call(this) }
-					</ul>
+					</div>
 				</div>
 			</BusyIndicator>
 		</div>