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

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

@@ -1,48 +1,264 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * @component vds-basic-dropdown
+ * @description A dropdown component that provides a selectable menu of options.
+ * Supports single selection with customizable trigger events (click/hover).
+ * Includes features like search filtering, keyboard navigation, and form integration.
+ * Can display informative icons, clear buttons, and custom positioning.
+ * @slot (default) - Dropdown items to display in the menu
+ * @example
+ * <!-- Basic dropdown with placeholder -->
+ * <vds-basic-dropdown
+ *   placeholder="Select an option"
+ *   match-width>
+ *   <vds-dropdown-item value="option1">Option 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="option2">Option 2</vds-dropdown-item>
+ *   <vds-dropdown-item value="option3">Option 3</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- Dropdown with pre-selected value -->
+ * <vds-basic-dropdown
+ *   value="option2"
+ *   placeholder="Choose"
+ *   match-width>
+ *   <vds-dropdown-item value="option1">Option 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="option2">Option 2</vds-dropdown-item>
+ *   <vds-dropdown-item value="option3">Option 3</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- Dropdown with informative icon -->
+ * <vds-basic-dropdown
+ *   placeholder="Select country"
+ *   informative-icon="system"
+ *   size="large"
+ *   match-width>
+ *   <vds-dropdown-item value="us">United States</vds-dropdown-item>
+ *   <vds-dropdown-item value="uk">United Kingdom</vds-dropdown-item>
+ *   <vds-dropdown-item value="ca">Canada</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- Dynamic informative icon from selected item -->
+ * <vds-basic-dropdown
+ *   placeholder="Choose status"
+ *   dynamic-informative-icon
+ *   match-width>
+ *   <vds-dropdown-item value="active" informative-icon="checked">Active</vds-dropdown-item>
+ *   <vds-dropdown-item value="pending" informative-icon="time">Pending</vds-dropdown-item>
+ *   <vds-dropdown-item value="inactive" informative-icon="error">Inactive</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- Dropdown with hover trigger -->
+ * <vds-basic-dropdown
+ *   event="hover"
+ *   placeholder="Hover to open"
+ *   match-width>
+ *   <vds-dropdown-item value="item1">Item 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="item2">Item 2</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- Disabled and readonly states -->
+ * <vds-basic-dropdown
+ *   disabled
+ *   value="disabled-value"
+ *   placeholder="Disabled"
+ *   match-width>
+ *   <vds-dropdown-item value="disabled-value">Disabled Item</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <vds-basic-dropdown
+ *   is-readonly
+ *   value="readonly-value"
+ *   placeholder="Read only"
+ *   match-width>
+ *   <vds-dropdown-item value="readonly-value">Read Only Item</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- With error state and max height -->
+ * <vds-basic-dropdown
+ *   error
+ *   max-height="200px"
+ *   match-width
+ *   placeholder="Select">
+ *   <vds-dropdown-item value="1">Item 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="2">Item 2</vds-dropdown-item>
+ *   <vds-dropdown-item value="3">Item 3</vds-dropdown-item>
+ *   <vds-dropdown-item value="4">Item 4</vds-dropdown-item>
+ *   <vds-dropdown-item value="5">Item 5</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- Small size without clear button -->
+ * <vds-basic-dropdown
+ *   size="small"
+ *   show-clear-button="false"
+ *   placeholder="Compact dropdown"
+ *   match-width>
+ *   <vds-dropdown-item value="a">Option A</vds-dropdown-item>
+ *   <vds-dropdown-item value="b">Option B</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- With backdrop overlay -->
+ * <vds-basic-dropdown
+ *   backdrop
+ *   placeholder="Select with backdrop"
+ *   match-width>
+ *   <vds-dropdown-item value="opt1">Option 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="opt2">Option 2</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- Dropdown without match-width (auto-sized menu) -->
+ * <vds-basic-dropdown
+ *   placeholder="Auto-width menu">
+ *   <vds-dropdown-item value="short">Short</vds-dropdown-item>
+ *   <vds-dropdown-item value="medium-length">Medium Length Option</vds-dropdown-item>
+ *   <vds-dropdown-item value="very-long">Very Long Option With Lots of Text</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <!-- Dropdown with custom position -->
+ * <vds-basic-dropdown
+ *   position="top"
+ *   placeholder="Opens above"
+ *   match-width>
+ *   <vds-dropdown-item value="item1">Item 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="item2">Item 2</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ *
+ * <vds-basic-dropdown
+ *   position="left"
+ *   placeholder="Opens left"
+ *   match-width>
+ *   <vds-dropdown-item value="item1">Item 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="item2">Item 2</vds-dropdown-item>
+ * </vds-basic-dropdown>
+ */
 export declare class VdsBasicDropdown {
     hostEl: HTMLElement;
-    /** Sets the dropdown's size. */
+    /**
+     * Sets the dropdown's size.
+     * @type {('small' | 'medium' | 'large')}
+     * @default "medium"
+     */
     size: 'small' | 'medium' | 'large';
-    /** Sets the dropdown's value. */
+    /**
+     * Sets the dropdown's selected value.
+     * @type {string}
+     * @default undefined
+     */
     value: string;
-    /** Allows user to define a information icon to the left of the dropdown. */
+    /**
+     * Defines an informative icon to display on the left of the dropdown.
+     * @type {string}
+     * @default undefined
+     */
     informativeIcon: string;
-    /** Allows dropdown-item informativeIcon reflect dynamically as informativeIcon of the dropdown. */
+    /**
+     * Allows dropdown-item informativeIcon to reflect dynamically as the dropdown's informativeIcon.
+     * When true, the selected item's icon becomes the dropdown's icon.
+     * @type {boolean}
+     * @default false
+     */
     dynamicInformativeIcon: boolean;
-    /** Sets the dropdown's placeholder. */
+    /**
+     * Sets the dropdown's placeholder text.
+     * @type {string}
+     * @default undefined
+     */
     placeholder: string;
-    /** Sets the dropdown in disabled state. */
+    /**
+     * Sets the dropdown in disabled state, preventing user interaction.
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the dropdown in readonly state. */
+    /**
+     * Sets the dropdown in readonly state.
+     * @type {boolean}
+     * @default false
+     */
     isReadonly: boolean;
-    /** Sets the dropdown in error state. */
+    /**
+     * Sets the dropdown in error state for validation feedback.
+     * @type {boolean}
+     * @default undefined
+     */
     error: boolean;
-    /** Sets the dropdown's trigger event. */
+    /**
+     * Sets the dropdown's trigger event.
+     * @type {('click' | 'hover')}
+     * @default "click"
+     */
     event: 'click' | 'hover';
-    /** Sets the dropdown's clear button visibility. */
+    /**
+     * Controls the visibility of the clear button.
+     * @type {boolean}
+     * @default true
+     */
     showClearButton: boolean;
-    /** Set the max height value for the floating container of the items */
+    /**
+     * Sets the max height value for the floating container of the items.
+     * @type {string}
+     * @default undefined
+     */
     maxHeight: string;
-    /** Sets the width value for the floating container of the items to match the dropdown width */
+    /**
+     * Sets the floating container width to match the dropdown width.
+     * @type {boolean}
+     * @default false
+     */
     matchWidth: boolean;
     /**
      * Toggles the floating container auto-positioning based on available window space.
-     * False by default as it may cause positioning issues in some situations, use with caution
+     * False by default as it may cause positioning issues in some situations, use with caution.
+     * @type {boolean}
+     * @default false
      */
     autoPosition: boolean;
-    /** Toggles the overlay element, allowing interaction only with this element when active */
+    /**
+     * Defines the position where the dropdown will be opened.
+     * @type {"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end"}
+     * @default "bottom"
+     */
+    position: 'top' | 'bottom' | 'right' | 'left' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+    /**
+     * Toggles the overlay element, allowing interaction only with this element when active.
+     * @type {boolean}
+     * @default false
+     */
     backdrop: boolean;
-    /** Emits event when floating element gets opens */
+    /**
+     * Emitted when the floating element opens.
+     * @event opened
+     * @type {EventEmitter<void>}
+     */
     opened: EventEmitter<void>;
-    /** Emits event when floating element gets closes */
+    /**
+     * Emitted when the floating element closes.
+     * @event closed
+     * @type {EventEmitter<void>}
+     */
     closed: EventEmitter<void>;
-    /** Emits event when an item is selected, this event contains the value of the selected item */
+    /**
+     * Emitted when an item is selected. Contains the value of the selected item.
+     * @event valueChanged
+     * @type {EventEmitter<string>}
+     */
     valueChanged: EventEmitter<string>;
-    /** Emits an event when the clear button is clicked */
+    /**
+     * Emitted when the clear button is clicked.
+     * @event cleared
+     * @type {EventEmitter<boolean>}
+     */
     cleared: EventEmitter<boolean>;
-    /** Dropdown's status. */
+    /**
+     * Dropdown's open/closed status.
+     * @type {boolean}
+     * @default false
+     */
     dropdownOpened: boolean;
-    /** Dropdown's label of the current value. */
+    /**
+     * Dropdown's label of the current value.
+     * @type {string}
+     * @default undefined
+     */
     private valueLabel;
     internals: ElementInternals;
     private actionElementRef;
@@ -51,50 +267,234 @@ export declare class VdsBasicDropdown {
     private options;
     private floatingCleanUp;
     observer: any;
+    /**
+     * Watches dropdownOpened state and manages floating container visibility.
+     * Emits opened/closed events and handles floating positioning.
+     * Scrolls to selected value when opened.
+     * @private
+     * @returns {Promise<void>}
+     */
     emitValue(): Promise<void>;
+    /**
+     * Watches value changes and updates UI, form value, and selection state.
+     * Emits input event and updates value label.
+     * @private
+     * @returns {void}
+     */
     setValueHandler(): void;
+    /**
+     * Sets the form value for form integration.
+     * @private
+     * @returns {void}
+     */
     private setFormValue;
-    private handleClickOut;
-    private handleFloatingKeydown;
+    /**
+     * Listens for clicks outside the dropdown to close it.
+     * @private
+     * @param {MouseEvent} evt - The mouse click event
+     * @returns {void}
+     */
+    handleClickOut(evt: MouseEvent): void;
+    /**
+     * Handles click events on the trigger element.
+     * Opens/closes dropdown when event type is 'click' and not disabled/readonly.
+     * @private
+     * @returns {void}
+     */
     private handleClick;
+    /**
+     * Clears the selected value from the dropdown.
+     * Stops event propagation and closes the dropdown.
+     * @private
+     * @param {Event} evt - The clear button click event
+     * @returns {void}
+     */
     private clearValue;
+    /**
+     * Listens for dropdown item click events.
+     * Handles selection, emits events, and updates dynamic icon if enabled.
+     * @private
+     * @param {CustomEvent<DropdownItemClickedEvent>} event - The dropdown item clicked event
+     * @returns {void}
+     */
     private handleDropdownItemClicked;
+    /**
+     * Handles item selection logic.
+     * Sets the value and value label from the selected item.
+     * @private
+     * @param {CustomEvent<DropdownItemClickedEvent>} event - The dropdown item clicked event
+     * @returns {void}
+     */
     private handleSelection;
+    /**
+     * Opens the floating element (menu) of the dropdown.
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     open(): Promise<void>;
+    /**
+     * Closes the floating element (menu) of the dropdown.
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     close(): Promise<void>;
+    /**
+     * Clears the selected value from the dropdown.
+     * Resets value, label, and dynamic icon. Unselects all items and emits events.
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     clear(): Promise<void>;
     /**
-     *  Gets the target that will manage the menu
-     *  returns a promise with the target HTMLElement.
+     * Gets the trigger target element that manages the menu.
+     * @method
+     * @public
+     * @returns {Promise<HTMLElement | null>} A promise that resolves with the target HTMLElement
      */
     getTarget(): Promise<HTMLElement | null>;
     /**
-     *  Gets the selected value of the dropdown
-     *  returns a promise with the value.
+     * Gets the selected value of the dropdown.
+     * @method
+     * @public
+     * @returns {Promise<String | null>} A promise that resolves with the selected value
      */
     getValue(): Promise<String | null>;
     /**
-     *  Set the value of the dropdown
+     * Sets the value of the dropdown.
+     * Clears the current selection before setting the new value.
+     * @method
+     * @public
+     * @param {string} value - The value to set
+     * @returns {Promise<void>}
      */
     setValue(value: string): Promise<void>;
+    /**
+     * Handles hover event on the trigger element.
+     * Opens dropdown when event type is 'hover'.
+     * @private
+     * @param {Event} event - The mouse hover event
+     * @returns {void}
+     */
     private handleHover;
+    /**
+     * Handles hover out event.
+     * Closes dropdown when event type is 'hover'.
+     * @private
+     * @param {Event} event - The mouse hover out event
+     * @returns {void}
+     */
     private handleHoverOut;
+    /**
+     * Sets a predefined item as selected based on the current value.
+     * @private
+     * @returns {void}
+     */
     private setPredefinedItem;
+    /**
+     * Finds and sets a predefined item that is already marked as selected.
+     * @private
+     * @returns {void}
+     */
     private findAndSetPredefinedItem;
+    /**
+     * Defines the dropdown value based on selected items.
+     * @private
+     * @returns {void}
+     */
     private defineValue;
+    /**
+     * Component lifecycle method called before the component loads.
+     * Initializes default informative icon if dynamic icon is enabled.
+     * @returns {void}
+     */
     componentWillLoad(): void;
+    /**
+     * Component lifecycle method called after each render.
+     * Updates dropdown items, floating position, and container width.
+     * @returns {void}
+     */
     componentDidRender(): void;
+    /**
+     * Component lifecycle method called after the component loads.
+     * Sets up event listeners, initializes selection, and renders options.
+     * @returns {void}
+     */
     componentDidLoad(): void;
+    /**
+     * Component lifecycle method called when the component is disconnected.
+     * Removes event listeners and disconnects observer.
+     * @returns {void}
+     */
     disconnectedCallback(): void;
-    private setListenerForChildren;
-    /** Gets the icon color.
-     *
-     * @returns string
+    /**
+     * Renders and updates the dropdown options list.
+     * @private
+     * @returns {void}
+     */
+    private renderOptions;
+    /**
+     * Handles slot change events to update options.
+     * @private
+     * @returns {void}
+     */
+    private handleSlotChange;
+    /**
+     * Gets the appropriate icon color based on disabled and readonly states.
+     * @private
+     * @returns {string} The icon color
      */
     private getIconColor;
+    /**
+     * Sets the dropdown chevron icon (up or down based on open state).
+     * @private
+     * @returns {HTMLElement} The dropdown icon element
+     */
     private setDropdownIcon;
+    /**
+     * Sets the informative icon if defined.
+     * @private
+     * @returns {HTMLElement | null} The informative icon element or null
+     */
     private setInformativeIcon;
+    /**
+     * Sets the label or placeholder value to display.
+     * @private
+     * @returns {HTMLElement} The label/placeholder element
+     */
     private setLabelValue;
+    /**
+     * Sets the clear value button icon if applicable.
+     * @private
+     * @returns {HTMLElement | null} The clear button element or null
+     */
     private setClearValueButtonIcon;
+    /**
+     * Initializes keyboard navigation for dropdown items.
+     * Subscribes to keyboard events and manages focus within the dropdown.
+     * Closes dropdown on Escape key and restores focus to trigger element.
+     * @private
+     * @returns {void}
+     */
+    private initKeyboardNavigation;
+    /**
+     * Destroys the active keyboard navigation session.
+     * @private
+     * @returns {void}
+     */
+    private destroyKeyboardNavigation;
+    /**
+     * Returns focusable dropdown items that can be navigated
+     * ignores dropdown group headers and disabled items.
+     * @private
+     * @returns {HTMLElement[]} An array of focusable dropdown items.
+     */
+    private getDropdownItems;
+    /**
+     * Renders the dropdown component.
+     * @returns {HTMLElement} The root dropdown element
+     */
     render(): any;
 }

package/dist/types/components/basic-dropdown/vds-basic-dropdown.stories.d.ts

@@ -31,6 +31,12 @@ declare const _default: {
         autoPosition: {
             control: string;
         };
+        position: {
+            options: string[];
+            control: {
+                type: string;
+            };
+        };
     };
 };
 export default _default;
