wabtec-internal-volt-basic-components 1.2.0 → 1.4.0

package/dist/collection/components/input/vds-basic-input.js

@@ -1,34 +1,186 @@
 import { Host, h } from "@stencil/core";
 import { isValidIcon, toggleFocusClass, getIconColor, setInputStyles, setTouchedClass, setDirtyClass, maskInput } from "./vds-basic-input.utils";
 import { combineClasses } from "../../utils/combine-classes";
-import { cloneAttributes } from "../../utils/clone-attributes";
 import { emitInputEvent, shadowSubmitForm } from "../../utils/form";
+import { setupAttributeSync } from "../../utils/attribute-sync";
+/**
+ * @component vds-basic-input
+ * @description A form-associated input component that supports various HTML5 input types, custom formatting, validation states, and action icons
+ * @slot primaryActionIcon - Icon button displayed at the right side of the input
+ * @slot secondaryActionIcon - Secondary icon button displayed before the primary action icon
+ * @example
+ * <!-- Basic text input -->
+ * <vds-basic-input
+ *   placeholder="Enter text"
+ *   value=""></vds-basic-input>
+ *
+ * <!-- Input with informative icon -->
+ * <vds-basic-input
+ *   placeholder="Email address"
+ *   type="email"
+ *   informative-icon="mail"
+ *   size="medium"></vds-basic-input>
+ *
+ * <!-- Required input with error state -->
+ * <vds-basic-input
+ *   placeholder="Username"
+ *   is-required
+ *   error
+ *   value=""></vds-basic-input>
+ *
+ * <!-- Password input with large size -->
+ * <vds-basic-input
+ *   type="password"
+ *   placeholder="Password"
+ *   size="large"></vds-basic-input>
+ *
+ * <!-- Disabled and readonly states -->
+ * <vds-basic-input
+ *   disabled
+ *   value="Disabled input"
+ *   placeholder="Disabled"></vds-basic-input>
+ *
+ * <vds-basic-input
+ *   is-readonly
+ *   value="Read only input"
+ *   placeholder="Read only"></vds-basic-input>
+ *
+ * <!-- Number input with custom formatter -->
+ * <vds-basic-input
+ *   id="formatted-input"
+ *   type="number"
+ *   placeholder="Enter amount"></vds-basic-input>
+ * <script>
+ *   const formattedInput = document.getElementById('formatted-input');
+ *   formattedInput.formatter = function(value) {
+ *     return value.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+ *   };
+ * </script>
+ *
+ * <!-- Small input with custom styles -->
+ * <vds-basic-input
+ *   id="styled-input"
+ *   size="small"
+ *   placeholder="Compact input"></vds-basic-input>
+ * <script>
+ *   const styledInput = document.getElementById('styled-input');
+ *   styledInput.allowedStyles = [{'text-align': 'center'}];
+ * </script>
+ *
+ * <!-- Input with action icons -->
+ * <vds-basic-input
+ *   placeholder="Search"
+ *   informative-icon="magnify">
+ *   <vds-icon-button
+ *     slot="primaryActionIcon"
+ *     icon="close"
+ *     size="small"></vds-icon-button>
+ * </vds-basic-input>
+ *
+ * <!-- Input with both primary and secondary action icons -->
+ * <vds-basic-input
+ *   placeholder="Search with filter"
+ *   informative-icon="magnify">
+ *   <vds-icon-button
+ *     slot="secondaryActionIcon"
+ *     icon="filter"
+ *     size="small"
+ *     aria-label="Filter"></vds-icon-button>
+ *   <vds-icon-button
+ *     slot="primaryActionIcon"
+ *     icon="close"
+ *     size="small"
+ *     aria-label="Clear"></vds-icon-button>
+ * </vds-basic-input>
+ *
+ * <!-- Date input -->
+ * <vds-basic-input
+ *   type="date"
+ *   placeholder="Select date"></vds-basic-input>
+ *
+ * <!-- Tel input with formatting -->
+ * <vds-basic-input
+ *   type="tel"
+ *   placeholder="Phone number"
+ *   informative-icon="phone"></vds-basic-input>
+ */
 export class VdsBasicInput {
     constructor() {
-        /** Sets the input size. */
+        /**
+         * Sets the input size
+         * @type {"small" | "medium" | "large"}
+         * @default "medium"
+         */
         this.size = "medium";
-        /** Sets input type in the DOM. Check HTML 5 Input type. */
+        /**
+         * Sets the input type in the DOM (supports HTML5 input types)
+         * @type {VdsInputType}
+         * @default "text"
+         */
         this.type = "text";
-        /** Sets the input value. */
+        /**
+         * Sets the input value
+         * @type {string}
+         * @default ""
+         */
         this.value = "";
-        /** Toggles the required sign in the field */
+        /**
+         * Toggles the required indicator
+         * @type {boolean}
+         * @default false
+         */
         this.isRequired = false;
-        /** Sets custom allowed styles to input (text-align, text-transform, unicode-bidi, direction) */
+        /**
+         * Sets custom allowed styles for the input (text-align, text-transform, unicode-bidi, direction)
+         * @type {Array<{[key: string]: string}>}
+         * @default []
+         */
         this.allowedStyles = [];
     }
+    /**
+     * Lifecycle hook that runs after component is loaded
+     * Sets form value and initializes attribute synchronization
+     * @returns {void}
+     */
     componentDidLoad() {
         this.setFormValue();
+        this.cleanupAttributeSync = setupAttributeSync(this.hostEl, () => this.inputEl);
+    }
+    /**
+     * Lifecycle hook that runs when component is disconnected
+     * Cleans up attribute synchronization
+     * @returns {void}
+     */
+    disconnectedCallback() {
+        if (this.cleanupAttributeSync) {
+            this.cleanupAttributeSync();
+        }
     }
+    /**
+     * Watches for value changes and updates form value
+     * @returns {void}
+     */
     setFormValue() {
-        emitInputEvent(this.hostEl, this.value);
+        const safeValue = this.getSafeValue();
+        emitInputEvent(this.hostEl, safeValue);
         if (this.internals && !!this.internals.setFormValue) {
-            this.internals.setFormValue(this.value);
+            this.internals.setFormValue(safeValue);
         }
     }
+    /**
+     * Gets the safe value (empty string if value is null or undefined)
+     * @private
+     * @returns {string} The safe value
+     */
+    getSafeValue() {
+        var _a;
+        return (_a = this.value) !== null && _a !== void 0 ? _a : "";
+    }
     /**
      * Displays vds-icon when icon string is valid
-     *
-     * @returns HTMLStencilElement
+     * @private
+     * @param {string} icon - The icon name to display
+     * @returns {HTMLStencilElement | null} The icon element or null
      */
     getInputIcon(icon) {
         if (!isValidIcon(icon))
@@ -38,29 +190,28 @@ export class VdsBasicInput {
         return (h("vds-icon", { class: "vds-input__informative-icon", svgIcon: icon, size: size, color: getIconColor(inputState) }));
     }
     /**
-     * Toggle class vds__input__container--focus in focus/blur input's event
-     *
-     * @returns void
+     * Toggles focus class on the input container during focus/blur events
+     * @private
+     * @returns {void}
      */
     toggleFocusClass() {
         this.inputContainerRef && toggleFocusClass(this.inputContainerRef);
     }
     /**
-     * Sets input inline styles for the allowedStyles
-     * [direction, text-align, textAlign, text-transform, textTransform, unicode-bidi, unicodeBidi]
-     *
-     * @returns void
+     * Sets input inline styles based on allowedStyles prop
+     * Supports: direction, text-align, textAlign, text-transform, textTransform, unicode-bidi, unicodeBidi
+     * @private
+     * @returns {{[key: string]: string}} The styles object
      */
     setInputStyles() {
         return setInputStyles(this.allowedStyles);
     }
     /**
-     * Sets value from input's event target.
-     * Emits change, input and changeInput events.
-     * Sets input as dirty when input's event is triggered.
-     * Executes formatter prop function on every inputed value.
-     *
-     * @returns void
+     * Handles input events, sets value, applies formatter if provided, and emits events
+     * Sets the input as dirty when triggered
+     * @private
+     * @param {InputEvent} evt - The input event
+     * @returns {void}
      */
     handleInput(evt) {
         evt.stopPropagation();
@@ -79,28 +230,28 @@ export class VdsBasicInput {
         this.hostEl.dispatchEvent(inputEvent);
     }
     /**
-       * Executes method when input's keyup event is triggered.
-       *
-       * @returns void
-       */
+     * Listens for keyup events and submits form when Enter key is pressed
+     * @param {KeyboardEvent} event - The keyboard event
+     * @returns {void}
+     */
     handleEnterKey(event) {
         if (event.key === "Enter") {
             shadowSubmitForm(this.hostEl);
         }
     }
     /**
-       * Executes method when vds-input gets focus.
-       *
-       * @returns void
-       */
+     * Listens for focus events and sets the input as touched
+     * @returns {void}
+     */
     handleFocus() {
         setTouchedClass(this.hostEl);
     }
     /**
-       * Sets focus on the vds-input element.
-       *
-       * @returns Promise<void>
-       */
+     * Sets focus on the input element
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when focus is set
+     */
     setFocus() {
         return new Promise((resolve) => {
             this.inputEl.focus();
@@ -108,20 +259,22 @@ export class VdsBasicInput {
         });
     }
     /**
-       * Gets value prop from the vds-input element.
-       *
-       * @returns Promise<string>
-       */
+     * Gets the current value of the input
+     * @method
+     * @public
+     * @returns {Promise<string>} A promise that resolves with the current value
+     */
     getValue() {
         return new Promise((resolve) => {
-            resolve(this.value);
+            resolve(this.getSafeValue());
         });
     }
     /**
-       * Clears value prop from the vds-input element.
-       *
-       * @returns Promise<void>
-       */
+     * Clears the input value
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the value is cleared
+     */
     clear() {
         return new Promise((resolve) => {
             this.value = "";
@@ -129,17 +282,21 @@ export class VdsBasicInput {
             resolve();
         });
     }
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render() {
         if (this.type === "datetime") {
             console.warn("The type datetime has been deprecated.Please use datetime-local.");
         }
-        return (h(Host, { key: '092953067ee8e9716f6a835ad6921f21b35dfc75', class: this.disabled ? "vds-basic-input--disabled" : "" }, h("div", { key: 'bcaa81ae31065cb2760f1860d99a98b2fb0bdab3', ref: (el) => {
+        return (h(Host, { key: '01864364e362f17f072df751b254b806a98fb239', class: this.disabled ? "vds-basic-input--disabled" : "" }, h("div", { key: '629b24441d0fa04f57c0e0c6c0a41c541cd787db', ref: (el) => {
                 if (el)
                     this.inputContainerRef = el;
-            }, class: combineClasses("vds__input__container", `vds__input--size-${this.size}`, this.error && "vds__input__container--error", this.isReadonly && "vds__input__container--readonly", this.disabled && "vds__input__container--disabled") }, this.getInputIcon(this.informativeIcon), h("input", Object.assign({ key: 'aaeda7cc72f965f5c61a711bdcb37f2e64d68c41', ref: (el) => {
+            }, class: combineClasses("vds__input__container", `vds__input--size-${this.size}`, this.error && "vds__input__container--error", this.isReadonly && "vds__input__container--readonly", this.disabled && "vds__input__container--disabled") }, this.getInputIcon(this.informativeIcon), h("input", { key: 'f0145b8dfbe642c0b9136d82793febbe4b498ba7', ref: (el) => {
                 if (el)
                     this.inputEl = el;
-            }, class: "vds__input", type: this.type, value: this.value, placeholder: this.placeholder, disabled: this.disabled, required: this.isRequired, readOnly: this.isReadonly, onInput: (evt) => this.handleInput(evt), onFocus: () => this.toggleFocusClass(), onBlur: () => this.toggleFocusClass(), style: this.setInputStyles() }, cloneAttributes(this.hostEl, "class", "value", "disabled", "placeholder", "label", "style"))), h("slot", { key: '3937435a84d228ddc18c3968e2e63bf66f3068e8', name: "secondaryActionIcon" }), h("slot", { key: 'fc2c441eedb6cd682e79e6ae4d598aa8ad31143e', name: "primaryActionIcon" }))));
+            }, class: "vds__input", type: this.type, value: this.getSafeValue(), placeholder: this.placeholder, disabled: this.disabled, required: this.isRequired, readOnly: this.isReadonly, onInput: (evt) => this.handleInput(evt), onFocus: () => this.toggleFocusClass(), onBlur: () => this.toggleFocusClass(), style: this.setInputStyles() }), h("slot", { key: '6089caa6b86a981cec2570e754f88371922f9ea6', name: "secondaryActionIcon" }), h("slot", { key: '112b39753c813046da7ed8fec348d39a9cd7c14b', name: "primaryActionIcon" }))));
     }
     static get is() { return "vds-basic-input"; }
     static get encapsulation() { return "shadow"; }
@@ -167,8 +324,14 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the input size."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"small\" | \"medium\" | \"large\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"medium\""
+                        }],
+                    "text": "Sets the input size"
                 },
                 "getter": false,
                 "setter": false,
@@ -186,15 +349,22 @@ export class VdsBasicInput {
                         "VdsInputType": {
                             "location": "import",
                             "path": "./vds-basic-input.utils",
-                            "id": "src/components/input/vds-basic-input.utils.ts::VdsInputType"
+                            "id": "src/components/input/vds-basic-input.utils.ts::VdsInputType",
+                            "referenceLocation": "VdsInputType"
                         }
                     }
                 },
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets input type in the DOM. Check HTML 5 Input type."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{VdsInputType}"
+                        }, {
+                            "name": "default",
+                            "text": "\"text\""
+                        }],
+                    "text": "Sets the input type in the DOM (supports HTML5 input types)"
                 },
                 "getter": false,
                 "setter": false,
