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

package/dist/collection/components/basic-dropdown/vds-basic-dropdown.js

@@ -1,42 +1,232 @@
-import { Host, h, forceUpdate } from "@stencil/core";
+import { Host, h } from "@stencil/core";
 import { combineClasses } from "../../utils/combine-classes";
 import { updateFloatingBoxPosition } from "../../utils/floating-engine-utils";
 import { getIconSize, getIconColor, getActionIconButtonSize } from "../../utils/icon-attr.utils";
-import { getSelectedLabel, scrollToSelectedValue, selectSelectedItems, setDropdownStyles, toggleContainerDisplay, unselectAllItems, unselectNonSelectedItems, updateContainerWidth, } from "./vds-basic-dropdown.utils";
+import { getDropdownFocusableItems, getSelectedLabel, scrollToSelectedValue, selectSelectedItems, setDropdownStyles, toggleContainerDisplay, unselectAllItems, unselectNonSelectedItems, updateContainerWidth, } from "./vds-basic-dropdown.utils";
 import { emitInputEvent } from "../../utils/form";
+import { KeyboardNavigation } from "../../utils/keyboard-navigation";
+import { getDeepActiveElement } from "../../utils/get-deep-active-element";
+/**
+ * @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 class VdsBasicDropdown {
     constructor() {
-        /** Sets the dropdown's size. */
+        /**
+         * Sets the dropdown's size.
+         * @type {('small' | 'medium' | 'large')}
+         * @default "medium"
+         */
         this.size = 'medium';
-        /** 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
+         */
         this.dynamicInformativeIcon = false;
-        /** Sets the dropdown in disabled state. */
+        /**
+         * Sets the dropdown in disabled state, preventing user interaction.
+         * @type {boolean}
+         * @default false
+         */
         this.disabled = false;
-        /** Sets the dropdown in readonly state. */
+        /**
+         * Sets the dropdown in readonly state.
+         * @type {boolean}
+         * @default false
+         */
         this.isReadonly = false;
-        /** Sets the dropdown's trigger event. */
+        /**
+         * Sets the dropdown's trigger event.
+         * @type {('click' | 'hover')}
+         * @default "click"
+         */
         this.event = 'click';
-        /** Sets the dropdown's clear button visibility. */
+        /**
+         * Controls the visibility of the clear button.
+         * @type {boolean}
+         * @default true
+         */
         this.showClearButton = true;
-        /** 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
+         */
         this.matchWidth = false;
         /**
          * 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
          */
         this.autoPosition = false;
-        /** 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"
+         */
+        this.position = 'bottom';
+        /**
+         * Toggles the overlay element, allowing interaction only with this element when active.
+         * @type {boolean}
+         * @default false
+         */
         this.backdrop = false;
-        /** Dropdown's status. */
+        /**
+         * Dropdown's open/closed status.
+         * @type {boolean}
+         * @default false
+         */
         this.dropdownOpened = false;
-        /** Dropdown's label of the current value. */
+        /**
+         * Dropdown's label of the current value.
+         * @type {string}
+         * @default undefined
+         */
         this.valueLabel = undefined;
         this.options = [];
     }