@@ -38,3 +44,5 @@ export declare const BasicUsage: any;
 export declare const BasicWithIconsUsage: any;
 export declare const BasicWithPredefinedItemUsage: any;
 export declare const BasicWithItemCheckmarkUsage: any;
+export declare const AutopositionUsage: any;
+export declare const CustomContentItemsUsage: any;

package/dist/types/components/basic-dropdown/vds-basic-dropdown.utils.d.ts

@@ -31,7 +31,7 @@ export declare const selectSelectedItems: (dropdownContent: HTMLElement, value:
 export declare const getSelectedLabel: (dropdownContent: HTMLElement, value: string) => string;
 export declare const scrollToSelectedValue: (dropdownContent: HTMLElement, value: string[] | string) => void;
 /**
- * Gets thje selected text items in a dropdown.
+ * Gets the selected text items in a dropdown.
  *
  * @param {HTMLElement} dropdownContent The dropdown content element.
  * @param {string[]|string} value The selected value or an array of selected values.
@@ -89,3 +89,10 @@ export declare const setDropdownStyles: (maxHeight: string) => {
  * @param {HTMLDivElement} dropdownContent - The dropdown content element whose width is to be updated.
  */
 export declare const updateContainerWidth: (dropdownTrigger: HTMLElement, matchWidth: boolean, dropdownContent: HTMLDivElement) => void;
+/**
+ * Returns focusable dropdown items that can be navigated
+ * ignores dropdown group headers and disabled items.
+
+ * @returns {HTMLElement[]} An array of focusable dropdown items.
+ */
+export declare const getDropdownFocusableItems: (hostEl: HTMLElement) => HTMLElement[];

package/dist/types/components/breadcrumb-item/vds-breadcrumbs-item.d.ts

@@ -1,7 +1,24 @@
+/**
+ * @component vds-breadcrumbs-item
+ * @description A breadcrumb navigation item component that displays a single step in a breadcrumb trail. Supports disabled and active states for navigation hierarchy indication.
+ * @slot - The content of the breadcrumb item (typically text or a link)
+ */
 export declare class VdsBreadcrumbItem {
-    /** Sets the breacrumb item in disabled state */
+    /**
+     * Sets the breadcrumb item in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the breacrumb item in active state */
+    /**
+     * Sets the breadcrumb item in active state
+     * @type {boolean}
+     * @default false
+     */
     isActive: boolean;
+    /**
+     * Renders the breadcrumb item component
+     * @returns {JSX.Element} The rendered breadcrumb item
+     */
     render(): any;
 }