feat(ui5-form): enhance a11y using description list

packages/main/cypress/specs/Form.cy.tsx

@@ -724,9 +724,9 @@ describe("Accessibility", () => {
 
 		cy.get("@form")
 			.shadow()
-			.find(".ui5-form-group")
+			.find(".ui5-form-group-layout")
 			.eq(0)
-			.as("firstGroupDOMRef");
+			.as("firstGroupDefinitionList");
 
 		cy.get("@form")
 			.shadow()
@@ -740,11 +740,11 @@ describe("Accessibility", () => {
 		cy.get("@formGroup")
 			.should("have.attr", "data-sap-ui-fastnavgroup", "true");
 
-		cy.get("@firstGroupDOMRef")
-			.should("have.attr", "role", "form");
+		cy.get("@firstGroupDefinitionList")
+			.should("not.have.attr", "role", "form");
 
 		// assert: the form group's aria-labelledby is equal to the form group title's ID
-		cy.get("@firstGroupDOMRef")
+		cy.get("@firstGroupDefinitionList")
 			.invoke("attr", "aria-labelledby")
 			.then(ariaLabelledBy => {
 				cy.get("@firstGroupTitle")
@@ -861,7 +861,7 @@ describe("Accessibility", () => {
 
 			cy.get("@form")
 				.shadow()
-				.find(".ui5-form-group")
+				.find(".ui5-form-group-layout")
 				.eq(0)
 				.should("have.attr", "aria-label", Form.i18nBundle.getText(FORM_GROUP_ACCESSIBLE_NAME, "1"));
 		});
@@ -882,7 +882,7 @@ describe("Accessibility", () => {
 
 			cy.get("@form")
 				.shadow()
-				.find(".ui5-form-group")
+				.find(".ui5-form-group-layout")
 				.eq(0)
 				.should("have.attr", "aria-label", EXPECTED_LABEL);
 		});
@@ -902,7 +902,7 @@ describe("Accessibility", () => {
 
 			cy.get("@form")
 				.shadow()
-				.find(".ui5-form-group")
+				.find(".ui5-form-group-layout")
 				.eq(0)
 				.as("group")
 				.invoke("attr", "aria-labelledby")
@@ -938,7 +938,7 @@ describe("Accessibility", () => {
 
 			cy.get("@form")
 				.shadow()
-				.find(".ui5-form-group")
+				.find(".ui5-form-group-layout")
 				.eq(0)
 				.as("group")
 				.invoke("attr", "aria-labelledby")

packages/main/src/Form.ts

@@ -3,18 +3,22 @@ import customElement from "@ui5/webcomponents-base/dist/decorators/customElement
 import property from "@ui5/webcomponents-base/dist/decorators/property.js";
 import i18n from "@ui5/webcomponents-base/dist/decorators/i18n.js";
 import { getScopedVarName } from "@ui5/webcomponents-base/dist/CustomElementsScope.js";
+import { getEffectiveAriaLabelText } from "@ui5/webcomponents-base/dist/util/AccessibilityTextsHelper.js";
 import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
+import type { AriaRole } from "@ui5/webcomponents-base";
+import type I18nBundle from "@ui5/webcomponents-base/dist/i18nBundle.js";
+
 // Template
 import FormTemplate from "./FormTemplate.js";
 
 // Styles
 import FormCss from "./generated/themes/Form.css.js";
 
 import type FormItemSpacing from "./types/FormItemSpacing.js";
+import type FormAccessibilityMode from "./types/FormAccessibilityMode.js";
 import type FormGroup from "./FormGroup.js";
 import type TitleLevel from "./types/TitleLevel.js";
-import type I18nBundle from "@ui5/webcomponents-base/dist/i18nBundle.js";
 
 import { FORM_ACCESSIBLE_NAME } from "./generated/i18n/i18n-defaults.js";
 
@@ -47,13 +51,17 @@ interface IFormItem extends UI5Element {
 	columnSpan?: number;
 	headerText?: string;
 	headerLevel?: `${TitleLevel}`;
+	accessibilityMode?: `${FormAccessibilityMode}`;
 }
 
 type GroupItemsInfo = {
 	groupItem: IFormItem,
 	items: Array<ItemsInfo>,
-	accessibleNameRef: string | undefined,
 	accessibleName: string | undefined,
+	accessibleNameInner: string | undefined,
+	accessibleNameRef: string | undefined,
+	accessibleNameRefInner: string | undefined,
+	role: AriaRole | undefined,
 }
 
 type ItemsInfo = {
@@ -222,6 +230,15 @@ class Form extends UI5Element {
 	@property()
 	accessibleName?: string;
 
+	/**
+	 * Defines id (or many ids) of the element (or elements) that label the component.
+	 * @default undefined
+	 * @public
+	 * @since 2.16.0
+	 */
+	@property()
+	accessibleNameRef?: string;
+
 	/**
 	 * Defines the number of columns to distribute the form content by breakpoint.
 	 *
@@ -294,16 +311,33 @@ class Form extends UI5Element {
 	/**
 	 * Defines the vertical spacing between form items.
 	 *
-	 * **Note:** If the Form is meant to be switched between "non-edit" and "edit" modes,
-	 * we recommend using "Large" item spacing in "non-edit" mode, and "Normal" - for "edit" mode,
-	 * to avoid "jumping" effect, caused by the hight difference between texts in "non-edit" mode and the input fields in "edit" mode.
+	 * **Note:** If the Form is meant to be switched between "display"("non-edit") and "edit" modes,
+	 * we recommend using "Large" item spacing in "display"("non-edit") mode, and "Normal" - for "edit" mode,
+	 * to avoid "jumping" effect, caused by the hight difference between texts in "display"("non-edit") mode and the input fields in "edit" mode.
 	 *
 	 * @default "Normal"
 	 * @public
 	 */
 	@property()
 	itemSpacing: `${FormItemSpacing}` = "Normal";
 
+	/**
+	 * Defines the accessibility mode of the component in "edit" and "display" use-cases.
+	 *
+	 * Based on the mode, the component renders different HTML elements and ARIA attributes,
+	 * which are appropriate for the use-case.
+	 *
+	 * **Usage:**
+	 * - Set this property to "Display", when the form consists of non-editable (e.g. texts) form items.
+	 * - Set this property to "Edit", when the form consists of editable (e.g. input fields) form items.
+	 *
+	 * @default "Display"
+	 * @since 2.16.0
+	 * @public
+	 */
+	@property()
+	accessibilityMode: `${FormAccessibilityMode}` = "Display";
+
 	/**
 	 * Defines the component header area.
 	 *
@@ -373,7 +407,7 @@ class Form extends UI5Element {
 		this.setGroupsColSpan();
 
 		// Set item spacing
-		this.setItemSpacing();
+		this.setItemsState();
 	}
 
 	onAfterRendering() {
@@ -521,9 +555,10 @@ class Form extends UI5Element {
 		return index === 0 ? MIN_COL_SPAN + (delta - groups) + 1 : MIN_COL_SPAN + 1;
 	}
 
-	setItemSpacing() {
+	setItemsState() {
 		this.items.forEach((item: IFormItem) => {
 			item.itemSpacing = this.itemSpacing;
+			item.accessibilityMode = this.accessibilityMode;
 		});
 	}
 
@@ -544,13 +579,18 @@ class Form extends UI5Element {
 	}
 
 	get effectiveAccessibleName() {
-		if (this.accessibleName) {
-			return this.accessibleName;
+		if (this.accessibleName || this.accessibleNameRef) {
+			return getEffectiveAriaLabelText(this);
 		}
+
 		return this.hasHeader ? undefined : Form.i18nBundle.getText(FORM_ACCESSIBLE_NAME);
 	}
 
 	get effectiveАccessibleNameRef(): string | undefined {
+		if (this.accessibleName || this.accessibleNameRef) {
+			return;
+		}
+
 		return this.hasHeaderText && !this.hasCustomHeader ? `${this._id}-header-text` : undefined;
 	}
 
@@ -582,11 +622,16 @@ class Form extends UI5Element {
 				}
 			});
 
+			const accessibleNameRef = (groupItem as FormGroup).effectiveAccessibleNameRef;
+
 			return {
 				groupItem,
-				accessibleName: (groupItem as FormGroup).getEffectiveAccessibleName(index),
-				accessibleNameRef: (groupItem as FormGroup).effectiveАccessibleNameRef,
+				accessibleName: this.accessibilityMode === "Edit" ? (groupItem as FormGroup).getEffectiveAccessibleName(index) : undefined,
+				accessibleNameInner: this.accessibilityMode === "Edit" ? undefined : (groupItem as FormGroup).getEffectiveAccessibleName(index),
+				accessibleNameRef: this.accessibilityMode === "Edit" ? accessibleNameRef : undefined,
+				accessibleNameRefInner: this.accessibilityMode === "Edit" ? undefined : accessibleNameRef,
 				items: this.getItemsInfo((Array.from(groupItem.children) as Array<IFormItem>)),
+				role: this.accessibilityMode === "Edit" ? "form" : undefined,
 			};
 		});
 	}

packages/main/src/FormGroup.ts

@@ -134,7 +134,7 @@ class FormGroup extends UI5Element implements IFormItem {
 		return FormGroup.i18nBundle.getText(FORM_GROUP_ACCESSIBLE_NAME, index + 1);
 	}
 
-	get effectiveАccessibleNameRef() {
+	get effectiveAccessibleNameRef() {
 		return this.headerText ? `${this._id}-group-header-text` : undefined;
 	}
 

packages/main/src/FormItem.ts

@@ -12,6 +12,7 @@ import FormItemCss from "./generated/themes/FormItem.css.js";
 
 import type { IFormItem } from "./Form.js";
 import type FormItemSpacing from "./types/FormItemSpacing.js";
+import type FormAccessibilityMode from "./types/FormAccessibilityMode.js";
 
 /**
  * @class
@@ -85,6 +86,12 @@ class FormItem extends UI5Element implements IFormItem {
 	@property()
 	itemSpacing: `${FormItemSpacing}` = "Normal"
 
+	/**
+	 * @private
+	 */
+	@property()
+	accessibilityMode: `${FormAccessibilityMode}` = "Display";
+
 	get isGroup() {
 		return false;
 	}

packages/main/src/FormItemTemplate.tsx

@@ -1,21 +1,42 @@
+import type { SlottedChild } from "@ui5/webcomponents-base/dist/UI5Element.js";
 import type FormItem from "./FormItem.js";
-import type SlottedChild from "@ui5/webcomponents-base/dist/UI5Element.js";
 
 export default function FormItemTemplate(this: FormItem) {
 	return (
 		<div class="ui5-form-item-root">
 			<div class="ui5-form-item-layout" part="layout">
-				<div class="ui5-form-item-label" part="label">
-					<slot name="labelContent"></slot>
-				</div>
-				<div class="ui5-form-item-content" part="content">
-					{this.content.map(item =>
-						<div class="ui5-form-item-content-child">
-							<slot name={(item as SlottedChild)._individualSlot}></slot>
-						</div>
-					)}
-				</div>
+				{ this.accessibilityMode === "Edit" ? content.call(this) : contentAsDefinitionList.call(this) }
 			</div>
 		</div>
 	);
 }
+
+function content(this: FormItem) {
+	return <>
+		<div class="ui5-form-item-label" part="label">
+			<slot name="labelContent"></slot>
+		</div>
+		<div class="ui5-form-item-content" part="content">
+			{this.content.map(item =>
+				<div class="ui5-form-item-content-child">
+					<slot name={(item as SlottedChild)._individualSlot}></slot>
+				</div>
+			)}
+		</div>
+	</>;
+}
+
+function contentAsDefinitionList(this: FormItem) {
+	return <>
+		<dt class="ui5-form-item-label" part="label">
+			<slot name="labelContent"></slot>
+		</dt>
+		<dd class="ui5-form-item-content" part="content">
+			{this.content.map(item =>
+				<div class="ui5-form-item-content-child">
+					<slot name={(item as SlottedChild)._individualSlot}></slot>
+				</div>
+			)}
+		</dd>
+	</>;
+}