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

package/dist/types/components/stepper-item/vds-stepper-item.d.ts

@@ -1,39 +1,238 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * @component vds-stepper-item
+ * @description A stepper item component that represents a single step in a multi-step process or workflow. Supports multiple states (default, completed, error), custom icons or text, and works with horizontal and vertical stepper containers. Ideal for onboarding flows, checkout processes, and multi-stage forms.
+ *
+ * @example
+ * <!-- Basic stepper item with number -->
+ * <vds-stepper-item text="1">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Step 1"
+ *     description="Basic information">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Stepper item with icon -->
+ * <vds-stepper-item icon="check" state="completed">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Account Created"
+ *     description="Your account is ready">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Completed state stepper -->
+ * <vds-stepper-item text="1" state="completed">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Personal Info"
+ *     description="Completed">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Error state stepper -->
+ * <vds-stepper-item text="2" state="error">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Payment"
+ *     description="Error: Invalid card">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Disabled stepper item -->
+ * <vds-stepper-item text="3" disabled="true">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Confirmation"
+ *     description="Not available yet">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Center aligned stepper -->
+ * <vds-stepper-item text="1" text-alignment="center">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Start">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Stepper with content -->
+ * <vds-stepper-item text="1">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Step 1"
+ *     description="Enter details">
+ *   </vds-stepper-item-header>
+ *   <div slot="item-content">
+ *     <p>Step content goes here</p>
+ *   </div>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Multiple steps in sequence -->
+ * <div style="display: flex; gap: 1rem;">
+ *   <vds-stepper-item text="1" state="completed">
+ *     <vds-stepper-item-header slot="item-header" title="Account"></vds-stepper-item-header>
+ *   </vds-stepper-item>
+ *
+ *   <vds-stepper-item text="2">
+ *     <vds-stepper-item-header slot="item-header" title="Profile"></vds-stepper-item-header>
+ *   </vds-stepper-item>
+ *
+ *   <vds-stepper-item text="3" disabled="true">
+ *     <vds-stepper-item-header slot="item-header" title="Complete"></vds-stepper-item-header>
+ *   </vds-stepper-item>
+ * </div>
+ *
+ * @example
+ * <!-- With icon in completed state -->
+ * <vds-stepper-item icon="checked" state="completed">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Verified"
+ *     description="Email confirmed">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Event handling -->
+ * <vds-stepper-item id="step1" text="1">
+ *   <vds-stepper-item-header slot="item-header"
+ *     title="Step 1"
+ *     description="Click to activate">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ * <script>
+ *   const step = document.getElementById('step1');
+ *   step.addEventListener('selected', (e) => {
+ *     console.log('Step selected:', e);
+ *   });
+ * </script>
+ *
+ * @example
+ * <!-- Full checkout flow -->
+ * <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+ *   <vds-stepper-item icon="check" state="completed">
+ *     <vds-stepper-item-header slot="item-header"
+ *       title="Cart"
+ *       description="3 items">
+ *     </vds-stepper-item-header>
+ *   </vds-stepper-item>
+ *
+ *   <vds-stepper-item text="2">
+ *     <vds-stepper-item-header slot="item-header"
+ *       title="Shipping"
+ *       description="Enter address">
+ *     </vds-stepper-item-header>
+ *     <div slot="item-content">
+ *       <input type="text" placeholder="Address" />
+ *     </div>
+ *   </vds-stepper-item>
+ *
+ *   <vds-stepper-item text="3" disabled="true">
+ *     <vds-stepper-item-header slot="item-header"
+ *       title="Payment"
+ *       description="Next step">
+ *     </vds-stepper-item-header>
+ *   </vds-stepper-item>
+ * </div>
+ */
 export declare class VdsStepperItem {
-    /** Sets the text alignment */
+    /**
+     * Sets the text alignment
+     * @type {"center" | "left"}
+     * @default "left"
+     */
     textAlignment: 'center' | 'left';
-    /** Sets the stepper in disabled state */
+    /**
+     * Sets the stepper in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the stepper state */
+    /**
+     * Sets the stepper state
+     * @type {"default" | "completed" | "error"}
+     * @default "default"
+     */
     state: 'default' | 'completed' | 'error';
-    /** Sets the text inside the circle in the stepper */
+    /**
+     * Sets the text inside the circle in the stepper
+     * @type {string}
+     * @default ""
+     */
     text: string;
-    /** Sets the icon inside the circle in the stepper. When set, the icon will override the text value */
+    /**
+     * Sets the icon inside the circle in the stepper. When set, the icon will override the text value
+     * @type {string}
+     * @default ""
+     */
     icon: string;
     /**
-     * Internal prop, it is used along side with `vds-vertical-stepper` on content inside mode (text-alignment='left')
+     * Internal prop, it is used along side with vds-vertical-stepper on content inside mode (text-alignment='left')
      * When true, the item stepper can render divider and activeContent
+     * @type {boolean}
+     * @default false
      */
     manageContent: boolean;
     /**
-     * Internal prop, it is used along side with `vds-vertical-stepper` on content inside mode (text-alignment='left')
+     * Internal prop, it is used along side with vds-vertical-stepper on content inside mode (text-alignment='left')
      * When true, the item stepper display the slot content of the element
-     * without being manage by the `vds-vertical-stepper` or `vds-horizontal-stepper`
+     * without being manage by the vds-vertical-stepper or vds-horizontal-stepper
+     * @type {boolean}
+     * @default false
      */
     activeContent: boolean;
     /**
-     * Internal prop, it is used along side with `vds-vertical-stepper` on content inside mode (text-alignment='left')
+     * Internal prop, it is used along side with vds-vertical-stepper on content inside mode (text-alignment='left')
      * When true, the item stepper renders a vds-divider after the header
+     * @type {boolean}
+     * @default false
      */
     divider: boolean;
-    /** Emits event when item is selected */
+    /**
+     * Emits event when item is selected
+     * @event selected
+     * @type {EventEmitter<MouseEvent>}
+     */
     selected: EventEmitter<MouseEvent>;
     hostEl: HTMLElement;
+    /**
+     * Component lifecycle hook - updates stepper header on load
+     * @private
+     */
     componentDidLoad(): void;
+    /**
+     * Watch for textAlignment and disabled prop changes to update stepper header
+     * @private
+     */
     onPropsChange(): void;
+    /**
+     * Updates the stepper header component with current props
+     * @private
+     */
     private updateStepperHeader;
+    /**
+     * Handles click events on the stepper item
+     * Emits selected event if not disabled
+     * @private
+     * @param {MouseEvent} evt - The click event
+     */
     private onClick;
+    /**
+     * Renders the content inside the circle (icon or text)
+     * @private
+     * @returns {HTMLElement | null} Icon or text element, or null if neither is provided
+     */
     private renderCircleContent;
+    /**
+     * Renders the stepper circle with appropriate state styling
+     * @private
+     * @returns {HTMLElement} The circle element
+     */
     renderCircle(): any;
+    /**
+     * Render the stepper item component
+     * @returns {HTMLElement} The rendered stepper item element
+     */
     render(): any;
 }

