@globalpayments/vega 2.77.1 → 2.78.0

package/dist/types/components.d.ts

@@ -2032,158 +2032,185 @@ export namespace Components {
     }
     interface VegaInput {
         /**
-          * 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
          */
         "autoValidation": boolean;
         /**
-          * 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
          */
         "autocomplete": InputAutocompleteTypes;
         /**
-          * 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
          */
         "disableCopyPaste": boolean;
         /**
-          * 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
          */
         "disabled": boolean;
         /**
-          * 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
          */
         "doBlur": () => Promise<void>;
         /**
-          * 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
          */
         "doFocus": () => Promise<void>;
         /**
-          * Enforces proper email format validation for the input field.  It ensures that the user enters a valid email address according to    standard email formatting rules.
-          * @deprecated Please use `type='email'` instead.
+          * 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
          */
         "email": boolean;
         /**
-          * 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
          */
         "hideSuggestionsDropdown": () => Promise<void>;
         /**
-          * 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
          */
         "hint": string;
         /**
-          * A hint to the browser for which keyboard to display. Please refer to https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode for more details.
+          * Provides a hint to the browser about the type of virtual keyboard to display on mobile devices, independent of the `type` attribute.  - `'text'` — Standard text keyboard. - `'numeric'` — Numeric keypad (digits only), useful for PIN codes or quantities.  See https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode for more details.
           * @vegaVersion 2.71.0
          */
         "inputmode": 'text' | 'numeric';
         /**
-          * 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
          */
         "isValid": boolean;
         /**
-          * Specifies the label or title for the input field.  It provides descriptive text that helps identify the    purpose or content expected in the input field.
+          * Specifies the visible label text displayed above 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
          */
         "label": string;
         /**
-          * Specifies the properties for the suffix button associated with the input.  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. Use this to provide contextual actions such as a "Forgot password?" link, a help tooltip trigger, or any custom label-level action.  When clicked, the `vegaLabelButtonClick` event is emitted.
+          * @default null
           * @vegaVersion 2.68.0
          */
         "labelSuffixButtonConfig": Nullable<LabelSuffixButtonConfig>;
         /**
-          * @deprecated Please use `LabelSuffixButtonConfig` instead  Specifies the properties for the suffix button associated with the input.  It provides essential information and functionality related to the suffix button's role and behavior.
+          * @deprecated Please use `labelSuffixButtonConfig` instead.  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
          */
         "labelSuffixButtonProps": Nullable<LabelSuffixButtonProps>;
         /**
-          * Specifies the configuration for applying a mask to the input field.  It provides a way to define a specific format or pattern for the input value,    restricting and guiding the user's input accordingly.
+          * Configures input masking to automatically format the user's input according to a predefined pattern.  Supports built-in mask types (`'phone'`, `'zipcode'`, `'taxId'`, `'thousand-comma'`, `'number'`) as well as custom masks via `'custom'` or `'custom-formatter'` strategies.  Pass a single `MaskConfigType` object or an array of configs to apply multiple masks. Each config specifies the mask `type`, optional formatting `options`, and a `trigger` (`'input'` or `'blur'`) to control when formatting is applied.
           * @vegaVersion 1.3.0
          */
         "maskConfig": MaskConfigType | MaskConfigType[];
         /**
-          * 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
          */
         "max": number | 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
          */
         "maxLength": number;
         /**
-          * 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
          */
         "min": number | 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
          */
         "minLength": number;
         /**
-          * 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
          */
         "name": string;
         /**
-          * Specifies a placeholder string that displays as a temporary hint    or example inside the input field.  It indicates the expected format or pattern of the input.
+          * Sets the placeholder text displayed inside the input when the value is empty.  Use this to provide a short hint about the expected input format or content (e.g., `'Enter your email'`, `'MM/DD/YYYY'`). The placeholder text disappears as soon as the user begins typing.  **Note:** Placeholder text is not a substitute for a `label` — always provide a descriptive label for accessibility.
           * @vegaVersion 1.3.0
          */
         "placeholder": string;
         /**
-          * Specifies an icon or symbol that appears before the input field,    providing visual context or enhancing the aesthetic appearance    of the input.
+          * Displays a Vega icon at the leading (left) side of the input field, providing visual context about the expected input.  Pass a valid Vega icon name (e.g., `'search'`, `'email'`, `'lock'`). The icon is rendered inside the input container and does not affect the input's value or validation.
           * @vegaVersion 1.0.5
          */
         "prefixIcon": string;
         /**
-          * 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
          */
         "required": boolean;
         /**
-          * 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
          */
         "showClearIcon": boolean;
         /**
-          * 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
          */
         "showSuggestionsDropdown": (dropdownConfig?: VegaInputSuggestionsDropdownConfig) => Promise<void>;
         /**
-          * 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
          */
         "size": 'default' | 'small';
         /**
-          * Sets the source array of items for the suggestion dropdown.    You should set this property at least a empty array if you want enable the source mode suggestion dropdown feature.
+          * Provides the data source for the input's autocomplete suggestion dropdown.  Pass an array of `VegaDropdownSourceItem` objects to enable the suggestions feature. The dropdown appears as the user types, filtering items that match the current input value. When the user selects a suggestion, the `vegaSuggestionItemClick` event is emitted.  **Important:** You must set this property to at least an empty array (`[]`) to enable the suggestion dropdown. If left `undefined`, the feature is disabled.
           * @vegaVersion 2.75.0
          */
         "suggestionsDropdownSource": VegaDropdownSourceItem[];
         /**
-          * Defines the specific type or category of the input field.  It specifies the intended format or purpose of the    data to be entered by the user.
+          * Sets the HTML input type, which controls the browser's input behavior, on-screen keyboard layout, and built-in validation.  - `'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
          */
         "type": InputType;
         /**
-          * 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
          */
         "validationRules": FormFieldValidationRule<unknown>[];
         /**
-          * Represents a pre-set or default value for 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.  If the value is too long, it may be truncated with    an ellipsis for visual presentation.
+          * The current value of the input field.  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.  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
          */
         "value": string;
         /**
-          * 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
          */
         "valueUpdateTrigger": InputValueUpdateTriggeredBy;
@@ -2247,231 +2274,271 @@ export namespace Components {
     }
     interface VegaInputNumeric {
         /**
-          * Determines whether the input field should undergo automatic validation    during the user's input.
+          * Determines whether the numeric input should be validated automatically as the user interacts with it. When `true`, validation rules (including `required`, `min`, `max`, and custom `validationRules`) are evaluated and the `isValid` property is updated accordingly.  Set to `false` to handle validation manually.
+          * @default true
           * @vegaVersion 2.29.0
          */
         "autoValidation": boolean;
         /**
-          * Determines whether the input numeric field is disabled.
+          * Specifies whether the numeric input field is disabled. When `true`, the field is non-interactive — the user cannot type, focus, or use keyboard controls to change the value.
+          * @default false
           * @vegaVersion 2.29.0
          */
         "disabled": boolean;
         /**
-          * Provides a supplementary prompt message that    assists users in selecting the appropriate    value for the input numeric.
+          * Supplementary helper message displayed below the input field that assists users in understanding the expected value or range. Visible at all times (not just on focus).
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "hint": string;
         /**
-          * Determines whether the numeric input field should restrict    input to integers only.
+          * When `true`, restricts user input to whole numbers only — decimal points and fractional digits are rejected. Useful for fields like quantity, count, or age.
+          * @default false
           * @vegaVersion 2.29.0
          */
         "integerOnly": boolean;
         /**
-          * Specifies the validation status of the input numeric field.
+          * Reflects the current validation status of the numeric input.  - `true` — the field value passes all validation rules. - `false` — one or more validation rules have failed. - `null` — the field has not been validated yet (initial state).  This property is mutable: it is updated automatically when `autoValidation` is enabled, but can also be set manually to override the validation state.
+          * @default null
           * @vegaVersion 2.29.0
          */
         "isValid": boolean;
         /**
-          * Provides a descriptive text or string that serves    as the label or title for the input numeric.
+          * Specifies the visible label text rendered above the numeric input. The label identifies the purpose of the field and serves as the accessible name for screen readers.
+          * @default ''
           * @vegaVersion 2.29.0
          */
         "label": string;
         /**
-          * Specifies the step value for increasing or decreasing the input    when pressing the ArrowUp or ArrowDown key    while holding the Shift key.    It controls larger adjustments in the numeric input.
+          * The step value used when the user presses `Shift` + `ArrowUp` or `Shift` + `ArrowDown` to increment or decrement the value by a larger amount. This enables quick coarse-grained adjustments.  For smaller steps, see `minorIncrement`.
+          * @default 10
           * @vegaVersion 2.29.0
          */
         "majorIncrement": number;
         /**
-          * Sets the maximum allowable value for the numeric input.
+          * Sets the maximum allowable value for the numeric input. When set, the built-in `MaxNumberRule` is applied during validation. Values above this threshold will cause validation to fail.  Set to `null` to remove the upper bound.
+          * @default null
           * @vegaVersion 2.63.0
          */
         "max": number | null;
         /**
-          * Sets the minimum allowable value for the numeric input.
+          * Sets the minimum allowable value for the numeric input. When set, the built-in `MinNumberRule` is applied during validation. Values below this threshold will cause validation to fail.  Set to `null` to remove the lower bound.
+          * @default null
           * @vegaVersion 2.63.0
          */
         "min": number | null;
         /**
-          * Specifies the step value for increasing or decreasing the input    when pressing the ArrowUp or ArrowDown key.    It controls the finer adjustments in the numeric input.
+          * The step value used when the user presses the `ArrowUp` or `ArrowDown` key to increment or decrement the value. This controls fine-grained adjustments to the numeric input.  For larger jumps, see `majorIncrement` (activated with `Shift` + arrow keys).
+          * @default 1
           * @vegaVersion 2.29.0
          */
         "minorIncrement": number;
         /**
-          * Specifies a placeholder string that displays as a temporary hint    or example inside the input numeric field.
+          * Specifies placeholder text displayed inside the input field when it is empty. The placeholder disappears once the user begins typing and is typically used to indicate the expected format (e.g., `'0.00'`).
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "placeholder": string;
         /**
-          * Specifies an icon or symbol that appears before the input field,    providing visual context or enhancing the aesthetic appearance    of the input numeric.
+          * Name of a Vega icon rendered before (to the left of) the input field, providing additional visual context. The icon is purely decorative and does not affect the input value.
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "prefixIcon": string;
         /**
-          * Defines the prefix for the input numeric field. It provides additional context or information displayed    before the numeric value, helping to    clarify its purpose or usage.
+          * Text displayed before (to the left of) the numeric value inside the input field. Use this to provide contextual information such as a currency symbol (e.g., `'$'`) or unit prefix.
+          * @default ''
           * @vegaVersion 2.29.0
          */
         "prefixText": string;
         /**
-          * Determines whether the input numeric field is required.
+          * Determines whether the numeric input field must have a value before the form can be submitted. When `true`, the built-in `RequiredFieldRule` is applied during validation and a required indicator is shown on the label.
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "required": boolean;
         /**
-          * Determines whether the clear icon should be displayed or hidden.
+          * Controls whether a clear (×) icon button is shown inside the input field when a value is present. Clicking the button resets the value to an empty string and triggers the `vegaChange` event.
+          * @default true
           * @vegaVersion 2.53.0
          */
         "showClearIcon": boolean;
         /**
-          * Defines the size of the input numeric field.
+          * Controls the visual size of the numeric input field.  - `'medium'` — Standard height, suitable for most form layouts. - `'small'` — Compact height, useful for dense UIs or inline editing.
+          * @default 'medium'
           * @vegaVersion 2.29.0
          */
         "size": 'medium' | 'small';
         /**
-          * Defines the suffix for the input numeric field. It provides additional context or information displayed    after the numeric value, helping to    clarify its purpose or usage.
+          * Text displayed after (to the right of) the numeric value inside the input field. Use this to provide contextual information such as a unit suffix (e.g., `'%'`, `'kg'`, `'USD'`).
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "suffixText": string;
         /**
-          * Determines whether the numeric input field should format numbers    with thousand separators (commas) during user input.
+          * When `true`, the numeric input automatically formats the displayed value with thousand separators (commas) as the user types (e.g., `1,000,000`). The underlying `value` property remains an unformatted numeric string.
+          * @default false
           * @vegaVersion 2.29.0
          */
         "thousandComma": boolean;
         /**
-          * Defines custom validation rules for the input numeric field.
+          * An array of custom validation rules applied to the numeric input in addition to the built-in rules (`RequiredFieldRule`, `MinNumberRule`, `MaxNumberRule`). Each rule must implement the `FormFieldValidationRule` interface.  Rules are evaluated in order when `autoValidation` is enabled or when validation is triggered programmatically.
+          * @default []
           * @vegaVersion 2.29.0
          */
         "validationRules": FormFieldValidationRule1<unknown>[];
         /**
-          * Represents a pre-set or default value for the input numeric field.
+          * The current value of the numeric input field, represented as a string.  This property is mutable and will be updated when the user types or uses keyboard increment/decrement actions. It can also be set externally to pre-populate or reset the field. When `thousandComma` is enabled, the display is formatted with separators but the underlying value remains unformatted. Changes to this property trigger the `vegaChange` event.
+          * @default ''
           * @vegaVersion 2.29.0
          */
         "value": string;
     }
     interface VegaInputPasscode {
         /**
-          * Determines whether the input passcode should undergo automatic validation    during the user's input.
+          * Determines whether the passcode input should be validated automatically as the user types. When `true`, validation rules (including `required` and custom `validationRules`) are evaluated and the `isValid` property is updated accordingly.  Set to `false` to handle validation manually.
+          * @default true
           * @vegaVersion 2.66.0
          */
         "autoValidation": boolean;
         /**
-          * Determines whether the input passcode is disabled.
+          * Specifies whether the passcode input is disabled. When `true`, all individual input boxes become non-interactive — the user cannot type, paste, or focus any box.
+          * @default false
           * @vegaVersion 2.66.0
          */
         "disabled": boolean;
         /**
-          * Provides a supplementary prompt message that assists users in    understanding the expected value for the input passcode.
+          * Supplementary helper message displayed below the passcode input that assists users in understanding the expected input. For example, `'Enter the 4-digit code sent to your email'`.
+          * @default ''
           * @vegaVersion 2.66.0
          */
         "hint": string;
         /**
-          * Specifies the input type of the input passcode    Numeric type: only 0-9 are accepted    Text type: any non-space character is accepted    Spaces are rejected for all types
+          * Specifies the type of characters accepted by each passcode box.  - `'numeric'` — Only digits `0`–`9` are accepted. - `'text'` — Any non-space character is accepted.  Spaces are always rejected regardless of the selected type.
+          * @default 'numeric'
           * @vegaVersion 2.66.0
          */
         "inputType": 'numeric' | 'text';
         /**
-          * Specifies the validation status of the input passcode.
+          * Reflects the current validation status of the passcode input.  - `true` — the field value passes all validation rules. - `false` — one or more validation rules have failed. - `null` — the field has not been validated yet (initial state).  This property is mutable: it is updated automatically when `autoValidation` is enabled, but can also be set manually to override the validation state.
+          * @default null
           * @vegaVersion 2.66.0
          */
         "isValid": boolean | null;
         /**
-          * Specifies the label or title for the input passcode.  It provides descriptive text that helps identify the    purpose or content expected in the input passcode.
+          * Specifies the visible label text rendered above the passcode input. The label identifies the purpose of the field (e.g., "Enter verification code") and serves as the accessible name for screen readers.
+          * @default ''
           * @vegaVersion 2.66.0
          */
         "label": string;
         /**
-          * Specifies the number of input boxes to display.
+          * Specifies the number of individual input boxes rendered for the passcode. Each box accepts a single character. Common values are `4` for a PIN and `6` for a two-factor authentication code.
+          * @default 4
           * @vegaVersion 2.66.0
          */
         "length": number;
         /**
-          * Determines whether the input passcode field is required.
+          * Determines whether the passcode field must have a value before the form can be submitted. When `true`, the built-in `RequiredFieldRule` is applied during validation and a required indicator is shown on the label.
+          * @default false
           * @vegaVersion 2.66.0
          */
         "required": boolean;
         /**
-          * Defines the size of the input passcode,    specifying its width or length.
+          * Controls the visual size of the passcode input boxes.  - `'medium'` — Standard height, suitable for most form layouts. - `'small'` — Compact height, useful for dense UIs.
+          * @default 'medium'
           * @vegaVersion 2.66.0
          */
         "size": 'medium' | 'small';
         /**
-          * Defines custom validation rules for the input passcode.
+          * An array of custom validation rules applied to the passcode input in addition to the built-in `RequiredFieldRule`. Each rule must implement the `FormFieldValidationRule` interface.  Rules are evaluated in order when `autoValidation` is enabled or when validation is triggered programmatically.
+          * @default []
           * @vegaVersion 2.66.0
          */
         "validationRules": FormFieldValidationRule<unknown>[];
         /**
-          * Specifies the value of the input passcode.
+          * The current value of the passcode input, represented as a concatenated string of all box values (e.g., `'1234'` for a 4-digit passcode).  This property is mutable and reflected to the host element attribute. It updates as the user types into the boxes and can be set externally to pre-populate or reset the field.
+          * @default ''
           * @vegaVersion 2.66.0
          */
         "value": string;
     }
     interface VegaInputPhoneNumber {
         /**
-          * Specifies the countries available for selection.  Note: By default, 245 codes are provided, but loading all of them may take time. To improve performance, it is recommended to include only the necessary codes.
+          * An array of country codes available for selection in the country dropdown. Each entry must be a two-letter uppercase ISO 3166-1 alpha-2 code.  By default all 245 supported codes are loaded, but providing a smaller subset improves initial render performance.
+          * @default VegaCountryCode[] (all 245 codes)
           * @vegaVersion 2.18.0
-          * @defaultValue ['US', 'CN', ...]{@link VegaCountryCode }
          */
         "allowedCountryCodes": VegaCountryCode[];
         /**
-          * Determines whether the phone number input field should undergo automatic validation    during the user's input.
+          * Determines whether the phone number input should be validated automatically as the user interacts with it. When `true`, validation rules (including `required`, `ValidPhoneNumberRule`, and custom `validationRules`) are evaluated and the `isValid` property is updated accordingly.  Set to `false` to handle validation manually.
+          * @default true
           * @vegaVersion 2.18.0
          */
         "autoValidation": boolean;
         /**
-          * Specifies the default country calling code using the two-letter uppercase country code.
+          * Specifies the currently selected country using a two-letter uppercase ISO 3166-1 alpha-2 code (e.g., `'US'`, `'GB'`, `'CN'`). The country code determines the flag icon and calling code prefix displayed in the country selector. Changing this value updates the phone number prefix accordingly.
+          * @default 'US'
           * @vegaVersion 2.18.0
-          * @defaultValue US
          */
         "countryCode": VegaCountryCode;
         /**
-          * Determines whether the phone number input field is disabled.
+          * Specifies whether the phone number input field is disabled. When `true`, both the country selector and the phone number text field become non-interactive — the user cannot type, select a country, or focus any part of the component.
+          * @default false
           * @vegaVersion 2.18.0
          */
         "disabled": boolean;
         /**
-          * Specifies whether the phone number input field can be set to an empty value. - `true`:      The value property is cleared when the input field is empty. - `false`:      The value property is `+1` when no phone number is entered.
+          * Controls whether the `value` property can be an empty string.  - `true` — The `value` property is cleared to `''` when the user   deletes all digits from the input field. - `false` — The `value` property always retains at least the country   calling code prefix (e.g., `'+1'` for US) even when no phone number   digits have been entered.
+          * @default false
           * @vegaVersion 2.35.0
          */
         "emptyValueEnabled": boolean;
         /**
-          * Provides a supplementary prompt message that assists users in    understanding the expected value for the input field.
+          * Supplementary helper message displayed below the phone number input that assists users in understanding the expected value or provides additional context (e.g., `'We will send a verification code to this number'`).
+          * @default ''
           * @vegaVersion 2.18.0
          */
         "hint": string;
         /**
-          * Indicates whether the current value in the field is considered valid    based on the defined validation rules.
+          * Reflects the current validation status of the phone number input.  - `true` — the field value passes all validation rules. - `false` — one or more validation rules have failed. - `null` — the field has not been validated yet (initial state).  This property is mutable: it is updated automatically when `autoValidation` is enabled, but can also be set manually to override the validation state.
+          * @default null
           * @vegaVersion 2.18.0
          */
         "isValid": boolean;
         /**
-          * Specifies the label or title for the phone number input field.  It provides descriptive text that helps identify the    purpose or content expected in the input field.
+          * Specifies the visible label text rendered above the phone number input. The label identifies the purpose of the field and serves as the accessible name for screen readers.
+          * @default ''
           * @vegaVersion 2.18.0
          */
         "label": string;
         /**
-          * Specifies a placeholder string that displays as a temporary hint    or example inside the input field.
+          * Specifies placeholder text displayed inside the phone number text field when it is empty. The placeholder disappears once the user begins typing and is typically used to indicate the expected format (e.g., `'(555) 555-5555'`).
+          * @default undefined
           * @vegaVersion 2.18.0
          */
         "placeholder": string;
         /**
-          * Determines whether the phone number input field is required.
+          * Determines whether the phone number input field must have a value before the form can be submitted. When `true`, the built-in `InputPhoneNumberRequiredRule` is applied during validation and a required indicator is shown on the label.
+          * @default false
           * @vegaVersion 2.18.0
          */
         "required": boolean;
         /**
-          * Specifies the size of the phone number input field.
+          * Controls the visual size of the phone number input field.  - `'default'` — Standard height, suitable for most form layouts. - `'small'` — Compact height, useful for dense UIs.
+          * @default 'default'
           * @vegaVersion 2.18.0
          */
         "size": 'default' | 'small';
         /**
-          * Specifies custom validation rules for the phone number input field.
+          * An array of custom validation rules applied to the phone number input in addition to the built-in rules (`InputPhoneNumberRequiredRule`, `ValidPhoneNumberRule`). Each rule must implement the `FormFieldValidationRule` interface.  Rules are evaluated in order when `autoValidation` is enabled or when validation is triggered programmatically.
+          * @default []
           * @vegaVersion 2.18.0
          */
         "validationRules": FormFieldValidationRule<unknown>[];
         /**
-          * Specifies the value of the phone number input in [E.164]{@link https ://en.wikipedia.org/wiki/E.164} format.
-          * @VegaWarning - Note: The input phone number field will always have a value. If no phone number is entered, the default format is `+{default_country_code}`. - For example, if the default country code is US, the default value will be `+1`.
+          * The current value of the phone number input in [E.164](https://en.wikipedia.org/wiki/E.164) format (e.g., `'+14155552671'`).  This property is mutable and reflected to the host element attribute. It updates as the user types and can be set externally to pre-populate or reset the field. When `emptyValueEnabled` is `false` and no digits have been entered, the value defaults to the country calling code prefix (e.g., `'+1'` for US).
+          * @default '+1'
           * @vegaVersion 2.18.0
-          * @defaultValue +1
          */
         "value": string;
     }
@@ -2619,7 +2686,7 @@ export namespace Components {
          */
         "selectType": SelectType;
         /**
-          * Allows customization of the text displayed within the    select field when single or multiple items are selected.    The default format for the selected label is    `${number of selected items} Selected` for multiple mode only.  To enable all modes, use the `SelectedLabelTypeForAllModes` type. 		For single mode, the default format is the `displayName` of the selected item if not set 		For multiple mode, the default format is `${number of selected items} Selected` if not set
+          * Allows customization of the text displayed within the    select field when single or multiple items are selected.    The default format for the selected label is    `{0} Selected` for multiple mode only.  To enable all modes, use the `SelectedLabelTypeForAllModes` type. 		For single mode, the default format is the `displayName` of the selected item if not set 		For multiple mode, the default format is `{0} Selected` if not set
           * @vegaVersion 1.35.0
          */
         "selectedLabel": SelectedLabelType | SelectedLabelTypeForAllModes;
@@ -4256,77 +4323,92 @@ export namespace Components {
     }
     interface VegaTextarea {
         /**
-          * Determines whether automatic validation should be    implemented for the text area.
+          * Determines whether the text area should be validated automatically as the user types. When `true`, validation rules (including `required`, `minLength`, `maxLength`, and custom `validationRules`) are evaluated on blur and the `isValid` property is updated accordingly.  Set to `false` to handle validation manually.
+          * @default true
           * @vegaVersion 1.11.0
          */
         "autoValidation": boolean;
         /**
-          * Specifies whether the text area is disabled.
+          * Specifies whether the text area is disabled. When `true`, the text area is non-interactive — the user cannot type, focus, or select the field. The disabled state is reflected as an HTML attribute for CSS styling.
+          * @default false
           * @vegaVersion 1.11.0
          */
         "disabled": boolean;
         /**
-          * Provides a supplementary prompt message that assists users in    understanding the expected value within the text area.
+          * Provides a supplementary helper message displayed below the text area that assists users in understanding the expected value or format.  The hint is visible at all times (not just on focus) and is typically used for guidance such as character requirements or formatting rules.
+          * @default ''
           * @vegaVersion 1.11.0
          */
         "hint": string;
         /**
-          * Specifies the validation status of the    text area component.
+          * Reflects the current validation status of the text area.  - `true` — the field value passes all validation rules. - `false` — one or more validation rules have failed. - `null` — the field has not been validated yet (initial state).  This property is mutable: it is updated automatically when `autoValidation` is enabled, but can also be set manually to override the validation state. The value is reflected as an HTML attribute.
+          * @default null
           * @vegaVersion 1.11.0
          */
         "isValid": boolean;
         /**
-          * Specifies the label or title for the text area.  It provides descriptive text that helps identify the    purpose or content expected within the text area.
+          * Specifies the visible label text rendered above the text area. The label helps identify the purpose or content expected within the field and also serves as the accessible `aria-label` for screen readers when present.  Clicking the label will focus the text area.
+          * @default ''
           * @vegaVersion 1.11.0
          */
         "label": string;
         /**
-          * Specifies the properties for the suffix button associated with the input.  It provides essential information and functionality  related to the suffix button's role and behavior.
+          * Configuration object for an optional suffix button rendered beside the field label. Use this to provide an inline action (e.g., a help or info button) next to the label text.  When the button is clicked, the `vegaLabelButtonClick` event is emitted. Set to `null` to hide the suffix button.
+          * @default null
           * @vegaVersion 2.68.0
          */
         "labelSuffixButtonConfig": Nullable<LabelSuffixButtonConfig>;
         /**
-          * Specifies the maximum number of characters (UTF-16 code units)    that the user can enter in the text area.
+          * Specifies the maximum number of characters (UTF-16 code units) that the user can enter in the text area. The native `maxlength` attribute is applied to the inner `<textarea>` element.  When `showCounter` is `true`, the maximum value is displayed alongside the current character count (e.g., `42/200`). Exceeding this limit triggers a visual warning on the counter and fails the `MaxStringLengthRule` during validation.  Set to `null` to allow unlimited input.
+          * @default null
           * @vegaVersion 1.11.0
          */
         "maxLength": number;
         /**
-          * Specifies the minimum number of characters (UTF-16 code units)   that the user must enter in the text area.
+          * Specifies the minimum number of characters (UTF-16 code units) that the user must enter in the text area for the value to be considered valid. The native `minlength` attribute is applied to the inner `<textarea>` element.  When set, the `MinStringLengthRule` is applied during validation. Set to `null` to impose no minimum length.
+          * @default null
           * @vegaVersion 1.11.0
          */
         "minLength": number;
         /**
-          * Specifies a placeholder string that displays as a    temporary hint or example within the text area.  It indicates the expected format or pattern of    the input within the text area.
+          * Specifies a placeholder string that displays as a temporary hint or example within the text area. The placeholder text is shown when the field is empty and disappears once the user begins typing.  Use this to indicate the expected format or content of the input, for example `'Enter your comments here...'`.
+          * @default ''
           * @vegaVersion 1.11.0
          */
         "placeholder": string;
         /**
-          * Determines whether the content of the textarea must be    provided by the user before submitting the form or    completing the input process.
+          * Determines whether the text area must have a non-empty value before the form can be submitted. When `true`, a required-field indicator is shown on the label and the built-in `RequiredFieldRule` is applied during validation.
+          * @default false
           * @vegaVersion 1.11.0
          */
         "required": boolean;
         /**
-          * Determines whether the text area is vertically resizable.
+          * Determines whether the user can vertically resize the text area by dragging its bottom-right corner. When `false`, the resize handle is hidden via CSS and the text area height is fixed.
+          * @default true
           * @vegaVersion 2.19.0
          */
         "resizable": boolean;
         /**
-          * Specifies the number of visible lines in the textarea. The value must be an integer greater than or equal to 2.
+          * Specifies the number of visible text lines in the text area, controlling its initial height. Accepts integers ≥ 2. For optimal display, values below 2 are internally adjusted to 4 rows.
+          * @default 5
           * @vegaVersion 2.63.0
          */
         "rows": number;
         /**
-          * Determines whether to display a character counter    for the textarea.
+          * Determines whether to display a live character counter below the text area.  When `true`, the counter shows the current character count. If `maxLength` is also set, the counter displays in the format `current/max` and visually highlights when the limit is exceeded.
+          * @default false
           * @vegaVersion 1.11.0
          */
         "showCounter": boolean;
         /**
-          * Specifies custom validation rules for the text area.
+          * An array of custom validation rules applied to the text area in addition to the built-in rules (`RequiredFieldRule`, `MinStringLengthRule`, `MaxStringLengthRule`). Each rule must implement the `FormFieldValidationRule` interface.  Rules are evaluated in order when `autoValidation` is enabled or when validation is triggered programmatically.
+          * @default []
           * @vegaVersion 1.11.0
          */
         "validationRules": FormFieldValidationRule<unknown>[];
         /**
-          * Specifies the initial value or content of the    textarea field.
+          * The current value (content) of the text area field.  This property is mutable and will be updated programmatically when the user types into the text area. It can also be set externally to pre-populate or reset the field. Changes to this property trigger the `vegaChange` event and update the character counter if `showCounter` is enabled. Supports two-way binding in framework wrappers.
+          * @default ''
           * @vegaVersion 1.11.0
          */
         "value": string;
@@ -8021,215 +8103,251 @@ declare namespace LocalJSX {
     }
     interface VegaInput {
         /**
-          * 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
          */
         "autoValidation"?: boolean;
         /**
-          * 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
          */
         "autocomplete"?: InputAutocompleteTypes;
         /**
-          * 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
          */
         "disableCopyPaste"?: boolean;
         /**
-          * 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
          */
         "disabled"?: boolean;
         /**
-          * Enforces proper email format validation for the input field.  It ensures that the user enters a valid email address according to    standard email formatting rules.
-          * @deprecated Please use `type='email'` instead.
+          * 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
          */
         "email"?: boolean;
         /**
-          * 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
          */
         "hint"?: string;
         /**
-          * A hint to the browser for which keyboard to display. Please refer to https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode for more details.
+          * Provides a hint to the browser about the type of virtual keyboard to display on mobile devices, independent of the `type` attribute.  - `'text'` — Standard text keyboard. - `'numeric'` — Numeric keypad (digits only), useful for PIN codes or quantities.  See https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode for more details.
           * @vegaVersion 2.71.0
          */
         "inputmode"?: 'text' | 'numeric';
         /**
-          * 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
          */
         "isValid"?: boolean;
         /**
-          * Specifies the label or title for the input field.  It provides descriptive text that helps identify the    purpose or content expected in the input field.
+          * Specifies the visible label text displayed above 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
          */
         "label"?: string;
         /**
-          * Specifies the properties for the suffix button associated with the input.  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. Use this to provide contextual actions such as a "Forgot password?" link, a help tooltip trigger, or any custom label-level action.  When clicked, the `vegaLabelButtonClick` event is emitted.
+          * @default null
           * @vegaVersion 2.68.0
          */
         "labelSuffixButtonConfig"?: Nullable<LabelSuffixButtonConfig>;
         /**
-          * @deprecated Please use `LabelSuffixButtonConfig` instead  Specifies the properties for the suffix button associated with the input.  It provides essential information and functionality related to the suffix button's role and behavior.
+          * @deprecated Please use `labelSuffixButtonConfig` instead.  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
          */
         "labelSuffixButtonProps"?: Nullable<LabelSuffixButtonProps>;
         /**
-          * Specifies the configuration for applying a mask to the input field.  It provides a way to define a specific format or pattern for the input value,    restricting and guiding the user's input accordingly.
+          * Configures input masking to automatically format the user's input according to a predefined pattern.  Supports built-in mask types (`'phone'`, `'zipcode'`, `'taxId'`, `'thousand-comma'`, `'number'`) as well as custom masks via `'custom'` or `'custom-formatter'` strategies.  Pass a single `MaskConfigType` object or an array of configs to apply multiple masks. Each config specifies the mask `type`, optional formatting `options`, and a `trigger` (`'input'` or `'blur'`) to control when formatting is applied.
           * @vegaVersion 1.3.0
          */
         "maskConfig"?: MaskConfigType | MaskConfigType[];
         /**
-          * 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
          */
         "max"?: number | 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
          */
         "maxLength"?: number;
         /**
-          * 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
          */
         "min"?: number | 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
          */
         "minLength"?: number;
         /**
-          * 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
          */
         "name"?: string;
         /**
-          * An event emitter notifying the blur of the inner input element.
+          * Native-namespace alias for the `vegaBlur` event.  Emitted at the same time and under the same conditions as `vegaBlur`. Use this event when integrating with frameworks that expect native-style event names.
+          * @eventDetail `undefined` — No payload; listen for the event occurrence only.
           * @eventSemantics namespace:native
           * @vegaVersion 2.0.0
          */
         "onBlur"?: (event: VegaInputCustomEvent<undefined>) => void;
         /**
-          * An event emitter notifying a value change.
+          * Native-namespace alias for the `vegaChange` event.  Emitted at the same time and under the same conditions as `vegaChange`. Use this event when integrating with frameworks that expect native-style event names (e.g., `@change` in Vue or Angular).
+          * @eventDetail `string` — The current input value after the change.
           * @eventSemantics namespace:native
           * @vegaVersion 2.0.0
          */
         "onChange"?: (event: VegaInputCustomEvent<string>) => void;
         /**
-          * An event emitter notifying the focus of the inner input element.
+          * Native-namespace alias for the `vegaFocus` event.  Emitted at the same time and under the same conditions as `vegaFocus`. Use this event when integrating with frameworks that expect native-style event names.
+          * @eventDetail `undefined` — No payload; listen for the event occurrence only.
           * @eventSemantics namespace:native
           * @vegaVersion 2.0.0
          */
         "onFocus"?: (event: VegaInputCustomEvent<undefined>) => void;
         /**
-          * An event emitter notifying that the suffix button associated with the field label has been clicked.
+          * Native-namespace alias for the `vegaLabelButtonClick` event.  Emitted at the same time and under the same conditions as `vegaLabelButtonClick`. Use this event when integrating with frameworks that expect native-style event names.
+          * @eventDetail `void` — No payload.
           * @eventSemantics namespace:native
           * @vegaVersion 2.25.0
          */
         "onLabelButtonClick"?: (event: VegaInputCustomEvent<any>) => void;
         /**
-          * An event emitter notifying a value change by input action of native input dom.
+          * Native-namespace alias for the `vegaNativeInputChange` event.  Emitted at the same time and under the same conditions as `vegaNativeInputChange`. Use this event when integrating with frameworks that expect native-style event names.
+          * @eventDetail `string` — The raw value from the native input element.
           * @eventSemantics namespace:native
           * @vegaVersion 2.75.0
          */
         "onNativeInputChange"?: (event: VegaInputCustomEvent<string>) => void;
         /**
-          * An event emitter notifying the paste of the inner input element.
+          * Native-namespace alias for the `vegaPaste` event.  Emitted at the same time and under the same conditions as `vegaPaste`. Use this event when integrating with frameworks that expect native-style event names.
+          * @eventDetail `DataTransferType` — An object containing the pasted data, including the MIME type and raw text content from the clipboard.
           * @eventSemantics namespace:native
           * @vegaVersion 2.66.0
          */
         "onPaste"?: (event: VegaInputCustomEvent<DataTransferType>) => void;
         /**
-          * An event emitter notifying the click of a suggestion item.
+          * Native-namespace alias for the `vegaSuggestionItemClick` event.  Emitted at the same time and under the same conditions as `vegaSuggestionItemClick`. Use this event when integrating with frameworks that expect native-style event names.
+          * @eventDetail `VegaDropdownSourceItem` — The full data object of the selected suggestion item, including its `label`, `value`, and any custom properties.
           * @eventSemantics namespace:native
           * @vegaVersion 2.75.0
          */
         "onSuggestionItemClick"?: (event: VegaInputCustomEvent<VegaDropdownSourceItem>) => void;
         /**
-          * An event emitter notifying the blur of the inner input element.
+          * Emitted when the input field loses focus.  This event fires after the underlying native `<input>` element's `blur` event. Useful for triggering validation, saving state, or updating UI when the user navigates away from the field.
+          * @eventDetail `undefined` — No payload; listen for the event occurrence only.
           * @vegaVersion 1.3.0
          */
         "onVegaBlur"?: (event: VegaInputCustomEvent<undefined>) => void;
         /**
-          * An event emitter notifying a value change.
+          * Emitted when the input value changes.  The timing of this event depends on the `valueUpdateTrigger` prop: - When `valueUpdateTrigger` is `'input'` (default), fires on every keystroke. - When `valueUpdateTrigger` is `'change'`, fires on blur or when the user presses Enter.  Also fires when the user clicks the clear icon or when the value is programmatically updated.
+          * @eventDetail `string` — The current input value after the change.
           * @vegaVersion 1.0.10
          */
         "onVegaChange"?: (event: VegaInputCustomEvent<string>) => void;
         /**
-          * An event emitter notifying the focus of the inner input element.
+          * Emitted when the input field receives focus.  This event fires after the underlying native `<input>` element's `focus` event, including when focus is set programmatically via the `doFocus()` method. Useful for highlighting the field, showing contextual help, or opening a suggestions dropdown.
+          * @eventDetail `undefined` — No payload; listen for the event occurrence only.
           * @vegaVersion 1.12.0
          */
         "onVegaFocus"?: (event: VegaInputCustomEvent<undefined>) => void;
         /**
-          * An event emitter notifying that the suffix button associated with the field label has been clicked.
+          * Emitted when the user clicks the suffix button in the field label.  This event only fires when a `labelSuffixButtonConfig` (or the deprecated `labelSuffixButtonProps`) is provided. Use it to handle contextual actions such as opening a tooltip, navigating to a help page, or triggering a "Forgot password?" flow.
+          * @eventDetail `void` — No payload.
           * @vegaVersion 2.25.0
          */
         "onVegaLabelButtonClick"?: (event: VegaInputCustomEvent<any>) => void;
         /**
-          * An event emitter notifying a value change by input action of native input dom.
+          * Emitted on every native `input` event from the underlying `<input>` element, regardless of the `valueUpdateTrigger` setting.  This event fires on every keystroke and provides the raw input value. Use this for real-time monitoring (e.g., driving a suggestions dropdown) while keeping `vegaChange` set to `'change'` trigger for the main value binding.
+          * @eventDetail `string` — The raw value from the native input element.
           * @vegaVersion 2.75.0
          */
         "onVegaNativeInputChange"?: (event: VegaInputCustomEvent<string>) => void;
         /**
-          * An event emitter notifying the paste of the inner input element.
+          * Emitted when the user pastes content into the input field.  This event fires regardless of the `disableCopyPaste` setting — the paste action is blocked visually, but the event still propagates for tracking purposes. Use this to inspect or transform pasted data before it is applied.
+          * @eventDetail `DataTransferType` — An object containing the pasted data, including the MIME type and raw text content from the clipboard.
           * @vegaVersion 2.66.0
          */
         "onVegaPaste"?: (event: VegaInputCustomEvent<DataTransferType>) => void;
         /**
-          * An event emitter notifying the click of a suggestion item.
+          * Emitted when the user selects an item from the suggestions dropdown.  This event only fires when the `suggestionsDropdownSource` prop is set. Use it to respond to the user's selection — for example, to populate related fields, navigate to a detail page, or trigger a search.
+          * @eventDetail `VegaDropdownSourceItem` — The full data object of the selected suggestion item, including its `label`, `value`, and any custom properties.
           * @vegaVersion 2.75.0
          */
         "onVegaSuggestionItemClick"?: (event: VegaInputCustomEvent<VegaDropdownSourceItem>) => void;
         /**
-          * Specifies a placeholder string that displays as a temporary hint    or example inside the input field.  It indicates the expected format or pattern of the input.
+          * Sets the placeholder text displayed inside the input when the value is empty.  Use this to provide a short hint about the expected input format or content (e.g., `'Enter your email'`, `'MM/DD/YYYY'`). The placeholder text disappears as soon as the user begins typing.  **Note:** Placeholder text is not a substitute for a `label` — always provide a descriptive label for accessibility.
           * @vegaVersion 1.3.0
          */
         "placeholder"?: string;
         /**
-          * Specifies an icon or symbol that appears before the input field,    providing visual context or enhancing the aesthetic appearance    of the input.
+          * Displays a Vega icon at the leading (left) side of the input field, providing visual context about the expected input.  Pass a valid Vega icon name (e.g., `'search'`, `'email'`, `'lock'`). The icon is rendered inside the input container and does not affect the input's value or validation.
           * @vegaVersion 1.0.5
          */
         "prefixIcon"?: string;
         /**
-          * 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
          */
         "required"?: boolean;
         /**
-          * 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
          */
         "showClearIcon"?: boolean;
         /**
-          * 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
          */
         "size"?: 'default' | 'small';
         /**
-          * Sets the source array of items for the suggestion dropdown.    You should set this property at least a empty array if you want enable the source mode suggestion dropdown feature.
+          * Provides the data source for the input's autocomplete suggestion dropdown.  Pass an array of `VegaDropdownSourceItem` objects to enable the suggestions feature. The dropdown appears as the user types, filtering items that match the current input value. When the user selects a suggestion, the `vegaSuggestionItemClick` event is emitted.  **Important:** You must set this property to at least an empty array (`[]`) to enable the suggestion dropdown. If left `undefined`, the feature is disabled.
           * @vegaVersion 2.75.0
          */
         "suggestionsDropdownSource"?: VegaDropdownSourceItem[];
         /**
-          * Defines the specific type or category of the input field.  It specifies the intended format or purpose of the    data to be entered by the user.
+          * Sets the HTML input type, which controls the browser's input behavior, on-screen keyboard layout, and built-in validation.  - `'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
          */
         "type"?: InputType;
         /**
-          * 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
          */
         "validationRules"?: FormFieldValidationRule<unknown>[];
         /**
-          * Represents a pre-set or default value for 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.  If the value is too long, it may be truncated with    an ellipsis for visual presentation.
+          * The current value of the input field.  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.  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
          */
         "value"?: string;
         /**
-          * 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
          */
         "valueUpdateTrigger"?: InputValueUpdateTriggeredBy;
@@ -8326,286 +8444,336 @@ declare namespace LocalJSX {
     }
     interface VegaInputNumeric {
         /**
-          * Determines whether the input field should undergo automatic validation    during the user's input.
+          * Determines whether the numeric input should be validated automatically as the user interacts with it. When `true`, validation rules (including `required`, `min`, `max`, and custom `validationRules`) are evaluated and the `isValid` property is updated accordingly.  Set to `false` to handle validation manually.
+          * @default true
           * @vegaVersion 2.29.0
          */
         "autoValidation"?: boolean;
         /**
-          * Determines whether the input numeric field is disabled.
+          * Specifies whether the numeric input field is disabled. When `true`, the field is non-interactive — the user cannot type, focus, or use keyboard controls to change the value.
+          * @default false
           * @vegaVersion 2.29.0
          */
         "disabled"?: boolean;
         /**
-          * Provides a supplementary prompt message that    assists users in selecting the appropriate    value for the input numeric.
+          * Supplementary helper message displayed below the input field that assists users in understanding the expected value or range. Visible at all times (not just on focus).
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "hint"?: string;
         /**
-          * Determines whether the numeric input field should restrict    input to integers only.
+          * When `true`, restricts user input to whole numbers only — decimal points and fractional digits are rejected. Useful for fields like quantity, count, or age.
+          * @default false
           * @vegaVersion 2.29.0
          */
         "integerOnly"?: boolean;
         /**
-          * Specifies the validation status of the input numeric field.
+          * Reflects the current validation status of the numeric input.  - `true` — the field value passes all validation rules. - `false` — one or more validation rules have failed. - `null` — the field has not been validated yet (initial state).  This property is mutable: it is updated automatically when `autoValidation` is enabled, but can also be set manually to override the validation state.
+          * @default null
           * @vegaVersion 2.29.0
          */
         "isValid"?: boolean;
         /**
-          * Provides a descriptive text or string that serves    as the label or title for the input numeric.
+          * Specifies the visible label text rendered above the numeric input. The label identifies the purpose of the field and serves as the accessible name for screen readers.
+          * @default ''
           * @vegaVersion 2.29.0
          */
         "label"?: string;
         /**
-          * Specifies the step value for increasing or decreasing the input    when pressing the ArrowUp or ArrowDown key    while holding the Shift key.    It controls larger adjustments in the numeric input.
+          * The step value used when the user presses `Shift` + `ArrowUp` or `Shift` + `ArrowDown` to increment or decrement the value by a larger amount. This enables quick coarse-grained adjustments.  For smaller steps, see `minorIncrement`.
+          * @default 10
           * @vegaVersion 2.29.0
          */
         "majorIncrement"?: number;
         /**
-          * Sets the maximum allowable value for the numeric input.
+          * Sets the maximum allowable value for the numeric input. When set, the built-in `MaxNumberRule` is applied during validation. Values above this threshold will cause validation to fail.  Set to `null` to remove the upper bound.
+          * @default null
           * @vegaVersion 2.63.0
          */
         "max"?: number | null;
         /**
-          * Sets the minimum allowable value for the numeric input.
+          * Sets the minimum allowable value for the numeric input. When set, the built-in `MinNumberRule` is applied during validation. Values below this threshold will cause validation to fail.  Set to `null` to remove the lower bound.
+          * @default null
           * @vegaVersion 2.63.0
          */
         "min"?: number | null;
         /**
-          * Specifies the step value for increasing or decreasing the input    when pressing the ArrowUp or ArrowDown key.    It controls the finer adjustments in the numeric input.
+          * The step value used when the user presses the `ArrowUp` or `ArrowDown` key to increment or decrement the value. This controls fine-grained adjustments to the numeric input.  For larger jumps, see `majorIncrement` (activated with `Shift` + arrow keys).
+          * @default 1
           * @vegaVersion 2.29.0
          */
         "minorIncrement"?: number;
         /**
-          * An event emitter notifying a value change.
+          * Native-equivalent mirror of `vegaChange`. Fires with the same payload and at the same time, allowing consumers to listen using the standard `change` event name.
+          * @eventDetail number
           * @eventSemantics namespace:native
           * @vegaVersion 2.29.0
          */
         "onChange"?: (event: VegaInputNumericCustomEvent<number>) => void;
         /**
-          * An event emitter notifying a value change.
+          * Fires whenever the numeric input's value changes — including typing, keyboard increment/decrement, clearing, and programmatic updates.  The event detail contains the new numeric value (`number`), or `NaN` when the field is empty.
+          * @eventDetail number
           * @vegaVersion 2.29.0
          */
         "onVegaChange"?: (event: VegaInputNumericCustomEvent<number>) => void;
         /**
-          * Specifies a placeholder string that displays as a temporary hint    or example inside the input numeric field.
+          * Specifies placeholder text displayed inside the input field when it is empty. The placeholder disappears once the user begins typing and is typically used to indicate the expected format (e.g., `'0.00'`).
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "placeholder"?: string;
         /**
-          * Specifies an icon or symbol that appears before the input field,    providing visual context or enhancing the aesthetic appearance    of the input numeric.
+          * Name of a Vega icon rendered before (to the left of) the input field, providing additional visual context. The icon is purely decorative and does not affect the input value.
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "prefixIcon"?: string;
         /**
-          * Defines the prefix for the input numeric field. It provides additional context or information displayed    before the numeric value, helping to    clarify its purpose or usage.
+          * Text displayed before (to the left of) the numeric value inside the input field. Use this to provide contextual information such as a currency symbol (e.g., `'$'`) or unit prefix.
+          * @default ''
           * @vegaVersion 2.29.0
          */
         "prefixText"?: string;
         /**
-          * Determines whether the input numeric field is required.
+          * Determines whether the numeric input field must have a value before the form can be submitted. When `true`, the built-in `RequiredFieldRule` is applied during validation and a required indicator is shown on the label.
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "required"?: boolean;
         /**
-          * Determines whether the clear icon should be displayed or hidden.
+          * Controls whether a clear (×) icon button is shown inside the input field when a value is present. Clicking the button resets the value to an empty string and triggers the `vegaChange` event.
+          * @default true
           * @vegaVersion 2.53.0
          */
         "showClearIcon"?: boolean;
         /**
-          * Defines the size of the input numeric field.
+          * Controls the visual size of the numeric input field.  - `'medium'` — Standard height, suitable for most form layouts. - `'small'` — Compact height, useful for dense UIs or inline editing.
+          * @default 'medium'
           * @vegaVersion 2.29.0
          */
         "size"?: 'medium' | 'small';
         /**
-          * Defines the suffix for the input numeric field. It provides additional context or information displayed    after the numeric value, helping to    clarify its purpose or usage.
+          * Text displayed after (to the right of) the numeric value inside the input field. Use this to provide contextual information such as a unit suffix (e.g., `'%'`, `'kg'`, `'USD'`).
+          * @default undefined
           * @vegaVersion 2.29.0
          */
         "suffixText"?: string;
         /**
-          * Determines whether the numeric input field should format numbers    with thousand separators (commas) during user input.
+          * When `true`, the numeric input automatically formats the displayed value with thousand separators (commas) as the user types (e.g., `1,000,000`). The underlying `value` property remains an unformatted numeric string.
+          * @default false
           * @vegaVersion 2.29.0
          */
         "thousandComma"?: boolean;
         /**
-          * Defines custom validation rules for the input numeric field.
+          * An array of custom validation rules applied to the numeric input in addition to the built-in rules (`RequiredFieldRule`, `MinNumberRule`, `MaxNumberRule`). Each rule must implement the `FormFieldValidationRule` interface.  Rules are evaluated in order when `autoValidation` is enabled or when validation is triggered programmatically.
+          * @default []
           * @vegaVersion 2.29.0
          */
         "validationRules"?: FormFieldValidationRule1<unknown>[];
         /**
-          * Represents a pre-set or default value for the input numeric field.
+          * The current value of the numeric input field, represented as a string.  This property is mutable and will be updated when the user types or uses keyboard increment/decrement actions. It can also be set externally to pre-populate or reset the field. When `thousandComma` is enabled, the display is formatted with separators but the underlying value remains unformatted. Changes to this property trigger the `vegaChange` event.
+          * @default ''
           * @vegaVersion 2.29.0
          */
         "value"?: string;
     }
     interface VegaInputPasscode {
         /**
-          * Determines whether the input passcode should undergo automatic validation    during the user's input.
+          * Determines whether the passcode input should be validated automatically as the user types. When `true`, validation rules (including `required` and custom `validationRules`) are evaluated and the `isValid` property is updated accordingly.  Set to `false` to handle validation manually.
+          * @default true
           * @vegaVersion 2.66.0
          */
         "autoValidation"?: boolean;
         /**
-          * Determines whether the input passcode is disabled.
+          * Specifies whether the passcode input is disabled. When `true`, all individual input boxes become non-interactive — the user cannot type, paste, or focus any box.
+          * @default false
           * @vegaVersion 2.66.0
          */
         "disabled"?: boolean;
         /**
-          * Provides a supplementary prompt message that assists users in    understanding the expected value for the input passcode.
+          * Supplementary helper message displayed below the passcode input that assists users in understanding the expected input. For example, `'Enter the 4-digit code sent to your email'`.
+          * @default ''
           * @vegaVersion 2.66.0
          */
         "hint"?: string;
         /**
-          * Specifies the input type of the input passcode    Numeric type: only 0-9 are accepted    Text type: any non-space character is accepted    Spaces are rejected for all types
+          * Specifies the type of characters accepted by each passcode box.  - `'numeric'` — Only digits `0`–`9` are accepted. - `'text'` — Any non-space character is accepted.  Spaces are always rejected regardless of the selected type.
+          * @default 'numeric'
           * @vegaVersion 2.66.0
          */
         "inputType"?: 'numeric' | 'text';
         /**
-          * Specifies the validation status of the input passcode.
+          * Reflects the current validation status of the passcode input.  - `true` — the field value passes all validation rules. - `false` — one or more validation rules have failed. - `null` — the field has not been validated yet (initial state).  This property is mutable: it is updated automatically when `autoValidation` is enabled, but can also be set manually to override the validation state.
+          * @default null
           * @vegaVersion 2.66.0
          */
         "isValid"?: boolean | null;
         /**
-          * Specifies the label or title for the input passcode.  It provides descriptive text that helps identify the    purpose or content expected in the input passcode.
+          * Specifies the visible label text rendered above the passcode input. The label identifies the purpose of the field (e.g., "Enter verification code") and serves as the accessible name for screen readers.
+          * @default ''
           * @vegaVersion 2.66.0
          */
         "label"?: string;
         /**
-          * Specifies the number of input boxes to display.
+          * Specifies the number of individual input boxes rendered for the passcode. Each box accepts a single character. Common values are `4` for a PIN and `6` for a two-factor authentication code.
+          * @default 4
           * @vegaVersion 2.66.0
          */
         "length"?: number;
         /**
-          * An event emitter notifying the change of the value in the input passcode,    whether triggered programmatically or through user interaction.
+          * Native-equivalent mirror of `vegaChange`. Fires with the same payload and at the same time, allowing consumers to listen using the standard `change` event name.
+          * @eventDetail string
           * @eventSemantics namespace:native
           * @vegaVersion 2.66.0
          */
         "onChange"?: (event: VegaInputPasscodeCustomEvent<string>) => void;
         /**
-          * An event emitter notifying the completion of all input passcode boxes.    whether triggered programmatically or through user interaction.
+          * Native-equivalent mirror of `vegaComplete`. Fires with the same payload and at the same time, allowing consumers to listen using the standard `complete` event name.
+          * @eventDetail string
           * @eventSemantics namespace:native
           * @vegaVersion 2.66.0
          */
         "onComplete"?: (event: VegaInputPasscodeCustomEvent<string>) => void;
         /**
-          * An event emitter notifying the change of the value in the input passcode,    whether triggered programmatically or through user interaction.
+          * Fires whenever the passcode value changes — each time a character is entered, deleted, or pasted into any box. The event detail contains the concatenated string of all box values at the time of the change.
+          * @eventDetail string
           * @vegaVersion 2.66.0
          */
         "onVegaChange"?: (event: VegaInputPasscodeCustomEvent<string>) => void;
         /**
-          * An event emitter notifying the completion of all input passcode boxes.    whether triggered programmatically or through user interaction.
+          * Fires when all passcode boxes have been filled (i.e., the value length equals the configured `length`). The event detail contains the complete passcode string. Useful for triggering auto-submit or verification workflows.
+          * @eventDetail string
           * @vegaVersion 2.66.0
          */
         "onVegaComplete"?: (event: VegaInputPasscodeCustomEvent<string>) => void;
         /**
-          * Determines whether the input passcode field is required.
+          * Determines whether the passcode field must have a value before the form can be submitted. When `true`, the built-in `RequiredFieldRule` is applied during validation and a required indicator is shown on the label.
+          * @default false
           * @vegaVersion 2.66.0
          */
         "required"?: boolean;
         /**
-          * Defines the size of the input passcode,    specifying its width or length.
+          * Controls the visual size of the passcode input boxes.  - `'medium'` — Standard height, suitable for most form layouts. - `'small'` — Compact height, useful for dense UIs.
+          * @default 'medium'
           * @vegaVersion 2.66.0
          */
         "size"?: 'medium' | 'small';
         /**
-          * Defines custom validation rules for the input passcode.
+          * An array of custom validation rules applied to the passcode input in addition to the built-in `RequiredFieldRule`. Each rule must implement the `FormFieldValidationRule` interface.  Rules are evaluated in order when `autoValidation` is enabled or when validation is triggered programmatically.
+          * @default []
           * @vegaVersion 2.66.0
          */
         "validationRules"?: FormFieldValidationRule<unknown>[];
         /**
-          * Specifies the value of the input passcode.
+          * The current value of the passcode input, represented as a concatenated string of all box values (e.g., `'1234'` for a 4-digit passcode).  This property is mutable and reflected to the host element attribute. It updates as the user types into the boxes and can be set externally to pre-populate or reset the field.
+          * @default ''
           * @vegaVersion 2.66.0
          */
         "value"?: string;
     }
     interface VegaInputPhoneNumber {
         /**
-          * Specifies the countries available for selection.  Note: By default, 245 codes are provided, but loading all of them may take time. To improve performance, it is recommended to include only the necessary codes.
+          * An array of country codes available for selection in the country dropdown. Each entry must be a two-letter uppercase ISO 3166-1 alpha-2 code.  By default all 245 supported codes are loaded, but providing a smaller subset improves initial render performance.
+          * @default VegaCountryCode[] (all 245 codes)
           * @vegaVersion 2.18.0
-          * @defaultValue ['US', 'CN', ...]{@link VegaCountryCode }
          */
         "allowedCountryCodes"?: VegaCountryCode[];
         /**
-          * Determines whether the phone number input field should undergo automatic validation    during the user's input.
+          * Determines whether the phone number input should be validated automatically as the user interacts with it. When `true`, validation rules (including `required`, `ValidPhoneNumberRule`, and custom `validationRules`) are evaluated and the `isValid` property is updated accordingly.  Set to `false` to handle validation manually.
+          * @default true
           * @vegaVersion 2.18.0
          */
         "autoValidation"?: boolean;
         /**
-          * Specifies the default country calling code using the two-letter uppercase country code.
+          * Specifies the currently selected country using a two-letter uppercase ISO 3166-1 alpha-2 code (e.g., `'US'`, `'GB'`, `'CN'`). The country code determines the flag icon and calling code prefix displayed in the country selector. Changing this value updates the phone number prefix accordingly.
+          * @default 'US'
           * @vegaVersion 2.18.0
-          * @defaultValue US
          */
         "countryCode"?: VegaCountryCode;
         /**
-          * Determines whether the phone number input field is disabled.
+          * Specifies whether the phone number input field is disabled. When `true`, both the country selector and the phone number text field become non-interactive — the user cannot type, select a country, or focus any part of the component.
+          * @default false
           * @vegaVersion 2.18.0
          */
         "disabled"?: boolean;
         /**
-          * Specifies whether the phone number input field can be set to an empty value. - `true`:      The value property is cleared when the input field is empty. - `false`:      The value property is `+1` when no phone number is entered.
+          * Controls whether the `value` property can be an empty string.  - `true` — The `value` property is cleared to `''` when the user   deletes all digits from the input field. - `false` — The `value` property always retains at least the country   calling code prefix (e.g., `'+1'` for US) even when no phone number   digits have been entered.
+          * @default false
           * @vegaVersion 2.35.0
          */
         "emptyValueEnabled"?: boolean;
         /**
-          * Provides a supplementary prompt message that assists users in    understanding the expected value for the input field.
+          * Supplementary helper message displayed below the phone number input that assists users in understanding the expected value or provides additional context (e.g., `'We will send a verification code to this number'`).
+          * @default ''
           * @vegaVersion 2.18.0
          */
         "hint"?: string;
         /**
-          * Indicates whether the current value in the field is considered valid    based on the defined validation rules.
+          * Reflects the current validation status of the phone number input.  - `true` — the field value passes all validation rules. - `false` — one or more validation rules have failed. - `null` — the field has not been validated yet (initial state).  This property is mutable: it is updated automatically when `autoValidation` is enabled, but can also be set manually to override the validation state.
+          * @default null
           * @vegaVersion 2.18.0
          */
         "isValid"?: boolean;
         /**
-          * Specifies the label or title for the phone number input field.  It provides descriptive text that helps identify the    purpose or content expected in the input field.
+          * Specifies the visible label text rendered above the phone number input. The label identifies the purpose of the field and serves as the accessible name for screen readers.
+          * @default ''
           * @vegaVersion 2.18.0
          */
         "label"?: string;
         /**
-          * An event emitter notifying a value change.
+          * Native-equivalent mirror of `vegaChange`. Fires with the same payload and at the same time, allowing consumers to listen using the standard `change` event name.
+          * @eventDetail string
           * @eventSemantics namespace:native
           * @vegaVersion 2.18.0
          */
         "onChange"?: (event: VegaInputPhoneNumberCustomEvent<string>) => void;
         /**
-          * An event emitter notifying a country change.
+          * Native-equivalent mirror of `vegaCountryChange`. Fires with the same payload and at the same time, allowing consumers to listen using the standard `countryChange` event name.
+          * @eventDetail VegaCountryType
           * @eventSemantics namespace:native
           * @vegaVersion 2.18.0
          */
         "onCountryChange"?: (event: VegaInputPhoneNumberCustomEvent<VegaCountryType>) => void;
         /**
-          * An event emitter notifying a value change.
+          * Fires whenever the phone number value changes — including typing, pasting, or programmatic updates. The event detail contains the full phone number in E.164 format (e.g., `'+14155552671'`).
+          * @eventDetail string
           * @vegaVersion 2.18.0
          */
         "onVegaChange"?: (event: VegaInputPhoneNumberCustomEvent<string>) => void;
         /**
-          * An event emitter notifying a country change.
+          * Fires whenever the selected country changes via the country dropdown. The event detail contains a `VegaCountryType` object with the country code, calling code, and display name of the newly selected country.
+          * @eventDetail VegaCountryType
           * @vegaVersion 2.18.0
          */
         "onVegaCountryChange"?: (event: VegaInputPhoneNumberCustomEvent<VegaCountryType>) => void;
         /**
-          * Specifies a placeholder string that displays as a temporary hint    or example inside the input field.
+          * Specifies placeholder text displayed inside the phone number text field when it is empty. The placeholder disappears once the user begins typing and is typically used to indicate the expected format (e.g., `'(555) 555-5555'`).
+          * @default undefined
           * @vegaVersion 2.18.0
          */
         "placeholder"?: string;
         /**
-          * Determines whether the phone number input field is required.
+          * Determines whether the phone number input field must have a value before the form can be submitted. When `true`, the built-in `InputPhoneNumberRequiredRule` is applied during validation and a required indicator is shown on the label.
+          * @default false
           * @vegaVersion 2.18.0
          */
         "required"?: boolean;
         /**
-          * Specifies the size of the phone number input field.
+          * Controls the visual size of the phone number input field.  - `'default'` — Standard height, suitable for most form layouts. - `'small'` — Compact height, useful for dense UIs.
+          * @default 'default'
           * @vegaVersion 2.18.0
          */
         "size"?: 'default' | 'small';
         /**
-          * Specifies custom validation rules for the phone number input field.
+          * An array of custom validation rules applied to the phone number input in addition to the built-in rules (`InputPhoneNumberRequiredRule`, `ValidPhoneNumberRule`). Each rule must implement the `FormFieldValidationRule` interface.  Rules are evaluated in order when `autoValidation` is enabled or when validation is triggered programmatically.
+          * @default []
           * @vegaVersion 2.18.0
          */
         "validationRules"?: FormFieldValidationRule<unknown>[];
         /**
-          * Specifies the value of the phone number input in [E.164]{@link https ://en.wikipedia.org/wiki/E.164} format.
-          * @VegaWarning - Note: The input phone number field will always have a value. If no phone number is entered, the default format is `+{default_country_code}`. - For example, if the default country code is US, the default value will be `+1`.
+          * The current value of the phone number input in [E.164](https://en.wikipedia.org/wiki/E.164) format (e.g., `'+14155552671'`).  This property is mutable and reflected to the host element attribute. It updates as the user types and can be set externally to pre-populate or reset the field. When `emptyValueEnabled` is `false` and no digits have been entered, the value defaults to the country calling code prefix (e.g., `'+1'` for US).
+          * @default '+1'
           * @vegaVersion 2.18.0
-          * @defaultValue +1
          */
         "value"?: string;
     }
@@ -8803,7 +8971,7 @@ declare namespace LocalJSX {
          */
         "selectType"?: SelectType;
         /**
-          * Allows customization of the text displayed within the    select field when single or multiple items are selected.    The default format for the selected label is    `${number of selected items} Selected` for multiple mode only.  To enable all modes, use the `SelectedLabelTypeForAllModes` type. 		For single mode, the default format is the `displayName` of the selected item if not set 		For multiple mode, the default format is `${number of selected items} Selected` if not set
+          * Allows customization of the text displayed within the    select field when single or multiple items are selected.    The default format for the selected label is    `{0} Selected` for multiple mode only.  To enable all modes, use the `SelectedLabelTypeForAllModes` type. 		For single mode, the default format is the `displayName` of the selected item if not set 		For multiple mode, the default format is `{0} Selected` if not set
           * @vegaVersion 1.35.0
          */
         "selectedLabel"?: SelectedLabelType | SelectedLabelTypeForAllModes;
@@ -9640,6 +9808,12 @@ declare namespace LocalJSX {
           * @vegaVersion 2.34.0
          */
         "onImageInserted"?: (event: VegaRichTextEditorCustomEvent<VegaRichTextEditorImage>) => void;
+        /**
+          * An event emitter notifying a source code change event. It triggers when the editor loses focus in source edit mode.
+          * @eventSemantics namespace:native
+          * @vegaVersion 2.78.0
+         */
+        "onSourceCodeChange"?: (event: VegaRichTextEditorCustomEvent<string>) => void;
         /**
           * An event emitter notifying a value change.
           * @vegaVersion 2.34.0
@@ -9650,6 +9824,11 @@ declare namespace LocalJSX {
           * @vegaVersion 2.34.0
          */
         "onVegaImageInserted"?: (event: VegaRichTextEditorCustomEvent<VegaRichTextEditorImage>) => void;
+        /**
+          * An event emitter notifying a source code change event. It triggers when the editor loses focus in source edit mode.
+          * @vegaVersion 2.78.0
+         */
+        "onVegaSourceCodeChange"?: (event: VegaRichTextEditorCustomEvent<string>) => void;
         /**
           * Specifies a placeholder string that displays as a    temporary hint or example within the rich text editor.  It indicates the expected format or pattern of    the input within the rich text editor.
           * @vegaVersion 2.34.0
@@ -10703,110 +10882,131 @@ declare namespace LocalJSX {
     }
     interface VegaTextarea {
         /**
-          * Determines whether automatic validation should be    implemented for the text area.
+          * Determines whether the text area should be validated automatically as the user types. When `true`, validation rules (including `required`, `minLength`, `maxLength`, and custom `validationRules`) are evaluated on blur and the `isValid` property is updated accordingly.  Set to `false` to handle validation manually.
+          * @default true
           * @vegaVersion 1.11.0
          */
         "autoValidation"?: boolean;
         /**
-          * Specifies whether the text area is disabled.
+          * Specifies whether the text area is disabled. When `true`, the text area is non-interactive — the user cannot type, focus, or select the field. The disabled state is reflected as an HTML attribute for CSS styling.
+          * @default false
           * @vegaVersion 1.11.0
          */
         "disabled"?: boolean;
         /**
-          * Provides a supplementary prompt message that assists users in    understanding the expected value within the text area.
+          * Provides a supplementary helper message displayed below the text area that assists users in understanding the expected value or format.  The hint is visible at all times (not just on focus) and is typically used for guidance such as character requirements or formatting rules.
+          * @default ''
           * @vegaVersion 1.11.0
          */
         "hint"?: string;
         /**
-          * Specifies the validation status of the    text area component.
+          * Reflects the current validation status of the text area.  - `true` — the field value passes all validation rules. - `false` — one or more validation rules have failed. - `null` — the field has not been validated yet (initial state).  This property is mutable: it is updated automatically when `autoValidation` is enabled, but can also be set manually to override the validation state. The value is reflected as an HTML attribute.
+          * @default null
           * @vegaVersion 1.11.0
          */
         "isValid"?: boolean;
         /**
-          * Specifies the label or title for the text area.  It provides descriptive text that helps identify the    purpose or content expected within the text area.
+          * Specifies the visible label text rendered above the text area. The label helps identify the purpose or content expected within the field and also serves as the accessible `aria-label` for screen readers when present.  Clicking the label will focus the text area.
+          * @default ''
           * @vegaVersion 1.11.0
          */
         "label"?: string;
         /**
-          * Specifies the properties for the suffix button associated with the input.  It provides essential information and functionality  related to the suffix button's role and behavior.
+          * Configuration object for an optional suffix button rendered beside the field label. Use this to provide an inline action (e.g., a help or info button) next to the label text.  When the button is clicked, the `vegaLabelButtonClick` event is emitted. Set to `null` to hide the suffix button.
+          * @default null
           * @vegaVersion 2.68.0
          */
         "labelSuffixButtonConfig"?: Nullable<LabelSuffixButtonConfig>;
         /**
-          * Specifies the maximum number of characters (UTF-16 code units)    that the user can enter in the text area.
+          * Specifies the maximum number of characters (UTF-16 code units) that the user can enter in the text area. The native `maxlength` attribute is applied to the inner `<textarea>` element.  When `showCounter` is `true`, the maximum value is displayed alongside the current character count (e.g., `42/200`). Exceeding this limit triggers a visual warning on the counter and fails the `MaxStringLengthRule` during validation.  Set to `null` to allow unlimited input.
+          * @default null
           * @vegaVersion 1.11.0
          */
         "maxLength"?: number;
         /**
-          * Specifies the minimum number of characters (UTF-16 code units)   that the user must enter in the text area.
+          * Specifies the minimum number of characters (UTF-16 code units) that the user must enter in the text area for the value to be considered valid. The native `minlength` attribute is applied to the inner `<textarea>` element.  When set, the `MinStringLengthRule` is applied during validation. Set to `null` to impose no minimum length.
+          * @default null
           * @vegaVersion 1.11.0
          */
         "minLength"?: number;
         /**
-          * An event emitter notifying the blur event of the inner    textarea element within the text area.
+          * Native-namespace mirror of `vegaBlur`. Fired when the inner `<textarea>` element loses focus. Provided for compatibility with standard DOM event listeners.
+          * @eventDetail undefined — No payload; signals the blur occurrence only.
           * @eventSemantics namespace:native
           * @vegaVersion 2.0.0
          */
         "onBlur"?: (event: VegaTextareaCustomEvent<undefined>) => void;
         /**
-          * An event emitter notifying about changes in the value    of the text area.
+          * Native-namespace mirror of `vegaChange`. Fired whenever the text area value changes. Provided for compatibility with standard DOM event listeners.
+          * @eventDetail string — The updated text area value.
           * @eventSemantics namespace:native
           * @vegaVersion 2.0.0
          */
         "onChange"?: (event: VegaTextareaCustomEvent<string>) => void;
         /**
-          * An event emitter notifying that the suffix button associated with the field label has been clicked.
+          * Native-namespace mirror of `vegaLabelButtonClick`. Fired when the label suffix button is clicked. Provided for compatibility with standard DOM event listeners.
+          * @eventDetail void
           * @eventSemantics namespace:native
           * @vegaVersion 2.68.0
          */
         "onLabelButtonClick"?: (event: VegaTextareaCustomEvent<any>) => void;
         /**
-          * An event emitter notifying the blur event of the inner    textarea element within the text area.
+          * Fired when the inner `<textarea>` element loses focus (blur). Use this event to trigger validation or save actions when the user leaves the text area.
+          * @eventDetail undefined — No payload; signals the blur occurrence only.
           * @vegaVersion 1.11.0
          */
         "onVegaBlur"?: (event: VegaTextareaCustomEvent<undefined>) => void;
         /**
-          * An event emitter notifying about changes in the value    of the text area.
+          * Fired whenever the text area value changes, whether by user input or programmatic update of the `value` property. This is the primary event for reacting to content changes and implementing two-way binding.
+          * @eventDetail string — The updated text area value.
           * @vegaVersion 1.11.0
          */
         "onVegaChange"?: (event: VegaTextareaCustomEvent<string>) => void;
         /**
-          * An event emitter notifying that the suffix button associated with the field label has been clicked.
+          * Fired when the suffix button configured via `labelSuffixButtonConfig` is clicked. Listen for this event to handle inline label actions such as opening a help dialog or toggling additional information.
+          * @eventDetail void
           * @vegaVersion 2.68.0
          */
         "onVegaLabelButtonClick"?: (event: VegaTextareaCustomEvent<any>) => void;
         /**
-          * Specifies a placeholder string that displays as a    temporary hint or example within the text area.  It indicates the expected format or pattern of    the input within the text area.
+          * Specifies a placeholder string that displays as a temporary hint or example within the text area. The placeholder text is shown when the field is empty and disappears once the user begins typing.  Use this to indicate the expected format or content of the input, for example `'Enter your comments here...'`.
+          * @default ''
           * @vegaVersion 1.11.0
          */
         "placeholder"?: string;
         /**
-          * Determines whether the content of the textarea must be    provided by the user before submitting the form or    completing the input process.
+          * Determines whether the text area must have a non-empty value before the form can be submitted. When `true`, a required-field indicator is shown on the label and the built-in `RequiredFieldRule` is applied during validation.
+          * @default false
           * @vegaVersion 1.11.0
          */
         "required"?: boolean;
         /**
-          * Determines whether the text area is vertically resizable.
+          * Determines whether the user can vertically resize the text area by dragging its bottom-right corner. When `false`, the resize handle is hidden via CSS and the text area height is fixed.
+          * @default true
           * @vegaVersion 2.19.0
          */
         "resizable"?: boolean;
         /**
-          * Specifies the number of visible lines in the textarea. The value must be an integer greater than or equal to 2.
+          * Specifies the number of visible text lines in the text area, controlling its initial height. Accepts integers ≥ 2. For optimal display, values below 2 are internally adjusted to 4 rows.
+          * @default 5
           * @vegaVersion 2.63.0
          */
         "rows"?: number;
         /**
-          * Determines whether to display a character counter    for the textarea.
+          * Determines whether to display a live character counter below the text area.  When `true`, the counter shows the current character count. If `maxLength` is also set, the counter displays in the format `current/max` and visually highlights when the limit is exceeded.
+          * @default false
           * @vegaVersion 1.11.0
          */
         "showCounter"?: boolean;
         /**
-          * Specifies custom validation rules for the text area.
+          * An array of custom validation rules applied to the text area in addition to the built-in rules (`RequiredFieldRule`, `MinStringLengthRule`, `MaxStringLengthRule`). Each rule must implement the `FormFieldValidationRule` interface.  Rules are evaluated in order when `autoValidation` is enabled or when validation is triggered programmatically.
+          * @default []
           * @vegaVersion 1.11.0
          */
         "validationRules"?: FormFieldValidationRule<unknown>[];
         /**
-          * Specifies the initial value or content of the    textarea field.
+          * The current value (content) of the text area field.  This property is mutable and will be updated programmatically when the user types into the text area. It can also be set externally to pre-populate or reset the field. Changes to this property trigger the `vegaChange` event and update the character counter if `showCounter` is enabled. Supports two-way binding in framework wrappers.
+          * @default ''
           * @vegaVersion 1.11.0
          */
         "value"?: string;