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

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

@@ -1,107 +1,332 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-basic-textarea
+ * @description A multi-line text input component with auto-grow functionality, character formatting, custom styling, and form integration. Supports different sizes, validation states, and accessibility features.
+ *
+ * @example
+ * <!-- Basic textarea -->
+ * <vds-basic-textarea
+ *   placeholder="Enter your message">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Textarea with value -->
+ * <vds-basic-textarea
+ *   value="Initial content"
+ *   placeholder="Description">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Small size textarea -->
+ * <vds-basic-textarea
+ *   size="small"
+ *   placeholder="Brief comment">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Large size textarea -->
+ * <vds-basic-textarea
+ *   size="large"
+ *   placeholder="Detailed description">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Required textarea with error state -->
+ * <vds-basic-textarea
+ *   is-required="true"
+ *   error="true"
+ *   placeholder="Required field">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Disabled textarea -->
+ * <vds-basic-textarea
+ *   disabled="true"
+ *   value="Cannot edit this content">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Readonly textarea -->
+ * <vds-basic-textarea
+ *   is-readonly="true"
+ *   value="Read-only content for display">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Fixed height textarea (autogrow disabled) -->
+ * <vds-basic-textarea
+ *   autogrow="false"
+ *   height="200px"
+ *   placeholder="Fixed height area">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Textarea with custom min/max height -->
+ * <vds-basic-textarea
+ *   autogrow="true"
+ *   min-height="100px"
+ *   max-height="300px"
+ *   placeholder="Auto-growing textarea">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Textarea with custom width -->
+ * <vds-basic-textarea
+ *   width="500px"
+ *   placeholder="Custom width textarea">
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Textarea with action icons -->
+ * <vds-basic-textarea placeholder="Message">
+ *   <vds-icon-button
+ *     slot="primaryActionIcon"
+ *     icon="share"
+ *     aria-label="Send">
+ *   </vds-icon-button>
+ *   <vds-icon-button
+ *     slot="secondaryActionIcon"
+ *     icon="paperclip"
+ *     aria-label="Attach file">
+ *   </vds-icon-button>
+ * </vds-basic-textarea>
+ *
+ * @example
+ * <!-- Textarea with custom text styles -->
+ * <vds-basic-textarea
+ *   placeholder="Styled text">
+ * </vds-basic-textarea>
+ * <script>
+ *   const textarea = document.querySelector('vds-basic-textarea');
+ *   textarea.allowedStyles = [
+ *     { 'text-align': 'center' },
+ *     { 'text-transform': 'uppercase' }
+ *   ];
+ * </script>
+ *
+ * @example
+ * <!-- Complete form example -->
+ * <form id="feedback-form">
+ *   <vds-field label="Feedback" is-required="true">
+ *     <vds-basic-textarea
+ *       id="feedback"
+ *       name="feedback"
+ *       is-required="true"
+ *       placeholder="Please share your feedback"
+ *       min-height="120px"
+ *       max-height="400px">
+ *     </vds-basic-textarea>
+ *   </vds-field>
+ *   <button type="submit">Submit</button>
+ * </form>
+ *
+ * @example
+ * <!-- Textarea with programmatic control -->
+ * <vds-basic-textarea id="my-textarea" placeholder="Enter text"></vds-basic-textarea>
+ * <button id="clear-btn">Clear</button>
+ * <button id="focus-btn">Focus</button>
+ * <button id="get-value-btn">Get Value</button>
+ * <script>
+ *   const textarea = document.getElementById('my-textarea');
+ *
+ *   document.getElementById('clear-btn').addEventListener('click', async () => {
+ *     await textarea.clear();
+ *   });
+ *
+ *   document.getElementById('focus-btn').addEventListener('click', async () => {
+ *     await textarea.setFocus();
+ *   });
+ *
+ *   document.getElementById('get-value-btn').addEventListener('click', async () => {
+ *     const value = await textarea.getValue();
+ *     console.log('Current value:', value);
+ *   });
+ *
+ *   // Overwrite the textarea value programmatically
+ *   await textarea.setValue('New content set programmatically');
+ *
+ *   textarea.addEventListener('changeInput', (e) => {
+ *     console.log('Value changed:', e.detail);
+ *   });
+ * </script>
+ */
 export declare class VdsBasicTextarea {
-    /** Sets the textarea's size. */
+    /**
+     * Sets the textarea's size
+     * @type {"small" | "medium" | "large"}
+     * @default "medium"
+     */
     size: "small" | "medium" | "large";
-    /** Sets the textarea's value. */
+    /**
+     * Sets the textarea's value
+     * @type {string}
+     * @default ""
+     */
     value: string;
-    /** Sets the textarea's placeholder. */
+    /**
+     * Sets the textarea's placeholder text
+     * @type {string}
+     */
     placeholder: string;
-    /** Sets the textarea in disabled state. */
+    /**
+     * Sets the textarea in disabled state
+     * @type {boolean}
+     */
     disabled: boolean;
-    /** Sets the textarea in readonly state. */
+    /**
+     * Sets the textarea in readonly state
+     * @type {boolean}
+     */
     isReadonly: boolean;
-    /** Sets the textarea in error state. */
+    /**
+     * Sets the textarea in error state
+     * @type {boolean}
+     */
     error: boolean;
-    /** Toggles the required sign in the field */
+    /**
+     * Toggles the required sign in the field
+     * @type {boolean}
+     * @default false
+     */
     isRequired: boolean;
-    /** Sets character formatting for user inputs. Useful for adding a mask to the textarea. */
+    /**
+     * Sets character formatting for user inputs. Useful for adding a mask to the textarea.
+     * @type {Function}
+     */
     formatter: Function;
-    /** Sets custom allowed styles to textarea (text-align, text-transform, unicode-bidi, direction) */
+    /**
+     * Sets custom allowed styles to textarea (text-align, text-transform, unicode-bidi, direction)
+     * @type {Array<{[key: string]: string}>}
+     * @default []
+     */
     allowedStyles: {
         [key: string]: string;
     }[];
-    /** Sets the width of the textarea. */
+    /**
+     * Sets the width of the textarea
+     * @type {string}
+     */
     width: string;
-    /** Sets the height of the textarea. This prop not works combining with autogrow=true. */
+    /**
+     * Sets the height of the textarea. This prop does not work when autogrow is enabled.
+     * @type {string}
+     */
     height: string;
-    /** Sets the min-height for the textarea. This property works combining with autogrow=true only.
-     * - Default for medium: '4.5rem'
-     * - Default for large: '6rem'
-     *
+    /**
+     * Sets the min-height for the textarea. This property works when autogrow is enabled.
+     * Default values: small='3rem', medium='4.5rem', large='6rem'
      * This value is automatically adjusted according to the 'size' property.
-     * @default '4.5rem' (when size is 'medium')
-    */
+     * @type {string}
+     * @default "4.5rem" (when size is 'medium')
+     */
     minHeight: string;
-    /** Sets the max-height for the textarea. This property works combining with autogrow=true only.
-     * - Default for medium: '12.15rem'
-     * - Default for large: '18rem'
-     *
+    /**
+     * Sets the max-height for the textarea. This property works when autogrow is enabled.
+     * Default values: small/medium='12.15rem', large='18rem'
      * This value is automatically adjusted according to the 'size' property.
-     * @default '12.15rem' (when size is 'medium')
-    */
+     * @type {string}
+     * @default "12.15rem" (when size is 'medium')
+     */
     maxHeight: string;
-    /** Makes the textarea grows with its content. This property works combining with maxHeight and minHeight. This prop not works combining with property height defined. */
+    /**
+     * Makes the textarea grow with its content. Works with maxHeight and minHeight. Does not work when height is defined.
+     * @type {boolean}
+     * @default true
+     */
     autogrow: boolean;
     hostEl: HTMLVdsBasicTextareaElement;
-    /**  Emits updated textarea value */
+    /**
+     * Emits updated textarea value
+     * @event changeInput
+     * @type {EventEmitter<string>}
+     */
     changeInput: EventEmitter<string>;
     internals: ElementInternals;
     private textareaContainerRef;
     private textAreaEl;
-    componentDidLoad(): void;
+    private cleanupAttributeSync;
+    /**
+     * Lifecycle method that runs after component loads
+     * @private
+     */ componentDidLoad(): void;
+    /**
+     * Lifecycle method that runs when component is removed from DOM
+     * @private
+     */
+    disconnectedCallback(): void;
+    /**
+     * Watches value changes and updates form value
+     * @private
+     */
     setFormValue(): void;
     /**
-     * Toggle class vds__textarea__container--focus in focus/blur textarea's event
-     *
-     * @returns void
+     * Returns a safe value (empty string if undefined)
+     * @private
+     * @returns {string} The safe value
+     */
+    private getSafeValue;
+    /**
+     * Toggles the focus class on the textarea container
+     * @private
+     * @returns {void}
      */
     private toggleFocusClass;
     /**
-     * Sets value from textarea's event target.
-     * Emits change, input and changeInput events.
-     * Sets textarea as dirty when textarea's event is triggered.
-     * Executes formatter prop function on every inputed value.
-     *
-     * @returns void
+     * Handles input events on the textarea. Sets value, emits events, applies formatting, and sets dirty state.
+     * @private
+     * @param {InputEvent} evt - The input event
+     * @returns {void}
      */
     private handleInput;
     /**
-     * Sets textarea inline styles for the allowedStyle, height and width
-     * [direction, text-align, textAlign, text-transform, textTransform, unicode-bidi, unicodeBidi]
-     *
-     * @returns { [key: string]: string }
+     * Sets textarea inline styles for allowed styles, height, and width.
+     * Supports: direction, text-align, textAlign, text-transform, textTransform, unicode-bidi, unicodeBidi
+     * @private
+     * @returns {{[key: string]: string}} Object containing CSS styles
      */
     private setTextareaStyles;
     /**
-     * Sets textarea inline styles for the height and width
-     *
-     * @returns { [key: string]: string }
+     * Sets textarea inline styles for height and width properties
+     * @private
+     * @param {{[key: string]: string}} styles - Initial styles object
+     * @returns {{[key: string]: string}} Updated styles object
      */
     private setSizesStyles;
     /**
-       * Executes method when vds-textarea gets focus.
-       *
-       * @returns void
-       */
+     * Handles focus event on the textarea element
+     * @private
+     * @returns {void}
+     */
     handleFocus(): void;
     /**
-       * Sets focus on the vds-textarea element.
-       *
-       * @returns Promise<void>
-       */
+     * Sets focus on the textarea element
+     * @public
+     * @returns {Promise<void>} Promise that resolves when focus is set
+     */
     setFocus(): Promise<void>;
     /**
-       * Gets value prop from the vds-textarea element.
-       *
-       * @returns Promise<string>
-       */
+     * Gets the current value from the textarea element
+     * @public
+     * @returns {Promise<string>} Promise that resolves with the current value
+     */
     getValue(): Promise<string>;
     /**
-     * Clears value prop from the vds-basic-textarea element.
-     *
-     * @returns Promise<void>
+     * Clears the value from the textarea element
+     * @public
+     * @returns {Promise<void>} Promise that resolves when value is cleared
      */
     clear(): Promise<void>;
+    /**
+     * Sets a new value in the textarea element, overwriting the current one
+     * @public
+     * @param {string} newValue - The new value to set in the textarea
+     * @returns {Promise<void>} Promise that resolves when the value is set
+     */
+    setValue(newValue: string): Promise<void>;
+    /**
+     * Renders the textarea component
+     * @returns {HTMLStencilElement} The rendered textarea element
+     */
     render(): HTMLStencilElement;
 }