@heartlandone/vega 2.77.1 → 2.79.0

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

@@ -120,171 +120,289 @@ export class VegaInput {
     this.vegaComponentUsageRuntimeMetricsSlimmer = new VegaComponentUsageRuntimeMetricsSlimmer(VegaInputRuntimeMetricsPayloadDefinition);
     this.passwordEyeRenderer = new VegaInputPasswordEyeRenderer();
     /**
-     * Specifies the label or title for the input field.
+     * Specifies the visible label text displayed above the input field.
      *
-     * It provides descriptive text that helps identify the
-     *    purpose or content expected in the input field.
+     * The label provides an accessible, descriptive title that helps users identify
+     * the purpose or content expected in the input field. It is rendered as a
+     * `<vega-field-label>` element and is associated with the native `<input>` for
+     * accessibility (screen readers, click-to-focus).
      *
+     * When set to an empty string, no label is rendered.
+     *
+     * @default ''
      * @vegaVersion 1.0.5
      */
     this.label = '';
     /**
-     * @deprecated Please use `LabelSuffixButtonConfig` instead
-     *
-     * Specifies the properties for the suffix button associated with the input.
+     * @deprecated Please use `labelSuffixButtonConfig` instead.
      *
-     * It provides essential information and functionality
-     *  related to the suffix button's role and behavior.
+     * Configures an optional action button displayed at the trailing end of the
+     * field label. This can be used to provide contextual actions such as a
+     * "Forgot password?" link or an info tooltip trigger.
      *
+     * @default null
      * @vegaVersion 2.25.0
      */
     this.labelSuffixButtonProps = null;
     /**
-     * Specifies the properties for the suffix button associated with the input.
+     * Configures an optional action button displayed at the trailing end of the
+     * field label. Use this to provide contextual actions such as a
+     * "Forgot password?" link, a help tooltip trigger, or any custom label-level action.
      *
-     * It provides essential information and functionality
-     *  related to the suffix button's role and behavior.
+     * When clicked, the `vegaLabelButtonClick` event is emitted.
      *
+     * @default null
      * @vegaVersion 2.68.0
      */
     this.labelSuffixButtonConfig = null;
     /**
-     * Represents a pre-set or default value for the input field.
+     * The current value of the input field.
      *
-     * It allows you to initialize the field with a specific value,
-     *    which is displayed to the user when the input is
-     *    initially rendered.
+     * Use this property to programmatically set or read the input's value.
+     * The value is two-way bound — it updates when the user types and can be
+     * set externally to pre-fill or reset the field.
      *
-     * If the value is too long, it may be truncated with
-     *    an ellipsis for visual presentation.
+     * When a `maskConfig` is applied, the displayed value may differ from the
+     * raw value (e.g., formatted phone numbers). The `vegaChange` event emits
+     * the current value whenever it changes.
      *
+     * @default ''
      * @vegaVersion 1.0.5
      */
     /* eslint-disable-next-line @stencil/strict-mutable */
     this.value = '';
     /**
-     * Specifies when the vegaChange event is triggered.
-     *     It controls whether the event is dispatched
-     *     after typing in the input or after a change event.
+     * Controls when the `vegaChange` event is emitted, allowing you to choose
+     * between real-time updates and committed-value updates.
+     *
+     * - `'input'` — Fires on every keystroke as the user types (real-time).
+     * - `'change'` — Fires only when the input loses focus or the user presses Enter,
+     *   similar to the native HTML `change` event behavior.
      *
+     * Use `'change'` for expensive operations (e.g., API calls) where you only need
+     * the final committed value. Use `'input'` for live search or filtering scenarios.
+     *
+     * @default 'input'
      * @vegaVersion 2.24.0
      */
     this.valueUpdateTrigger = 'input';
     /**
-     * Defines the specific type or category of the input field.
+     * Sets the HTML input type, which controls the browser's input behavior,
+     * on-screen keyboard layout, and built-in validation.
      *
-     * It specifies the intended format or purpose of the
-     *    data to be entered by the user.
+     * - `'text'` — Standard single-line text input.
+     * - `'email'` — Optimized for email entry; triggers email validation automatically.
+     * - `'password'` — Masks the entered characters; displays a show/hide toggle icon.
+     * - `'number'` — Restricts input to numeric values; may show increment/decrement controls.
+     * - `'hidden'` — Renders the input as invisible (useful for programmatic form values).
      *
+     * @default 'text'
      * @vegaVersion 1.0.9
      */
     this.type = 'text';
     /**
-     * Defines the specific name of the input field.
+     * Sets the `name` attribute on the underlying native `<input>` element.
      *
+     * This is used to identify the field when submitting form data and is also
+     * used by the browser's autocomplete feature to recall previously entered values.
      *
+     * @default ''
      * @vegaVersion 1.0.5
      */
     this.name = '';
     /**
-     * Controls the autofill behavior and specifies whether the
-     *    input should receive automated suggestions or
-     *    previously entered values.
+     * Controls the browser's autofill and autocomplete behavior for this input.
+     *
+     * Set to a semantic token (e.g., `'email'`, `'tel'`, `'street-address'`) to help
+     * the browser suggest previously saved values. Set to `'off'` to disable
+     * autocomplete suggestions entirely.
+     *
+     * See the full list of valid tokens:
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete
      *
+     * @default 'off'
      * @vegaVersion 1.0.5
      */
     this.autocomplete = 'off';
     /**
-     * Enforces proper email format validation for the input field.
+     * Sets the input field as read-only, preventing direct keyboard input.
      *
-     * It ensures that the user enters a valid email address according to
-     *    standard email formatting rules.
+     * When set to `true`, prevents manual keyboard text entry in the input field on
+     *    all platforms. On touch devices, this typically suppresses the virtual keyboard.
      *
-     * @deprecated Please use `type='email'` instead.
+     * @default false
+     * @vegaVersion 2.79.0
+     */
+    this.readOnly = false;
+    /**
+     * When `true`, enforces email format validation on the input value.
+     *
+     * The validation checks that the entered text conforms to standard email
+     * formatting rules (e.g., `user@domain.com`). An invalid email will cause
+     * `isValid` to be set to `false` when validation is triggered.
+     *
+     * @deprecated Please use `type='email'` instead, which provides the same
+     * validation along with optimized mobile keyboard and browser autofill support.
+     * @default false
      * @vegaVersion 1.0.5
      */
     this.email = false;
     /**
-     * Determines whether the input field is required.
+     * Marks the input field as required for form submission.
+     *
+     * When `true`, a required-field validation rule is automatically applied.
+     * If `autoValidation` is enabled, the field will display a validation error
+     * when the user leaves it empty. A visual required indicator (asterisk) is
+     * shown next to the label.
      *
+     * @default false
      * @vegaVersion 1.0.5
      */
     /* eslint-disable-next-line @stencil/strict-mutable */
     this.required = false;
     /**
-     * Sets the minimum allowable numeric value for the input value.
+     * Sets the minimum allowable numeric value for the input.
      *
+     * When set, a `MinNumberRule` validation is applied automatically.
+     * If the user enters a number below this threshold, the field will
+     * be marked as invalid. Only applies when the input value is numeric.
+     *
+     * @default null
      * @vegaVersion 1.0.5
      */
     this.min = null;
     /**
-     * Sets the maximum allowable numeric value for the input value.
+     * Sets the maximum allowable numeric value for the input.
+     *
+     * When set, a `MaxNumberRule` validation is applied automatically.
+     * If the user enters a number above this threshold, the field will
+     * be marked as invalid. Only applies when the input value is numeric.
      *
+     * @default null
      * @vegaVersion 1.0.5
      */
     this.max = null;
     /**
-     * Sets the minimum length requirement for the input value.
+     * Sets the minimum character length required for the input value.
+     *
+     * When set, a `MinStringLengthRule` validation is applied automatically.
+     * If the user enters fewer characters than specified, the field will be
+     * marked as invalid when validation is triggered.
      *
+     * @default null
      * @vegaVersion 1.0.5
      */
     this.minLength = null;
     /**
-     * Sets the maximum length requirement for the input value.
+     * Sets the maximum character length allowed for the input value.
      *
+     * When set, a `MaxStringLengthRule` validation is applied automatically.
+     * If the user enters more characters than specified, the field will be
+     * marked as invalid when validation is triggered.
+     *
+     * @default null
      * @vegaVersion 1.0.5
      */
     this.maxLength = null;
     /**
-     * Determines whether the clear icon should be displayed or hidden.
+     * Controls whether a clear (✕) icon button is displayed inside the input
+     * when the field has a non-empty value.
+     *
+     * When `true`, clicking the clear icon resets the input value to an empty
+     * string and emits a `vegaChange` event. Set to `false` to hide the icon
+     * (e.g., for inputs where clearing is not desired, such as read-only displays).
      *
+     * @default true
      * @vegaVersion 1.3.0
      */
     this.showClearIcon = true;
     /**
-     * Indicates whether the current value in the field is considered valid or
-     *    invalid based on the defined validation rules.
+     * Reflects the current validation state of the input field.
+     *
+     * - `true` — The field value passes all validation rules; no error styling is shown.
+     * - `false` — The field value is invalid; error styling and messages are displayed.
+     * - `null` — Validation has not yet been triggered (initial state).
      *
+     * This property is automatically updated when `autoValidation` is `true`.
+     * It can also be set programmatically to force a specific validation state
+     * (e.g., after server-side validation).
+     *
+     * @default null
      * @vegaVersion 1.3.0
      */
     /* eslint-disable-next-line @stencil/strict-mutable */
     this.isValid = null;
     /**
-     * Determines whether the input field should undergo automatic validation
-     *    during the user's input.
+     * Enables or disables automatic validation as the user interacts with the input.
+     *
+     * When `true`, the component validates the input value in real-time against
+     * all configured validation rules (`required`, `min`, `max`, `minLength`,
+     * `maxLength`, `email`, and custom `validationRules`). Validation is triggered
+     * on blur and during input, updating the `isValid` property accordingly.
+     *
+     * Set to `false` when you need to manage validation manually (e.g., only on
+     * form submission).
      *
+     * @default true
      * @vegaVersion 1.0.10
      */
     this.autoValidation = true;
     /**
-     * Defines custom validation rules for the input field.
+     * An array of custom validation rules applied to the input field in addition
+     * to the built-in rules derived from `required`, `min`, `max`, `minLength`,
+     * `maxLength`, and `email` props.
      *
+     * Each rule is a `FormFieldValidationRule` object that defines a validation
+     * function and an associated error message. Rules are evaluated in order;
+     * the first failing rule's message is displayed.
+     *
+     * @default []
      * @vegaVersion 1.0.10
      */
     this.validationRules = [];
     /**
-     * Defines the size of the input field,
-     *    specifying its width or length.
+     * Sets the visual size variant of the input field, affecting its height
+     * and internal padding.
+     *
+     * - `'default'` — Standard height (40px), suitable for most form layouts.
+     * - `'small'` — Compact height (32px), useful in dense or inline
+     *   layouts. Such as table cells or toolbars.
      *
+     * @default 'default'
      * @vegaVersion 1.3.0
      */
     this.size = 'default';
     /**
-     * Determines whether the input field is disabled.
+     * When `true`, disables the input field, preventing user interaction.
      *
+     * A disabled input cannot receive focus, does not respond to click or keyboard
+     * events, and is visually styled with reduced opacity to indicate its inactive
+     * state. Disabled fields are excluded from form validation.
+     *
+     * @default false
      * @vegaVersion 1.3.0
      */
     this.disabled = false;
     /**
-     * Provides a supplementary prompt message that assists users in
-     *    understanding the expected value for the input field.
+     * Displays a helper text message below the input field.
+     *
+     * Use this to provide additional guidance about the expected input, such as
+     * format requirements (e.g., `'Must be at least 8 characters'`) or contextual
+     * tips. The hint is rendered via the `<vega-hint>` sub-component and is
+     * replaced by an error message when validation fails.
      *
+     * @default ''
      * @vegaVersion 1.3.0
      */
     this.hint = '';
     /**
-     * Controls whether copying or pasting is enabled for the input.
+     * When `true`, disables the ability to copy from or paste into the input field.
+     *
+     * This is useful for security-sensitive fields (e.g., password confirmation)
+     * where you want to prevent users from pasting values. Both keyboard shortcuts
+     * and context menu copy/paste actions are blocked.
      *
+     * @default false
      * @vegaVersion 2.1.0
      */
     this.disableCopyPaste = false;
@@ -331,32 +449,56 @@ export class VegaInput {
     methodPlaceholder();
   }
   /**
-   * Invoke this method to focus the current input.
+   * Programmatically sets focus on the underlying native `<input>` element.
    *
+   * Use this method when you need to direct the user's attention to this input
+   * (e.g., after form validation fails or on page load). Calling this method
+   * triggers the `vegaFocus` event.
+   *
+   * @returns A promise that resolves once focus has been applied.
    * @vegaVersion 1.12.0
    */
   async doFocus() {
     methodPlaceholder();
   }
   /**
-   * Invoke this method to blur the current input.
+   * Programmatically removes focus from the underlying native `<input>` element.
+   *
+   * Use this method when you need to dismiss the keyboard on mobile or move
+   * focus away from the input programmatically. Calling this method triggers
+   * the `vegaBlur` event and, if `autoValidation` is enabled, validation
+   * will be executed.
    *
+   * @returns A promise that resolves once blur has been applied.
    * @vegaVersion 1.12.0
    */
   async doBlur() {
     methodPlaceholder();
   }
   /**
-   * Invoke this method to show the suggestions dropdown.
+   * Programmatically opens the suggestions dropdown.
+   *
+   * Use this method when you need to display the dropdown independently of
+   * user input — for example, to show all available suggestions on focus
+   * or in response to an external trigger. Requires `suggestionsDropdownSource`
+   * to be set.
    *
+   * @param dropdownConfig - Optional configuration to customize the dropdown
+   * behavior (e.g., itemDisplayRule, caseSensitive).
+   * @returns A promise that resolves once the dropdown is displayed.
    * @vegaVersion 2.75.0
    */
   async showSuggestionsDropdown(dropdownConfig) {
     methodPlaceholder(dropdownConfig);
   }
   /**
-   * Invoke this method to hide the suggestions dropdown.
+   * Programmatically closes the suggestions dropdown.
    *
+   * Use this method when you need to dismiss the dropdown in response to an
+   * external event (e.g., pressing Escape, clicking outside, or completing
+   * a selection workflow).
+   *
+   * @returns A promise that resolves once the dropdown is hidden.
    * @vegaVersion 2.75.0
    */
   async hideSuggestionsDropdown() {
@@ -387,10 +529,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "''"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Specifies the label or title for the input field.\n\nIt provides descriptive text that helps identify the\n   purpose or content expected in the input field."
+        "text": "Specifies the visible label text displayed above the input field.\n\nThe label provides an accessible, descriptive title that helps users identify\nthe purpose or content expected in the input field. It is rendered as a\n`<vega-field-label>` element and is associated with the native `<input>` for\naccessibility (screen readers, click-to-focus).\n\nWhen set to an empty string, no label is rendered."
       },
       "attribute": "label",
       "reflect": true,
@@ -418,7 +563,10 @@ export class VegaInput {
       "docs": {
         "tags": [{
             "name": "deprecated",
-            "text": "Please use `LabelSuffixButtonConfig` instead\n\nSpecifies the properties for the suffix button associated with the input.\n\nIt provides essential information and functionality\nrelated to the suffix button's role and behavior."
+            "text": "Please use `labelSuffixButtonConfig` instead.\n\nConfigures an optional action button displayed at the trailing end of the\nfield label. This can be used to provide contextual actions such as a\n\"Forgot password?\" link or an info tooltip trigger."
+          }, {
+            "name": "default",
+            "text": "null"
           }, {
             "name": "vegaVersion",
             "text": "2.25.0"
@@ -448,10 +596,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "null"
+          }, {
             "name": "vegaVersion",
             "text": "2.68.0"
           }],
-        "text": "Specifies the properties for the suffix button associated with the input.\n\nIt provides essential information and functionality\n related to the suffix button's role and behavior."
+        "text": "Configures an optional action button displayed at the trailing end of the\nfield label. Use this to provide contextual actions such as a\n\"Forgot password?\" link, a help tooltip trigger, or any custom label-level action.\n\nWhen clicked, the `vegaLabelButtonClick` event is emitted."
       },
       "defaultValue": "null"
     },
@@ -467,10 +618,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "''"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Represents a pre-set or default value for the input field.\n\nIt allows you to initialize the field with a specific value,\n   which is displayed to the user when the input is\n   initially rendered.\n\nIf the value is too long, it may be truncated with\n   an ellipsis for visual presentation."
+        "text": "The current value of the input field.\n\nUse this property to programmatically set or read the input's value.\nThe value is two-way bound \u2014 it updates when the user types and can be\nset externally to pre-fill or reset the field.\n\nWhen a `maskConfig` is applied, the displayed value may differ from the\nraw value (e.g., formatted phone numbers). The `vegaChange` event emits\nthe current value whenever it changes."
       },
       "attribute": "value",
       "reflect": true,
