@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,653 @@
+import { h } from "@stencil/core";
+import { triggerFormSubmit, toBool, handleDisabledAttribute, hideTooltip, showTooltip } from "../../global/functions";
+import { globalMessages } from "../../global/intl";
+/**
+ * Accessible single-line text input. Supports text and number types, character limits,
+ * symbol prefixes/suffixes, and inline info/error messaging. Use instead of a native
+ * `<input>` in all Watermark UI.
+ *
+ * @category Form Inputs
+ *
+ * @keyboardInteraction
+ * - **Enter**: Submits the containing form when `is-submit` is true.
+ *
+ * @accessibility
+ * - `label` is required even when `label-position` is `"none"` — it becomes the input's aria label.
+ * - Error messages and character-limit warnings are announced via an `aria-live` region.
+ * - Info text is associated via `aria-describedby` and read when the field receives focus.
+ * - `required-field` sets `aria-required="true"` on the underlying input.
+ *
+ * @usageNotes
+ * - `wmInputValueChanged` only fires on blur and only when the value has changed — use the
+ *   native `input` event if you need every keystroke.
+ * - When using `symbol-before`, `symbol-after`, or `text-after`, the full field context is
+ *   announced to screen readers by associating those elements via `aria-describedby`.
+ * - Keep `text-after` to 55 characters or fewer.
+ *
+ * @example {html} Basic input
+ * <wm-input label="First name"></wm-input>
+ *
+ * @example {react} Basic input
+ * <WmInput label="First name" />
+ *
+ * @example {html} Required field with error
+ * <wm-input label="Email" required-field error-message="Please enter a valid email address"></wm-input>
+ *
+ * @example {react} Form with submit validation and blur error clearing
+ * // wmInputValueChanged fires on blur only when the value has changed.
+ * // event.detail.value is the current string value.
+ * // Validate required fields on submit; clear individual errors on blur once the user provides a value.
+ * const [name, setName] = useState("");
+ * const [email, setEmail] = useState("");
+ * const [errors, setErrors] = useState({ name: "", email: "" });
+ *
+ * const setError = (field, message) =>
+ *   setErrors((prev) => ({ ...prev, [field]: message }));
+ *
+ * const handleNameBlur = (e) => {
+ *   const val = e.detail.value;
+ *   setName(val);
+ *   if (val) setError("name", "");
+ * };
+ *
+ * const handleEmailBlur = (e) => {
+ *   const val = e.detail.value;
+ *   setEmail(val);
+ *   if (!val) setError("email", "");
+ *   else if (!val.includes("@")) setError("email", "Please enter a valid email address.");
+ *   else setError("email", "");
+ * };
+ *
+ * const handleSubmit = () => {
+ *   const newErrors = {
+ *     name: name ? "" : "Full name is required.",
+ *     email: !email ? "Email is required." : !email.includes("@") ? "Please enter a valid email address." : "",
+ *   };
+ *   setErrors(newErrors);
+ *   if (Object.values(newErrors).every((e) => e === "")) { handleFormSubmit(); }
+ * };
+ *
+ * <WmInput label="Full name" requiredField={true} value={name}
+ *   errorMessage={errors.name} onWmInputValueChanged={handleNameBlur} />
+ * <WmInput label="Email" requiredField={true} value={email}
+ *   errorMessage={errors.email} onWmInputValueChanged={handleEmailBlur} />
+ * <WmButton buttonType="secondary" onClick={handleCancel}>Cancel</WmButton>
+ * <WmButton buttonType="primary" onClick={handleSubmit}>Submit</WmButton>
+ *
+ * @example {html} Character limit
+ * <wm-input label="Bio" character-limit="200"></wm-input>
+ *
+ * @example {react} Character limit
+ * <WmInput label="Bio" characterLimit={200} />
+ *
+ * @example {html} Currency input with symbol
+ * <wm-input label="Amount" symbol-before="$" type="number" min={0} step={0.01}></wm-input>
+ *
+ * @example {react} Currency input with symbol
+ * <WmInput label="Amount" symbolBefore="$" type="number" min={0} step={0.01} />
+ *
+ * @example {html} Disabled input with pre-filled value
+ * <wm-input label="Username" value="jsmith" disabled></wm-input>
+ *
+ * @example {react} Disabled input with pre-filled value
+ * <WmInput label="Username" value="jsmith" disabled={true} />
+ *
+ */
+export class Input {
+    constructor() {
+        this.previousValue = "";
+        this.label = undefined;
+        this.labelPosition = "top";
+        this.value = "";
+        this.disabled = false;
+        this.info = undefined;
+        this.inputWidth = "";
+        this.placeholder = "";
+        this.requiredField = false;
+        this.errorMessage = undefined;
+        this.characterLimit = undefined;
+        this.symbolBefore = undefined;
+        this.symbolAfter = undefined;
+        this.textAfter = undefined;
+        this.type = "text";
+        this.step = 1;
+        this.min = undefined;
+        this.max = undefined;
+        this.isSubmit = false;
+        this.announcement = "";
+    }
+    getInputWidth() {
+        return this.inputWidth ? { width: this.inputWidth } : { flex: "1" };
+    }
+    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() {
+        if (!this.label) {
+            console.error("wm-input requires the label property");
+        }
+        handleDisabledAttribute(this.el, this.isDisabled);
+    }
+    componentDidLoad() {
+        this.previousValue = this.inputEl.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(this.generateCharacterLimitWarning(this.charCount, this.characterLimit));
+        }
+    }
+    handleLabelMouseEnter(ev) {
+        const labelEl = ev.target;
+        if (labelEl.scrollWidth > labelEl.clientWidth) {
+            showTooltip("right", labelEl, this.label);
+        }
+    }
+    handleKeyDown(ev) {
+        // in most browsers, onInput doesn't fire if the input's maxLength is reached
+        // to handle the case where a user continues to type after reaching the character limit, the keyDown event must be used
+        const isModifierKey = ev.ctrlKey || ev.metaKey || ev.altKey;
+        const isCharacter = /^.$/.test(ev.key) && !isModifierKey;
+        const hasReachedCharacterLimit = isCharacter && this.characterLimit && this.inputEl.value.length >= this.characterLimit;
+        if (hasReachedCharacterLimit) {
+            this.announce(this.generateCharacterLimitWarning(this.charCount, this.characterLimit));
+        }
+        if (ev.key === "Enter") {
+            this.isSubmit && triggerFormSubmit(this.el.closest("form"));
+        }
+    }
+    handleBlur() {
+        if (this.value !== this.previousValue) {
+            this.wmInputValueChanged.emit({ value: this.value });
+        }
+        this.previousValue = this.value;
+        this.inputWrapperEl.classList.remove("focus");
+    }
+    handleFocus() {
+        this.inputWrapperEl.classList.add("focus");
+    }
+    announce(message) {
+        if (this.liveRegionEl.textContent === message) {
+            message += "\u00A0";
+        }
+        this.announcement = message;
+    }
+    generateCharacterLimitWarning(charCount, charLimit) {
+        let message = globalMessages.getCharactersEntered(charCount, charLimit);
+        if (charCount >= charLimit) {
+            message += ` ${globalMessages.characterLimitReached}`;
+        }
+        return message;
+    }
+    descriptors() {
+        // the input field value is announced to provide context to symbol-before, symbol-after and text-after. If none are present, it shouldn't be announced.
+        return this.symbolBefore || this.symbolAfter || this.textAfter
+            ? `symbol-before inputfield symbol-after text-after info error`
+            : `info error`;
+    }
+    render() {
+        return (h("div", { key: 'c95455fb6668414ec09dbf301323f11fc7270e47', class: `wrapper label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}`, ref: (el) => (this.inputWrapperEl = el) }, h("div", { key: 'de0ada2ec3c43c411924417df348ebe34a477e8e', class: "label-wrapper" }, h("label", { key: '04884ea505a88026aa311a38e30cbdf049b390c3', htmlFor: "inputfield", class: "label", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label, this.characterLimit && (h("span", { key: '1eedd2faffbfcc670ad3b87298465ab16328a1d3', class: "sr-only" }, " ", globalMessages.getCharacterLimit(this.characterLimit)))), this.labelPosition !== "none" && this.requiredField && (h("div", { key: '51224587e46ef0132891dee01536d5cf07ea54f6', class: "required", "aria-hidden": "true" }, "*"))), h("div", { key: 'ed40b31ab7ab588f6165cc0af2ec52bb8d86509b', class: "inner-wrapper" }, h("div", { key: '67a06543806995e8b95db4186a4ea053d4d33b45', class: "text-after-wrapper" }, h("div", { key: '78ad09bd7849f5f7c422d36a6f01e156c9c6db5e', class: `inputfield-wrapper ${this.isDisabled ? "disabled" : ""}`, style: this.getInputWidth() }, this.symbolBefore && (h("span", { key: '19a85ba9d2d9d17d634ac78179dbd90b378b2b7b', class: "symbol", id: "symbol-before" }, this.symbolBefore)), h("input", { key: 'f8a4b6d837abf040d9ca1237297836d066cd3f71', ref: (el) => (this.inputEl = el), id: "inputfield", disabled: this.isDisabled, "aria-describedby": this.descriptors(), onInput: (ev) => this.handleInput(ev), onKeyDown: (ev) => this.handleKeyDown(ev), onBlur: () => this.handleBlur(), onFocus: () => this.handleFocus(), placeholder: this.placeholder, autocomplete: "off", "aria-required": this.requiredField ? "true" : null, maxLength: this.characterLimit || undefined, type: this.type, step: this.step, max: this.max, min: this.min, value: this.el.value }), this.symbolAfter && (h("span", { key: '105dec7aa348f910b25db38b86eec650c943ef40', class: "symbol", id: "symbol-after" }, this.symbolAfter)), this.characterLimit && typeof this.characterLimit === "number" ? (h("div", { class: "character-count" }, this.charCount, "/", this.characterLimit)) : ("")), this.textAfter && (h("span", { key: '2ea643f3a9bc736bb33200d5cf87600e14aa2f18', class: "text-after", id: "text-after" }, this.textAfter))), this.info && (h("div", { key: '07e341cfc2b91a6bcf4880158aa735fd06ea51ea', id: "info", class: "info" }, this.info)), h("div", { key: '41f5fe8184dd6d15e868a9212c61f2a70dcdb9a9', id: "error", class: "error-message" }, this.errorMessage), h("div", { key: '860193d77a6576a5aec0c133f43bffe72a853e57', class: "sr-only", "aria-live": "polite", "aria-atomic": "true", ref: (el) => (this.liveRegionEl = el) }, this.announcement))));
+    }
+    static get is() { return "wm-input"; }
+    static get encapsulation() { return "shadow"; }
+    static get delegatesFocus() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-input.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-input.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": "Visible label for the input. Required even when `label-position` is `'none'` \u2014 used as the aria label for screen readers."
+                        }, {
+                            "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": "Position of the label relative to the input. `'none'` hides the label visually but keeps it accessible."
+                        }, {
+                            "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 initial value of the input field, or its current value when reading from the component."
+                        }, {
+                            "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 input, preventing 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 input field. Read by screen readers when the field is focused."
+                        }],
+                    "text": ""
+                },
+                "attribute": "info",
+                "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 input element itself, independent of the component's overall width (which includes the label, info, and error). Useful when you want the label wider than the input."
+                        }],
+                    "text": ""
+                },
+                "attribute": "input-width",
+                "reflect": false,
+                "defaultValue": "\"\""
+            },
+            "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 input field."
+                        }],
+                    "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 and sets `aria-required=\"true\"` on the input."
+                        }, {
+                            "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 input. Set to a non-empty string to activate; clear to remove."
+                        }],
+                    "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 the user can type. Displays a live character counter and announces warnings via an `aria-live` region. Disabled when unset."
+                        }],
+                    "text": ""
+                },
+                "attribute": "character-limit",
+                "reflect": false
+            },
+            "symbolBefore": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "String displayed before the input value (e.g. `'$'` for a currency field)."
+                        }],
+                    "text": ""
+                },
+                "attribute": "symbol-before",
+                "reflect": false
+            },
+            "symbolAfter": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "String displayed after the input value (e.g. `'%'` for a percentage field)."
+                        }],
+                    "text": ""
+                },
+                "attribute": "symbol-after",
+                "reflect": false
+            },
+            "textAfter": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Text displayed after the input element (outside it). Keep to 55 characters or fewer."
+                        }],
+                    "text": ""
+                },
+                "attribute": "text-after",
+                "reflect": false
+            },
+            "type": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"number\" | \"text\"",
+                    "resolved": "\"number\" | \"text\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "The input type. Use `'number'` for numeric fields; pair with `min`, `max`, and `step`."
+                        }, {
+                            "name": "default",
+                            "text": "\"text\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "type",
+                "reflect": false,
+                "defaultValue": "\"text\""
+            },
+            "step": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "For use with `type='number'`. The interval between values when stepping."
+                        }, {
+                            "name": "default",
+                            "text": "1"
+                        }],
+                    "text": ""
+                },
+                "attribute": "step",
+                "reflect": false,
+                "defaultValue": "1"
+            },
+            "min": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "For use with `type='number'`. The minimum value reachable with the stepper."
+                        }],
+                    "text": ""
+                },
+                "attribute": "min",
+                "reflect": false
+            },
+            "max": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "For use with `type='number'`. The maximum value reachable with the stepper."
+                        }],
+                    "text": ""
+                },
+                "attribute": "max",
+                "reflect": false
+            },
+            "isSubmit": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, pressing Enter when the input is focused submits the containing form."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "is-submit",
+                "reflect": false,
+                "defaultValue": "false"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "announcement": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "wmInputValueChanged",
+                "name": "wmInputValueChanged",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires on blur when the input value has changed since the last blur. Use the\nnative `input` event if you need to react to every keystroke."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ value: string }} value \u2014 the current value of the input 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"
+            }];
+    }
+}