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

package/dist/types/components/input/vds-basic-input.d.ts

@@ -1,96 +1,290 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { VdsInputType } from './vds-basic-input.utils';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @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 declare class VdsBasicInput {
-    /** Sets the input size. */
+    /**
+     * Sets the input size
+     * @type {"small" | "medium" | "large"}
+     * @default "medium"
+     */
     size: "small" | "medium" | "large";
-    /** 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"
+     */
     type: VdsInputType;
-    /** Sets the input value. */
+    /**
+     * Sets the input value
+     * @type {string}
+     * @default ""
+     */
     value: string;
-    /** Sets the input placeholder. */
+    /**
+     * Sets the input placeholder text
+     * @type {string}
+     */
     placeholder: string;
-    /** Sets the input in disabled state. */
+    /**
+     * Sets the input in disabled state
+     * @type {boolean}
+     */
     disabled: boolean;
-    /** Sets the input in readonly state. */
+    /**
+     * Sets the input in readonly state
+     * @type {boolean}
+     */
     isReadonly: boolean;
-    /** Sets the input in error state. */
+    /**
+     * Sets the input in error state for validation feedback
+     * @type {boolean}
+     */
     error: boolean;
-    /** Toggles the required sign in the field */
+    /**
+     * Toggles the required indicator
+     * @type {boolean}
+     * @default false
+     */
     isRequired: boolean;
-    /** Allows user to define a information icon inside the input at its left . */
+    /**
+     * Defines an informative icon displayed at the left side of the input
+     * @type {string}
+     */
     informativeIcon: string;
-    /** Sets character formatting for user input. Useful for adding a mask to the input. */
+    /**
+     * Sets character formatting function for user input (useful for adding masks)
+     * @type {Function}
+     */
     formatter?: Function;
-    /** 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 []
+     */
     allowedStyles: {
         [key: string]: string;
     }[];
+    /**
+     * Reference to the host element
+     * @type {HTMLInputElement}
+     */
     hostEl: HTMLInputElement;
-    /**  Emits updated input value */
+    /**
+     * Emits updated input value when input changes
+     * @event changeInput
+     * @type {EventEmitter<string>}
+     */
     changeInput: EventEmitter<string>;
+    /**
+     * ElementInternals API for form association
+     * @type {ElementInternals}
+     */
     internals: ElementInternals;
+    /**
+     * Reference to the input container element
+     * @private
+     * @type {HTMLDivElement}
+     */
     private inputContainerRef;
+    /**
+     * Reference to the native input element
+     * @private
+     * @type {HTMLInputElement}
+     */
     private inputEl;
+    /**
+     * Cleanup function for attribute synchronization
+     * @private
+     * @type {() => void}
+     */
+    private cleanupAttributeSync;
+    /**
+     * Lifecycle hook that runs after component is loaded
+     * Sets form value and initializes attribute synchronization
+     * @returns {void}
+     */
     componentDidLoad(): void;
+    /**
+     * Lifecycle hook that runs when component is disconnected
+     * Cleans up attribute synchronization
+     * @returns {void}
+     */
+    disconnectedCallback(): void;
+    /**
+     * Watches for value changes and updates form value
+     * @returns {void}
+     */
     setFormValue(): void;
+    /**
+     * Gets the safe value (empty string if value is null or undefined)
+     * @private
+     * @returns {string} The safe value
+     */
+    private getSafeValue;
     /**
      * 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
      */
     private getInputIcon;
     /**
-     * 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}
      */
     private toggleFocusClass;
     /**
-     * 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
      */
     private setInputStyles;
     /**
-     * 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}
      */
     private handleInput;
     /**
-       * 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: KeyboardEvent): void;
     /**
-       * Executes method when vds-input gets focus.
-       *
-       * @returns void
-       */
+     * Listens for focus events and sets the input as touched
+     * @returns {void}
+     */
     handleFocus(): void;
     /**
-       * 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(): Promise<void>;
     /**
-       * 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(): Promise<string>;
     /**
-       * 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(): Promise<void>;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/input/vds-basic-input.utils.d.ts

@@ -1,9 +1,10 @@
 import { IconColors } from "../../definitions/colors";
 export type VdsInputType = "number" | "text" | "date" | "tel" | "datetime" | "datetime-local" | "email" | "submit" | "password" | "month" | "time" | "url" | "week";
 /**
- * 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 declare const isValidIcon: (icon: string) => boolean;

package/dist/types/components/key-value-pair/vds-key-value-pair.d.ts

@@ -1,15 +1,92 @@
 import { HTMLStencilElement } from '../../stencil-public-runtime';
 import { Typography } from '../../definitions/typography';
+/**
+ * @component vds-key-value-pair
+ * @description A component that displays a label-value pair with configurable positioning and typography styles
+ * @slot label-slot - Additional content to display alongside the label
+ * @slot value-slot - Additional content to display alongside the value
+ * @example
+ * <!-- Basic key-value pair with label on top -->
+ * <vds-key-value-pair
+ *   label="Name"
+ *   value="John Doe"></vds-key-value-pair>
+ *
+ * <!-- With label at bottom -->
+ * <vds-key-value-pair
+ *   label="Temperature"
+ *   value="72°F"
+ *   label-position="bottom"></vds-key-value-pair>
+ *
+ * <!-- With custom typography sizes -->
+ * <vds-key-value-pair
+ *   label="Total Amount"
+ *   value="$1,234.56"
+ *   label-size="body-small"
+ *   value-size="headline-large"></vds-key-value-pair>
+ *
+ * <!-- With label slot for additional content -->
+ * <vds-key-value-pair
+ *   label="Status"
+ *   value="Active">
+ *   <vds-icon slot="label-slot" svg-icon="information"></vds-icon>
+ * </vds-key-value-pair>
+ *
+ * <!-- With value slot for icons or badges -->
+ * <vds-key-value-pair
+ *   label="Priority"
+ *   value="">
+ *   <vds-badge-pill
+ *     slot="value-slot"
+ *     value="Urgent"
+ *     status-color="danger"></vds-badge-pill>
+ * </vds-key-value-pair>
+ *
+ * <!-- Small label and value -->
+ * <vds-key-value-pair
+ *   label="ID"
+ *   value="12345"
+ *   label-size="body-extra-small"
+ *   value-size="body-small"></vds-key-value-pair>
+ *
+ * <!-- Multiple key-value pairs in a group -->
+ * <div style="display: flex; gap: 2rem;">
+ *   <vds-key-value-pair label="First Name" value="Jane"></vds-key-value-pair>
+ *   <vds-key-value-pair label="Last Name" value="Smith"></vds-key-value-pair>
+ *   <vds-key-value-pair label="Age" value="28"></vds-key-value-pair>
+ * </div>
+ */
 export declare class VdsKeyValuePair {
-    /** Set the position for the label */
+    /**
+     * Sets the position of the label relative to the value
+     * @type {'top' | 'bottom'}
+     * @default 'top'
+     */
     labelPosition: 'top' | 'bottom';
-    /** Set the label value */
+    /**
+     * Sets the label text
+     * @type {string}
+     */
     label: string;
-    /** Set the size of the label */
+    /**
+     * Sets the typography size of the label
+     * @type {Typography}
+     * @default 'body-medium'
+     */
     labelSize: Typography;
-    /** Define the value content */
+    /**
+     * Sets the value content
+     * @type {string}
+     */
     value: string;
-    /** Define the text value size based on the vds font mixing */
+    /**
+     * Sets the typography size of the value based on the Volt font mixing
+     * @type {Typography}
+     * @default 'headline-small'
+     */
     valueSize: Typography;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/label/vds-label.d.ts

@@ -1,16 +1,92 @@
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-label
+ * @description A label component that displays text with optional required indicator and icon, supporting various sizes and disabled state
+ * @example
+ * <!-- Basic label -->
+ * <vds-label label-value="Username"></vds-label>
+ *
+ * <!-- Required label with asterisk -->
+ * <vds-label
+ *   label-value="Email"
+ *   required></vds-label>
+ *
+ * <!-- Label with icon -->
+ * <vds-label
+ *   label-value="Settings"
+ *   icon="module-settings"></vds-label>
+ *
+ * <!-- Large size label -->
+ * <vds-label
+ *   label-value="Title"
+ *   size="large"></vds-label>
+ *
+ * <!-- Small size label -->
+ * <vds-label
+ *   label-value="Subtitle"
+ *   size="small"></vds-label>
+ *
+ * <!-- Disabled label -->
+ * <vds-label
+ *   label-value="Disabled Field"
+ *   disabled></vds-label>
+ *
+ * <!-- Required label with icon -->
+ * <vds-label
+ *   label-value="Important Field"
+ *   required
+ *   icon="star"></vds-label>
+ *
+ * <!-- Label for form field -->
+ * <vds-field>
+ *   <vds-label label-value="Password" required size="medium"></vds-label>
+ *   <vds-basic-input type="password"></vds-basic-input>
+ * </vds-field>
+ */
 export declare class VdsLabel {
-    /** Sets the size of the label */
+    /**
+     * Sets the size of the label
+     * @type {"small" | "large" | "medium"}
+     * @default "medium"
+     */
     size: "small" | "large" | "medium";
-    /** Sets label in disabled state */
+    /**
+     * Sets the label in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the label as required element adding * at the end */
+    /**
+     * Sets the label as required, adding an asterisk at the end
+     * @type {boolean}
+     * @default false
+     */
     required: boolean;
-    /** Sets the label text */
+    /**
+     * Sets the label text content
+     * @type {string}
+     */
     labelValue: string;
-    /** Displays icon at the end of the text */
+    /**
+     * Displays an icon at the end of the label text
+     * @type {string}
+     */
     icon: string;
+    /**
+     * Renders the required asterisk indicator
+     * @private
+     * @returns {HTMLStencilElement} The required indicator element
+     */
     private getRequired;
+    /**
+     * Renders the icon at the end of the label
+     * @private
+     * @returns {HTMLStencilElement} The icon element
+     */
     private getIcon;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }