@ui5/webcomponents 1.0.0-rc.6 → 1.0.0

package/dist/TextArea.js

@@ -1,24 +1,40 @@
 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";
+
 import TextAreaTemplate from "./generated/templates/TextAreaTemplate.lit.js";
+import TextAreaPopoverTemplate from "./generated/templates/TextAreaPopoverTemplate.lit.js";
 
-import { TEXTAREA_CHARACTERS_LEFT, TEXTAREA_CHARACTERS_EXCEEDED } from "./generated/i18n/i18n-defaults.js";
+import {
+	VALUE_STATE_INFORMATION,
+	VALUE_STATE_ERROR,
+	VALUE_STATE_WARNING,
+	TEXTAREA_CHARACTERS_LEFT,
+	TEXTAREA_CHARACTERS_EXCEEDED,
+} from "./generated/i18n/i18n-defaults.js";
 
 // Styles
 import styles from "./generated/themes/TextArea.css.js";
+import valueStateMessageStyles from "./generated/themes/ValueStateMessage.css.js";
 
 /**
  * @public
  */
 const metadata = {
 	tag: "ui5-textarea",
+	languageAware: true,
+	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 ""
@@ -31,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
@@ -42,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}
@@ -56,7 +72,7 @@ const metadata = {
 		},
 
 		/**
-		 * Defines whether the <code>ui5-textarea</code> is required.
+		 * Defines whether the component is required.
 		 *
 		 * @type {boolean}
 		 * @defaultvalue false
@@ -78,6 +94,31 @@ const metadata = {
 			type: String,
 		},
 
+		/**
+		 * Defines the value state of the component.
+		 * <br><br>
+		 * Available options are:
+		 * <ul>
+		 * <li><code>None</code></li>
+		 * <li><code>Error</code></li>
+		 * <li><code>Warning</code></li>
+		 * <li><code>Success</code></li>
+		 * <li><code>Information</code></li>
+		 * </ul>
+		 * <br><br>
+		 * <b>Note:</b> If <code>maxlength</code> property is set,
+		 * the component turns into "Warning" state once the characters exceeds the limit.
+		 * In this case, only the "Error" state is considered and can be applied.
+		 * @type {ValueState}
+		 * @defaultvalue "None"
+		 * @since 1.0.0-rc.7
+		 * @public
+		 */
+		valueState: {
+			type: ValueState,
+			defaultValue: ValueState.None,
+		},
+
 		/**
 		 * Defines the number of visible text lines for the component.
 		 * <br><br>
@@ -88,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
 		 */
@@ -100,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
 		 */
@@ -111,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
@@ -127,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}
@@ -139,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
 		 */