@@ -493,10 +647,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "'input'"
+          }, {
             "name": "vegaVersion",
             "text": "2.24.0"
           }],
-        "text": "Specifies when the vegaChange event is triggered.\n    It controls whether the event is dispatched\n    after typing in the input or after a change event."
+        "text": "Controls when the `vegaChange` event is emitted, allowing you to choose\nbetween real-time updates and committed-value updates.\n\n- `'input'` \u2014 Fires on every keystroke as the user types (real-time).\n- `'change'` \u2014 Fires only when the input loses focus or the user presses Enter,\n  similar to the native HTML `change` event behavior.\n\nUse `'change'` for expensive operations (e.g., API calls) where you only need\nthe final committed value. Use `'input'` for live search or filtering scenarios."
       },
       "attribute": "value-update-trigger",
       "reflect": false,
@@ -519,10 +676,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "'text'"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.9"
           }],
-        "text": "Defines the specific type or category of the input field.\n\nIt specifies the intended format or purpose of the\n   data to be entered by the user."
+        "text": "Sets the HTML input type, which controls the browser's input behavior,\non-screen keyboard layout, and built-in validation.\n\n- `'text'` \u2014 Standard single-line text input.\n- `'email'` \u2014 Optimized for email entry; triggers email validation automatically.\n- `'password'` \u2014 Masks the entered characters; displays a show/hide toggle icon.\n- `'number'` \u2014 Restricts input to numeric values; may show increment/decrement controls.\n- `'hidden'` \u2014 Renders the input as invisible (useful for programmatic form values)."
       },
       "attribute": "type",
       "reflect": true,