package/dist/types/components/stepper-item-header/vds-stepper-item-header.d.ts

@@ -1,11 +1,160 @@
+/**
+ * @component vds-stepper-item-header
+ * @description A header component for stepper items that displays a title and optional description. Designed to be used within vds-stepper-item components to provide context for each step. Supports left and center text alignment.
+ *
+ * @example
+ * <!-- Basic stepper header with title only -->
+ * <vds-stepper-item-header
+ *   slot="item-header"
+ *   title="Step 1">
+ * </vds-stepper-item-header>
+ *
+ * @example
+ * <!-- Stepper header with title and description -->
+ * <vds-stepper-item-header
+ *   slot="item-header"
+ *   title="Personal Information"
+ *   description="Enter your name and contact details">
+ * </vds-stepper-item-header>
+ *
+ * @example
+ * <!-- Center aligned header -->
+ * <vds-stepper-item-header
+ *   slot="item-header"
+ *   title="Review"
+ *   text-alignment="center">
+ * </vds-stepper-item-header>
+ *
+ * @example
+ * <!-- Disabled stepper header -->
+ * <vds-stepper-item-header
+ *   slot="item-header"
+ *   title="Confirmation"
+ *   description="Complete previous steps first"
+ *   disabled="true">
+ * </vds-stepper-item-header>
+ *
+ * @example
+ * <!-- Used within vds-stepper-item -->
+ * <vds-stepper-item text="1">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Account Setup"
+ *     description="Create your account">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Completed step header -->
+ * <vds-stepper-item icon="check" state="completed">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Email Verified"
+ *     description="Successfully confirmed">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Error step header -->
+ * <vds-stepper-item text="2" state="error">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Payment Failed"
+ *     description="Please check your payment method">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Multi-step flow -->
+ * <vds-stepper-item text="1" state="completed">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Profile"
+ *     description="Basic information">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * <vds-stepper-item text="2">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Preferences"
+ *     description="Set your options">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * <vds-stepper-item text="3" disabled="true">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Review"
+ *     description="Final check">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Checkout process headers -->
+ * <vds-stepper-item icon="check" state="completed">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Cart"
+ *     description="3 items added">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * <vds-stepper-item text="2">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Shipping"
+ *     description="Enter delivery address">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * <vds-stepper-item text="3" disabled="true">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Payment"
+ *     description="Card details required">
+ *   </vds-stepper-item-header>
+ * </vds-stepper-item>
+ *
+ * @example
+ * <!-- Onboarding flow with descriptions -->
+ * <vds-stepper-item text="1">
+ *   <vds-stepper-item-header
+ *     slot="item-header"
+ *     title="Welcome"
+ *     description="Get started with your account">
+ *   </vds-stepper-item-header>
+ *   <div slot="item-content">
+ *     <p>Welcome to our platform!</p>
+ *   </div>
+ * </vds-stepper-item>
+ */
 export declare class VdsStepperItemHeader {
-    /** Define the text in the title label */
+    /**
+     * Define the text in the title label
+     * @type {string}
+     */
     title: string;
-    /** Define the text in the description label */
+    /**
+     * Define the text in the description label
+     * @type {string}
+     */
     description: string;
-    /** Sets the stepper item header in disabled state */
+    /**
+     * Sets the stepper item header in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the text alignment */
+    /**
+     * Sets the text alignment
+     * @type {"center" | "left"}
+     * @default "left"
+     */
     textAlignment: 'center' | 'left';
+    /**
+     * Render the stepper item header component
+     * @returns {HTMLElement | null} The rendered header element, or null if no title or description provided
+     */
     render(): any;
 }

