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

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

@@ -1,51 +1,188 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
 import { DropdownItemClickedEvent } from './vds-dropdown-item-clicked-event';
+/**
+ * @component vds-dropdown-item
+ * @description A dropdown item component that can display as a selectable option with optional checkmarks, icons, and link functionality. Supports custom content mode and various styling states.
+ * @slot - The default slot for custom content (only when type is "custom")
+ */
 export declare class VdsDropdownItem {
-    /** Puts the VdsDropdownItem in disabled state */
+    /**
+     * Puts the VdsDropdownItem in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Define the icon value */
+    /**
+     * Define the icon value
+     * @type {string}
+     */
     informativeIcon: string;
-    /** Define item as active when is true */
+    /**
+     * Define item as active when is true
+     * @type {boolean}
+     * @default false
+     */
     isActive: boolean;
-    /** Defines the element as a link */
+    /**
+     * Defines the element as a link
+     * @type {string}
+     * @default null
+     */
     linkHref: string;
-    /** Sets the link target value */
+    /**
+     * Sets the link target value
+     * @type {"_self" | "_blank" | "_parent" | "_top"}
+     * @default "_self"
+     */
     linkTarget: '_self' | '_blank' | '_parent' | '_top';
-    /** Sets the link rel value */
+    /**
+     * Sets the link rel value
+     * @type {string}
+     * @default null
+     */
     linkRel: string;
-    /** Define item value */
+    /**
+     * Define item value
+     * @type {string}
+     */
     value: string;
-    /** Define item label */
+    /**
+     * Define item label
+     * @type {string}
+     */
     label: string;
-    /** Define aria-label */
+    /**
+     * Define aria-label
+     * @type {string}
+     */
     setAriaLabel: string;
-    /** Set size of menu item */
+    /**
+     * Set size of dropdown item
+     * @type {"small" | "medium" | "large"}
+     * @default "medium"
+     */
     size: 'small' | 'medium' | 'large';
-    /** Shows checkmark */
+    /**
+     * Shows checkmark
+     * @type {boolean}
+     * @default false
+     */
     hasCheckmark: boolean;
-    /** Set state of checkmark */
+    /**
+     * Set state of checkmark
+     * @type {boolean}
+     * @default false
+     */
     isSelected: boolean;
-    /** When has-checkmark is true, sets the checks element as checkmark or checkbox.  */
+    /**
+     * When has-checkmark is true, sets the check element as checkmark or checkbox
+     * @type {"checkbox" | "checkmark"}
+     * @default "checkmark"
+     */
     checkmarkVariant: 'checkbox' | 'checkmark';
-    /** When has-checkmark is true, sets the checks element at the beginning or end.  */
+    /**
+     * When has-checkmark is true, sets the check element at the beginning or end
+     * @type {"start" | "end"}
+     * @default "start"
+     */
     checkmarkAlignment: 'start' | 'end';
-    /** Sets the dropdown item to danger state.  */
+    /**
+     * Sets the dropdown item to danger state
+     * @type {boolean}
+     * @default false
+     */
     danger: boolean;
-    /** Emits event when item gets clicked */
+    /**
+     * Controls the rendering mode of the dropdown item.
+     * - 'default': Renders the item with the standard layout and functionality.
+     * - 'custom': Allows insertion of custom HTML/content inside the item.
+     * When set to 'custom', you can provide custom HTML as children to this component.
+     * @type {"default" | "custom"}
+     * @default "default"
+     */
+    type: 'default' | 'custom';
+    /**
+     * Emits event when item gets clicked
+     * @event dropdownItemClicked
+     * @type {EventEmitter<DropdownItemClickedEvent>}
+     */
     dropdownItemClicked: EventEmitter<DropdownItemClickedEvent>;
-    /** Emits event when item is selected */
+    /**
+     * Emits event when item is selected
+     * @event selected
+     * @type {EventEmitter<MouseEvent>}
+     */
     selected: EventEmitter<MouseEvent>;
-    /** Emits event when item is deselected */
+    /**
+     * Emits event when item is deselected
+     * @event deselected
+     * @type {EventEmitter<MouseEvent>}
+     */
     deselected: EventEmitter<MouseEvent>;
+    /**
+     * Reference to the host element
+     * @type {HTMLElement}
+     */
     hostEl: HTMLElement;
+    /**
+     * Updates the item active state when isSelected changes
+     * @returns {void}
+     */
     updateItemState(): void;
+    /**
+     * Handles click events on the dropdown item
+     * @private
+     * @param {MouseEvent} evt - The mouse click event
+     * @returns {void}
+     */
     private handleClick;
+    /**
+     * Handles selected/deselected state changes and emits appropriate events
+     * @private
+     * @param {MouseEvent} evt - The mouse event
+     * @returns {void}
+     */
     private handleSelected;
+    /**
+     * Generates the checkmark icon button element
+     * @private
+     * @returns {JSX.Element} The rendered checkmark icon button
+     */
     private generateCheckmarkIconButton;
+    /**
+     * Generates the checkbox element
+     * @private
+     * @returns {JSX.Element} The rendered checkbox
+     */
     private generateCheckbox;
+    /**
+     * Generates the informative icon element
+     * @private
+     * @returns {JSX.Element} The rendered informative icon
+     */
     private generateInformativeIcon;
+    /**
+     * Generates the label element
+     * @private
+     * @returns {JSX.Element} The rendered label
+     */
     private generateLabel;
+    /**
+     * Sets the aria-label text from setAriaLabel, label, or value props
+     * @private
+     * @returns {string} The aria-label text
+     */
     private setAriaLabelText;
+    /**
+     * Renders the dropdown content based on the type prop (default or custom)
+     * @private
+     * @returns {JSX.Element} The rendered dropdown content
+     */
+    private renderDropdownContent;
+    /**
+     * Renders the dropdown item component
+     * @returns {HTMLStencilElement} The rendered dropdown item element
+     */
     render(): HTMLStencilElement;
 }

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