@@ -540,10 +700,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "''"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Defines the specific name of the input field."
+        "text": "Sets the `name` attribute on the underlying native `<input>` element.\n\nThis is used to identify the field when submitting form data and is also\nused by the browser's autocomplete feature to recall previously entered values."
       },
       "attribute": "name",
       "reflect": false,
@@ -566,10 +729,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "'off'"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Controls the autofill behavior and specifies whether the\n   input should receive automated suggestions or\n   previously entered values."
+        "text": "Controls the browser's autofill and autocomplete behavior for this input.\n\nSet to a semantic token (e.g., `'email'`, `'tel'`, `'street-address'`) to help\nthe browser suggest previously saved values. Set to `'off'` to disable\nautocomplete suggestions entirely.\n\nSee the full list of valid tokens:\nhttps://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete"
       },
       "attribute": "autocomplete",
       "reflect": false,
@@ -590,11 +756,35 @@ export class VegaInput {
             "name": "vegaVersion",
             "text": "2.71.0"
           }],
-        "text": "A hint to the browser for which keyboard to display.\nPlease refer to https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode for more details."
+        "text": "Provides a hint to the browser about the type of virtual keyboard to display\non mobile devices, independent of the `type` attribute.\n\n- `'text'` \u2014 Standard text keyboard.\n- `'numeric'` \u2014 Numeric keypad (digits only), useful for PIN codes or quantities.\n\nSee https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode for more details."
       },
       "attribute": "inputmode",
       "reflect": false
     },
