@ui5/webcomponents 1.0.0-rc.8 → 1.0.2

package/dist/TextArea.js

@@ -2,9 +2,11 @@ import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
 import ResizeHandler from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
 import Integer from "@ui5/webcomponents-base/dist/types/Integer.js";
-import { fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getEffectiveAriaLabelText } from "@ui5/webcomponents-base/dist/util/AriaLabelHelper.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 import { getFeature } from "@ui5/webcomponents-base/dist/FeaturesRegistry.js";
 import { isIE } from "@ui5/webcomponents-base/dist/Device.js";
+import { isEscape } from "@ui5/webcomponents-base/dist/Keys.js";
 import ValueState from "@ui5/webcomponents-base/dist/types/ValueState.js";
 import Popover from "./Popover.js";
 
@@ -32,7 +34,7 @@ const metadata = {
 	managedSlots: true,
 	properties: /** @lends sap.ui.webcomponents.main.TextArea.prototype */ {
 		/**
-		 * Defines the value of the Web Component.
+		 * Defines the value of the component.
 		 *
 		 * @type {string}
 		 * @defaultvalue ""
@@ -45,7 +47,7 @@ const metadata = {
 		/**
 		 * Indicates whether the user can interact with the component or not.
 		 * <br><br>
-		 * <b>Note:</b> Disabled components cannot be focused and they are out of the tab chain.
+		 * <b>Note:</b> A disabled component is completely noninteractive.
 		 *
 		 * @type {boolean}
 		 * @defaultvalue false
@@ -56,9 +58,9 @@ const metadata = {
 		},
 
 		/**
-		 * Defines whether the <code>ui5-textarea</code> is read-only.
+		 * Defines whether the component is read-only.
 		 * <br><br>
-		 * <b>Note:</b> A read-only <code>ui5-textarea</code> is not editable,
+		 * <b>Note:</b> A read-only component is not editable,
 		 * but still provides visual feedback upon user interaction.
 		 *
 		 * @type {boolean}
@@ -70,7 +72,7 @@ const metadata = {
 		},
 
 		/**
-		 * Defines whether the <code>ui5-textarea</code> is required.
+		 * Defines whether the component is required.
 		 *
 		 * @type {boolean}
 		 * @defaultvalue false
@@ -93,7 +95,7 @@ const metadata = {
 		},
 
 		/**
-		 * Defines the value state of the <code>ui5-textarea</code>.
+		 * Defines the value state of the component.
 		 * <br><br>
 		 * Available options are:
 		 * <ul>
@@ -127,7 +129,7 @@ const metadata = {
 		 * <li>The CSS <code>height</code> property wins over the <code>rows</code> property, if both are set.</li>
 		 * </ul>
 		 *
-		 * @type {number}
+		 * @type {Integer}
 		 * @defaultvalue 0
 		 * @public
 		 */
@@ -139,7 +141,7 @@ const metadata = {
 		/**
 		 * Defines the maximum number of characters that the <code>value</code> can have.
 		 *
-		 * @type {number}
+		 * @type {Integer}
 		 * @defaultValue null
 		 * @public
 		 */
@@ -150,12 +152,12 @@ const metadata = {
 
 		/**
 		 * Determines whether the characters exceeding the maximum allowed character count are visible
-		 * in the <code>ui5-textarea</code>.
+		 * in the component.
 		 * <br><br>
 		 * If set to <code>false</code>, the user is not allowed to enter more characters than what is set in the
 		 * <code>maxlength</code> property.
 		 * If set to <code>true</code> the characters exceeding the <code>maxlength</code> value are selected on
-		 * paste and the counter below the <code>ui5-textarea</code> displays their number.
+		 * paste and the counter below the component displays their number.
 		 *
 		 * @type {boolean}
 		 * @defaultvalue false
@@ -166,7 +168,7 @@ const metadata = {
 		},
 
 		/**
-		 * Enables the <code>ui5-textarea</code> to automatically grow and shrink dynamically with its content.
+		 * Enables the component to automatically grow and shrink dynamically with its content.
 		 * <br><br>
 		 * <b>Note:</b> If set to <code>true</code>, the CSS <code>height</code> property is ignored.
 		 * @type {boolean}
@@ -178,9 +180,9 @@ const metadata = {
 		},
 
 		/**
-		 * Defines the maximum number of lines that the Web Component can grow.
+		 * Defines the maximum number of lines that the component can grow.
 		 *
-		 * @type {number}
+		 * @type {Integer}
 		 * @defaultvalue 0
 		 * @public
 		 */
@@ -190,7 +192,7 @@ const metadata = {
 		},
 
 		/**
-		 * Determines the name with which the <code>ui5-textarea</code> will be submitted in an HTML form.
+		 * Determines the name with which the component will be submitted in an HTML form.
 		 *
 		 * <br><br>
 		 * <b>Important:</b> For the <code>name</code> property to have effect, you must add the following import to your project:
@@ -198,7 +200,7 @@ const metadata = {
 		 *
 		 * <br><br>
 		 * <b>Note:</b> When set, a native <code>input</code> HTML element
-		 * will be created inside the <code>ui5-textarea</code> so that it can be submitted as
+		 * will be created inside the component so that it can be submitted as
 		 * part of an HTML form. Do not use this property unless you need to submit a form.
 		 *
 		 * @type {string}
@@ -209,6 +211,29 @@ const metadata = {
 			type: String,
 		},
 
+		/**
+		 * Sets the accessible aria name of the component.
+		 *
+		 * @type {String}
+		 * @public
+		 * @since 1.0.0-rc.15
+		 */
+		accessibleName: {
+			type: String,
+		},
+
+		/**
+		 * Receives id(or many ids) of the elements that label the textarea.
+		 *
+		 * @type {String}
+		 * @defaultvalue ""
+		 * @public
+		 * @since 1.0.0-rc.15
+		 */
+		accessibleNameRef: {
+			type: String,
+		},
+
 		/**
 		 * @private
 		 */
@@ -250,13 +275,13 @@ const metadata = {
 	slots: /** @lends sap.ui.webcomponents.main.TextArea.prototype */ {
 
 		/**
-		 * Defines the value state message that will be displayed as pop up under the <code>ui5-textarea</code>.
+		 * Defines the value state message that will be displayed as pop up under the component.
 		 *
 		 * <br><br>
 		 * <b>Note:</b> If not specified, a default text (in the respective language) will be displayed.
 		 *
 		 * <br><br>
-		 * <b>Note:</b> The <code>valueStateMessage</code> would be displayed if the <code>ui5-textarea</code> has
+		 * <b>Note:</b> The <code>valueStateMessage</code> would be displayed if the component has
 		 * <code>valueState</code> of type <code>Information</code>, <code>Warning</code> or <code>Error</code>.
 		 * @type {HTMLElement[]}
 		 * @since 1.0.0-rc.7
@@ -266,10 +291,21 @@ const metadata = {
 		valueStateMessage: {
 			type: HTMLElement,
 		},
+
+		/**
+		 * The slot is used to render native <code>input</code> HTML element within Light DOM to enable form submit,
+		 * when <code>name</code> property is set.
+		 * @type {HTMLElement[]}
+		 * @slot
+		 * @private
+		 */
+		formSupport: {
+			type: HTMLElement,
+		},
 	},
 	events: /** @lends sap.ui.webcomponents.main.TextArea.prototype */ {
 		/**
-		 * Fired when the text has changed and the focus leaves the <code>ui5-textarea</code>.
+		 * Fired when the text has changed and the focus leaves the component.
 		 *
 		 * @event
 		 * @public
@@ -277,7 +313,7 @@ const metadata = {
 		change: {},
 
 		/**
-		 * Fired when the value of the <code>ui5-textarea</code> changes at each keystroke or when
+		 * Fired when the value of the component changes at each keystroke or when
 		 * something is pasted.
 		 *
 		 * @event
@@ -293,14 +329,20 @@ const metadata = {
  *
  * <h3 class="comment-api-title">Overview</h3>
  *
- * The <code>ui5-textarea</code> component provides large spaces for text
- * entries in the form of multiple rows.
- * It has the functionality of the <code>TextField</code> with the additional
- * functionality for multiline texts.
+ * The <code>ui5-textarea</code> component is used to enter multiple lines of text.
  * <br><br>
  * When empty, it can hold a placeholder similar to a <code>ui5-input</code>.
  * You can define the rows of the <code>ui5-textarea</code> and also determine specific behavior when handling long texts.
  *
+ * <h3>CSS Shadow Parts</h3>
+ *
+ * <ui5-link target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/CSS/::part">CSS Shadow Parts</ui5-link> allow developers to style elements inside the Shadow DOM.
+ * <br>
+ * The <code>ui5-textarea</code> exposes the following CSS Shadow Parts:
+ * <ul>
+ * <li>textarea - Used to style the native textarea</li>
+ * </ul>
+ *
  * <h3>ES6 Module Import</h3>
  *
  * <code>import "@ui5/webcomponents/dist/TextArea";</code>
@@ -343,7 +385,6 @@ class TextArea extends UI5Element {
 		this._firstRendering = true;
 		this._openValueStateMsgPopover = false;
 		this._fnOnResize = this._onResize.bind(this);
-		this.i18nBundle = getI18nBundle("@ui5/webcomponents");
 	}
 
 	onEnterDOM() {
@@ -382,8 +423,16 @@ class TextArea extends UI5Element {
 		return this.getDomRef().querySelector("textarea");
 	}
 
-	_onkeydown() {
+	_onkeydown(event) {
 		this._keyDown = true;
+
+		if (isEscape(event)) {
+			const nativeTextArea = this.getInputDomRef();
+
+			this.value = this.previousValue;
+			nativeTextArea.value = this.value;
+			this.fireEvent("input");
+		}
 	}
 
 	_onkeyup() {
@@ -393,11 +442,16 @@ class TextArea extends UI5Element {
 	_onfocusin() {
 		this.focused = true;
 		this._openValueStateMsgPopover = true;
+		this.previousValue = this.getInputDomRef().value;
 	}
 
-	_onfocusout() {
+	_onfocusout(event) {
+		const focusedOutToValueStateMessage = event.relatedTarget && event.relatedTarget.shadowRoot && event.relatedTarget.shadowRoot.querySelector(".ui5-valuestatemessage-root");
 		this.focused = false;
-		this._openValueStateMsgPopover = false;
+
+		if (!focusedOutToValueStateMessage) {
+			this._openValueStateMsgPopover = false;
+		}
 	}
 
 	_onchange() {
@@ -444,7 +498,7 @@ class TextArea extends UI5Element {
 
 	async openPopover() {
 		this.popover = await this._getPopover();
-		this.popover && this.popover.openBy(this.shadowRoot.querySelector(".ui5-textarea-inner"));
+		this.popover && this.popover.showAt(this.shadowRoot.querySelector(".ui5-textarea-inner"));
 	}
 
 	async closePopover() {
@@ -454,7 +508,7 @@ class TextArea extends UI5Element {
 
 	async _getPopover() {
 		const staticAreaItem = await this.getStaticAreaItemDomRef();
-		return staticAreaItem.querySelector("ui5-popover");
+		return staticAreaItem.querySelector("[ui5-popover]");
 	}
 
 	_tokenizeText(value) {
@@ -490,9 +544,9 @@ class TextArea extends UI5Element {
 				leftCharactersCount = maxLength - this.value.length;
 
 				if (leftCharactersCount >= 0) {
-					exceededText = this.i18nBundle.getText(TEXTAREA_CHARACTERS_LEFT, [leftCharactersCount]);
+					exceededText = TextArea.i18nBundle.getText(TEXTAREA_CHARACTERS_LEFT, leftCharactersCount);
 				} else {
-					exceededText = this.i18nBundle.getText(TEXTAREA_CHARACTERS_EXCEEDED, [Math.abs(leftCharactersCount)]);
+					exceededText = TextArea.i18nBundle.getText(TEXTAREA_CHARACTERS_EXCEEDED, Math.abs(leftCharactersCount));
 				}
 			}
 		} else {
@@ -539,8 +593,34 @@ class TextArea extends UI5Element {
 		return this.disabled ? undefined : "0";
 	}
 
-	get ariaLabelledBy() {
-		return this.showExceededText ? `${this._id}-exceededText` : undefined;
+	get ariaLabelText() {
+		const effectiveAriaLabelText = getEffectiveAriaLabelText(this);
+
+		if (this.showExceededText) {
+			if (effectiveAriaLabelText) {
+				return `${effectiveAriaLabelText} ${this._exceededTextProps.exceededText}`;
+			}
+
+			return this._exceededTextProps.exceededText;
+		}
+
+		return effectiveAriaLabelText;
+	}
+
+	get ariaDescribedBy() {
+		return this.hasValueState ? `${this._id}-valueStateDesc` : undefined;
+	}
+
+	get ariaValueStateHiddenText() {
+		if (!this.hasValueState) {
+			return;
+		}
+
+		if (this.hasCustomValueState) {
+			return this.valueStateMessageText.map(el => el.textContent).join(" ");
+		}
+
+		return this.valueStateText;
 	}
 
 	get ariaInvalid() {
@@ -575,21 +655,34 @@ class TextArea extends UI5Element {
 		return this.valueStateTextMappings()[this.valueState];
 	}
 
-	valueStateTextMappings() {
-		const i18nBundle = this.i18nBundle;
+	/**
+	 * This method is relevant for sap_horizon theme only
+	 */
+	get _valueStateMessageIcon() {
+		const iconPerValueState = {
+			Error: "error",
+			Warning: "alert",
+			Success: "sys-enter-2",
+			Information: "information",
+		};
+
+		return this.valueState !== ValueState.None ? iconPerValueState[this.valueState] : "";
+	}
 
+	valueStateTextMappings() {
 		return {
-			"Information": i18nBundle.getText(VALUE_STATE_INFORMATION),
-			"Error": i18nBundle.getText(VALUE_STATE_ERROR),
-			"Warning": i18nBundle.getText(VALUE_STATE_WARNING),
+			"Information": TextArea.i18nBundle.getText(VALUE_STATE_INFORMATION),
+			"Error": TextArea.i18nBundle.getText(VALUE_STATE_ERROR),
+			"Warning": TextArea.i18nBundle.getText(VALUE_STATE_WARNING),
 		};
 	}
 
+	static get dependencies() {
+		return [Popover];
+	}
+
 	static async onDefine() {
-		await Promise.all([
-			Popover.define(),
-			fetchI18nBundle("@ui5/webcomponents"),
-		]);
+		TextArea.i18nBundle = await getI18nBundle("@ui5/webcomponents");
 	}
 }