@@ -213,8 +383,14 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the input value."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }, {
+                            "name": "default",
+                            "text": "\"\""
+                        }],
+                    "text": "Sets the input value"
                 },
                 "getter": false,
                 "setter": false,
@@ -233,8 +409,11 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the input placeholder."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the input placeholder text"
                 },
                 "getter": false,
                 "setter": false,
@@ -252,8 +431,11 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the input in disabled state."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }],
+                    "text": "Sets the input in disabled state"
                 },
                 "getter": false,
                 "setter": false,
@@ -271,8 +453,11 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the input in readonly state."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }],
+                    "text": "Sets the input in readonly state"
                 },
                 "getter": false,
                 "setter": false,
@@ -290,12 +475,15 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the input in error state."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }],
+                    "text": "Sets the input in error state for validation feedback"
                 },
                 "getter": false,
                 "setter": false,
-                "reflect": true,
+                "reflect": false,
                 "attribute": "error"
             },
             "isRequired": {
@@ -309,8 +497,14 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Toggles the required sign in the field"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Toggles the required indicator"
                 },
                 "getter": false,
                 "setter": false,
@@ -329,8 +523,11 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Allows user to define a information icon inside the input at its left ."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Defines an informative icon displayed at the left side of the input"
                 },
                 "getter": false,
                 "setter": false,