+    "readOnly": {
+      "type": "boolean",
+      "mutable": false,
+      "complexType": {
+        "original": "boolean",
+        "resolved": "boolean",
+        "references": {}
+      },
+      "required": false,
+      "optional": false,
+      "docs": {
+        "tags": [{
+            "name": "default",
+            "text": "false"
+          }, {
+            "name": "vegaVersion",
+            "text": "2.79.0"
+          }],
+        "text": "Sets the input field as read-only, preventing direct keyboard input.\n\nWhen set to `true`, prevents manual keyboard text entry in the input field on\n   all platforms. On touch devices, this typically suppresses the virtual keyboard."
+      },
+      "attribute": "read-only",
+      "reflect": false,
+      "defaultValue": "false"
+    },
     "prefixIcon": {
       "type": "string",
       "mutable": false,
@@ -610,7 +800,7 @@ export class VegaInput {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Specifies an icon or symbol that appears before the input field,\n   providing visual context or enhancing the aesthetic appearance\n   of the input."
+        "text": "Displays a Vega icon at the leading (left) side of the input field,\nproviding visual context about the expected input.\n\nPass a valid Vega icon name (e.g., `'search'`, `'email'`, `'lock'`).\nThe icon is rendered inside the input container and does not affect\nthe input's value or validation."
       },
       "attribute": "prefix-icon",
       "reflect": true
@@ -628,12 +818,15 @@ export class VegaInput {
       "docs": {
         "tags": [{
             "name": "deprecated",
-            "text": "Please use `type='email'` instead."
+            "text": "Please use `type='email'` instead, which provides the same\nvalidation along with optimized mobile keyboard and browser autofill support."
+          }, {
+            "name": "default",
+            "text": "false"
           }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Enforces proper email format validation for the input field.\n\nIt ensures that the user enters a valid email address according to\n   standard email formatting rules."
+        "text": "When `true`, enforces email format validation on the input value.\n\nThe validation checks that the entered text conforms to standard email\nformatting rules (e.g., `user@domain.com`). An invalid email will cause\n`isValid` to be set to `false` when validation is triggered."
       },
       "attribute": "email",
       "reflect": true,
@@ -651,10 +844,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "false"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Determines whether the input field is required."
+        "text": "Marks the input field as required for form submission.\n\nWhen `true`, a required-field validation rule is automatically applied.\nIf `autoValidation` is enabled, the field will display a validation error\nwhen the user leaves it empty. A visual required indicator (asterisk) is\nshown next to the label."
       },
       "attribute": "required",
       "reflect": true,
@@ -672,10 +868,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "null"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Sets the minimum allowable numeric value for the input value."
+        "text": "Sets the minimum allowable numeric value for the input.\n\nWhen set, a `MinNumberRule` validation is applied automatically.\nIf the user enters a number below this threshold, the field will\nbe marked as invalid. Only applies when the input value is numeric."
       },
       "attribute": "min",
       "reflect": true,
@@ -693,10 +892,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "null"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Sets the maximum allowable numeric value for the input value."
+        "text": "Sets the maximum allowable numeric value for the input.\n\nWhen set, a `MaxNumberRule` validation is applied automatically.\nIf the user enters a number above this threshold, the field will\nbe marked as invalid. Only applies when the input value is numeric."
       },
       "attribute": "max",
       "reflect": true,