package/dist/types/components/switch/vds-switch.d.ts

@@ -1,68 +1,218 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * @component vds-switch
+ * @description A toggle switch component for binary on/off states. Form-associated with native form support, customizable size, label positioning, and required field indicators. Ideal for settings, preferences, and feature toggles.
+ *
+ * @example
+ * <!-- Basic switch -->
+ * <vds-switch
+ *   label-value="Enable notifications">
+ * </vds-switch>
+ *
+ * @example
+ * <!-- Checked switch -->
+ * <vds-switch
+ *   label-value="Dark mode"
+ *   checked="true">
+ * </vds-switch>
+ *
+ * @example
+ * <!-- Large switch -->
+ * <vds-switch
+ *   label-value="Airplane mode"
+ *   size="large">
+ * </vds-switch>
+ *
+ * @example
+ * <!-- Disabled switch -->
+ * <vds-switch
+ *   label-value="Premium features"
+ *   disabled="true">
+ * </vds-switch>
+ *
+ * @example
+ * <!-- Required switch -->
+ * <vds-switch
+ *   label-value="Accept terms"
+ *   is-required="true">
+ * </vds-switch>
+ *
+ * @example
+ * <!-- Label at start -->
+ * <vds-switch
+ *   label-value="Auto-save"
+ *   label-alignment="start">
+ * </vds-switch>
+ *
+ * @example
+ * <!-- Switch without label -->
+ * <vds-switch checked="true"></vds-switch>
+ *
+ * @example
+ * <!-- Disabled checked switch -->
+ * <vds-switch
+ *   label-value="Read only"
+ *   checked="true"
+ *   disabled="true">
+ * </vds-switch>
+ *
+ * @example
+ * <!-- Switch with custom value -->
+ * <vds-switch
+ *   label-value="Newsletter subscription"
+ *   value="subscribed"
+ *   checked="true">
+ * </vds-switch>
+ *
+ * @example
+ * <!-- Switch with event handling -->
+ * <vds-switch
+ *   id="theme-switch"
+ *   label-value="Dark theme">
+ * </vds-switch>
+ * <script>
+ *   const themeSwitch = document.getElementById('theme-switch');
+ *   themeSwitch.addEventListener('check', (e) => {
+ *     console.log('Switch toggled:', e.detail);
+ *     document.body.classList.toggle('dark-theme', e.detail);
+ *   });
+ * </script>
+ *
+ * @example
+ * <!-- Settings panel with multiple switches -->
+ * <div style="display: flex; flex-direction: column; gap: 1rem;">
+ *   <vds-switch label-value="Push notifications" checked="true"></vds-switch>
+ *   <vds-switch label-value="Email notifications" checked="true"></vds-switch>
+ *   <vds-switch label-value="SMS notifications"></vds-switch>
+ *   <vds-switch label-value="Marketing emails" disabled="true"></vds-switch>
+ * </div>
+ *
+ * @example
+ * <!-- Form integration -->
+ * <form id="preferences-form">
+ *   <vds-switch
+ *     name="notifications"
+ *     label-value="Enable notifications"
+ *     checked="true">
+ *   </vds-switch>
+ *
+ *   <vds-switch
+ *     name="auto-save"
+ *     label-value="Auto-save changes"
+ *     is-required="true">
+ *   </vds-switch>
+ *
+ *   <button type="submit">Save Preferences</button>
+ * </form>
+ */
 export declare class VdsSwitch {
-    /** Sets the text to be shown in the switch */
+    /**
+     * Sets the text to be shown in the switch
+     * @type {string}
+     */
     labelValue: string;
-    /** Sets the switch in checked state */
+    /**
+     * Sets the switch in checked state
+     * @type {boolean}
+     * @default false
+     */
     checked: boolean;
-    /** Sets the switch in disabled state */
+    /**
+     * Sets the switch in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the switch's size */
+    /**
+     * Sets the switch's size
+     * @type {"medium" | "large"}
+     * @default "medium"
+     */
     size: "medium" | "large";
-    /** Toggles the required sign in the field */
+    /**
+     * Toggles the required sign in the field
+     * @type {boolean}
+     * @default false
+     */
     isRequired: boolean;
-    /** Sets the value in the input. Usually uses checked prop as string.
-    *  Used to manage Reactive forms and other native functionality */
+    /**
+     * Sets the value in the input. Usually uses checked prop as string.
+     * Used to manage Reactive forms and other native functionality
+     * @type {string}
+     */
     value: string;
-    /** Aligns the label in relation to the switch*/
+    /**
+     * Aligns the label in relation to the switch
+     * @type {"start" | "end"}
+     * @default "end"
+     */
     labelAlignment: "start" | "end";
     hostEl: HTMLElement;
     internals: ElementInternals;
-    /** Makes a custom change to target property using checked (use for React components) */
+    /**
+     * Makes a custom change to target property using checked (use for React components)
+     * @event check
+     * @type {EventEmitter<boolean>}
+     */
     check: EventEmitter<boolean>;
+    /**
+     * Internal state of the switch
+     * @private
+     */
     private state;
+    /**
+     * Component lifecycle hook - sets switch state
+     * @private
+     */
     componentWillRender(): void;
+    /**
+     * Component lifecycle hook - sets form value
+     * @private
+     */
     componentDidLoad(): void;
     /**
      * Executes every time checked value changes.
      * Sets form value in order to work properly with native forms
-     *
-     * @returns void
+     * @private
      */
     setCheckedStates(): void;
     /**
-     * Executes every time the switch is being click.
+     * Executes every time the switch is being clicked.
      * Executes toggleCheck method.
-     *
-     * @param event - MouseEvent
-     * @returns void
+     * @private
+     * @param {MouseEvent} _ - The mouse event (unused)
      */
     handleClick(_: MouseEvent): void;
     /**
     * Toggles switch value.
     * Emits check event with checked value.
-    *
-    * @returns Promise<void>
+    * @method
+    * @public
+    * @returns {Promise<void>}
     */
     toggleCheck(): Promise<void>;
     /**
      * Determine state of the switch based on the checked property.
      * When checked is true, state is checked.
      * When checked is false, state is unchecked.
-     *
-     * @returns void
+     * @private
      */
     private setSwitchState;
     /**
      * Returns the icon prop based on the state and calculate the size.
-     *
-     * @returns HTMLStencilElement
+     * @private
+     * @returns {HTMLStencilElement} The switch icon element
      */
     private renderSwitch;
     /**
     * Returns the vds-label for the switch when there is a label provided.
-    *
-    * @returns HTMLStencilElement
+    * @private
+    * @returns {HTMLStencilElement} The label element
     */
     private renderLabel;
+    /**
+     * Render the switch component
+     * @returns {HTMLElement} The rendered switch element
+     */
     render(): any;
 }