@@ -1,106 +1,434 @@
 import { EventEmitter } from "../../stencil-public-runtime";
 import { HTMLStencilElement } from "../../stencil-public-runtime";
 import { DropdownItemClickedEvent } from "../dropdown-item/vds-dropdown-item-clicked-event";
+/**
+ * @component vds-basic-dropdown-multiselect
+ * @description A multi-select dropdown component that allows users to select multiple options from a list. Form-associated with support for custom icons, filtering, and accessible keyboard navigation.
+ * @slot - The default slot for dropdown items (vds-dropdown-item components)
+ * @example
+ * <!-- Basic multi-select dropdown -->
+ * <vds-basic-dropdown-multiselect
+ *   id="basic-multiselect"
+ *   placeholder="Select options">
+ *   <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-multiselect>
+ * <script>
+ *   const basicMultiselect = document.getElementById('basic-multiselect');
+ *   basicMultiselect.value = ['option1', 'option2'];
+ * </script>
+ *
+ * <!-- With display limit and custom text -->
+ * <vds-basic-dropdown-multiselect
+ *   placeholder="Select items"
+ *   display-selection-limit="2"
+ *   display-selection-limit-text="items selected">
+ *   <vds-dropdown-item value="item1">Item 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="item2">Item 2</vds-dropdown-item>
+ *   <vds-dropdown-item value="item3">Item 3</vds-dropdown-item>
+ *   <vds-dropdown-item value="item4">Item 4</vds-dropdown-item>
+ * </vds-basic-dropdown-multiselect>
+ *
+ * <!-- With informative icon and clear button -->
+ * <vds-basic-dropdown-multiselect
+ *   placeholder="Choose categories"
+ *   informative-icon="tag"
+ *   show-clear-button
+ *   size="large">
+ *   <vds-dropdown-item value="category1">Category 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="category2">Category 2</vds-dropdown-item>
+ * </vds-basic-dropdown-multiselect>
+ *
+ * <!-- Disabled and readonly states -->
+ * <vds-basic-dropdown-multiselect
+ *   id="disabled-multiselect"
+ *   placeholder="Disabled"
+ *   disabled>
+ *   <vds-dropdown-item value="val1">Value 1</vds-dropdown-item>
+ * </vds-basic-dropdown-multiselect>
+ * <script>
+ *   const disabledMultiselect = document.getElementById('disabled-multiselect');
+ *   disabledMultiselect.value = ['val1'];
+ * </script>
+ *
+ * <vds-basic-dropdown-multiselect
+ *   id="readonly-multiselect"
+ *   placeholder="Read only"
+ *   is-readonly>
+ *   <vds-dropdown-item value="val2">Value 2</vds-dropdown-item>
+ * </vds-basic-dropdown-multiselect>
+ * <script>
+ *   const readonlyMultiselect = document.getElementById('readonly-multiselect');
+ *   readonlyMultiselect.value = ['val2'];
+ * </script>
+ *
+ * <!-- With error state and max height -->
+ * <vds-basic-dropdown-multiselect
+ *   placeholder="Select tags"
+ *   error
+ *   max-height="200px"
+ *   match-width>
+ *   <vds-dropdown-item value="tag1">Tag 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="tag2">Tag 2</vds-dropdown-item>
+ *   <vds-dropdown-item value="tag3">Tag 3</vds-dropdown-item>
+ *   <vds-dropdown-item value="tag4">Tag 4</vds-dropdown-item>
+ *   <vds-dropdown-item value="tag5">Tag 5</vds-dropdown-item>
+ * </vds-basic-dropdown-multiselect>
+ *
+ * <!-- With custom position -->
+ * <vds-basic-dropdown-multiselect
+ *   placeholder="Opens above"
+ *   position="top"
+ *   match-width>
+ *   <vds-dropdown-item value="item1">Item 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="item2">Item 2</vds-dropdown-item>
+ *   <vds-dropdown-item value="item3">Item 3</vds-dropdown-item>
+ * </vds-basic-dropdown-multiselect>
+ *
+ * <vds-basic-dropdown-multiselect
+ *   placeholder="Opens left"
+ *   position="left"
+ *   match-width>
+ *   <vds-dropdown-item value="item1">Item 1</vds-dropdown-item>
+ *   <vds-dropdown-item value="item2">Item 2</vds-dropdown-item>
+ *   <vds-dropdown-item value="item3">Item 3</vds-dropdown-item>
+ * </vds-basic-dropdown-multiselect>
+ */
 export declare class VdsBasicDropdownMultiselect {
-    /** 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 value (array of selected item values)
+     * @type {string[] | string}
+     * @default []
+     */
     value: string[] | string;
-    /** Allows user to define a information icon to the left of the dropdown. */
+    /**
+     * Allows user to define an information icon to the left of the dropdown
+     * @type {string}
+     */
     informativeIcon: string;
-    /** Sets the dropdown's placeholder. */
+    /**
+     * Sets the dropdown's placeholder
+     * @type {string}
+     */
     placeholder: string;
-    /** Sets the dropdown in disabled state. */
+    /**
+     * Sets the dropdown in disabled state
+     * @type {boolean}
+     */
     disabled: boolean;
-    /** Sets the dropdown in readonly state. */
+    /**
+     * Sets the dropdown in readonly state
+     * @type {boolean}
+     */
     isReadonly: boolean;
-    /** Sets the dropdown in error state. */
+    /**
+     * Sets the dropdown in error state
+     * @type {boolean}
+     */
     error: boolean;
-    /** Sets the dropdown's trigger event. */
+    /**
+     * Sets the dropdown's trigger event
+     * @type {"click"}
+     * @default "click"
+     */
     event: "click";
-    /** Sets the dropdown's value max items selected in plain text. */
+    /**
+     * Sets the dropdown's value max items selected to display in plain text
+     * @type {number}
+     */
     displaySelectionLimit: number;
-    /** Sets displaySelectionLimit text */
+    /**
+     * Sets displaySelectionLimit text
+     * @type {string}
+     * @default "Items selected"
+     */
     displaySelectionLimitText: string;
-    /** Sets the dropdown's clear button visibility. */
+    /**
+     * Sets the dropdown's clear button visibility
+     * @type {boolean}
+     * @default true
+     */
     showClearButton: boolean;
-    /** Set the max height value for the floating container of the items */
+    /**
+     * Set the max height value for the floating container of the items
+     * @type {string}
+     */
     maxHeight: string;
-    /** Sets the width value for the floating container of the items to match the dropdown width */
+    /**
+     * Sets the width value for the floating container of the items to match the dropdown width
+     * @type {boolean}
+     * @default false
+     */
     matchWidth: boolean;
-    /** Toggles the floating container auto-positioning based on available window space.
+    /**
+     * 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
+     * @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 */
+    /**
+     * Emits event when floating element gets opened
+     * @event opened
+     * @type {EventEmitter<void>}
+     */
     opened: EventEmitter<void>;
-    /** Emits event when floating element gets closes */
+    /**
+     * Emits event when floating element gets closed
+     * @event closed
+     * @type {EventEmitter<void>}
+     */
     closed: EventEmitter<void>;
-    /** Emits event when an item is selected, this event contains the value of the selected item */
+    /**
+     * Emits event when an item is selected, this event contains the value of the selected items
+     * @event valueChanged
+     * @type {EventEmitter<string[]>}
+     */
     valueChanged: EventEmitter<string[]>;
-    /** Emits an event when the clear button is clicked */
+    /**
+     * Emits an event when the clear button is clicked
+     * @event cleared
+     * @type {EventEmitter<boolean>}
+     */
     cleared: EventEmitter<boolean>;
+    /**
+     * Internal state tracking whether the dropdown is opened
+     * @type {boolean}
+     */
     isOpened: boolean;
+    /**
+     * Reference to the host element
+     * @type {HTMLElement}
+     */
     hostEl: HTMLElement;
+    /**
+     * ElementInternals API for form association
+     * @type {ElementInternals}
+     */
     internals: ElementInternals;
+    /**
+     * Reference to the dropdown trigger button
+     * @private
+     * @type {HTMLButtonElement}
+     */
     private dropdownTrigger;
+    /**
+     * Reference to the dropdown content container
+     * @private
+     * @type {HTMLDivElement}
+     */
     private dropdownContent;
+    /**
+     * Array of dropdown item elements
+     * @private
+     * @type {HTMLVdsDropdownItemElement[]}
+     */
     private options;
+    /**
+     * MutationObserver for watching slot changes
+     * @private
+     * @type {MutationObserver}
+     */
     private observer;
+    /**
+     * Cleanup function for floating positioning
+     * @private
+     * @type {() => void}
+     */
     private floatingCleanUp;
+    /**
+     * Lifecycle hook that runs after component is loaded
+     * @returns {void}
+     */
     componentDidLoad(): void;
+    /**
+     * Lifecycle hook that runs when component is disconnected
+     * @returns {void}
+     */
     disconnectedCallback(): void;
-    private setListenerForChildren;
+    /**
+     * Renders the dropdown options from slotted items
+     * @private
+     * @returns {void}
+     */
+    private renderOptions;
+    /**
+     * Handles slot change events to update options
+     * @private
+     * @returns {void}
+     */
+    private handleSlotChange;
+    /**
+     * Watches for value changes to update internal state and form value
+     * Validates whether the newValue is string or array and normalizes to array format
+     * @param {string | string[]} newValue - The new value(s)
+     * @returns {void}
+     */
     setValueHandler(newValue: string[] | string): void;
+    /**
+     * Lifecycle hook that runs after each render
+     * Updates options list and floating position
+     * @returns {void}
+     */
     componentDidRender(): void;
+    /**
+     * Watches for dropdown open state changes and manages positioning
+     * @returns {Promise<void>}
+     */
     toggleDropdown(): Promise<void>;
+    /**
+     * Opens the floating dropdown menu
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the dropdown is opened
+     */
     open(): Promise<void>;
+    /**
+     * Closes the floating dropdown menu
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the dropdown is closed
+     */
     close(): Promise<void>;
     /**
-     * Clears the selected options and resets the value of the dropdown.
-     *
-     * @returns {Promise<void>} A promise that resolves when the clearing operation is complete.
+     * Clears the selected options and resets the value of the dropdown
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the clearing operation is complete
      */
     clear(): Promise<void>;
     /**
-     *  Gets the target that will manage the menu
-     *  returns a promise with the target HTMLElement.
-     *
-     *  @returns {Promise<HTMLElement>} A promise that resolves with the target html element.
+     * Gets the target element that manages the dropdown menu
+     * @method
+     * @public
+     * @returns {Promise<HTMLElement | null>} A promise that resolves with the target html element
      */
     getTarget(): Promise<HTMLElement | null>;
     /**
-     *  Gets the selected value of the dropdown
-     *  returns a promise with the value.
-     *
-     *  @returns {Promise<string[]>} A promise that resolves with the value as string[].
+     * Gets the selected value of the dropdown
+     * @method
+     * @public
+     * @returns {Promise<string[]>} A promise that resolves with the value as string[]
      */
     getValue(): Promise<string[]>;
     /**
-     * Sets the selected value(s) for the dropdown.
-     *
-     * @param {string[] | string} value The new value or array of values to select.
-     * @returns {Promise<void>} A promise that resolves when the value is set.
+     * Sets the selected value(s) for the dropdown
+     * @method
+     * @public
+     * @param {string[] | string} value - The new value or array of values to select
+     * @returns {Promise<void>} A promise that resolves when the value is set
      */
     setValue(value: string[] | string): Promise<void>;
-    private handleClickOut;
     /**
-     * Listen when Dropdown Item element is clicked to close Dropdown Items window, set the value and emit the changes.
-     *
-     * @param {CustomEvent<DropdownItemClickedEvent>} event The dropdown item clicked event.
+     * Closes the floating element when clicking outside the component
+     * @param {MouseEvent} evt - The mouse click event
+     * @returns {void}
+     */
+    handleClickOut(evt: MouseEvent): void;
+    /**
+     * Listens for dropdown item clicks to toggle selection and update value
+     * @param {CustomEvent<DropdownItemClickedEvent>} event - The dropdown item clicked event
+     * @returns {void}
      */
     handleDropdownSelection(event: CustomEvent<DropdownItemClickedEvent>): void;
+    /**
+     * Opens the floating element with click on the trigger element
+     * @private
+     * @returns {void}
+     */
     private handleClick;
-    private handleFloatingKeydown;
+    /**
+     * 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;
+    /**
+     * Handles clear icon click to clear selection and close dropdown
+     * @private
+     * @param {Event} evt - The click event
+     * @returns {void}
+     */
     private clearIconClick;
+    /**
+     * Renders the label/value display for the dropdown trigger
+     * @private
+     * @returns {HTMLStencilElement} The label element
+     */
     private renderLabelValue;
+    /**
+     * Gets the text value to display based on selection and display limit
+     * @private
+     * @returns {string} The display text
+     */
     private getTextValue;
+    /**
+     * Gets the icon color based on disabled and readonly states
+     * @private
+     * @returns {string} The icon color
+     */
     private getIconColor;
+    /**
+     * Renders the informative icon if specified
+     * @private
+     * @returns {HTMLStencilElement} The icon element
+     */
     private renderInformativeIcon;
+    /**
+     * Renders the clear button icon
+     * @private
+     * @returns {HTMLStencilElement} The clear icon button element
+     */
     private renderClearIcon;
+    /**
+     * Renders the dropdown chevron icon
+     * @private
+     * @returns {HTMLStencilElement} The dropdown icon element
+     */
     private renderDropdownIcon;
+    /**
+     * Checks if the dropdown has any selected values
+     * @private
+     * @returns {boolean} True if there are selected values
+     */
     private hasValue;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }

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

@@ -28,6 +28,12 @@ declare const _default: {
                 type: string;
             };
         };
+        position: {
+            options: string[];
+            control: {
+                type: string;
+            };
+        };
     };
 };
 export default _default;