@@ -714,10 +916,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "null"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Sets the minimum length requirement for the input value."
+        "text": "Sets the minimum character length required for the input value.\n\nWhen set, a `MinStringLengthRule` validation is applied automatically.\nIf the user enters fewer characters than specified, the field will be\nmarked as invalid when validation is triggered."
       },
       "attribute": "min-length",
       "reflect": true,
@@ -735,10 +940,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "null"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.5"
           }],
-        "text": "Sets the maximum length requirement for the input value."
+        "text": "Sets the maximum character length allowed for the input value.\n\nWhen set, a `MaxStringLengthRule` validation is applied automatically.\nIf the user enters more characters than specified, the field will be\nmarked as invalid when validation is triggered."
       },
       "attribute": "max-length",
       "reflect": true,
@@ -756,10 +964,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "true"
+          }, {
             "name": "vegaVersion",
             "text": "1.3.0"
           }],
-        "text": "Determines whether the clear icon should be displayed or hidden."
+        "text": "Controls whether a clear (\u2715) icon button is displayed inside the input\nwhen the field has a non-empty value.\n\nWhen `true`, clicking the clear icon resets the input value to an empty\nstring and emits a `vegaChange` event. Set to `false` to hide the icon\n(e.g., for inputs where clearing is not desired, such as read-only displays)."
       },
       "attribute": "show-clear-icon",
       "reflect": false,
@@ -777,10 +988,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "null"
+          }, {
             "name": "vegaVersion",
             "text": "1.3.0"
           }],
-        "text": "Indicates whether the current value in the field is considered valid or\n   invalid based on the defined validation rules."
+        "text": "Reflects the current validation state of the input field.\n\n- `true` \u2014 The field value passes all validation rules; no error styling is shown.\n- `false` \u2014 The field value is invalid; error styling and messages are displayed.\n- `null` \u2014 Validation has not yet been triggered (initial state).\n\nThis property is automatically updated when `autoValidation` is `true`.\nIt can also be set programmatically to force a specific validation state\n(e.g., after server-side validation)."
       },
       "attribute": "is-valid",
       "reflect": true,
@@ -798,10 +1012,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "true"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.10"
           }],
-        "text": "Determines whether the input field should undergo automatic validation\n   during the user's input."
+        "text": "Enables or disables automatic validation as the user interacts with the input.\n\nWhen `true`, the component validates the input value in real-time against\nall configured validation rules (`required`, `min`, `max`, `minLength`,\n`maxLength`, `email`, and custom `validationRules`). Validation is triggered\non blur and during input, updating the `isValid` property accordingly.\n\nSet to `false` when you need to manage validation manually (e.g., only on\nform submission)."
       },
       "attribute": "auto-validation",
       "reflect": true,
@@ -824,10 +1041,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "[]"
+          }, {
             "name": "vegaVersion",
             "text": "1.0.10"
           }],
-        "text": "Defines custom validation rules for the input field."
+        "text": "An array of custom validation rules applied to the input field in addition\nto the built-in rules derived from `required`, `min`, `max`, `minLength`,\n`maxLength`, and `email` props.\n\nEach rule is a `FormFieldValidationRule` object that defines a validation\nfunction and an associated error message. Rules are evaluated in order;\nthe first failing rule's message is displayed."
       },
       "defaultValue": "[]"
     },
@@ -843,10 +1063,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "'default'"
+          }, {
             "name": "vegaVersion",
             "text": "1.3.0"
           }],
