@globalpayments/vega 2.77.0 → 2.78.0

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

@@ -23,154 +23,236 @@ export declare class VegaTextarea {
   host: HTMLVegaTextareaElement;
   currentCharCount: number;
   /**
-   * Specifies a placeholder string that displays as a
-   *    temporary hint or example 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.
    *
-   * It indicates the expected format or pattern of
-   *    the input within the text area.
+   * 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;
   /**
-   * 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 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;
   /**
-   * Specifies the label or title for 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.
    *
-   * It provides descriptive text that helps identify the
-   *    purpose or content expected within the text area.
+   * 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.
+   * 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.
    *
-   * It provides essential information and functionality
-   *  related to the suffix button's role and behavior.
+   * 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>;
   /**
-   * 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 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;
   watchValue(value: string): void;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * 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;
   /**
-   * 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>[];
   watchValidationRules(): 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
    */
   vegaChange: EventEmitter<string>;
   /**
-   * 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
    */
   change: EventEmitter<string>;
   /**
-   * 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
    */
   vegaBlur: EventEmitter<undefined>;
   /**
-   * 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
    */
   blur: EventEmitter<undefined>;
   /**
-   * 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
    */
   vegaLabelButtonClick: EventEmitter;
   /**
-   * 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
    */