From 5887d29bbe26ddc73c5a6eb3be14985126e9490f Mon Sep 17 00:00:00 2001
From: Nikolay Hristov <n.hristov@sap.com>
Date: Mon, 6 Jan 2025 17:01:09 +0200
Subject: [PATCH] feat(ui5-dynamic-side-content): add customizable aria labels
 (#10416)

Until now the **Dynamic Side Content** component (`<ui5-dynamic-side-content>`) had `role` with value **complementary** and fixed translatable `aria-label` only for its **Side Content** area.

With this PR is intruduced new property `accessibilityAttributes` that can be used for setting of custom `aria-label` texts for both **Main Content** and **Side Content** areas. Also, a `role` attribute with value **main** and a fixed translatable label is provided for the **Main Content** as a fallback if there is no custom label defined.

There are tests added for the new feature.

Fixes: #8612
---
 .../cypress/specs/DynamicSideContent.cy.ts    | 83 +++++++++++++++++++
 packages/fiori/src/DynamicSideContent.ts      | 35 +++++++-
 .../fiori/src/DynamicSideContentTemplate.tsx  |  4 +-
 .../fiori/src/i18n/messagebundle.properties   |  3 +
 .../fiori/test/pages/DynamicSideContent.html  |  9 ++
 .../test/specs/DynamicSideContent.spec.js     | 10 ---
 6 files changed, 131 insertions(+), 13 deletions(-)
 create mode 100644 packages/fiori/cypress/specs/DynamicSideContent.cy.ts

diff --git a/packages/fiori/cypress/specs/DynamicSideContent.cy.ts b/packages/fiori/cypress/specs/DynamicSideContent.cy.ts
new file mode 100644
index 000000000000..577f232490dc
--- /dev/null
+++ b/packages/fiori/cypress/specs/DynamicSideContent.cy.ts
@@ -0,0 +1,83 @@
+import { html } from "lit";
+import "../../src/DynamicSideContent.js";
+import type DynamicSideContent from "../../src/DynamicSideContent.js";
+
+describe("Accessibility", () => {
+	it("tests main and side content roles", () => {
+		cy.mount(html`
+			<ui5-dynamic-side-content>
+				<div>
+					<h1>Main Content</h1>
+				</div>
+				<div slot="sideContent">
+					<h1>Side Content</h1>
+				</div>
+			</ui5-dynamic-side-content>
+		`);
+
+		cy.get("[ui5-dynamic-side-content]")
+			.as("dsc");
+
+		cy.get("@dsc")
+			.shadow()
+			.find(".ui5-dsc-main")
+			.should("have.attr", "role", "main");
+
+		   cy.get("@dsc")
+			.shadow()
+			.find(".ui5-dsc-side")
+			.should("have.attr", "role", "complementary");
+	});
+
+	it("tests main and side content aria-label values", () => {
+		const customMainContentLabel = "Custom Main Content Label";
+		const customSideContentLabel = "Custom Side Content Label";
+
+		cy.mount(html`
+			<ui5-dynamic-side-content>
+				<div>
+					<h1>Main Content</h1>
+					<ui5-button>Set Custom ARIA Labels</ui5-button>
+				</div>
+				<div slot="sideContent">
+					<h1>Side Content</h1>
+				</div>
+			</ui5-dynamic-side-content>
+		`);
+
+		cy.get("[ui5-dynamic-side-content]")
+			.as("dsc");
+
+		cy.get("@dsc")
+			.shadow()
+			.find(".ui5-dsc-main")
+			.should("have.attr", "aria-label", "Main Content");
+
+		cy.get("@dsc")
+			.shadow()
+			.find(".ui5-dsc-side")
+			.should("have.attr", "aria-label", "Side Content");
+
+		cy.get<DynamicSideContent>("@dsc")
+			.then($dsc => {
+				$dsc.get(0).accessibilityAttributes = {
+					"mainContent": {
+						"ariaLabel": customMainContentLabel,
+					},
+					"sideContent": {
+						"ariaLabel": customSideContentLabel,
+					},
+				};
+			});
+
+		cy.get("@dsc")
+			.shadow()
+			.find(".ui5-dsc-main")
+			.should("have.attr", "aria-label", customMainContentLabel);
+
+		cy.get("@dsc")
+			.shadow()
+			.find(".ui5-dsc-side")
+			.should("have.attr", "aria-label", customSideContentLabel);
+	});
+});
diff --git a/packages/fiori/src/DynamicSideContent.ts b/packages/fiori/src/DynamicSideContent.ts
index ff5e5f471c4c..a0121a178d5e 100644
--- a/packages/fiori/src/DynamicSideContent.ts
+++ b/packages/fiori/src/DynamicSideContent.ts
@@ -12,12 +12,16 @@ import SideContentPosition from "./types/SideContentPosition.js";
 import SideContentVisibility from "./types/SideContentVisibility.js";
 import SideContentFallDown from "./types/SideContentFallDown.js";
 import DynamicSideContentTemplate from "./DynamicSideContentTemplate.js";
+import type {
+	AccessibilityAttributes,
+} from "@ui5/webcomponents-base";
 
 // Styles
 import DynamicSideContentCss from "./generated/themes/DynamicSideContent.css.js";
 
 // Texts
 import {
+	DSC_MAIN_ARIA_LABEL,
 	DSC_SIDE_ARIA_LABEL,
 } from "./generated/i18n/i18n-defaults.js";
 
@@ -34,6 +38,12 @@ type DynamicSideContentLayoutChangeEventDetail = {
 	sideContentVisible: boolean,
 }
 
+type DynamicSideContentAriaAccessibilityAttributes = Pick<AccessibilityAttributes, "ariaLabel">;
+type DynamicSideContentAccessibilityAttributes = {
+	mainContent?: DynamicSideContentAriaAccessibilityAttributes,
+	sideContent?: DynamicSideContentAriaAccessibilityAttributes,
+}
+
 /**
  * @class
  *
@@ -186,6 +196,21 @@ class DynamicSideContent extends UI5Element {
 	@property({ type: Boolean })
 	equalSplit = false;
 
+	/**
+	* Defines additional accessibility attributes on different areas of the component.
+	*
+	* The accessibilityAttributes object has the following fields:
+	*
+	*  - **mainContent**: `mainContent.ariaLabel` defines the aria-label of the main content area. Accepts any string.
+	*  - **sideContent**: `sideContent.ariaLabel` defines the aria-label of the side content area. Accepts any string.
+	*
+	* @default {}
+	* @public
+	* @since 2.6.0
+	*/
+	@property({ type: Object })
+	accessibilityAttributes: DynamicSideContentAccessibilityAttributes = {};
+
 	/**
 	 * @private
 	 */
@@ -285,9 +310,14 @@ class DynamicSideContent extends UI5Element {
 		};
 	}
 