-        "text": "Defines the size of the input field,\n   specifying its width or length."
+        "text": "Sets the visual size variant of the input field, affecting its height\nand internal padding.\n\n- `'default'` \u2014 Standard height (40px), suitable for most form layouts.\n- `'small'` \u2014 Compact height (32px), useful in dense or inline\n  layouts. Such as table cells or toolbars."
       },
       "attribute": "size",
       "reflect": false,
@@ -867,7 +1090,7 @@ export class VegaInput {
             "name": "vegaVersion",
             "text": "1.3.0"
           }],
-        "text": "Specifies a placeholder string that displays as a temporary hint\n   or example inside the input field.\n\nIt indicates the expected format or pattern of the input."
+        "text": "Sets the placeholder text displayed inside the input when the value is empty.\n\nUse this to provide a short hint about the expected input format or content\n(e.g., `'Enter your email'`, `'MM/DD/YYYY'`). The placeholder text disappears\nas soon as the user begins typing.\n\n**Note:** Placeholder text is not a substitute for a `label` \u2014 always provide\na descriptive label for accessibility."
       },
       "attribute": "placeholder",
       "reflect": false
@@ -884,10 +1107,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "false"
+          }, {
             "name": "vegaVersion",
             "text": "1.3.0"
           }],
-        "text": "Determines whether the input field is disabled."
+        "text": "When `true`, disables the input field, preventing user interaction.\n\nA disabled input cannot receive focus, does not respond to click or keyboard\nevents, and is visually styled with reduced opacity to indicate its inactive\nstate. Disabled fields are excluded from form validation."
       },
       "attribute": "disabled",
       "reflect": true,
@@ -905,10 +1131,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "''"
+          }, {
             "name": "vegaVersion",
             "text": "1.3.0"
           }],
-        "text": "Provides a supplementary prompt message that assists users in\n   understanding the expected value for the input field."
+        "text": "Displays a helper text message below the input field.\n\nUse this to provide additional guidance about the expected input, such as\nformat requirements (e.g., `'Must be at least 8 characters'`) or contextual\ntips. The hint is rendered via the `<vega-hint>` sub-component and is\nreplaced by an error message when validation fails."
       },
       "attribute": "hint",
       "reflect": false,
@@ -934,7 +1163,7 @@ export class VegaInput {
             "name": "vegaVersion",
             "text": "1.3.0"
           }],
-        "text": "Specifies the configuration for applying a mask to the input field.\n\nIt provides a way to define a specific format or pattern for the input value,\n   restricting and guiding the user's input accordingly."
+        "text": "Configures input masking to automatically format the user's input according\nto a predefined pattern.\n\nSupports built-in mask types (`'phone'`, `'zipcode'`, `'taxId'`,\n`'thousand-comma'`, `'number'`) as well as custom masks via `'custom'` or\n`'custom-formatter'` strategies.\n\nPass a single `MaskConfigType` object or an array of configs to apply\nmultiple masks. Each config specifies the mask `type`, optional formatting\n`options`, and a `trigger` (`'input'` or `'blur'`) to control when\nformatting is applied."
       }
     },
     "disableCopyPaste": {
@@ -949,10 +1178,13 @@ export class VegaInput {
       "optional": false,
       "docs": {
         "tags": [{
+            "name": "default",
+            "text": "false"
+          }, {
             "name": "vegaVersion",
             "text": "2.1.0"
           }],
-        "text": "Controls whether copying or pasting is enabled for the input."
+        "text": "When `true`, disables the ability to copy from or paste into the input field.\n\nThis is useful for security-sensitive fields (e.g., password confirmation)\nwhere you want to prevent users from pasting values. Both keyboard shortcuts\nand context menu copy/paste actions are blocked."
       },
       "attribute": "disable-copy-paste",
       "reflect": false,
@@ -978,7 +1210,7 @@ export class VegaInput {
             "name": "vegaVersion",
             "text": "2.75.0"
           }],
-        "text": "Sets the source array of items for the suggestion dropdown.\n   You should set this property at least a empty array if you want enable the source mode suggestion dropdown feature."
+        "text": "Provides the data source for the input's autocomplete suggestion dropdown.\n\nPass an array of `VegaDropdownSourceItem` objects to enable the suggestions\nfeature. The dropdown appears as the user types, filtering items that match\nthe current input value. When the user selects a suggestion, the\n`vegaSuggestionItemClick` event is emitted.\n\n**Important:** You must set this property to at least an empty array (`[]`)\nto enable the suggestion dropdown. If left `undefined`, the feature is disabled."
       }
     }
   }; }
@@ -997,10 +1229,13 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`string` \u2014 The current input value after the change."
+          }, {
             "name": "vegaVersion",
             "text": "1.0.10"
           }],
-        "text": "An event emitter notifying a value change."
+        "text": "Emitted when the input value changes.\n\nThe timing of this event depends on the `valueUpdateTrigger` prop:\n- When `valueUpdateTrigger` is `'input'` (default), fires on every keystroke.\n- When `valueUpdateTrigger` is `'change'`, fires on blur or when the user presses Enter.\n\nAlso fires when the user clicks the clear icon or when the value is\nprogrammatically updated."
       },
       "complexType": {
         "original": "string",
@@ -1015,13 +1250,16 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`string` \u2014 The current input value after the change."
+          }, {
             "name": "eventSemantics",
             "text": "namespace:native"
           }, {
             "name": "vegaVersion",
             "text": "2.0.0"
           }],