@@ -353,8 +550,11 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets character formatting for user input. Useful for adding a mask to the input."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{Function}"
+                        }],
+                    "text": "Sets character formatting function for user input (useful for adding masks)"
                 },
                 "getter": false,
                 "setter": false
@@ -370,8 +570,14 @@ export class VdsBasicInput {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets custom allowed styles to input (text-align, text-transform, unicode-bidi, direction)"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{Array<{[key: string]: string}>}"
+                        }, {
+                            "name": "default",
+                            "text": "[]"
+                        }],
+                    "text": "Sets custom allowed styles for the input (text-align, text-transform, unicode-bidi, direction)"
                 },
                 "getter": false,
                 "setter": false,
@@ -387,8 +593,14 @@ export class VdsBasicInput {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits updated input value"
+                    "tags": [{
+                            "name": "event",
+                            "text": "changeInput"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<string>}"
+                        }],
+                    "text": "Emits updated input value when input changes"
                 },
                 "complexType": {
                     "original": "string",
@@ -412,10 +624,16 @@ export class VdsBasicInput {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Sets focus on the vds-input element.",
+                    "text": "Sets focus on the input element",
                     "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
                             "name": "returns",
-                            "text": "Promise<void>"
+                            "text": "A promise that resolves when focus is set"
                         }]
                 }
             },