+    /**
+     * 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>}
+     */
     async emitValue() {
         if (this.dropdownOpened) {
-            this.floatingCleanUp = await updateFloatingBoxPosition(this.actionElementRef, this.dropdownContentElementRef, null, 'bottom', this.autoPosition);
+            this.floatingCleanUp = await updateFloatingBoxPosition(this.actionElementRef, this.dropdownContentElementRef, null, this.position, this.autoPosition, ['top', 'bottom']);
             toggleContainerDisplay(this.dropdownContentElementRef, true);
+            this.initKeyboardNavigation();
             if (this.value) {
                 scrollToSelectedValue(this.dropdownContentElementRef, this.value);
             }
@@ -45,9 +235,16 @@ export class VdsBasicDropdown {
         else {
             toggleContainerDisplay(this.dropdownContentElementRef, false);
             this.floatingCleanUp();
+            this.destroyKeyboardNavigation();
             this.closed.emit();
         }
     }
+    /**
+     * Watches value changes and updates UI, form value, and selection state.
+     * Emits input event and updates value label.
+     * @private
+     * @returns {void}
+     */
     setValueHandler() {
         emitInputEvent(this.hostEl, this.value);
         unselectNonSelectedItems(this.dropdownContentElementRef, this.value);
@@ -56,65 +253,103 @@ export class VdsBasicDropdown {
         this.setFormValue();
         this.valueLabel = getSelectedLabel(this.dropdownContentElementRef, this.value);
     }
+    /**
+     * Sets the form value for form integration.
+     * @private
+     * @returns {void}
+     */
     setFormValue() {
         if (this.internals && !!this.internals.setFormValue) {
             this.internals.setFormValue(this.value);
         }
     }
-    /* Close the floating element when click outside */
+    /**
+     * Listens for clicks outside the dropdown to close it.
+     * @private
+     * @param {MouseEvent} evt - The mouse click event
+     * @returns {void}
+     */
     handleClickOut(evt) {
-        evt.stopPropagation();
-        const isClickInside = this.hostEl.contains(evt.target);
+        const path = evt.composedPath ? evt.composedPath() : [];
+        const isClickInside = path.includes(this.hostEl);
         if (!isClickInside) {
             this.close();
         }
     }
-    /* Close the floating element with keydown on the trigger element  */
-    handleFloatingKeydown(event) {
-        event.stopImmediatePropagation();
-        if (event.key === 'Escape' || event.key === 'Esc') {
-            this.close();
-        }
-    }
-    /* Open the floating element with click on the trigger element  */
-    handleClick(evt) {
-        evt.stopImmediatePropagation();
-        if (this.event === 'click') {
-            const clickedElement = evt.target;
-            if (clickedElement && !this.disabled && !this.isReadonly) {
-                this.dropdownOpened = !this.dropdownOpened;
-            }
+    /**
+     * Handles click events on the trigger element.
+     * Opens/closes dropdown when event type is 'click' and not disabled/readonly.
+     * @private
+     * @returns {void}
+     */
+    handleClick() {
+        if (this.event === 'click' && !this.disabled && !this.isReadonly) {
+            this.dropdownOpened = !this.dropdownOpened;
         }
     }
-    /* Clear selected value from the Dropdown  */
+    /**
+     * 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}
+     */
     clearValue(evt) {
         evt.stopImmediatePropagation();
         this.clear();
         this.close();
     }
-    /* Listen when Dropdown Item element is clicked to close Dropdown Items window */
+    /**
+     * 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}
+     */
     handleDropdownItemClicked(event) {
         this.handleSelection(event);
         this.valueChanged.emit(this.value);
-        const inputEvent = new InputEvent("input");
+        const inputEvent = new InputEvent('input');
         this.hostEl.dispatchEvent(inputEvent);
         this.dynamicInformativeIcon ? (this.informativeIcon = event.detail.icon) : null;
         this.close();
     }
-    /* Checks if the item is already selected and if so clears the selection, otherwise sets the value */
+    /**
+     * 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}
+     */
     handleSelection(event) {
         this.value = event.detail.value;
         this.valueLabel = event.detail.label;
     }
-    /* Open the floating element(menu) of the Dropdown. */
+    /**
+     * Opens the floating element (menu) of the dropdown.
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     async open() {
         this.dropdownOpened = true;
     }
-    /* Close the floating element(menu) of the Dropdown. */
+    /**
+     * Closes the floating element (menu) of the dropdown.
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     async close() {
         this.dropdownOpened = false;
     }
-    /* Clear the selected value from the Dropdown. */
+    /**
+     * Clears the selected value from the dropdown.
+     * Resets value, label, and dynamic icon. Unselects all items and emits events.
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     async clear() {
         this.value = null;
         this.valueLabel = null;
@@ -124,38 +359,66 @@ export class VdsBasicDropdown {
         this.cleared.emit(true);
     }
     /**
-     *  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
      */
     async getTarget() {
         return document.querySelector('.vds__dropdown--trigger');
     }
     /**
-     *  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
      */
     async getValue() {
         return this.value;
     }
     /**
-     *  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>}
      */
     async setValue(value) {
         this.clear();
         this.value = value;
     }
+    /**
+     * Handles hover event on the trigger element.
+     * Opens dropdown when event type is 'hover'.
+     * @private
+     * @param {Event} event - The mouse hover event
+     * @returns {void}
+     */
     handleHover(event) {
         const hoveredElement = event.target;
         if (this.event === 'hover' && hoveredElement) {
             this.dropdownOpened = true;
         }
     }
+    /**
+     * Handles hover out event.
+     * Closes dropdown when event type is 'hover'.
+     * @private
+     * @param {Event} event - The mouse hover out event
+     * @returns {void}
+     */
     handleHoverOut(event) {
         const hoveredElement = event.target;
         if (this.event === 'hover' && hoveredElement) {
             this.close();
         }
     }
+    /**
+     * Sets a predefined item as selected based on the current value.
+     * @private
+     * @returns {void}
+     */
     setPredefinedItem() {
         var _a;
         const slotElement = (_a = this.dropdownContentElementRef) === null || _a === void 0 ? void 0 : _a.querySelector('slot');
@@ -167,6 +430,11 @@ export class VdsBasicDropdown {
             this.valueLabel = preselectedItem.getAttribute('label');
         }
     }
+    /**
+     * Finds and sets a predefined item that is already marked as selected.
+     * @private
+     * @returns {void}
+     */
     findAndSetPredefinedItem() {
         var _a;
         let getPreselectedItem = undefined;
@@ -183,6 +451,11 @@ export class VdsBasicDropdown {
             this.valueLabel = getPreselectedItem.getAttribute('label');
         }
     }
+    /**
+     * Defines the dropdown value based on selected items.
+     * @private
+     * @returns {void}
+     */
     defineValue() {
         if (this.value && !this.valueLabel) {
             this.setPredefinedItem();
@@ -191,27 +464,36 @@ export class VdsBasicDropdown {
             this.findAndSetPredefinedItem();
         }
     }
+    /**
+     * Component lifecycle method called before the component loads.
+     * Initializes default informative icon if dynamic icon is enabled.
+     * @returns {void}
+     */
     componentWillLoad() {
         if (this.dynamicInformativeIcon && this.defaultInformativeIcon === undefined) {
             this.defaultInformativeIcon = this.informativeIcon;
         }
     }
+    /**
+     * Component lifecycle method called after each render.
+     * Updates dropdown items, floating position, and container width.
+     * @returns {void}
+     */
     componentDidRender() {
         this.options = Array.from(this.hostEl.querySelectorAll('vds-dropdown-item'));
-        updateFloatingBoxPosition(this.actionElementRef, this.dropdownContentElementRef, null, 'bottom', false);
+        updateFloatingBoxPosition(this.actionElementRef, this.dropdownContentElementRef, null, this.position, false, ['top', 'bottom']);
         updateContainerWidth(this.actionElementRef, this.matchWidth, this.dropdownContentElementRef);
     }
+    /**
+     * Component lifecycle method called after the component loads.
+     * Sets up event listeners, initializes selection, and renders options.
+     * @returns {void}
+     */
     componentDidLoad() {
-        var _a, _b;
-        if (this.event === 'click') {
-            this.actionElementRef.addEventListener('click', this.handleClick.bind(this));
-        }
-        else if (this.event === 'hover') {
+        if (this.event === 'hover') {
             this.actionElementRef.addEventListener('mouseenter', this.handleHover.bind(this));
             this.dropdownContentElementRef.addEventListener('mouseleave', this.handleHoverOut.bind(this));
         }
-        (_a = this.actionElementRef) === null || _a === void 0 ? void 0 : _a.addEventListener('keydown', this.handleFloatingKeydown.bind(this));
-        (_b = this.dropdownContentElementRef) === null || _b === void 0 ? void 0 : _b.addEventListener('keydown', this.handleFloatingKeydown.bind(this));
         if (!this.dropdownContentElementRef) {
             this.dropdownContentElementRef = this.hostEl.shadowRoot.querySelector('.vds__dropdown--container');
         }
@@ -222,43 +504,59 @@ export class VdsBasicDropdown {
             this.findAndSetPredefinedItem();
         }
         this.setFormValue();
-        this.setListenerForChildren();
+        this.renderOptions();
     }
+    /**
+     * Component lifecycle method called when the component is disconnected.
+     * Removes event listeners and disconnects observer.
+     * @returns {void}
+     */
     disconnectedCallback() {
         var _a;
-        window.removeEventListener('click', this.handleClickOut.bind(this));
-        if (this.event === 'click') {
-            this.actionElementRef.removeEventListener('click', this.handleClick.bind(this));
-        }
-        else if (this.event === 'hover') {
+        if (this.event === 'hover') {
             this.actionElementRef.removeEventListener('mouseenter', this.handleHover.bind(this));
             this.dropdownContentElementRef.removeEventListener('mouseleave', this.handleHoverOut.bind(this));
-            this.actionElementRef.removeEventListener('keydown', this.handleFloatingKeydown.bind(this));
-            this.dropdownContentElementRef.removeEventListener('keydown', this.handleFloatingKeydown.bind(this));
         }
         (_a = this.observer) === null || _a === void 0 ? void 0 : _a.disconnect();
+        this.destroyKeyboardNavigation();
     }
-    setListenerForChildren() {
-        const config = {
-            childList: true,
-            subtree: true,
-        };
-        this.observer = new MutationObserver(() => {
-            this.options = Array.from(this.hostEl.querySelectorAll('vds-dropdown-item'));
-            forceUpdate(this);
-        });
-        this.observer.observe(this.hostEl, config);
+    /**
+     * Renders and updates the dropdown options list.
+     * @private
+     * @returns {void}
+     */
+    renderOptions() {
+        this.options = Array.from(this.hostEl.querySelectorAll('vds-dropdown-item'));
     }
-    /** Gets the icon color.
-     *
-     * @returns string
+    /**
+     * Handles slot change events to update options.
+     * @private
+     * @returns {void}
+     */
+    handleSlotChange() {
+        this.renderOptions();
+    }
+    /**
+     * Gets the appropriate icon color based on disabled and readonly states.
+     * @private
+     * @returns {string} The icon color
      */
     getIconColor() {
         return getIconColor(this.disabled, this.isReadonly);
     }
+    /**
+     * Sets the dropdown chevron icon (up or down based on open state).
+     * @private
+     * @returns {HTMLElement} The dropdown icon element
+     */
     setDropdownIcon() {
         return h("vds-icon", { svgIcon: this.dropdownOpened ? 'chevron-up' : 'chevron-down', color: this.getIconColor(), size: getIconSize(this.size) });
     }
+    /**
+     * Sets the informative icon if defined.
+     * @private
+     * @returns {HTMLElement | null} The informative icon element or null
+     */
     setInformativeIcon() {
         if (this.informativeIcon) {
             return h("vds-icon", { class: 'vds-dropdown__informative-icon', svgIcon: this.informativeIcon, color: this.getIconColor(), size: getIconSize(this.size) });
@@ -267,9 +565,19 @@ export class VdsBasicDropdown {
             return null;
         }
     }
+    /**
+     * Sets the label or placeholder value to display.
+     * @private
+     * @returns {HTMLElement} The label/placeholder element
+     */
     setLabelValue() {
         return (h("span", { class: combineClasses('vds__dropdown--value', 'vds__dropdown--value-' + this.size, 'vds__dropdown--value-' + (this.value && this.valueLabel ? 'label' : 'placeholder')) }, this.value && this.valueLabel ? this.valueLabel : this.placeholder));
     }
+    /**
+     * Sets the clear value button icon if applicable.
+     * @private
+     * @returns {HTMLElement | null} The clear button element or null
+     */
     setClearValueButtonIcon() {
         if (this.value && this.valueLabel && this.showClearButton) {
             return (h("vds-icon-button", { icon: "close", variant: "secondary", size: getActionIconButtonSize(this.size), onClick: !this.disabled && !this.isReadonly
@@ -282,16 +590,55 @@ export class VdsBasicDropdown {
             return null;
         }
     }
+    /**
+     * 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}
+     */
+    initKeyboardNavigation() {
+        const dropdownItems = this.getDropdownItems();
+        if (dropdownItems.length === 0) {
+            return;
+        }
+        const triggerEl = getDeepActiveElement();
+        if (!triggerEl) {
+            return;
+        }
+        KeyboardNavigation.subscribe(dropdownItems, triggerEl, this.close.bind(this));
+    }
+    /**
+     * Destroys the active keyboard navigation session.
+     * @private
+     * @returns {void}
+     */
+    destroyKeyboardNavigation() {
+        KeyboardNavigation.unsubscribe();
+    }
+    /**
+     * Returns focusable dropdown items that can be navigated
+     * ignores dropdown group headers and disabled items.
+     * @private
+     * @returns {HTMLElement[]} An array of focusable dropdown items.
+     */
+    getDropdownItems() {
+        return getDropdownFocusableItems(this.hostEl);
+    }
+    /**
+     * Renders the dropdown component.
+     * @returns {HTMLElement} The root dropdown element
+     */
     render() {
-        return (h(Host, { key: '616eedd8c799a2409d88874ba0758448edd0285d', class: combineClasses(this.disabled ? 'vds-basic-dropdown--disabled' : ''), onClicked: event => this.handleDropdownItemClicked(event.detail) }, h("div", { key: '2aabe96aaa92a9255e282883b280b09a8749baed', class: 'vds-basic-dropdown__container' }, h("button", { key: 'f3d0fcf355f30dd0c29bffb677937481c89515ae', tabIndex: 0, disabled: this.disabled, value: this.value, class: combineClasses('vds__dropdown--trigger', this.disabled ? 'vds__dropdown--trigger-disabled' : '', this.isReadonly ? 'vds__dropdown--trigger--readonly' : '', this.error ? 'vds__dropdown--trigger-error' : '', `vds__dropdown--trigger--size-${this.size}`), onClick: (evt) => {
-                this.handleClick(evt);
+        return (h(Host, { key: 'ed62bd9e592fae710bd857bf11be2685c8fbea9e', class: combineClasses(this.disabled ? 'vds-basic-dropdown--disabled' : ''), onClicked: event => this.handleDropdownItemClicked(event.detail) }, h("div", { key: 'bb4dff918277730761a916db53794f8a882efe4c', class: 'vds-basic-dropdown__container' }, h("button", { key: '19a52bdaab7ecce0f7d7bdec0a0f7b811fd5ede7', tabIndex: 0, disabled: this.disabled, value: this.value, class: combineClasses('vds__dropdown--trigger', this.disabled ? 'vds__dropdown--trigger-disabled' : '', this.isReadonly ? 'vds__dropdown--trigger--readonly' : '', this.error ? 'vds__dropdown--trigger-error' : '', `vds__dropdown--trigger--size-${this.size}`), onClick: () => {
+                this.handleClick();
             }, ref: triggerEl => {
                 if (triggerEl)
                     this.actionElementRef = triggerEl;
-            } }, h("span", { key: '539454912726ea7446220d9fa87c6e9bc5484acc', class: "vds__dropdown--left-content" }, this.setInformativeIcon(), this.setLabelValue()), h("span", { key: '5e0b393ef2558a1a7ef3a7769989dae2128654f8', class: "vds__dropdown--right-actions" }, this.setClearValueButtonIcon(), this.setDropdownIcon())), this.backdrop && this.dropdownOpened ? h("div", { class: "vds-floating-backdrop", onClick: this.close.bind(this) }) : '', h("div", { key: '0749713281a272b18799f399f5fbc5511e3c9407', class: combineClasses('vds__dropdown--container', this.maxHeight ? 'has-scroll' : '', this.options.length === 0 ? 'no-shadow' : ''), ref: dropdownEl => {
+            } }, h("span", { key: '3aff3a91e42e4031d00cfe595aa249d8c241a5fe', class: "vds__dropdown--left-content" }, this.setInformativeIcon(), this.setLabelValue()), h("span", { key: '7d259dc82b66bd49d708a5ecc1749897e21a5986', class: "vds__dropdown--right-actions" }, this.setClearValueButtonIcon(), this.setDropdownIcon())), this.backdrop && this.dropdownOpened ? h("div", { class: "vds-floating-backdrop", onClick: this.close.bind(this) }) : '', h("div", { key: 'e78f2bc0de879c77926e7ba6654dec8186f6a357', class: combineClasses('vds__dropdown--container', this.maxHeight ? 'has-scroll' : '', this.options.length === 0 ? 'no-shadow' : ''), ref: dropdownEl => {
                 if (dropdownEl)
                     this.dropdownContentElementRef = dropdownEl;
-            } }, h("div", { key: 'fcb82abe92dc75927d15e40bdcd323addcb58bf2', class: combineClasses('vds-dropdown__content', this.maxHeight ? 'scrollable' : ''), style: setDropdownStyles(this.maxHeight) }, h("slot", { key: '6e0b66bbd2fda0dc66d43fd48b6a229440310b66' }))))));
+            } }, h("div", { key: '91fccdcf460c51dd95fd0d380a43bde88187fe15', class: combineClasses('vds-dropdown__content', this.maxHeight ? 'scrollable' : ''), style: setDropdownStyles(this.maxHeight) }, h("slot", { key: '45a0c0e8fe44af7d6650441e02d9982b352658ec', onSlotchange: () => this.handleSlotChange() }))))));
     }
     static get is() { return "vds-basic-dropdown"; }
     static get encapsulation() { return "shadow"; }
@@ -319,7 +666,13 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "type",
+                            "text": "{('small' | 'medium' | 'large')}"
+                        }, {
+                            "name": "default",
+                            "text": "\"medium\""
+                        }],
                     "text": "Sets the dropdown's size."
                 },
                 "getter": false,
@@ -339,8 +692,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the dropdown's value."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }, {
+                            "name": "default",
+                            "text": "undefined"
+                        }],
+                    "text": "Sets the dropdown's selected value."
                 },
                 "getter": false,
                 "setter": false,
@@ -358,8 +717,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Allows user to define a information icon to the left of the dropdown."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }, {
+                            "name": "default",
+                            "text": "undefined"
+                        }],
+                    "text": "Defines an informative icon to display on the left of the dropdown."
                 },
                 "getter": false,
                 "setter": false,
@@ -377,8 +742,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Allows dropdown-item informativeIcon reflect dynamically as informativeIcon of the dropdown."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Allows dropdown-item informativeIcon to reflect dynamically as the dropdown's informativeIcon.\nWhen true, the selected item's icon becomes the dropdown's icon."
                 },
                 "getter": false,
                 "setter": false,
@@ -397,8 +768,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the dropdown's placeholder."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }, {
+                            "name": "default",
+                            "text": "undefined"
+                        }],
+                    "text": "Sets the dropdown's placeholder text."
                 },
                 "getter": false,
                 "setter": false,
@@ -416,8 +793,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the dropdown in disabled state."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Sets the dropdown in disabled state, preventing user interaction."
                 },
                 "getter": false,
                 "setter": false,