-        "text": "An event emitter notifying a value change."
+        "text": "Native-namespace alias for the `vegaChange` event.\n\nEmitted at the same time and under the same conditions as `vegaChange`.\nUse this event when integrating with frameworks that expect native-style\nevent names (e.g., `@change` in Vue or Angular)."
       },
       "complexType": {
         "original": "string",
@@ -1036,10 +1274,13 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`string` \u2014 The raw value from the native input element."
+          }, {
             "name": "vegaVersion",
             "text": "2.75.0"
           }],
-        "text": "An event emitter notifying a value change by input action of native input dom."
+        "text": "Emitted on every native `input` event from the underlying `<input>` element,\nregardless of the `valueUpdateTrigger` setting.\n\nThis event fires on every keystroke and provides the raw input value.\nUse this for real-time monitoring (e.g., driving a suggestions dropdown)\nwhile keeping `vegaChange` set to `'change'` trigger for the main value binding."
       },
       "complexType": {
         "original": "string",
@@ -1054,13 +1295,16 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`string` \u2014 The raw value from the native input element."
+          }, {
             "name": "eventSemantics",
             "text": "namespace:native"
           }, {
             "name": "vegaVersion",
             "text": "2.75.0"
           }],
-        "text": "An event emitter notifying a value change by input action of native input dom."
+        "text": "Native-namespace alias for the `vegaNativeInputChange` event.\n\nEmitted at the same time and under the same conditions as\n`vegaNativeInputChange`. Use this event when integrating with frameworks\nthat expect native-style event names."
       },
       "complexType": {
         "original": "string",
@@ -1075,10 +1319,13 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`undefined` \u2014 No payload; listen for the event occurrence only."
+          }, {
             "name": "vegaVersion",
             "text": "1.3.0"
           }],
-        "text": "An event emitter notifying the blur of the inner input element."
+        "text": "Emitted when the input field loses focus.\n\nThis event fires after the underlying native `<input>` element's `blur`\nevent. Useful for triggering validation, saving state, or updating UI\nwhen the user navigates away from the field."
       },
       "complexType": {
         "original": "undefined",
@@ -1093,13 +1340,16 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`undefined` \u2014 No payload; listen for the event occurrence only."
+          }, {
             "name": "eventSemantics",
             "text": "namespace:native"
           }, {
             "name": "vegaVersion",
             "text": "2.0.0"
           }],
-        "text": "An event emitter notifying the blur of the inner input element."
+        "text": "Native-namespace alias for the `vegaBlur` event.\n\nEmitted at the same time and under the same conditions as `vegaBlur`.\nUse this event when integrating with frameworks that expect native-style\nevent names."
       },
       "complexType": {
         "original": "undefined",
@@ -1114,10 +1364,13 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`undefined` \u2014 No payload; listen for the event occurrence only."
+          }, {
             "name": "vegaVersion",
             "text": "1.12.0"
           }],
-        "text": "An event emitter notifying the focus of the inner input element."
+        "text": "Emitted when the input field receives focus.\n\nThis event fires after the underlying native `<input>` element's `focus`\nevent, including when focus is set programmatically via the `doFocus()` method.\nUseful for highlighting the field, showing contextual help, or opening\na suggestions dropdown."
       },
       "complexType": {
         "original": "undefined",
@@ -1132,13 +1385,16 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`undefined` \u2014 No payload; listen for the event occurrence only."
+          }, {
             "name": "eventSemantics",
             "text": "namespace:native"
           }, {
             "name": "vegaVersion",
             "text": "2.0.0"
           }],
-        "text": "An event emitter notifying the focus of the inner input element."
+        "text": "Native-namespace alias for the `vegaFocus` event.\n\nEmitted at the same time and under the same conditions as `vegaFocus`.\nUse this event when integrating with frameworks that expect native-style\nevent names."
       },
       "complexType": {
         "original": "undefined",
@@ -1153,10 +1409,13 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`void` \u2014 No payload."
+          }, {
             "name": "vegaVersion",
             "text": "2.25.0"
           }],
-        "text": "An event emitter notifying that the suffix button associated with the field label has been clicked."
+        "text": "Emitted when the user clicks the suffix button in the field label.\n\nThis event only fires when a `labelSuffixButtonConfig` (or the deprecated\n`labelSuffixButtonProps`) is provided. Use it to handle contextual actions\nsuch as opening a tooltip, navigating to a help page, or triggering a\n\"Forgot password?\" flow."
       },
       "complexType": {
         "original": "any",
@@ -1171,13 +1430,16 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`void` \u2014 No payload."
+          }, {
             "name": "eventSemantics",
             "text": "namespace:native"
           }, {
             "name": "vegaVersion",
             "text": "2.25.0"
           }],
-        "text": "An event emitter notifying that the suffix button associated with the field label has been clicked."
+        "text": "Native-namespace alias for the `vegaLabelButtonClick` event.\n\nEmitted at the same time and under the same conditions as\n`vegaLabelButtonClick`. Use this event when integrating with frameworks\nthat expect native-style event names."
       },
       "complexType": {
         "original": "any",
@@ -1192,10 +1454,13 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`DataTransferType` \u2014 An object containing the pasted data,\nincluding the MIME type and raw text content from the clipboard."
+          }, {
             "name": "vegaVersion",
             "text": "2.66.0"
           }],
-        "text": "An event emitter notifying the paste of the inner input element."
+        "text": "Emitted when the user pastes content into the input field.\n\nThis event fires regardless of the `disableCopyPaste` setting \u2014 the paste\naction is blocked visually, but the event still propagates for tracking\npurposes. Use this to inspect or transform pasted data before it is applied."
       },
       "complexType": {
         "original": "DataTransferType",
@@ -1215,13 +1480,16 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`DataTransferType` \u2014 An object containing the pasted data,\nincluding the MIME type and raw text content from the clipboard."
+          }, {
             "name": "eventSemantics",
             "text": "namespace:native"
           }, {
             "name": "vegaVersion",
             "text": "2.66.0"
           }],
