feat(ui5-form, ui5-form-group): add headerLevel property (#11372)

- headerLevel API (similar to Panel and others) for customizing the aria-levels of Form and FormGroup headings according to the use-case with default values of 2 for the Form and 3 for the FormGroup.
- accessibleName API to allow defining a unique accessible name of the Form, especially when used without a header or when multiple forms are used (as the aria-label should be unique and even if we set built-in one, the tools would complain that the role+accessible name combination isn't unique).
- updates font-size of the FormGroup heading (from H5 to H6) to to match the latest design

Fixes: #11371

Author: ilhan007

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

@@ -777,7 +777,8 @@ describe("Accessibility", () => {
 		cy.get("@form")
 			.shadow()
 			.find(".ui5-form-root")
-			.should("have.attr", "role", "form");
+			.should("have.attr", "role", "form")
+			.and("not.have.attr", "aria-label", "Form");
 
 		cy.get("@form")
 			.should("have.attr", "data-sap-ui-fastnavgroup", "true");
@@ -793,6 +794,57 @@ describe("Accessibility", () => {
 			});
 	});
 
+	it("tests 'role' and 'aria-label' of form without header", () => {
+		cy.mount(<Form>
+			<FormItem>
+				<Label>Name:</Label>
+				<Text>Red Point Stores</Text>
+			</FormItem>
+			<FormItem>
+				<Label>Twitter:</Label>
+				<Text>@sap</Text>
+			</FormItem>
+			<FormItem>
+				<Label>Name:</Label>
+				<Text>Red Point Stores</Text>
+			</FormItem>
+		</Form>);
+
+		cy.get("[ui5-form]")
+			.as("form");
+
+		cy.get("@form")
+			.shadow()
+			.find(".ui5-form-root")
+			.should("have.attr", "role", "form")
+			.and("have.attr", "aria-label", "Form");
+	});
+
+	it("tests 'aria-label' via 'accessibleName'", () => {
+		cy.mount(<Form headerText="Form header text" accessibleName="basic form">
+			<FormItem>
+				<Label>Name:</Label>
+				<Text>Red Point Stores</Text>
+			</FormItem>
+			<FormItem>
+				<Label>Twitter:</Label>
+				<Text>@sap</Text>
+			</FormItem>
+			<FormItem>
+				<Label>Name:</Label>
+				<Text>Red Point Stores</Text>
+			</FormItem>
+		</Form>);
+
+		cy.get("[ui5-form]")
+			.as("form");
+
+		cy.get("@form")
+			.shadow()
+			.find(".ui5-form-root")
+			.should("have.attr", "aria-label", "basic form");
+	});
+
 	it("tests F6 navigation", () => {
 		cy.mount(
 			<>
@@ -937,6 +989,34 @@ ui5AccDescribe("Automated accessibility tests", () => {
 			</Form>
 		);
 
+		cy.ui5CheckA11y();
+	});
+
+	it("without header", () => {
+		cy.mount(
+			<Form>
+				<FormItem>
+					<Label slot="labelContent">Name:</Label>
+					<Text>Red Point Stores</Text>
+				</FormItem>
+				
+				<FormItem>
+					<Label slot="labelContent">ZIP Code/City:</Label>
+					<Text>411 Maintown</Text>
+				</FormItem>
+				
+				<FormItem>
+					<Label slot="labelContent">Street:</Label>
+					<Text>Main St 1618</Text>
+				</FormItem>
+
+				<FormItem>
+					<Label slot="labelContent">Country:</Label>
+					<Text>Germany</Text>
+				</FormItem>
+			</Form>
+		);
+
 		cy.ui5CheckA11y();
 	})
 });

packages/main/src/Form.ts

@@ -1,6 +1,7 @@
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
 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 slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
@@ -12,6 +13,10 @@ import FormCss from "./generated/themes/Form.css.js";
 
 import type FormItemSpacing from "./types/FormItemSpacing.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";
 
 const additionalStylesMap = new Map<string, string>();
 
@@ -41,6 +46,7 @@ interface IFormItem extends UI5Element {
 	colsS?: number;
 	columnSpan?: number;
 	headerText?: string;
+	headerLevel?: `${TitleLevel}`;
 }
 
 type GroupItemsInfo = {
@@ -206,6 +212,15 @@ type ItemsInfo = {
 	template: FormTemplate,
 })
 class Form extends UI5Element {
+	/**
+	 * Defines the accessible ARIA name of the component.
+	 * @default undefined
+	 * @public
+	 * @since 2.10.0
+	 */
+	@property()
+	accessibleName?: string;
+
 	/**
 	 * Defines the number of columns to distribute the form content by breakpoint.
 	 *
@@ -265,6 +280,16 @@ class Form extends UI5Element {
 	@property()
 	headerText?: string;
 
+	/**
+	 * Defines the compoennt heading level,
+	 * set by the `headerText`.
+	 * @default "H2"
+	 * @since 2.10.0
+	 * @public
+	*/
+	@property()
+	headerLevel: `${TitleLevel}` = "H2";
+
 	/**
 	 * Defines the vertical spacing between form items.
 	 *
@@ -302,6 +327,9 @@ class Form extends UI5Element {
 	})
 	items!: Array<IFormItem>;
 
+	@i18n("@ui5/webcomponents")
+	static i18nBundle: I18nBundle;
+
 	/**
 	 * @private
 	 */
@@ -514,6 +542,13 @@ class Form extends UI5Element {
 		return !!this.header.length;
 	}
 
+	get effectiveAccessibleName() {
+		if (this.accessibleName) {
+			return this.accessibleName;
+		}
+		return this.hasHeader ? undefined : Form.i18nBundle.getText(FORM_ACCESSIBLE_NAME);
+	}
+
 	get effectiveАccessibleNameRef(): string | undefined {
 		return this.hasHeaderText && !this.hasCustomHeader ? `${this._id}-header-text` : undefined;
 	}

packages/main/src/FormGroup.ts

@@ -6,6 +6,7 @@ import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 import type FormItem from "./FormItem.js";
 import type { IFormItem } from "./Form.js";
 import type FormItemSpacing from "./types/FormItemSpacing.js";
+import type TitleLevel from "./types/TitleLevel.js";
 
 /**
  * @class
@@ -47,6 +48,16 @@ class FormGroup extends UI5Element implements IFormItem {
 	@property()
 	headerText?: string;
 
+	/**
+	 * Defines the compoennt heading level,
+	 * set by the `headerText`.
+	 * @default "H3"
+	 * @public
+	 * @since 2.10.0
+	*/
+	@property()
+	headerLevel: `${TitleLevel}` = "H3";
+
 	/**
 	 * Defines column span of the component,
 	 * e.g how many columns the group should span to.

packages/main/src/FormTemplate.tsx

@@ -6,14 +6,15 @@ export default function FormTemplate(this: Form) {
 		<div
 			class="ui5-form-root"
 			role={this.effectiveAccessibleRole}
+			aria-label={this.effectiveAccessibleName}
 			aria-labelledby={this.effectiveАccessibleNameRef}
 		>
 			{this.hasHeader &&
 				<div class="ui5-form-header" part="header">
 					{this.hasCustomHeader ?
 						<slot name="header"></slot>
 						:
-						<Title id={`${this._id}-header-text`} level="H4">{this.headerText}</Title>
+						<Title id={`${this._id}-header-text`} level={this.headerLevel}>{this.headerText}</Title>
 					}
 				</div>
 			}
@@ -38,7 +39,7 @@ export default function FormTemplate(this: Form) {
 											<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="H6">{groupItem.headerText}</Title>
+													<Title id={`${groupItem._id}-group-header-text`} level={groupItem.headerLevel} size="H6">{groupItem.headerText}</Title>
 												</div>
 												}
 

packages/main/src/i18n/messagebundle.properties

@@ -614,6 +614,9 @@ TOOLBAR_OVERFLOW_BUTTON_ARIA_LABEL=Additional Options
 #XACT: ARIA announcement for Toolbar's popup
 TOOLBAR_POPOVER_AVAILABLE_VALUES=Available Values
 
+#XACT: ARIA announcement for the Form aria-label attribute
+FORM_ACCESSIBLE_NAME=Form
+
 #XMSG: Text used for reporting that a radio button group requires one of the radio buttons to be checked
 FORM_CHECKABLE_REQUIRED=Please tick this box if you want to proceed.