@@ -436,7 +819,13 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": "Sets the dropdown in readonly state."
                 },
                 "getter": false,
@@ -456,8 +845,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the dropdown in error state."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "undefined"
+                        }],
+                    "text": "Sets the dropdown in error state for validation feedback."
                 },
                 "getter": false,
                 "setter": false,
@@ -475,7 +870,13 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "type",
+                            "text": "{('click' | 'hover')}"
+                        }, {
+                            "name": "default",
+                            "text": "\"click\""
+                        }],
                     "text": "Sets the dropdown's trigger event."
                 },
                 "getter": false,
@@ -495,8 +896,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the dropdown's clear button visibility."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "true"
+                        }],
+                    "text": "Controls the visibility of the clear button."
                 },
                 "getter": false,
                 "setter": false,
@@ -515,8 +922,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set the max height value for the floating container of the items"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }, {
+                            "name": "default",
+                            "text": "undefined"
+                        }],
+                    "text": "Sets the max height value for the floating container of the items."
                 },
                 "getter": false,
                 "setter": false,
@@ -534,8 +947,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the width value for the floating container of the items to match the dropdown width"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Sets the floating container width to match the dropdown width."
                 },
                 "getter": false,
                 "setter": false,
@@ -554,8 +973,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Toggles the floating container auto-positioning based on available window space.\nFalse by default as it may cause positioning issues in some situations, use with caution"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Toggles the floating container auto-positioning based on available window space.\nFalse by default as it may cause positioning issues in some situations, use with caution."
                 },
                 "getter": false,
                 "setter": false,