-        "text": "An event emitter notifying the paste of the inner input element."
+        "text": "Native-namespace alias for the `vegaPaste` event.\n\nEmitted at the same time and under the same conditions as `vegaPaste`.\nUse this event when integrating with frameworks that expect native-style\nevent names."
       },
       "complexType": {
         "original": "DataTransferType",
@@ -1241,10 +1509,13 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`VegaDropdownSourceItem` \u2014 The full data object of the selected\nsuggestion item, including its `label`, `value`, and any custom properties."
+          }, {
             "name": "vegaVersion",
             "text": "2.75.0"
           }],
-        "text": "An event emitter notifying the click of a suggestion item."
+        "text": "Emitted when the user selects an item from the suggestions dropdown.\n\nThis event only fires when the `suggestionsDropdownSource` prop is set.\nUse it to respond to the user's selection \u2014 for example, to populate\nrelated fields, navigate to a detail page, or trigger a search."
       },
       "complexType": {
         "original": "VegaDropdownSourceItem",
@@ -1264,13 +1535,16 @@ export class VegaInput {
       "composed": true,
       "docs": {
         "tags": [{
+            "name": "eventDetail",
+            "text": "`VegaDropdownSourceItem` \u2014 The full data object of the selected\nsuggestion item, including its `label`, `value`, and any custom properties."
+          }, {
             "name": "eventSemantics",
             "text": "namespace:native"
           }, {
             "name": "vegaVersion",
             "text": "2.75.0"
           }],
-        "text": "An event emitter notifying the click of a suggestion item."
+        "text": "Native-namespace alias for the `vegaSuggestionItemClick` event.\n\nEmitted at the same time and under the same conditions as\n`vegaSuggestionItemClick`. Use this event when integrating with frameworks\nthat expect native-style event names."
       },
       "complexType": {
         "original": "VegaDropdownSourceItem",
@@ -1296,8 +1570,11 @@ export class VegaInput {
         "return": "Promise<void>"
       },
       "docs": {
-        "text": "Invoke this method to focus the current input.",
+        "text": "Programmatically sets focus on the underlying native `<input>` element.\n\nUse this method when you need to direct the user's attention to this input\n(e.g., after form validation fails or on page load). Calling this method\ntriggers the `vegaFocus` event.",
         "tags": [{
+            "name": "returns",
+            "text": "A promise that resolves once focus has been applied."
+          }, {
             "name": "vegaVersion",
             "text": "1.12.0"
           }]
@@ -1315,8 +1592,11 @@ export class VegaInput {
         "return": "Promise<void>"
       },
       "docs": {
-        "text": "Invoke this method to blur the current input.",
+        "text": "Programmatically removes focus from the underlying native `<input>` element.\n\nUse this method when you need to dismiss the keyboard on mobile or move\nfocus away from the input programmatically. Calling this method triggers\nthe `vegaBlur` event and, if `autoValidation` is enabled, validation\nwill be executed.",
         "tags": [{
+            "name": "returns",
+            "text": "A promise that resolves once blur has been applied."
+          }, {
             "name": "vegaVersion",
             "text": "1.12.0"
           }]
@@ -1326,8 +1606,11 @@ export class VegaInput {
       "complexType": {
         "signature": "(dropdownConfig?: VegaInputSuggestionsDropdownConfig) => Promise<void>",
         "parameters": [{
-            "tags": [],
-            "text": ""
+            "tags": [{
+                "name": "param",
+                "text": "dropdownConfig - Optional configuration to customize the dropdown\nbehavior (e.g., itemDisplayRule, caseSensitive)."
+              }],
+            "text": "- Optional configuration to customize the dropdown\nbehavior (e.g., itemDisplayRule, caseSensitive)."
           }],
         "references": {
           "Promise": {
@@ -1341,8 +1624,14 @@ export class VegaInput {
         "return": "Promise<void>"
       },
       "docs": {
-        "text": "Invoke this method to show the suggestions dropdown.",
+        "text": "Programmatically opens the suggestions dropdown.\n\nUse this method when you need to display the dropdown independently of\nuser input \u2014 for example, to show all available suggestions on focus\nor in response to an external trigger. Requires `suggestionsDropdownSource`\nto be set.",
         "tags": [{
+            "name": "param",
+            "text": "dropdownConfig - Optional configuration to customize the dropdown\nbehavior (e.g., itemDisplayRule, caseSensitive)."
+          }, {
+            "name": "returns",
+            "text": "A promise that resolves once the dropdown is displayed."
+          }, {
             "name": "vegaVersion",
             "text": "2.75.0"
           }]
@@ -1360,8 +1649,11 @@ export class VegaInput {
         "return": "Promise<void>"
       },
       "docs": {
-        "text": "Invoke this method to hide the suggestions dropdown.",
+        "text": "Programmatically closes the suggestions dropdown.\n\nUse this method when you need to dismiss the dropdown in response to an\nexternal event (e.g., pressing Escape, clicking outside, or completing\na selection workflow).",
         "tags": [{
+            "name": "returns",
+            "text": "A promise that resolves once the dropdown is hidden."
+          }, {
             "name": "vegaVersion",
             "text": "2.75.0"
           }]