@globalpayments/vega 2.77.0 → 2.78.0

package/dist/types/components/vega-input/vega-input.d.ts

@@ -21,11 +21,15 @@ import { VegaInputValueController } from './slimmers/controllers/vega-input-valu
 import { VegaInputInputSuggestionsRenderer } from './slimmers/renderers/vega-input-input-suggestions-renderer';
 import { VegaDropdownSourceItem } from '../vega-dropdown/types';
 import { VegaInputRenderModeController } from './slimmers/controllers/vega-input-render-mode-controller';
+import { AriaAttributesValueMapper } from '../../helpers/slimmers/mutation-observer/aria-attributes-value-mapper';
+import { DataTabIndexValueMapper } from '../../helpers/slimmers/mutation-observer/data-tab-index-value-mapper';
 /**
  * @vegaVersion 1.0.5
  */
 export declare class VegaInput {
   protected readonly globalSlimmers: GlobalSlimmers;
+  protected ariaAttributesValueMapper: AriaAttributesValueMapper;
+  protected dataTabIndexValueMapper: DataTabIndexValueMapper;
   protected readonly formFieldController: FormFieldControllerSlimmer<string>;
   protected readonly pageResizeObserverSlimmer: PageResizeObserverSlimmer;
   protected renderModeController: VegaInputRenderModeController;
@@ -56,44 +60,53 @@ export declare class VegaInput {
   isPasswordDisplay: boolean;
   suggestionsDropdownConfig: VegaInputSuggestionsDropdownConfig;
   /**
-   * Specifies the label or title for the input field.
+   * Specifies the visible label text displayed above the input field.
    *
-   * It provides descriptive text that helps identify the
-   *    purpose or content expected in the input field.
+   * The label provides an accessible, descriptive title that helps users identify
+   * the purpose or content expected in the input field. It is rendered as a
+   * `<vega-field-label>` element and is associated with the native `<input>` for
+   * accessibility (screen readers, click-to-focus).
    *
+   * When set to an empty string, no label is rendered.
+   *
+   * @default ''
    * @vegaVersion 1.0.5
    */
   label: string;
   /**
-   * @deprecated Please use `LabelSuffixButtonConfig` instead
-   *
-   * Specifies the properties for the suffix button associated with the input.
+   * @deprecated Please use `labelSuffixButtonConfig` instead.
    *
-   * It provides essential information and functionality
-   *  related to the suffix button's role and behavior.
+   * Configures an optional action button displayed at the trailing end of the
+   * field label. This can be used to provide contextual actions such as a
+   * "Forgot password?" link or an info tooltip trigger.
    *
+   * @default null
    * @vegaVersion 2.25.0
    */
   labelSuffixButtonProps: Nullable<LabelSuffixButtonProps>;
   /**
-   * Specifies the properties for the suffix button associated with the input.
+   * Configures an optional action button displayed at the trailing end of the
+   * field label. Use this to provide contextual actions such as a
+   * "Forgot password?" link, a help tooltip trigger, or any custom label-level action.
    *
-   * It provides essential information and functionality
-   *  related to the suffix button's role and behavior.
+   * When clicked, the `vegaLabelButtonClick` event is emitted.
    *
+   * @default null
    * @vegaVersion 2.68.0
    */
   labelSuffixButtonConfig: Nullable<LabelSuffixButtonConfig>;
   /**
-   * Represents a pre-set or default value for the input field.
+   * The current value of the input field.
    *
-   * It allows you to initialize the field with a specific value,
-   *    which is displayed to the user when the input is
-   *    initially rendered.
+   * Use this property to programmatically set or read the input's value.
+   * The value is two-way bound — it updates when the user types and can be
+   * set externally to pre-fill or reset the field.
    *
-   * If the value is too long, it may be truncated with
-   *    an ellipsis for visual presentation.
+   * When a `maskConfig` is applied, the displayed value may differ from the
+   * raw value (e.g., formatted phone numbers). The `vegaChange` event emits
+   * the current value whenever it changes.
    *
+   * @default ''
    * @vegaVersion 1.0.5
    */
   value: string;
@@ -110,19 +123,31 @@ export declare class VegaInput {
    */
   watchValue(value: string): void;
   /**
-   * 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;
   /**
-   * Defines the specific type or category of the input field.
+   * Sets the HTML input type, which controls the browser's input behavior,
+   * on-screen keyboard layout, and built-in validation.
    *
-   * It specifies the intended format or purpose of the
-   *    data to be entered by the user.
+   * - `'text'` — Standard single-line text input.
+   * - `'email'` — Optimized for email entry; triggers email validation automatically.
+   * - `'password'` — Masks the entered characters; displays a show/hide toggle icon.
+   * - `'number'` — Restricts input to numeric values; may show increment/decrement controls.
+   * - `'hidden'` — Renders the input as invisible (useful for programmatic form values).
    *
+   * @default 'text'
    * @vegaVersion 1.0.9
    */
   type: InputType;
@@ -132,136 +157,237 @@ export declare class VegaInput {
    */
   watchTypeChange(newType: InputType, oldType: InputType): void;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * 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';
   /**
-   * 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;
   /**
-   * Enforces proper email format validation for the input field.
+   * When `true`, enforces email format validation on the input value.
    *
-   * It ensures that the user enters a valid email address according to
-   *    standard email formatting rules.
+   * 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.
+   * @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;
   /**
-   * 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;
   /**
-   * 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 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 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;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * 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>[];
   watchValidationRules(): 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';
   /**
-   * Specifies a placeholder string that displays as a temporary hint
-   *    or example inside the input field.
+   * Sets the placeholder text displayed inside the input when the value is empty.
    *
-   * It indicates the expected format or pattern of the input.
+   * 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;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * Specifies the configuration for applying a mask to the input field.
+   * Configures input masking to automatically format the user's input according
+   * to a predefined pattern.
    *
-   * It provides a way to define a specific format or pattern for the input value,
-   *    restricting and guiding the user's input accordingly.
+   * 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
    */
@@ -274,131 +400,247 @@ export declare class VegaInput {
    */
   watchMaskChange(newValue: MaskConfigType | MaskConfigType[], oldValue: MaskConfigType | MaskConfigType[]): void;
   /**
-   * 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;
   /**
-   * 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[];
   watchSuggestionsDropdownSource(): 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
    */
   vegaChange: EventEmitter<string>;
   /**
-   * 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
    */
   change: EventEmitter<string>;
   /**
-   * 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
    */
   vegaNativeInputChange: EventEmitter<string>;
   /**
-   * 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
    */
   nativeInputChange: EventEmitter<string>;
   /**
-   * 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
    */
   vegaBlur: EventEmitter<undefined>;
   /**
-   * 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
    */
   blur: EventEmitter<undefined>;
   /**
-   * 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
    */
   vegaFocus: EventEmitter<undefined>;
   /**
-   * 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
    */
   focus: EventEmitter<undefined>;
   /**
-   * 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
    */
   vegaLabelButtonClick: EventEmitter;
   /**
-   * 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
    */
   labelButtonClick: EventEmitter;
   /**
-   * 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
    */
   vegaPaste: EventEmitter<DataTransferType>;
   /**
-   * 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
    */
   paste: EventEmitter<DataTransferType>;
   /**
-   * 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
    */
   vegaSuggestionItemClick: EventEmitter<VegaDropdownSourceItem>;
   /**
-   * 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
    */
   suggestionItemClick: EventEmitter<VegaDropdownSourceItem>;
   /**
-   * 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>;
   /**
-   * 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 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>;
   /**
-   * 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>;