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

packages/main/src/Form.ts

@@ -3,6 +3,7 @@ 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";
 // Template
@@ -221,6 +222,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.
 	 *
@@ -543,13 +553,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;
 	}
 

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.itemSpacing === "Large" ? 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>
+	</>;
+}

packages/main/src/FormTemplate.tsx

@@ -1,5 +1,6 @@
 import type Form from "./Form.js";
 import Title from "./Title.js";
+import type { IFormItem } from "./Form.js";
 
 export default function FormTemplate(this: Form) {
 	return (
@@ -19,58 +20,77 @@ export default function FormTemplate(this: Form) {
 				</div>
 			}
 
-			<div class="ui5-form-layout" part="layout">
-				{
-					this.hasGroupItems ?
-						<>
-							{
-								this.groupItemsInfo.map(groupItemInfo => {
-									const groupItem = groupItemInfo.groupItem;
-									return (
-										<div class={{
-											"ui5-form-column": true,
-											[`ui5-form-column-spanL-${groupItem.colsL}`]: true,
-											[`ui5-form-column-spanXL-${groupItem.colsXl}`]: true,
-											[`ui5-form-column-spanM-${groupItem.colsM}`]: true,
-											[`ui5-form-column-spanS-${groupItem.colsS}`]: true,
-										}}
-										part="column"
-										>
-											<div class="ui5-form-group" role="form" aria-labelledby={groupItemInfo.accessibleNameRef}>
-												{groupItem.headerText &&
-												<div class="ui5-form-group-heading">
-													<Title id={`${groupItem._id}-group-header-text`} level={groupItem.headerLevel} size="H6">{groupItem.headerText}</Title>
-												</div>
-												}
+			{ this.hasGroupItems ? groupLayout.call(this) : layout.call(this) }
+		</div>
+	);
+}
 
-												<div class="ui5-form-group-layout">
-													<slot name={groupItem._individualSlot}></slot>
-												</div>
-											</div>
-										</div>
-									);
-								}
-								)}
-						</>
-						:
-						<>
-							{
-								this.itemsInfo.map(itemInfo => {
-									const item = itemInfo.item;
-									return (
-										<div class={{
-											"ui5-form-item": true,
-											[`ui5-form-item-span-${item.columnSpan}`]: item.columnSpan !== undefined,
-										}}
-										>
-											<slot name={item._individualSlot}></slot>
-										</div>
-									);
-								})
-							}
-						</>
+function groupLayout(this: Form) {
+	return <div class="ui5-form-layout" part="layout">
+		{ this.groupItemsInfo.map(groupItemInfo => {
+			const groupItem = groupItemInfo.groupItem;
+			return <div
+				class={{
+					"ui5-form-column": true,
+					[`ui5-form-column-spanL-${groupItem.colsL}`]: true,
+					[`ui5-form-column-spanXL-${groupItem.colsXl}`]: true,
+					[`ui5-form-column-spanM-${groupItem.colsM}`]: true,
+					[`ui5-form-column-spanS-${groupItem.colsS}`]: true,
+				}}
+				part="column"
+			>
+				{ this.itemSpacing === "Large" ?
+					<div class="ui5-form-group" role="form" aria-labelledby={groupItemInfo.accessibleNameRef}>
+						{ groupLayoutContent.call(this, groupItem) }
+					</div>
+					:
+					<dl class="ui5-form-group" aria-labelledby={groupItemInfo.accessibleNameRef}>
+						{ groupLayoutContent.call(this, groupItem) }
+					</dl>
 				}
+			</div>;
+		})}
+	</div>;
+}
+
+function groupLayoutContent(this: Form, groupItem: IFormItem) {
+	return <>
+		{ groupItem.headerText &&
+			<div class="ui5-form-group-heading">
+				<Title id={`${groupItem._id}-group-header-text`} level={groupItem.headerLevel} size="H6">{groupItem.headerText}</Title>
 			</div>
+		}
+
+		<div class="ui5-form-group-layout">
+			<slot name={groupItem._individualSlot}></slot>
 		</div>
+	</>;
+}
+
+function layout(this: Form) {
+	return (
+		this.itemSpacing === "Large" ?
+			<div class="ui5-form-layout" part="layout">
+				{ layoutContent.call(this) }
+			</div>
+			:
+			<dl class="ui5-form-layout" part="layout">
+				{ layoutContent.call(this) }
+			</dl>
 	);
 }
+
+function layoutContent(this: Form) {
+	return this.itemsInfo.map(itemInfo => {
+		const item = itemInfo.item;
+		return (
+			<div class={{
+				"ui5-form-item": true,
+				[`ui5-form-item-span-${item.columnSpan}`]: item.columnSpan !== undefined,
+			}}
+			>
+				<slot name={item._individualSlot}></slot>
+			</div>
+		);
+	});
+}

packages/main/src/themes/Form.css

@@ -49,3 +49,8 @@
 ::slotted([ui5-form-group]) {
 	display: contents;
 }
+
+dl {
+	padding: 0;
+	margin: 0;
+}

packages/main/src/themes/FormItem.css

@@ -95,5 +95,8 @@
 	:host {
 		order: var(--ui5-form-item-order-Xl, unset);
 	}
+}
 
+dd {
+	margin-inline-start: 0;
 }