@@ -151,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:
@@ -159,17 +200,40 @@ 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}
-		 * @defaultvalue: ""
+		 * @defaultvalue ""
 		 * @public
 		 */
 		name: {
 			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
 		 */
@@ -184,19 +248,64 @@ const metadata = {
 			type: Boolean,
 		},
 
+		/**
+		 * @private
+		 */
 		_mirrorText: {
 			type: Object,
 			multiple: true,
 			defaultValue: "",
 		},
+
+		/**
+		 * @private
+		 */
 		_maxHeight: {
 			type: String,
 			noAttribute: true,
 		},
+
+		/**
+		 * @private
+		 */
+		_width: {
+			type: Integer,
+		},
+	},
+	slots: /** @lends sap.ui.webcomponents.main.TextArea.prototype */ {
+
+		/**
+		 * 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 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
+		 * @slot
+		 * @public
+		 */
+		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
@@ -204,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
@@ -220,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>
@@ -256,10 +371,28 @@ class TextArea extends UI5Element {
 		return TextAreaTemplate;
 	}
 
+	static get staticAreaTemplate() {
+		return TextAreaPopoverTemplate;
+	}
+
+	static get staticAreaStyles() {
+		return valueStateMessageStyles;
+	}
+
 	constructor() {
 		super();
 
-		this.i18nBundle = getI18nBundle("@ui5/webcomponents");
+		this._firstRendering = true;
+		this._openValueStateMsgPopover = false;
+		this._fnOnResize = this._onResize.bind(this);
+	}
+
+	onEnterDOM() {
+		ResizeHandler.register(this, this._fnOnResize);
+	}
+
+	onExitDOM() {
+		ResizeHandler.deregister(this, this._fnOnResize);
 	}
 
 	onBeforeRendering() {
@@ -281,12 +414,25 @@ class TextArea extends UI5Element {
 		}
 	}
 
+	onAfterRendering() {
+		this.toggleValueStateMessage(this.openValueStateMsgPopover);
+		this._firstRendering = false;
+	}
+
 	getInputDomRef() {
 		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() {
@@ -295,10 +441,17 @@ 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;
+
+		if (!focusedOutToValueStateMessage) {
+			this._openValueStateMsgPopover = false;
+		}
 	}
 
 	_onchange() {
@@ -306,14 +459,14 @@ class TextArea extends UI5Element {
 	}
 
 	_oninput(event) {
-		const nativeTextarea = this.getInputDomRef();
+		const nativeTextArea = this.getInputDomRef();
 
 		/* skip calling change event when an textarea with a placeholder is focused on IE
 			- value of the host and the internal textarea should be different in case of actual input
 			- input is called when a key is pressed => keyup should not be called yet
 		*/
-		const skipFiring = (this.getInputDomRef().value === this.value) && isIE() && !this._keyDown && !!this.placeholder;
-		if (event.target === nativeTextarea) {
+		const skipFiring = (nativeTextArea.value === this.value) && isIE() && !this._keyDown && !!this.placeholder;
+		if (event.target === nativeTextArea) {
 			// stop the native event, as the semantic "input" would be fired.
 			event.stopImmediatePropagation();
 		}
@@ -322,15 +475,44 @@ class TextArea extends UI5Element {
 			return;
 		}
 
-		this.value = nativeTextarea.value;
+		this.value = nativeTextArea.value;
 		this.fireEvent("input", {});
 
 		// Angular two way data binding
 		this.fireEvent("value-changed");
 	}
 
+	_onResize() {
+		if (this.displayValueStateMessagePopover) {
+			this._width = this.offsetWidth;
+		}
+	}
+
+	toggleValueStateMessage(toggle) {
+		if (toggle) {
+			this.openPopover();
+		} else {
+			this.closePopover();
+		}
+	}
+
+	async openPopover() {
+		this.popover = await this._getPopover();
+		this.popover && this.popover.showAt(this.shadowRoot.querySelector(".ui5-textarea-inner"));
+	}
+
+	async closePopover() {
+		this.popover = await this._getPopover();
+		this.popover && this.popover.close();
+	}
+
+	async _getPopover() {
+		const staticAreaItem = await this.getStaticAreaItemDomRef();
+		return staticAreaItem.querySelector("[ui5-popover]");
+	}
+
 	_tokenizeText(value) {
-		const tokenizedText = value.replace(/&/gm, "&amp;").replace(/"/gm, "&quot;").replace(/"/gm, "&#39;").replace(/</gm, "&lt;")
+		const tokenizedText = value.replace(/&/gm, "&amp;").replace(/"/gm, "&quot;").replace(/'/gm, "&apos;").replace(/</gm, "&lt;")
 			.replace(/>/gm, "&gt;")
 			.split("\n");
 
@@ -362,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 {
@@ -376,6 +558,16 @@ class TextArea extends UI5Element {
 		};
 	}
 
+	get classes() {
+		return {
+			valueStateMsg: {
+				"ui5-valuestatemessage--error": this.valueState === ValueState.Error,
+				"ui5-valuestatemessage--warning": this.valueState === ValueState.Warning || this.exceeding,
+				"ui5-valuestatemessage--information": this.valueState === ValueState.Information,
+			},
+		};
+	}
+
 	get styles() {
 		const lineHeight = 1.4 * 16;
 
@@ -391,6 +583,9 @@ class TextArea extends UI5Element {
 				"height": (this.showExceededText ? "calc(100% - 26px)" : "100%"),
 				"max-height": (this._maxHeight),
 			},
+			valueStateMsgPopover: {
+				"max-width": `${this._width}px`,
+			},
 		};
 	}
 
@@ -398,16 +593,96 @@ 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() {
 		return this.valueState === "Error" ? "true" : undefined;
 	}
 
+	get openValueStateMsgPopover() {
+		return !this._firstRendering && this._openValueStateMsgPopover && this.displayValueStateMessagePopover;
+	}
+
+	get displayValueStateMessagePopover() {
+		return this.hasCustomValueState || this.hasValueState || this.exceeding;
+	}
+
+	get hasCustomValueState() {
+		return !!this.valueStateMessage.length && this.hasValueState;
+	}
+
+	get hasValueState() {
+		return this.valueState === ValueState.Error || this.valueState === ValueState.Warning || this.valueState === ValueState.Information;
+	}
+
+	get valueStateMessageText() {
+		return this.valueStateMessage.map(x => x.cloneNode(true));
+	}
+
+	get valueStateText() {
+		if (this.valueState !== ValueState.Error && this.exceeding) {
+			return this.valueStateTextMappings()[ValueState.Warning];
+		}
+
+		return this.valueStateTextMappings()[this.valueState];
+	}
+
+	/**
+	 * 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": 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 fetchI18nBundle("@ui5/webcomponents");
+		TextArea.i18nBundle = await getI18nBundle("@ui5/webcomponents");
 	}
 }