@@ -563,6 +988,32 @@ export class VdsBasicDropdown {
                 "attribute": "auto-position",
                 "defaultValue": "false"
             },
+            "position": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'top' | 'bottom' | 'right' | 'left' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'",
+                    "resolved": "\"bottom\" | \"bottom-end\" | \"bottom-start\" | \"left\" | \"right\" | \"top\" | \"top-end\" | \"top-start\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"top\" | \"bottom\" | \"right\" | \"left\" | \"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"bottom\""
+                        }],
+                    "text": "Defines the position where the dropdown will be opened."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "position",
+                "defaultValue": "'bottom'"
+            },
             "backdrop": {
                 "type": "boolean",
                 "mutable": false,
@@ -574,8 +1025,14 @@ export class VdsBasicDropdown {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Toggles the overlay element, allowing interaction only with this element when active"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Toggles the overlay element, allowing interaction only with this element when active."
                 },
                 "getter": false,
                 "setter": false,
@@ -599,8 +1056,14 @@ export class VdsBasicDropdown {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when floating element gets opens"
+                    "tags": [{
+                            "name": "event",
+                            "text": "opened"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }],
+                    "text": "Emitted when the floating element opens."
                 },
                 "complexType": {
                     "original": "void",
@@ -614,8 +1077,14 @@ export class VdsBasicDropdown {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when floating element gets closes"
+                    "tags": [{
+                            "name": "event",
+                            "text": "closed"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }],
+                    "text": "Emitted when the floating element closes."
                 },
                 "complexType": {
                     "original": "void",
@@ -629,8 +1098,14 @@ export class VdsBasicDropdown {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when an item is selected, this event contains the value of the selected item"
+                    "tags": [{
+                            "name": "event",
+                            "text": "valueChanged"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<string>}"
+                        }],
+                    "text": "Emitted when an item is selected. Contains the value of the selected item."
                 },
                 "complexType": {
                     "original": "string",
@@ -644,8 +1119,14 @@ export class VdsBasicDropdown {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits an event when the clear button is clicked"
+                    "tags": [{
+                            "name": "event",
+                            "text": "cleared"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<boolean>}"
+                        }],
+                    "text": "Emitted when the clear button is clicked."
                 },
                 "complexType": {
                     "original": "boolean",
@@ -669,8 +1150,17 @@ export class VdsBasicDropdown {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Opens the floating element (menu) of the dropdown.",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": undefined
+                        }]
                 }
             },
             "close": {
@@ -686,8 +1176,17 @@ export class VdsBasicDropdown {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Closes the floating element (menu) of the dropdown.",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": undefined
+                        }]
                 }
             },
             "clear": {
@@ -703,8 +1202,17 @@ export class VdsBasicDropdown {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Clears the selected value from the dropdown.\nResets value, label, and dynamic icon. Unselects all items and emits events.",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": undefined
+                        }]
                 }
             },
             "getTarget": {
@@ -724,8 +1232,17 @@ export class VdsBasicDropdown {
                     "return": "Promise<HTMLElement>"
                 },
                 "docs": {
-                    "text": "Gets the target that will manage the menu\nreturns a promise with the target HTMLElement.",
-                    "tags": []
+                    "text": "Gets the trigger target element that manages the menu.",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves with the target HTMLElement"
+                        }]
                 }
             },
             "getValue": {
@@ -745,8 +1262,17 @@ export class VdsBasicDropdown {
                     "return": "Promise<String>"
                 },
                 "docs": {
-                    "text": "Gets the selected value of the dropdown\nreturns a promise with the value.",
-                    "tags": []
+                    "text": "Gets the selected value of the dropdown.",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves with the selected value"
+                        }]
                 }
             },
             "setValue": {
@@ -755,7 +1281,7 @@ export class VdsBasicDropdown {
                     "parameters": [{
                             "name": "value",
                             "type": "string",
-                            "docs": ""
+                            "docs": "- The value to set"
                         }],
                     "references": {
                         "Promise": {
@@ -766,8 +1292,20 @@ export class VdsBasicDropdown {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Set the value of the dropdown",
-                    "tags": []
+                    "text": "Sets the value of the dropdown.\nClears the current selection before setting the new value.",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "param",
+                            "text": "value - The value to set"
+                        }, {
+                            "name": "returns",
+                            "text": undefined
+                        }]
                 }
             }
         };
@@ -799,4 +1337,3 @@ export class VdsBasicDropdown {
     }
     static get attachInternalsMemberName() { return "internals"; }
 }
-//# sourceMappingURL=vds-basic-dropdown.js.map