From b61807961cc04c1aac6504760a69333ebddbe4a7 Mon Sep 17 00:00:00 2001
From: Nikolay Deshev <nikolay.deshev@sap.com>
Date: Mon, 13 Oct 2025 11:26:33 +0300
Subject: [PATCH 1/2] feat(ui5-textarea): support accessible description and
 description ref

related to #12004
---
 packages/main/cypress/specs/TextArea.cy.tsx | 76 +++++++++++++++++++++
 packages/main/src/TextArea.ts               | 39 ++++++++++-
 packages/main/src/TextAreaTemplate.tsx      |  4 ++
 packages/main/test/pages/TextArea.html      | 10 +++
 4 files changed, 127 insertions(+), 2 deletions(-)

diff --git a/packages/main/cypress/specs/TextArea.cy.tsx b/packages/main/cypress/specs/TextArea.cy.tsx
index 7a3f1c3e9880..6db77dbdf060 100644
--- a/packages/main/cypress/specs/TextArea.cy.tsx
+++ b/packages/main/cypress/specs/TextArea.cy.tsx
@@ -133,6 +133,82 @@ describe("TextArea general interaction", () => {
 				.find("textarea")
 				.should("have.attr", "aria-label", attributeValue);
 		});
+
+		it("Tests accessibleDescription property", () => {
+			const descriptionValue = "This is a direct description";
+
+			cy.mount(<TextArea accessibleDescription={descriptionValue}></TextArea>);
+
+			cy.get("[ui5-textarea]")
+				.shadow()
+				.find("#accessibleDescription")
+				.should("contain.text", descriptionValue);
+
+			cy.get("[ui5-textarea]")
+				.shadow()
+				.find("textarea")
+				.should("have.attr", "aria-describedby")
+				.and("include", "accessibleDescription");
+		});
+
+		it("Tests accessibleDescriptionRef property", () => {
+			const descriptionValue = "External description text";
+
+			cy.mount(
+				<>
+					<div id="external-desc">{descriptionValue}</div>
+					<TextArea accessibleDescriptionRef="external-desc"></TextArea>
+				</>
+			);
+
+			cy.get("[ui5-textarea]")
+				.shadow()
+				.find("#accessibleDescription")
+				.should("contain.text", descriptionValue);
+
+			cy.get("[ui5-textarea]")
+				.shadow()
+				.find("textarea")
+				.should("have.attr", "aria-describedby")
+				.and("include", "accessibleDescription");
+		});
+
+		it("Tests accessibleDescriptionRef with multiple references", () => {
+			const desc1 = "First description";
+			const desc2 = "Second description";
+
+			cy.mount(
+				<>
+					<div id="desc1">{desc1}</div>
+					<div id="desc2">{desc2}</div>
+					<TextArea accessibleDescriptionRef="desc1 desc2"></TextArea>
+				</>
+			);
+
+			cy.get("[ui5-textarea]")
+				.shadow()
+				.find("#accessibleDescription")
+				.should("contain.text", desc1)
+				.and("contain.text", desc2);
+		});
+
+		it("Tests accessibleDescriptionRef takes precedence over accessibleDescription", () => {
+			const directDesc = "Direct description";
+			const refDesc = "Referenced description";
+
+			cy.mount(
+				<>
+					<div id="ref-desc">{refDesc}</div>
+					<TextArea accessibleDescription={directDesc} accessibleDescriptionRef="ref-desc"></TextArea>
+				</>
+			);
+
+			cy.get("[ui5-textarea]")
+				.shadow()
+				.find("#accessibleDescription")
+				.should("contain.text", refDesc)
+				.and("not.contain.text", directDesc);
+		});
 	});
 
 	describe("disabled and readonly textarea", () => {
diff --git a/packages/main/src/TextArea.ts b/packages/main/src/TextArea.ts
index 02b03be5d940..e6564dc6a821 100644
--- a/packages/main/src/TextArea.ts
+++ b/packages/main/src/TextArea.ts
@@ -7,7 +7,11 @@ import customElement from "@ui5/webcomponents-base/dist/decorators/customElement
 import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
 import ResizeHandler from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
 import type { ResizeObserverCallback } from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
-import { getEffectiveAriaLabelText, getAssociatedLabelForTexts } from "@ui5/webcomponents-base/dist/util/AccessibilityTextsHelper.js";
+import {
+	getEffectiveAriaLabelText,
+	getAssociatedLabelForTexts,
+	getEffectiveAriaDescriptionText,
+} from "@ui5/webcomponents-base/dist/util/AccessibilityTextsHelper.js";
 import i18n from "@ui5/webcomponents-base/dist/decorators/i18n.js";
 import type I18nBundle from "@ui5/webcomponents-base/dist/i18nBundle.js";
 import { isEscape } from "@ui5/webcomponents-base/dist/Keys.js";
@@ -273,6 +277,24 @@ class TextArea extends UI5Element implements IFormInputElement {
 	@property()
 	accessibleNameRef?: string;
 
+	/**
+	 * Defines the accessible description of the component.
+	 * @default undefined
+	 * @public
+	 * @since 2.9.0
+	 */
+	@property()
+	accessibleDescription?: string;
+
+	/**
+	 * Receives id(or many ids) of the elements that describe the textarea.
+	 * @default undefined
+	 * @public
+	 * @since 2.9.0
+	 */
+	@property()
+	accessibleDescriptionRef?: string;
+
 	/**
 	 * @private
 	 */
@@ -575,8 +597,21 @@ class TextArea extends UI5Element implements IFormInputElement {
 		return effectiveAriaLabelText;
 	}
 
+	get ariaDescriptionText() {
+		return getEffectiveAriaDescriptionText(this);
+	}
+
+	get ariaDescriptionTextId() {
+		return this.ariaDescriptionText ? "accessibleDescription" : "";
+	}
+
 	get ariaDescribedBy() {
-		return this.hasValueState ? `${this._id}-valueStateDesc` : undefined;
+		const ids = [
+			this.hasValueState ? `${this._id}-valueStateDesc` : "",
+			this.ariaDescriptionTextId,
+		].filter(Boolean).join(" ");
+
+		return ids || undefined;
 	}
 
 	get ariaValueStateHiddenText() {
diff --git a/packages/main/src/TextAreaTemplate.tsx b/packages/main/src/TextAreaTemplate.tsx
index 728a4b6c3e2a..5dbe2e2a4a3a 100644
--- a/packages/main/src/TextAreaTemplate.tsx
+++ b/packages/main/src/TextAreaTemplate.tsx
@@ -51,6 +51,10 @@ export default function TextAreaTemplate(this: TextArea) {
 				<span class="ui5-textarea-exceeded-text">{this._exceededTextProps.exceededText}</span>
 				}
 
+				{this.ariaDescriptionText &&
+				<span id="accessibleDescription" class="ui5-hidden-text">{this.ariaDescriptionText}</span>
+				}
+
 				{this.hasValueState &&
 				<span id={`${this._id}-valueStateDesc`} class="ui5-hidden-text">{this.ariaValueStateHiddenText}</span>
 				}
diff --git a/packages/main/test/pages/TextArea.html b/packages/main/test/pages/TextArea.html
index ca7b9c0f5f72..aa000d6d2b1f 100644
--- a/packages/main/test/pages/TextArea.html
+++ b/packages/main/test/pages/TextArea.html
@@ -215,6 +215,16 @@
 		<ui5-textarea id="textarea-prevent-escape" class="textarea-width" placeholder="Escape prevention test"></ui5-textarea>
 	</section>
 
+	<section class="group">
+		<ui5-title>Text Area: Accessible Description</ui5-title>
+		<div id="external-desc">This is an external description element</div>
+		<div id="another-desc">Additional description text</div>
+		<ui5-textarea id="textarea-accessible-description" class="textarea-width" accessible-description="Direct accessible description" placeholder="TextArea with direct accessible description"></ui5-textarea>
+		<ui5-textarea id="textarea-accessible-description-ref" class="textarea-width" accessible-description-ref="external-desc" placeholder="TextArea with referenced accessible description"></ui5-textarea>
+		<ui5-textarea id="textarea-accessible-description-multiple-refs" class="textarea-width" accessible-description-ref="external-desc another-desc" placeholder="TextArea with multiple referenced descriptions"></ui5-textarea>
+		<ui5-textarea id="textarea-accessible-description-both" class="textarea-width" accessible-description="Direct description" accessible-description-ref="external-desc" placeholder="TextArea with both direct and referenced descriptions"></ui5-textarea>
+	</section>
+
 	<script>
 		var changeCounter = 0;
 		var inputCounter = 0;

From f216f6172197ab55c7fff5f96e9db057cd9282ef Mon Sep 17 00:00:00 2001
From: Nikolay Deshev <nikolay.deshev@sap.com>
Date: Mon, 13 Oct 2025 11:29:43 +0300
Subject: [PATCH 2/2] feat(ui5-textarea): support accessible description and
 description ref

fix documented version
---
 packages/main/src/TextArea.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/main/src/TextArea.ts b/packages/main/src/TextArea.ts
index e6564dc6a821..1129a86b8f97 100644
--- a/packages/main/src/TextArea.ts
+++ b/packages/main/src/TextArea.ts
@@ -281,7 +281,7 @@ class TextArea extends UI5Element implements IFormInputElement {
 	 * Defines the accessible description of the component.
 	 * @default undefined
 	 * @public
-	 * @since 2.9.0
+	 * @since 2.16.0
 	 */
 	@property()
 	accessibleDescription?: string;
@@ -290,7 +290,7 @@ class TextArea extends UI5Element implements IFormInputElement {
 	 * Receives id(or many ids) of the elements that describe the textarea.
 	 * @default undefined
 	 * @public
-	 * @since 2.9.0
+	 * @since 2.16.0
 	 */
 	@property()
 	accessibleDescriptionRef?: string;