@@ -432,10 +650,16 @@ export class VdsBasicInput {
                     "return": "Promise<string>"
                 },
                 "docs": {
-                    "text": "Gets value prop from the vds-input element.",
+                    "text": "Gets the current value of the input",
                     "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
                             "name": "returns",
-                            "text": "Promise<string>"
+                            "text": "A promise that resolves with the current value"
                         }]
                 }
             },
@@ -452,10 +676,16 @@ export class VdsBasicInput {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Clears value prop from the vds-input element.",
+                    "text": "Clears the input value",
                     "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
                             "name": "returns",
-                            "text": "Promise<void>"
+                            "text": "A promise that resolves when the value is cleared"
                         }]
                 }
             }
@@ -485,4 +715,3 @@ export class VdsBasicInput {
     }
     static get attachInternalsMemberName() { return "internals"; }
 }
-//# sourceMappingURL=vds-basic-input.js.map

package/dist/collection/components/input/vds-basic-input.stories.js

@@ -88,4 +88,3 @@ BasicUsage.args = {
     min: "",
     max: ""
 };
-//# sourceMappingURL=vds-basic-input.stories.js.map

package/dist/collection/components/input/vds-basic-input.utils.js

@@ -1,13 +1,24 @@
 import { getIconsFromSpriteFile } from "../../utils/icon-utils";
 /**
- * Validates whether an icon is valid or not by comparing with sprite file.
+ * Validates whether an icon is valid or not by comparing with sprite file or checking if it's a valid URL.
+ * Accepts sprite icon names, external SVG URLs, external image URLs, and inline SVG strings.
  *
- * @param icon string
+ * @param icon string - Icon name, URL, or inline SVG string
  * @returns boolean
  */
 export const isValidIcon = (icon) => {
-    const ICON_LIST = getIconsFromSpriteFile();
-    return icon && ICON_LIST.some(ico => ico === icon);
+    if (!icon)
+        return false;
+    if (icon.trim().startsWith('<svg'))
+        return true;
+    try {
+        new URL(icon);
+        return true;
+    }
+    catch (_a) {
+        const ICON_LIST = getIconsFromSpriteFile();
+        return ICON_LIST.some(ico => ico === icon);
+    }
 };
 /**
  * Toggle class [vds__input__container--focus] in focus/blur input's event
@@ -116,4 +127,3 @@ export const setInputStyles = (allowedStyles) => {
 export const maskInput = (formatter, input, currentValue, eventData, element, fullEvent) => {
     return formatter(input, currentValue, eventData, element, fullEvent);
 };
-//# sourceMappingURL=vds-basic-input.utils.js.map