refactor(ui5-*): use unified API to define a11y attributes via `acces…

…sibilityAttributes` (#8810)

Unifies the API to define additional a11y attributes cross components. The common approach in all relevant components to define additional a11y attributes is via property `accessibilityAttributes`.

BREAKING CHANGE: 
FlexibleLayout's `accessibilityTexts` and `accessibilityRoles` properties are removed. If you have previously used the `accessibilityTexts` or `accessibilityRoles` properties:
```js
fcl.accessibilityTexts = {
    startColumnAccessibleName: "Products list",
    midColumnAccessibleName: "Product information",
    endColumnAccessibleName: "Product detailed information",
    startArrowLeftText: "Collapse products list",
    startArrowRightText: "Expand products list",
    endArrowLeftText: "Expand product detailed information",
    endArrowRightText: "Collapse product detailed information",
    startArrowContainerAccessibleName: "Start Arrow Container",
    endArrowContainerAccessibleName: "End Arrow Container",
}

fcl.accessibilityRoles = {
    startColumnRole: "complementary",
    startArrowContainerRole: "navigation",
    midColumnRole: "main",
    endArrowContainerRole: "navigation",
    endColumnRole: "complementary".
}
```
Now use `accessibilityAttributes` instead:
```js
fcl.accessibilityAttributes = {
    startColumn: {
      role: "complementary",
      name: "Products list",
    },
    midColumn: {
      role: "main",
      name: "Product information",
    },
    endColumn: {
      role: "complementary",
      name: "Product detailed information",
    },
    startArrowLeft:  {
      name: "Collapse products list",
    },
    startArrowRight: {
      name: "Expand products list",
    },
    endArrowLeft: {
      name: "Expand product detailed information",
    },
    endArrowRight:  {
      name: "Collapse product detailed information",
    },
    startArrowContainer: {
      role: "navigation",
      name: "Start Arrow Container",
    },
    endArrowContainer: {
      role: "navigation",
      name: "End Arrow Container",
    },
};
```

ShellBar's `accessibilityTexts` and `accessibilityRoles` properties are removed. If you have previously used the `accessibilityTexts` or `accessibilityRoles` properties:
```js
shellbar.accessibilityTexts = {
    profileButtonTitle: "John Dow",
    logoTitle: "Custom logo title",
}

shellbar.accessibilityRoles = {
    logoRole: "link"
};
```
Now use `accessibilityAttributes` instead:
```js
shellbar.accessibilityAttributes = {
  profile: {
    name:  "John Dow",
  },
  logo: {
    role: "link"
    name: "Custom logo title"
  },
};
```

Related to: #8461

docs/2-advanced/07-accessibility.md

@@ -217,14 +217,14 @@ Setting the property on the custom element as:
 <script>
     const component = document.getElemetnById("component");
     component.accessibilityRoles = {
-        startColumnRole: "complimentary",
+        startColumnRole: "complementary",
     };
 </script>
 ```
 
 Results in the shadow DOM as: 
 ```html
-<div role="complimentary" ... >
+<div role="complementary" ... >
     ...
 </div>
 ```

docs/Migrating to version 2.0 guide.md

@@ -933,6 +933,75 @@ d.open = false;
 
 instead.
 
+
+
+### ui5-flexible-column-layout
+| Changed item | Old    | New                                                           | 
+|--------------|--------|---------------------------------------------------------------|
+| Property     | `accessibilityTexts` | removed |
+| Property     | `accessibilityRoles` | removed |
+
+- The `accessibilityTexts` and `accessibilityRoles` properties of the `ui5-flexible-column-layout` are removed. If you have previously used the `accessibilityTexts` or `accessibilityRoles` properties:
+```js
+fcl.accessibilityTexts = {
+    startColumnAccessibleName: "Products list",
+    midColumnAccessibleName: "Product information",
+    endColumnAccessibleName: "Product detailed information",
+    startArrowLeftText: "Collapse products list",
+    startArrowRightText: "Expand products list",
+    endArrowLeftText: "Expand product detailed information",
+    endArrowRightText: "Collapse product detailed information",
+    startArrowContainerAccessibleName: "Start Arrow Container",
+    endArrowContainerAccessibleName: "End Arrow Container",
+}
+
+fclAccRoles.accessibilityRoles = {
+    startColumnRole: "complementary",
+    startArrowContainerRole: "navigation",
+    midColumnRole: "main",
+    endArrowContainerRole: "navigation",
+    endColumnRole: "complementary".
+}
+```
+
+Now use `accessibilityAttributes` instead:
+```js
+fcl.accessibilityAttributes = {
+    startColumn: {
+      role: "complementary"
+      name: "Products list",
+    },
+    midColumn: {
+      role: "complementary"
+      name: "Product information",
+    },
+    endColumn: {
+      role: "complementary"
+      name: "Product detailed information",
+    },
+    startArrowLeft:  {
+      name: "Collapse products list",
+    },
+    startArrowRight: {
+      name: "Expand products list",
+    },
+    endArrowLeft: {
+      name: "Expand product detailed information",
+    },
+    endArrowRight:  {
+      name: "Collapse product detailed information",
+    },
+    startArrowContainer: {
+      role: "navigation"
+      name: "Start Arrow Container",
+    },
+    endArrowContainer: {
+      role: "navigation"
+      name: "End Arrow Container",
+    },
+};
+```
+
 ### ui5-illustrated-message
 
 | Changed item | Old    | New                                                           | 
@@ -949,6 +1018,38 @@ Now use `design` instead:
 <ui5-illustrated-message design="Dialog">
 ```
 
+
+### ui5-shellbar
+| Changed item | Old    | New                                                           | 
+|--------------|--------|---------------------------------------------------------------|
+| Property     | `accessibilityTexts` | removed |
+| Property     | `accessibilityRoles` | removed |
+
+- The `accessibilityTexts` and `accessibilityRoles` properties of the `ui5-shellbar` are removed. If you have previously used the `accessibilityTexts` or `accessibilityRoles` properties:
+```js
+shellbar.accessibilityTexts = {
+    profileButtonTitle: "John Dow",
+    logoTitle: "Custom logo title",
+}
+
+shellbar.accessibilityRoles = {
+		logoRole: "link"
+};
+```
+Now use `accessibilityAttributes` instead:
+```js
+shellbar.accessibilityAttributes = {
+    profile: {
+      name:  "John Dow",
+    },
+    logo: {
+      role: "link"
+      name: "Custom logo title"
+    },
+};
+```
+
+
 ### ui5-upload-collection
 
 | Changed item            | Old                                         | New                                                                  | 

packages/base/src/types.ts

@@ -1,3 +1,6 @@
+import type AriaHasPopup from "./types/AriaHasPopup.js";
+import type AriaRole from "./types/AriaRole.js";
+
 type PromiseResolve = (value: void | PromiseLike<void>) => void;
 type Timeout = ReturnType<typeof setTimeout>;
 type Interval = ReturnType<typeof setInterval>;
@@ -20,9 +23,12 @@ type PassiveEventListenerObject = EventListenerObject & { passive: boolean };
 
 type LowercaseString<T> = T extends string ? Lowercase<T> : never;
 
+type ARIARoles = LowercaseString<AriaRole>;
+type ARIAHasPopup = LowercaseString<AriaHasPopup>;
+
 type AccessibilityInfo = {
 	// The WAI-ARIA role of the component.
-	role?: LowercaseString<string>,
+	role?: ARIARoles,
 
 	// A translated text that represents the component type. Used when several components share same role,
 	// f.e. Select and ComboBox both have role="combobox".
@@ -45,8 +51,19 @@ type AccessibilityInfo = {
 	children?: Array<HTMLElement>,
 }
 
+type AccessibilityAttributes = {
+	ariaSetsize?: number,
+	ariaPosinset?: number,
+	controls?: LowercaseString<string>
+	expanded?: "true" | "false" | boolean,
+	hasPopup?: ARIAHasPopup,
+	name?: string
+	role?: ARIARoles,
+}
+
 export type {
 	AccessibilityInfo,
+	AccessibilityAttributes,
 	PromiseResolve,
 	Timeout,
 	Interval,

packages/main/src/types/HasPopup.ts → packages/base/src/types/AriaHasPopup.ts

@@ -1,8 +1,8 @@
 /**
- * Different types of HasPopup.
+ * Different types of ARIA hasPopup.
  * @public
  */
-enum HasPopup {
+enum AriaHasPopup {
 	/**
 	 * Dialog popup type.
 	 * @public
@@ -34,4 +34,4 @@ enum HasPopup {
 	Tree = "Tree",
 }
 
-export default HasPopup;
+export default AriaHasPopup;

packages/base/src/types/AriaLandmarkRole.ts

@@ -0,0 +1,89 @@
+/**
+ * Defines the ARIA accessible landmark roles.
+ */
+enum AriaLandmarkRole {
+	/**
+	 * No explicit role is applicable.
+	 *
+	 * The interpretation of this value depends on the  element which defines a property with this type.
+	 * Normally this value means that no accessible landmark should be written.
+	 *
+	 * @public
+	 */
+	None = "None",
+
+	/**
+	 * The ARIA role <code>banner</code>.
+	 *
+	 * A banner usually appears at the top of the page and typically spans the full width.
+	 *
+	 * @public
+	 */
+	Banner = "Banner",
+
+	/**
+	 * The ARIA role <code>main</code>.
+	 *
+	 * The main content of a page.
+	 *
+	 * @public
+	 */
+	Main = "Main",
+
+	/**
+	 * The ARIA role <code>region</code>.
+	 *
+	 * A section of a page, that is important enough to be included in a page summary or table of contents.
+	 *
+	 * @public
+	 */
+	Region = "Region",
+
+	/**
+	 * The ARIA role <code>navigation</code>.
+	 *
+	 * A region that contains a collection of items and objects that, as a whole, combine to create a navigation facility.
+	 *
+	 * @public
+	 */
+	Navigation = "Navigation",
+
+	/**
+	 * The ARIA role <code>search</code>.
+	 *
+	 * A region that contains a collection of items and objects that, as a whole, combine to create a search facility.
+	 *
+	 * @public
+	 */
+	Search = "Search",
+
+	/**
+	 * The ARIA role <code>complementary</code>.
+	 *
+	 * A section of the page, designed to be complementary to the main content at a similar level in the DOM hierarchy.
+	 *
+	 * @public
+	 */
+	Complementary = "Complementary",
+
+	/**
+	 * The ARIA role <code>form</code>.
+	 *
+	 * A region that contains a collection of items and objects that, as a whole, combine to create a form.
+	 *
+	 * @public
+	 */
+	Form = "Form",
+
+	/**
+	 * The ARIA role <code>contentinfo</code>.
+	 *
+	 * A region that contains information about the content on the page.
+	 *
+	 * @public
+	 */
+	ContentInfo = "ContentInfo"
+
+}
+
+export default AriaLandmarkRole;

packages/base/src/types/AriaRole.ts

@@ -0,0 +1,31 @@
+/**
+ * Types of ARIA roles.
+ * @public
+ */
+enum AriaRole {
+	/**
+	* The ARIA role "alertdialog".
+	* @public
+	*/
+	AlertDialog = "AlertDialog",
+
+	/**
+	 * The ARIA role "button".
+	 * @public
+	 */
+	Button = "Button",
+
+	/**
+	 * The ARIA role "dialog".
+	 * @public
+	 */
+	Dialog = "Dialog",
+
+	/**
+	 * The ARIA role "link".
+	 * @public
+	 */
+	Link = "Link",
+}
+
+export default AriaRole;