-	get accInfo() {
+	get accInfo(): DynamicSideContentAccessibilityAttributes {
 		return {
-			"label": DynamicSideContent.i18nBundle.getText(DSC_SIDE_ARIA_LABEL),
+			mainContent: {
+				ariaLabel: this.accessibilityAttributes.mainContent?.ariaLabel || DynamicSideContent.i18nBundle.getText(DSC_MAIN_ARIA_LABEL),
+			},
+			sideContent: {
+				ariaLabel: this.accessibilityAttributes.sideContent?.ariaLabel || DynamicSideContent.i18nBundle.getText(DSC_SIDE_ARIA_LABEL),
+			},
 		};
 	}
 
@@ -462,4 +492,5 @@ DynamicSideContent.define();
 export default DynamicSideContent;
 export type {
 	DynamicSideContentLayoutChangeEventDetail,
+	DynamicSideContentAccessibilityAttributes,
 };
diff --git a/packages/fiori/src/DynamicSideContentTemplate.tsx b/packages/fiori/src/DynamicSideContentTemplate.tsx
index 4647bff3180f..538f593c9bbd 100644
--- a/packages/fiori/src/DynamicSideContentTemplate.tsx
+++ b/packages/fiori/src/DynamicSideContentTemplate.tsx
@@ -24,6 +24,8 @@ export default function DynamicSideContentTemplate(this: DynamicSideContent) {
 function mainContent(this: DynamicSideContent) {
 	return (
 		<div
+			role="main"
+			aria-label={this.accInfo.mainContent?.ariaLabel}
 			class={this.classes.main}
 			style={this.styles.main}
 		>
@@ -36,7 +38,7 @@ function sideContent(this: DynamicSideContent) {
 	return (
 		<aside
 			role="complementary"
-			aria-label={this.accInfo.label}
+			aria-label={this.accInfo.sideContent?.ariaLabel}
 			class={this.classes.side}
 			style={this.styles.side}
 		>
diff --git a/packages/fiori/src/i18n/messagebundle.properties b/packages/fiori/src/i18n/messagebundle.properties
index ca7675c8c770..20260ecedb81 100644
--- a/packages/fiori/src/i18n/messagebundle.properties
+++ b/packages/fiori/src/i18n/messagebundle.properties
@@ -407,6 +407,9 @@ IM_TITLE_SURVEY=Your Opinion Matters
 #XTIT: IllustratedMessage's subtitle for the Survey illustration
 IM_SUBTITLE_SURVEY=We want to hear what you think about SAP software. Share your feedback with us by taking our short survey.
 
+#XACT: ARIA announcement for DynamicSideContent main content label
+DSC_MAIN_ARIA_LABEL=Main Content
+
 #XACT: ARIA announcement for DynamicSideContent side content label
 DSC_SIDE_ARIA_LABEL=Side Content
 
diff --git a/packages/fiori/test/pages/DynamicSideContent.html b/packages/fiori/test/pages/DynamicSideContent.html
index c463dbaf68ce..2574aa591529 100644
--- a/packages/fiori/test/pages/DynamicSideContent.html
+++ b/packages/fiori/test/pages/DynamicSideContent.html
@@ -126,6 +126,15 @@ <h1>Side Content</h1>
 			mainVisible.value = event.detail.mainContentVisible ? "1" : "0"
 			sideVisible.value = event.detail.sideContentVisible ? "1" : "0"
 		});
+
+		dynamicSideContent.accessibilityAttributes = {
+			mainContent: {
+				ariaLabel: "Main Content Area",
+			},
+			sideContent: {
+				ariaLabel: "Side Content Area",
+			}
+		};
 	</script>
 
 </body>
diff --git a/packages/fiori/test/specs/DynamicSideContent.spec.js b/packages/fiori/test/specs/DynamicSideContent.spec.js
index b44d9c78a019..fdf875b5e6af 100644
--- a/packages/fiori/test/specs/DynamicSideContent.spec.js
+++ b/packages/fiori/test/specs/DynamicSideContent.spec.js
@@ -462,14 +462,4 @@ describe("'layout-change' event: ", () => {
 		assert.strictEqual(await mainVisible.getValue(), "1", "The event returns correct main content visibility");
 		assert.strictEqual(await sideVisible.getValue(), "1", "The event returns correct side content visibility");
 	});
-});
-
-describe("ARIA attributes: ", () => {
-	it("exist", async () => {
-		await browser.url(`test/pages/DynamicSideContent.html`);
-		const dynamicSideContent = await browser.$("ui5-dynamic-side-content");
-
-		assert.strictEqual(await dynamicSideContent.shadow$(".ui5-dsc-side").getAttribute("aria-label"), "Side Content", "'aria-label' attribute is set correctly");
-		assert.strictEqual(await dynamicSideContent.shadow$(".ui5-dsc-side").getAttribute("role"), "complementary", "'role' attribute is set correctly");
-	});
 });
\ No newline at end of file