@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/collection/components/wm-textarea/wm-textarea.js

@@ -0,0 +1,423 @@
+import { h } from "@stencil/core";
+import { handleDisabledAttribute, toBool, showTooltip, hideTooltip } from "../../global/functions";
+import { globalMessages } from "../../global/intl";
+/**
+ * Multi-line plain-text editing control with a drag handle for vertical resizing. Shares
+ * most functionality with wm-input. Use instead of native `<textarea>` in all Watermark UI.
+ *
+ * @category Form Inputs
+ *
+ * @accessibility
+ * - `label` sets the accessible label for the textarea; required even when
+ *   `label-position="none"`.
+ * - When `character-limit` is set, a counter below the field turns red when exceeded; the
+ *   count is announced via `aria-live` when within 5 characters of the limit or exceeded.
+ * - Error messages are announced via an `aria-live` region.
+ * - `info` text is associated via `aria-describedby` and read by screen readers on focus.
+ *
+ * @usageNotes
+ * - In HTML, set the initial value via text content: `<wm-textarea>initial value</wm-textarea>`.
+ *   In React, use the `value` prop for controlled usage.
+ * - `wmTextareaValueChanged` fires on blur only when the value has changed; use the native
+ *   `input` event for per-keystroke updates.
+ * - `event.detail.value` is the current string value.
+ *
+ * @example {html} Basic textarea
+ * <wm-textarea label="Notes" placeholder="Enter notes here..."></wm-textarea>
+ *
+ * @example {react} Basic textarea
+ * // value + onWmTextareaValueChanged is the standard controlled pattern.
+ * const [notes, setNotes] = useState("");
+ *
+ * <WmTextarea
+ *   label="Notes"
+ *   placeholder="Enter notes here..."
+ *   value={notes}
+ *   onWmTextareaValueChanged={(e) => setNotes(e.detail.value)} />
+ *
+ * @example {html} With character limit
+ * <wm-textarea label="Summary" character-limit="500"></wm-textarea>
+ *
+ * @example {react} With character limit
+ * <WmTextarea label="Summary" characterLimit={500} />
+ *
+ */
+export class Textarea {
+    constructor() {
+        this.previousValue = "";
+        this.label = undefined;
+        this.labelPosition = "top";
+        this.value = "";
+        this.disabled = false;
+        this.info = undefined;
+        this.placeholder = "";
+        this.requiredField = false;
+        this.errorMessage = undefined;
+        this.characterLimit = undefined;
+        this.inputWidth = "";
+        this.inputHeight = "";
+        this.announcement = "";
+    }
+    get charCount() {
+        return this.value.length;
+    }
+    get isDisabled() {
+        // string "false" needs to be treated as bool False because react wrappers convert bool to string.
+        return toBool(this.disabled);
+    }
+    componentWillLoad() {
+        this.el.focus = () => {
+            this.el.shadowRoot.querySelector("textarea").focus();
+        };
+        if (!this.label) {
+            console.error("wm-textarea requires the label property");
+        }
+        if (this.el.textContent) {
+            this.value = this.el.textContent;
+        }
+        handleDisabledAttribute(this.el, this.isDisabled);
+        this.previousValue = this.value;
+    }
+    handleDisabledChange() {
+        handleDisabledAttribute(this.el, this.isDisabled);
+    }
+    announceError() {
+        if (this.errorMessage) {
+            setTimeout(() => this.announce(this.errorMessage), 100);
+        }
+    }
+    handleInput(ev) {
+        // keep component's value in sync with input's value
+        this.value = ev.target.value;
+        if (this.characterLimit && this.charCount >= this.characterLimit - 5) {
+            this.announce(globalMessages.getCharactersEntered(this.charCount, this.characterLimit));
+        }
+    }
+    handleBlur() {
+        if (this.value !== this.previousValue) {
+            this.wmTextareaValueChanged.emit({ value: this.value });
+        }
+        this.previousValue = this.value;
+    }
+    handleLabelMouseEnter(ev) {
+        const labelEl = ev.target;
+        if (labelEl.scrollWidth > labelEl.clientWidth) {
+            showTooltip("right", ev.target, this.label);
+        }
+    }
+    announce(message) {
+        if (this.liveRegionEl.textContent === message) {
+            message += "\u00A0";
+        }
+        this.announcement = message;
+    }
+    render() {
+        return (h("div", { key: 'dcedd229ad3e262c92cc369d5f0a597f0d67f529', class: `wrapper label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: 'f2b0db3d98b06af6330366071d097eda6438a331', class: "label-wrapper" }, h("label", { key: '6307eb9dc125d860a3059fedf4f6a404fcb0ae22', htmlFor: "inputfield", class: "label", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label, this.characterLimit && (h("span", { key: 'b32122dda37e3adab27b8333e6c2d2ff5207004a', class: "sr-only" }, " ", globalMessages.getCharacterLimit(this.characterLimit)))), this.labelPosition !== "none" && this.requiredField && (h("span", { key: '864be330760cd3d6396462fc8e191b731a4906ee', class: "required", "aria-hidden": "true" }, "*"))), h("div", { key: 'cb04bd7ee99a025ede0781d8011467373f2517c5', class: "inner-wrapper" }, h("div", { key: 'eca53f48452099cecf60a3f853f6a021d6d1277e', class: `inputfield-wrapper ${this.errorMessage ? "invalid" : ""}`, style: this.inputWidth ? { width: this.inputWidth } : {} }, h("textarea", { key: 'd855cdf9c8a55c46404c322b329efbe0344059b1', id: "inputfield", disabled: this.isDisabled, "aria-describedby": "info error", onInput: (ev) => this.handleInput(ev), onBlur: () => this.handleBlur(), placeholder: this.placeholder, autocomplete: "off", "aria-required": this.requiredField ? "true" : null, value: this.value, rows: 3, style: { height: this.inputHeight } }), this.characterLimit && typeof this.characterLimit === "number" ? (h("div", { class: `character-count ${this.value.length > this.characterLimit ? "exceeded" : ""}` }, this.charCount, "/", this.characterLimit)) : ("")), this.info && (h("div", { key: '549bd207bd19b5b0de6e0d4bf5d208249e1833f7', id: "info", class: "info" }, this.info)), h("div", { key: '0bd0a4f5b22e1775c5aad031b9433db7cd77c13e', id: "error", class: "error-message" }, this.errorMessage), h("div", { key: 'f7b51879d3d30fbe33e43d2a7f84db0a9d1385b4', id: "live-polite", class: "sr-only", "aria-live": "polite", "aria-atomic": "true", ref: (el) => (this.liveRegionEl = el) }, this.announcement))));
+    }
+    static get is() { return "wm-textarea"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-textarea.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-textarea.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible label for the textarea. Required even when\n`label-position=\"none\"`."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "label",
+                "reflect": false
+            },
+            "labelPosition": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"top\" | \"left\" | \"none\"",
+                    "resolved": "\"left\" | \"none\" | \"top\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Controls label placement. `'none'` hides the label visually but keeps it\naccessible."
+                        }, {
+                            "name": "default",
+                            "text": "\"top\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "label-position",
+                "reflect": false,
+                "defaultValue": "\"top\""
+            },
+            "value": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "The current value typed by the user. Line breaks are represented as `\\n`.\nTo set an initial value, use the element's text content instead:\n`<wm-textarea>initial value</wm-textarea>`."
+                        }, {
+                            "name": "default",
+                            "text": "\"\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "value",
+                "reflect": false,
+                "defaultValue": "\"\""
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the component, preventing all interaction."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "disabled",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "info": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Hint text displayed below the textarea. Read by screen readers on focus via\n`aria-describedby`."
+                        }],
+                    "text": ""
+                },
+                "attribute": "info",
+                "reflect": false
+            },
+            "placeholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Placeholder text shown inside the empty textarea."
+                        }, {
+                            "name": "default",
+                            "text": "\"\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "placeholder",
+                "reflect": false,
+                "defaultValue": "\"\""
+            },
+            "requiredField": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Displays a required-field asterisk next to the label."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "required-field",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "errorMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Puts the component in an error state and displays this message below the\ntextarea."
+                        }],
+                    "text": ""
+                },
+                "attribute": "error-message",
+                "reflect": false
+            },
+            "characterLimit": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Maximum number of characters allowed. Displays a live counter below the\nfield. Does not prevent typing beyond the limit (to allow pasting and editing) but the\ncounter turns red when exceeded. Disabled when unset."
+                        }],
+                    "text": ""
+                },
+                "attribute": "character-limit",
+                "reflect": false
+            },
+            "inputWidth": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "CSS width value for the textarea element itself, independent of the overall\ncomponent width. Useful when the label or error message should extend wider than the\nfield."
+                        }, {
+                            "name": "default",
+                            "text": "\"\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "input-width",
+                "reflect": false,
+                "defaultValue": "\"\""
+            },
+            "inputHeight": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "CSS height value for the initial height of the textarea. The user can resize\nit with the drag handle."
+                        }, {
+                            "name": "default",
+                            "text": "\"\" (approximately 3 lines)"
+                        }],
+                    "text": ""
+                },
+                "attribute": "input-height",
+                "reflect": false,
+                "defaultValue": "\"\""
+            }
+        };
+    }
+    static get states() {
+        return {
+            "announcement": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "wmTextareaValueChanged",
+                "name": "wmTextareaValueChanged",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires on blur when the value has changed since load or the last blur. Use\nthe native `input` event for per-keystroke updates."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ value: string }} value \u2014 the current textarea value at the time of blur."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "{ value: string }",
+                    "resolved": "{ value: string; }",
+                    "references": {}
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "disabled",
+                "methodName": "handleDisabledChange"
+            }, {
+                "propName": "errorMessage",
+                "methodName": "announceError"
+            }];
+    }
+}