@siemens/ix 4.4.0 → 5.0.0

package/dist/collection/components/dropdown/dropdown.js

@@ -7,62 +7,168 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { autoUpdate, computePosition, flip, inline, offset, shift, } from "@floating-ui/dom";
-import { h, Host, } from "@stencil/core";
+import { h, Host, Mixin, } from "@stencil/core";
 import { addDisposableEventListener, } from "../utils/disposable-event-listener";
 import { findElement } from "../utils/find-element";
-import { ArrowFocusController } from "../utils/focus";
+import { addFocusTrap, } from "../utils/focus/focus-trap";
+import { focusElementInContext, focusFirstDescendant, focusLastDescendant, queryElements, } from "../utils/focus/focus-utilities";
+import { DefaultMixins } from "../utils/internal/component";
+import { hasKeyboardMode, removeVisibleFocus, } from "../utils/internal/mixins/setup.mixin";
 import { makeRef } from "../utils/make-ref";
 import { requestAnimationFrameNoNgZone } from "../utils/requestAnimationFrame";
 import { dropdownController, hasDropdownItemWrapperImplemented, } from "./dropdown-controller";
+import { configureKeyboardInteraction } from "./dropdown-focus";
 let sequenceId = 0;
-export class Dropdown {
+export class Dropdown extends Mixin(...DefaultMixins) {
     constructor() {
-        /**
-         * Suppress the automatic placement of the dropdown.
-         */
-        this.suppressAutomaticPlacement = false;
-        /**
-         * Show dropdown
-         */
-        this.show = false;
-        /**
-         * Controls if the dropdown will be closed in response to a click event depending on the position of the event relative to the dropdown.
-         * If the dropdown is a child of another one, it will be closed with the parent, regardless of its own close behavior.
-         */
-        this.closeBehavior = 'both';
-        /**
-         * Placement of the dropdown
-         */
-        this.placement = 'bottom-start';
-        /**
-         * Position strategy
-         */
-        this.positioningStrategy = 'fixed';
-        /**
-         * @internal
-         * If initialization of this dropdown is expected to be deferred submenu discovery will have to be re-run globally by the controller.
-         * This property indicates the need for that to the controller.
-         */
-        this.discoverAllSubmenus = false;
-        /** @internal */
-        this.ignoreRelatedSubmenu = false;
-        /** @internal */
-        this.suppressOverflowBehavior = false;
-        /**
-         * Enable Popover API rendering for top-layer positioning.
-         *
-         * @default false in v4.x, will default to true in v5.0.0
-         */
-        this.enableTopLayer = false;
-        this.dialogRef = makeRef();
-        this.localUId = `dropdown-${sequenceId++}`;
-        this.assignedSubmenu = [];
-        this.itemObserver = new MutationObserver(() => {
-            if (this.arrowFocusController) {
-                this.arrowFocusController.items = this.dropdownItems;
-            }
-        });
+        super();
     }
+    hostElement;
+    /**
+     * Suppress the automatic placement of the dropdown.
+     */
+    suppressAutomaticPlacement = false;
+    /**
+     * Show dropdown
+     */
+    show = false;
+    /**
+     * Define an element that triggers the dropdown.
+     * A trigger can either be a string that will be interpreted as id attribute or a DOM element.
+     */
+    trigger;
+    /**
+     * Define an anchor element
+     */
+    anchor;
+    /**
+     * Controls if the dropdown will be closed in response to a click event depending on the position of the event relative to the dropdown.
+     * If the dropdown is a child of another one, it will be closed with the parent, regardless of its own close behavior.
+     */
+    closeBehavior = 'both';
+    /**
+     * Placement of the dropdown
+     */
+    placement = 'bottom-start';
+    /**
+     * Position strategy
+     */
+    positioningStrategy = 'fixed';
+    /**
+     * An optional header shown at the top of the dropdown
+     */
+    header;
+    /**
+     * By default the dropdown gets closed if the trigger is not visible anymore (e.g. due to scrolling). Setting this property prevents that behavior.
+     *
+     * @since 5.0.0
+     */
+    suppressTriggerVisibilityCheck = false;
+    /**
+     * Suppress automatic focus when the dropdown is shown
+     *
+     * @since 4.3.0
+     */
+    disableFocusHandling = false;
+    /**
+     * Close dropdown when tabbing away, and do not trap focus inside dropdown
+     *
+     * @since 4.3.0
+     */
+    disableFocusTrap = false;
+    /**
+     * Enable Popover API rendering for top-layer positioning.
+     *
+     * @default false in v5.x, will default to true in v6.0.0
+     * @since 4.3.0
+     */
+    enableTopLayer = false;
+    /**
+     * If true, the dropdown will try to focus checked items first when opened via keyboard, otherwise it will always focus the first focusable item.
+     *
+     * @since 5.0.0
+     */
+    focusCheckedItem = false;
+    /**
+     * Keys that will open the dropdown when the trigger is focused
+     *
+     * @internal
+     */
+    keyboardActivationKeys = [
+        'Home',
+        'End',
+        'ArrowDown',
+        'ArrowUp',
+        'Enter',
+        ' ',
+    ];
+    /**
+     * Keys that will open the dropdown when the trigger is focused
+     *
+     * @internal
+     */
+    keyboardItemTriggerKeys = ['Enter', ' '];
+    /**
+     * Move dropdown along main axis of alignment
+     *
+     * @internal
+     */
+    offset;
+    /**
+     * @internal
+     */
+    overwriteDropdownStyle;
+    /**
+     * @internal
+     * If initialization of this dropdown is expected to be deferred submenu discovery will have to be re-run globally by the controller.
+     * This property indicates the need for that to the controller.
+     */
+    discoverAllSubmenus = false;
+    /** @internal */
+    ignoreRelatedSubmenu = false;
+    /** @internal */
+    suppressOverflowBehavior = false;
+    /** @internal */
+    focusHost;
+    /** @internal */
+    focusTrapOptions;
+    /** @internal */
+    hostRole;
+    /**
+     * @internal
+     * Called instead of the default focus-on-open logic when the dropdown is
+     * opened via keyboard. When not set, default behavior is used.
+     */
+    callbackFocusElement;
+    /**
+     * Fire event before visibility of dropdown has changed, preventing event will cancel showing dropdown
+     */
+    showChange;
+    /**
+     * Fire event after visibility of dropdown has changed
+     */
+    showChanged;
+    fallbackPlacement;
+    /**
+     * Will be fired only after dropdown changed visibility to "true"
+     *
+     * @internal
+     */
+    experimentalRequestFocus;
+    /**
+     * @internal
+     */
+    experimentalFocusNextElement;
+    autoUpdateCleanup;
+    dialogRef = makeRef();
+    intersectObserverTrigger;
+    triggerElement;
+    anchorElement;
+    forwardQueryElement = null;
+    dropdownElementId = `dropdown-${sequenceId++}`;
+    assignedSubmenu = [];
+    keyboardNavigationCleanup;
+    focusUtilities;
     connectedCallback() {
         dropdownController.connected(this);
         if (this.trigger != undefined) {
@@ -78,25 +184,8 @@ export class Dropdown {
         }
     }
     disconnectedCallback() {
-        var _a;
         dropdownController.dismiss(this);
         dropdownController.disconnected(this);
-        if (this.arrowFocusController) {
-            (_a = this.arrowFocusController) === null || _a === void 0 ? void 0 : _a.disconnect();
-            this.arrowFocusController = undefined;
-        }
-        if (this.itemObserver) {
-            this.itemObserver.disconnect();
-            this.itemObserver = undefined;
-        }
-        if (this.disposeClickListener) {
-            this.disposeClickListener();
-            this.disposeClickListener = undefined;
-        }
-        if (this.disposeKeyListener) {
-            this.disposeKeyListener();
-            this.disposeKeyListener = undefined;
-        }
         if (this.autoUpdateCleanup) {
             this.autoUpdateCleanup();
             this.autoUpdateCleanup = undefined;
@@ -115,14 +204,14 @@ export class Dropdown {
         this.show = false;
     }
     getId() {
-        return this.localUId;
+        return this.dropdownElementId;
     }
     willDismiss() {
-        const { defaultPrevented } = this.showChanged.emit(false);
+        const { defaultPrevented } = this.showChange.emit(false);
         return !defaultPrevented;
     }
     willPresent() {
-        const { defaultPrevented } = this.showChanged.emit(true);
+        const { defaultPrevented } = this.showChange.emit(true);
         return !defaultPrevented;
     }
     get dropdownItems() {
@@ -131,62 +220,184 @@ export class Dropdown {
     get slotElement() {
         return this.hostElement.shadowRoot.querySelector('slot');
     }
-    addEventListenersFor() {
-        var _a, _b, _c;
-        (_a = this.disposeClickListener) === null || _a === void 0 ? void 0 : _a.call(this);
-        (_b = this.disposeKeyListener) === null || _b === void 0 ? void 0 : _b.call(this);
-        const toggleController = () => {
-            if (!this.isPresent()) {
-                dropdownController.present(this);
+    disposeClickListener;
+    disposeKeyListener;
+    toggleController() {
+        if (!this.isPresent()) {
+            dropdownController.present(this);
+        }
+        else {
+            dropdownController.dismiss(this);
+        }
+        dropdownController.dismissOthers(this.getId());
+    }
+    onTriggerClick = (event) => this.handleTriggerClick(event);
+    handleTriggerClick(event) {
+        if (!event.defaultPrevented) {
+            this.toggleController();
+        }
+    }
+    onTriggerKeydown = (event) => this.handleTriggerKeydown(event);
+    handleTriggerKeydown(event) {
+        const focusFirst = (element) => requestAnimationFrameNoNgZone(async () => {
+            let shouldPreventDefault = false;
+            if (this.callbackFocusElement) {
+                shouldPreventDefault =
+                    (await this.callbackFocusElement(event)) ?? false;
             }
-            else {
-                dropdownController.dismiss(this);
+            if (shouldPreventDefault) {
+                return;
             }
-            dropdownController.dismissOthers(this.getId());
-        };
-        if (!this.triggerElement) {
+            focusFirstDescendant(element, undefined, {
+                focusCheckedItem: this.focusCheckedItem,
+            });
+        });
+        const focusLast = (element) => requestAnimationFrameNoNgZone(async () => {
+            let shouldPreventDefault = false;
+            if (this.callbackFocusElement) {
+                shouldPreventDefault =
+                    (await this.callbackFocusElement(event)) ?? false;
+            }
+            if (shouldPreventDefault) {
+                return;
+            }
+            focusLastDescendant(element);
+        });
+        const shouldCloseOnTab = this.disableFocusTrap === true && event.key === 'Tab';
+        if ((event.key === 'Escape' || shouldCloseOnTab) && this.show) {
+            dropdownController.dismiss(this);
+            return;
+        }
+        if (this.show) {
             return;
         }
-        this.disposeClickListener = addDisposableEventListener(this.triggerElement, 'click', (event) => {
+        const navigationKeys = this.keyboardActivationKeys ?? [
+            'Home',
+            'End',
+            'ArrowUp',
+            'ArrowDown',
+            ' ',
+            'Enter',
+        ];
+        if (!navigationKeys.includes(event.key)) {
+            return;
+        }
+        // If dropdown is not yet shown, try to open it
+        if (!this.isAnchorSubmenu()) {
             if (!event.defaultPrevented) {
-                toggleController();
+                this.toggleController();
             }
+            if (this.disableFocusHandling) {
+                event.stopImmediatePropagation();
+                event.preventDefault();
+            }
+            else {
+                // Focus first item for all keys except ArrowUp (which focuses last)
+                if (event.altKey) {
+                    return;
+                }
+                if (event.key === 'ArrowUp' || event.key === 'End') {
+                    focusLast(this.hostElement);
+                }
+                else {
+                    focusFirst(this.hostElement);
+                }
+            }
+        }
+        else if (!this.disableFocusHandling) {
+            // Dropdown is already open - handle focus navigation
+            if (this.callbackFocusElement) {
+                this.callbackFocusElement(event);
+            }
+            else if (event.key === 'ArrowUp' || event.key === 'End') {
+                focusLast(this.hostElement);
+            }
+            else {
+                focusFirst(this.hostElement);
+            }
+        }
+        this.experimentalRequestFocus.emit({
+            keyEvent: event,
         });
-        (_c = this.triggerElement) === null || _c === void 0 ? void 0 : _c.setAttribute('data-ix-dropdown-trigger', this.localUId);
+        // Prevent click listener from also toggling the dropdown, which would close it again
+        event.preventDefault();
+    }
+    addEventListenersFor() {
+        if (!this.triggerElement) {
+            return;
+        }
+        if (!this.disposeClickListener) {
+            this.disposeClickListener = addDisposableEventListener(this.triggerElement, 'click', this.onTriggerClick);
+        }
+        if (!this.disposeKeyListener) {
+            this.disposeKeyListener = addDisposableEventListener(this.triggerElement, 'keydown', this.onTriggerKeydown);
+        }
+        this.triggerElement?.setAttribute('data-ix-dropdown-trigger', this.dropdownElementId);
     }
     /** @internal */
     async discoverSubmenu() {
-        var _a;
-        (_a = this.triggerElement) === null || _a === void 0 ? void 0 : _a.dispatchEvent(new CustomEvent('ix-assign-sub-menu', {
+        this.triggerElement?.dispatchEvent(new CustomEvent('ix-assign-sub-menu', {
             bubbles: true,
             composed: true,
             cancelable: true,
-            detail: this.localUId,
+            detail: this.dropdownElementId,
         }));
     }
     registerKeyListener() {
         if (!this.triggerElement) {
             return;
         }
-        this.disposeKeyListener = addDisposableEventListener(this.triggerElement, 'keydown', ((event) => {
-            if (event.key !== 'ArrowDown') {
-                return;
-            }
-            if (document.activeElement !== this.triggerElement) {
-                return;
-            }
-            dropdownController.present(this);
-            setTimeout(() => {
-                this.focusDropdownItem(0);
-            });
-        }));
     }
     async registerListener(element) {
         this.triggerElement = await this.resolveElement(element);
-        if (this.triggerElement) {
-            this.addEventListenersFor();
-            this.discoverSubmenu();
+        if (!this.triggerElement) {
+            return;
         }
+        this.addEventListenersFor();
+        this.discoverSubmenu();
+    }
+    addObserverForTriggerVisibility() {
+        if (this.intersectObserverTrigger) {
+            this.intersectObserverTrigger.disconnect();
+        }
+        if (this.suppressTriggerVisibilityCheck) {
+            return;
+        }
+        if (!this.triggerElement) {
+            return;
+        }
+        this.intersectObserverTrigger = new IntersectionObserver((entries) => {
+            entries.forEach((entry) => {
+                if (!entry.isIntersecting) {
+                    dropdownController.dismiss(this);
+                    return;
+                }
+                const isTopHidden = entry.intersectionRect.top > entry.boundingClientRect.top;
+                const isBottomHidden = entry.intersectionRect.bottom < entry.boundingClientRect.bottom;
+                const isLeftHidden = entry.intersectionRect.left > entry.boundingClientRect.left;
+                const isRightHidden = entry.intersectionRect.right < entry.boundingClientRect.right;
+                this.fallbackPlacement = undefined;
+                if (isTopHidden) {
+                    this.fallbackPlacement = this.createFallbackPlacement('bottom');
+                }
+                if (isBottomHidden) {
+                    this.fallbackPlacement = this.createFallbackPlacement('top');
+                }
+                if (isLeftHidden) {
+                    this.fallbackPlacement = this.createFallbackPlacement('right');
+                }
+                if (isRightHidden) {
+                    this.fallbackPlacement = this.createFallbackPlacement('left');
+                }
+            });
+        }, {
+            threshold: [0, 0.5, 1],
+        });
+        this.intersectObserverTrigger.observe(this.anchorElement);
+    }
+    createFallbackPlacement(side) {
+        const alignment = this.placement.endsWith('-end') ? 'end' : 'start';
+        return `${side}-${alignment}`;
     }
     async resolveElement(element) {
         const el = await findElement(element);
@@ -216,32 +427,95 @@ export class Dropdown {
         }
     }
     async changedShow(newShow) {
-        var _a;
         if (!newShow) {
+            if (this.triggerElement &&
+                this.triggerElement.ariaHasPopup === 'menu' &&
+                this.triggerElement.tagName === 'IX-DROPDOWN-ITEM') {
+                this.triggerElement.ariaExpanded = 'false';
+            }
             this.cleanupOnHide();
             if (this.enableTopLayer) {
-                await this.hideDropdownAsync();
+                await this.hideDialog();
             }
             return;
         }
-        this.arrowFocusController = new ArrowFocusController(this.dropdownItems, this.hostElement, (index) => this.focusDropdownItem(index));
-        (_a = this.itemObserver) === null || _a === void 0 ? void 0 : _a.observe(this.hostElement, {
-            childList: true,
-            subtree: true,
-        });
+        await this.resolveAnchorElement();
         this.registerKeyListener();
-        if (this.enableTopLayer) {
-            await this.showDropdownAsync();
-            return;
+        if (!this.disableFocusHandling && !this.callbackFocusElement) {
+            this.keyboardNavigationCleanup = configureKeyboardInteraction(() => this.forwardQueryElement ?? this.focusHost ?? this.hostElement, {
+                getEventListenerTarget: () => this.triggerElement ??
+                    this.anchorElement,
+                onItemActivation: (event, activeElement) => {
+                    event.preventDefault();
+                    activeElement?.click();
+                },
+                itemTriggerKeys: this.keyboardItemTriggerKeys,
+            });
         }
-        await this.resolveAnchorElement();
-        if (this.anchorElement) {
-            this.applyDropdownPosition();
+        if (!this.disableFocusTrap) {
+            addFocusTrap(this.focusHost ?? this.hostElement, this.focusTrapOptions).then((focusTrap) => {
+                this.focusUtilities = focusTrap;
+            });
+        }
+        if (this.triggerElement &&
+            this.triggerElement.ariaHasPopup === 'menu' &&
+            this.triggerElement.tagName === 'IX-DROPDOWN-ITEM') {
+            this.triggerElement.ariaExpanded = 'true';
+        }
+        if (this.enableTopLayer) {
+            const popover = await this.dialogRef.waitForCurrent();
+            if (!popover) {
+                return;
+            }
+            popover.showPopover();
         }
+        this.addObserverForTriggerVisibility();
+        this.applyDropdownPosition();
     }
-    changedTrigger(newTriggerValue) {
+    async emitShowChanged(newShow) {
+        requestAnimationFrameNoNgZone(() => this.showChanged.emit(newShow));
+    }
+    changedTrigger(newTriggerValue, oldTriggerValue) {
+        if (newTriggerValue && newTriggerValue !== oldTriggerValue) {
+            this.disposeClickListener?.();
+            this.disposeClickListener = undefined;
+            this.disposeKeyListener?.();
+            this.disposeKeyListener = undefined;
+        }
         this.registerListener(newTriggerValue);
     }
+    applyFallbackPosition(element) {
+        requestAnimationFrameNoNgZone(() => {
+            const referenceElement = this.hostElement.parentElement || this.hostElement;
+            const refRect = referenceElement.getBoundingClientRect();
+            const transform = `translate(${Math.round(refRect.left)}px, ${Math.round(refRect.top)}px)`;
+            Object.assign(element.style, {
+                top: '0',
+                left: '0',
+                transform,
+            });
+        });
+    }
+    async hideDialog() {
+        const popover = await this.dialogRef.waitForCurrent();
+        if (popover?.matches(':popover-open')) {
+            popover.hidePopover();
+        }
+    }
+    cleanupOnHide() {
+        this.intersectObserverTrigger?.disconnect();
+        this.destroyAutoUpdate();
+        this.keyboardNavigationCleanup?.();
+        this.focusUtilities?.destroy();
+        this.resetForwardQueryElement();
+        removeVisibleFocus();
+        if (!this.disableFocusTrap && hasKeyboardMode()) {
+            // Restore focus to trigger element
+            requestAnimationFrameNoNgZone(() => {
+                this.triggerElement?.focus();
+            });
+        }
+    }
     destroyAutoUpdate() {
         if (this.autoUpdateCleanup) {
             this.autoUpdateCleanup();
@@ -249,68 +523,32 @@ export class Dropdown {
         }
     }
     isAnchorSubmenu() {
-        var _a;
         if (!hasDropdownItemWrapperImplemented(this.anchorElement)) {
             // Is no official dropdown-item, but check if any dropdown-item
             // is placed somewhere up the DOM
-            return !!((_a = this.anchorElement) === null || _a === void 0 ? void 0 : _a.closest('ix-dropdown-item'));
+            return !!this.anchorElement?.closest('ix-dropdown-item');
         }
         return true;
     }
-    async showDropdownAsync() {
-        const popover = await this.dialogRef.waitForCurrent();
-        if (!popover) {
-            return;
-        }
-        popover.showPopover();
-        await this.resolveAnchorElement();
-        if (this.anchorElement) {
-            this.applyDropdownPosition();
-        }
-        else {
-            requestAnimationFrameNoNgZone(() => {
-                const referenceElement = this.hostElement.parentElement || this.hostElement;
-                const refRect = referenceElement.getBoundingClientRect();
-                const transform = `translate(${Math.round(refRect.left)}px, ${Math.round(refRect.top)}px)`;
-                Object.assign(popover.style, {
-                    top: '0',
-                    left: '0',
-                    transform,
-                });
-            });
-        }
-    }
-    async hideDropdownAsync() {
-        const popover = await this.dialogRef.waitForCurrent();
-        if (popover === null || popover === void 0 ? void 0 : popover.matches(':popover-open')) {
-            popover.hidePopover();
-        }
-    }
-    cleanupOnHide() {
-        var _a, _b, _c;
-        this.destroyAutoUpdate();
-        (_a = this.arrowFocusController) === null || _a === void 0 ? void 0 : _a.disconnect();
-        (_b = this.itemObserver) === null || _b === void 0 ? void 0 : _b.disconnect();
-        (_c = this.disposeKeyListener) === null || _c === void 0 ? void 0 : _c.call(this);
-    }
     async applyDropdownPosition() {
-        var _a, _b;
+        const targetElement = this.enableTopLayer
+            ? await this.dialogRef.waitForCurrent()
+            : this.hostElement;
         if (!this.show) {
             return;
         }
+        if (!targetElement) {
+            return;
+        }
         if (!this.anchorElement) {
+            this.applyFallbackPosition(targetElement);
             return;
         }
         const referenceElement = this.anchorElement;
         const isSubmenu = this.isAnchorSubmenu();
-        let targetElement = this.hostElement;
         let strategy = this.positioningStrategy;
         if (this.enableTopLayer) {
-            const dialog = await this.dialogRef.waitForCurrent();
-            if (!dialog) {
-                return;
-            }
-            targetElement = dialog;
+            // Popover API only supports fixed positioning
             strategy = 'fixed';
         }
         let positionConfig = {
@@ -318,11 +556,16 @@ export class Dropdown {
             middleware: [],
         };
         if (!this.suppressAutomaticPlacement) {
-            (_a = positionConfig.middleware) === null || _a === void 0 ? void 0 : _a.push(flip({ fallbackStrategy: 'initialPlacement' }));
+            positionConfig.middleware?.push(flip({ fallbackStrategy: 'initialPlacement' }));
+        }
+        let placement = this.placement;
+        if (this.suppressTriggerVisibilityCheck === false &&
+            this.fallbackPlacement) {
+            placement = this.fallbackPlacement;
         }
-        positionConfig.placement = isSubmenu ? 'right-start' : this.placement;
+        positionConfig.placement = isSubmenu ? 'right-start' : placement;
         positionConfig.middleware = [
-            ...(((_b = positionConfig.middleware) === null || _b === void 0 ? void 0 : _b.filter(Boolean)) || []),
+            ...(positionConfig.middleware?.filter(Boolean) || []),
             inline(),
             shift(),
         ];
@@ -332,6 +575,8 @@ export class Dropdown {
         this.destroyAutoUpdate();
         this.autoUpdateCleanup = autoUpdate(referenceElement, targetElement, async () => {
             const computeResponse = await computePosition(referenceElement, targetElement, positionConfig);
+            this.hostElement.dataset.ixDropdownPlacement =
+                computeResponse.placement;
             Object.assign(targetElement.style, {
                 top: '0',
                 left: '0',
@@ -350,23 +595,11 @@ export class Dropdown {
             elementResize: true,
         });
     }
-    focusDropdownItem(index) {
-        requestAnimationFrameNoNgZone(() => {
-            var _a, _b;
-            const button = (_b = (_a = this.dropdownItems[index]) === null || _a === void 0 ? void 0 : _a.shadowRoot) === null || _b === void 0 ? void 0 : _b.querySelector('button');
-            if (button) {
-                button.focus();
-            }
-        });
-    }
     async componentDidLoad() {
-        if (this.show) {
-            this.changedShow(true);
-        }
         if (!this.trigger) {
             return;
         }
-        this.changedTrigger(this.trigger);
+        this.changedTrigger(this.trigger, undefined);
     }
     async componentDidRender() {
         await this.applyDropdownPosition();
@@ -402,25 +635,64 @@ export class Dropdown {
     async updatePosition() {
         this.applyDropdownPosition();
     }
+    openSubmenu(event) {
+        const submenuIds = this.getAssignedSubmenuIds();
+        if (submenuIds.length === 0) {
+            return;
+        }
+        event.detail.activeElement.classList.add('ix-dropdown-submenu-trigger-active');
+        dropdownController.present(dropdownController.getDropdownById(submenuIds[0]));
+        this.forwardQueryElement = dropdownController.getDropdownById(submenuIds[0]).hostElement;
+        requestAnimationFrameNoNgZone(() => {
+            focusFirstDescendant(dropdownController.getDropdownById(submenuIds[0]).hostElement);
+        });
+    }
+    closeSubmenu() {
+        const parent = dropdownController.getParentDropdownId(this.getId());
+        if (parent) {
+            const parentDropdown = dropdownController.getDropdownById(parent);
+            const activeTriggers = queryElements(parentDropdown?.hostElement, '.ix-dropdown-submenu-trigger-active');
+            dropdownController.dismissChildren(parent);
+            if (parentDropdown && activeTriggers.length > 0) {
+                const activeTrigger = activeTriggers[0];
+                activeTrigger.classList.remove('ix-dropdown-submenu-trigger-active');
+                parentDropdown.hostElement.resetForwardQueryElement();
+                requestAnimationFrameNoNgZone(() => {
+                    focusElementInContext(activeTrigger, parentDropdown.hostElement);
+                });
+            }
+        }
+    }
+    /**@internal */
+    async resetForwardQueryElement() {
+        this.forwardQueryElement = null;
+    }
     render() {
-        if (this.enableTopLayer) {
-            return (h(Host, { "data-ix-dropdown": this.localUId, class: {
-                    'dropdown-menu': true,
-                    show: this.show,
-                } }, h("dialog", { ref: this.dialogRef, class: {
-                    dialog: true,
-                    overflow: !this.suppressOverflowBehavior,
-                }, popover: "manual", "aria-modal": "true", "aria-label": this.header, tabindex: -1, onClick: (event) => this.onDropdownClick(event) }, h("div", { class: "dropdown-container" }, this.header && h("div", { class: "dropdown-header" }, this.header), this.show && h("slot", null)))));
-        }
-        return (h(Host, { "data-ix-dropdown": this.localUId, class: {
+        const ariaAttributes = {};
+        if (this.triggerElement &&
+            this.triggerElement.tagName === 'IX-DROPDOWN-ITEM') {
+            ariaAttributes['aria-labelledby'] = this.triggerElement.id;
+            ariaAttributes['aria-owns'] = this.triggerElement.id;
+            ariaAttributes['role'] = 'menu';
+        }
+        else if (this.hostRole) {
+            ariaAttributes['role'] = this.hostRole;
+        }
+        return (h(Host, { key: 'e822f0f658533d267365bb69eed0223ecf9dc4eb', ...ariaAttributes, "aria-modal": "true", "data-ix-dropdown": this.dropdownElementId, "data-ix-focus-trap": true, class: {
                 'dropdown-menu': true,
                 show: this.show,
+                // overflow handling not needed when using top-layer
+                overflow: !this.suppressOverflowBehavior && !this.enableTopLayer,
+            }, style: this.enableTopLayer
+                ? {}
+                : {
+                    margin: '0',
+                    minWidth: '0px',
+                    position: this.positioningStrategy,
+                }, onClick: (event) => this.onDropdownClick(event) }, this.enableTopLayer ? (h("dialog", { role: "presentation", ref: this.dialogRef, class: {
+                dialog: true,
                 overflow: !this.suppressOverflowBehavior,
-            }, style: {
-                margin: '0',
-                minWidth: '0px',
-                position: this.positioningStrategy,
-            }, role: "list", onClick: (event) => this.onDropdownClick(event) }, h("div", { style: { display: 'contents' } }, this.header && h("div", { class: "dropdown-header" }, this.header), this.show && h("slot", null))));
+            }, popover: "manual", tabindex: -1, onClick: (event) => this.onDropdownClick(event) }, h("div", { class: "dropdown-container" }, this.header && h("div", { class: "dropdown-header" }, this.header), this.show && h("slot", null)))) : (h("div", { style: { display: 'contents' }, role: "presentation" }, this.header && h("div", { class: "dropdown-header" }, this.header), this.show && h("slot", null)))));
     }
     static get is() { return "ix-dropdown"; }
     static get encapsulation() { return "shadow"; }
@@ -621,6 +893,166 @@ export class Dropdown {
                 "reflect": false,
                 "attribute": "header"
             },
+            "suppressTriggerVisibilityCheck": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "since",
+                            "text": "5.0.0"
+                        }],
+                    "text": "By default the dropdown gets closed if the trigger is not visible anymore (e.g. due to scrolling). Setting this property prevents that behavior."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "suppress-trigger-visibility-check",
+                "defaultValue": "false"
+            },
+            "disableFocusHandling": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "since",
+                            "text": "4.3.0"
+                        }],
+                    "text": "Suppress automatic focus when the dropdown is shown"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disable-focus-handling",
+                "defaultValue": "false"
+            },
+            "disableFocusTrap": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "since",
+                            "text": "4.3.0"
+                        }],
+                    "text": "Close dropdown when tabbing away, and do not trap focus inside dropdown"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disable-focus-trap",
+                "defaultValue": "false"
+            },
+            "enableTopLayer": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false in v5.x, will default to true in v6.0.0"
+                        }, {
+                            "name": "since",
+                            "text": "4.3.0"
+                        }],
+                    "text": "Enable Popover API rendering for top-layer positioning."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "enable-top-layer",
+                "defaultValue": "false"
+            },
+            "focusCheckedItem": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "since",
+                            "text": "5.0.0"
+                        }],
+                    "text": "If true, the dropdown will try to focus checked items first when opened via keyboard, otherwise it will always focus the first focusable item."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "focus-checked-item",
+                "defaultValue": "false"
+            },
+            "keyboardActivationKeys": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "string[]",
+                    "resolved": "string[]",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }],
+                    "text": "Keys that will open the dropdown when the trigger is focused"
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "[\n    'Home',\n    'End',\n    'ArrowDown',\n    'ArrowUp',\n    'Enter',\n    ' ',\n  ]"
+            },
+            "keyboardItemTriggerKeys": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "string[]",
+                    "resolved": "string[]",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }],
+                    "text": "Keys that will open the dropdown when the trigger is focused"
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "['Enter', ' ']"
+            },
             "offset": {
                 "type": "unknown",
                 "mutable": false,
@@ -747,33 +1179,133 @@ export class Dropdown {
                 "attribute": "suppress-overflow-behavior",
                 "defaultValue": "false"
             },
-            "enableTopLayer": {
-                "type": "boolean",
+            "focusHost": {
+                "type": "unknown",
                 "mutable": false,
                 "complexType": {
-                    "original": "boolean",
-                    "resolved": "boolean",
+                    "original": "HTMLElement",
+                    "resolved": "HTMLElement | undefined",
+                    "references": {
+                        "HTMLElement": {
+                            "location": "global",
+                            "id": "global::HTMLElement"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false
+            },
+            "focusTrapOptions": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "FocusTrapOptions",
+                    "resolved": "undefined | { targetElement?: HTMLElement | MakeRef<any> | undefined; trapFocusInShadowDom?: boolean | undefined; excludeElements?: boolean | undefined; }",
+                    "references": {
+                        "FocusTrapOptions": {
+                            "location": "import",
+                            "path": "../utils/focus/focus-trap",
+                            "id": "src/components/utils/focus/focus-trap.ts::FocusTrapOptions",
+                            "referenceLocation": "FocusTrapOptions"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false
+            },
+            "hostRole": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
                     "references": {}
                 },
                 "required": false,
-                "optional": false,
+                "optional": true,
                 "docs": {
                     "tags": [{
-                            "name": "default",
-                            "text": "false in v4.x, will default to true in v5.0.0"
+                            "name": "internal",
+                            "text": undefined
                         }],
-                    "text": "Enable Popover API rendering for top-layer positioning."
+                    "text": ""
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
-                "attribute": "enable-top-layer",
-                "defaultValue": "false"
+                "attribute": "host-role"
+            },
+            "callbackFocusElement": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "(\n    event: KeyboardEvent\n  ) => Promise<boolean | undefined>",
+                    "resolved": "((event: KeyboardEvent) => Promise<boolean | undefined>) | undefined",
+                    "references": {
+                        "KeyboardEvent": {
+                            "location": "global",
+                            "id": "global::KeyboardEvent"
+                        },
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": "Called instead of the default focus-on-open logic when the dropdown is\nopened via keyboard. When not set, default behavior is used."
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false
             }
         };
     }
+    static get states() {
+        return {
+            "fallbackPlacement": {}
+        };
+    }
     static get events() {
         return [{
+                "method": "showChange",
+                "name": "showChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fire event before visibility of dropdown has changed, preventing event will cancel showing dropdown"
+                },
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                }
+            }, {
                 "method": "showChanged",
                 "name": "showChanged",
                 "bubbles": true,
@@ -788,6 +1320,47 @@ export class Dropdown {
                     "resolved": "boolean",
                     "references": {}
                 }
+            }, {
+                "method": "experimentalRequestFocus",
+                "name": "experimentalRequestFocus",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }],
+                    "text": "Will be fired only after dropdown changed visibility to \"true\""
+                },
+                "complexType": {
+                    "original": "{\n    keyEvent: KeyboardEvent;\n  }",
+                    "resolved": "{ keyEvent: KeyboardEvent; }",
+                    "references": {
+                        "KeyboardEvent": {
+                            "location": "global",
+                            "id": "global::KeyboardEvent"
+                        }
+                    }
+                }
+            }, {
+                "method": "experimentalFocusNextElement",
+                "name": "experimentalFocusNextElement",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
             }];
     }
     static get methods() {
@@ -828,6 +1401,26 @@ export class Dropdown {
                     "text": "Update position of dropdown",
                     "tags": []
                 }
+            },
+            "resetForwardQueryElement": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }]
+                }
             }
         };
     }
@@ -836,6 +1429,9 @@ export class Dropdown {
         return [{
                 "propName": "show",
                 "methodName": "changedShow"
+            }, {
+                "propName": "show",
+                "methodName": "emitShowChanged"
             }, {
                 "propName": "trigger",
                 "methodName": "changedTrigger"
@@ -848,6 +1444,18 @@ export class Dropdown {
                 "target": undefined,
                 "capture": false,
                 "passive": false
+            }, {
+                "name": "ix-open-submenu",
+                "method": "openSubmenu",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "ix-close-submenu",
+                "method": "closeSubmenu",
+                "target": undefined,
+                "capture": false,
+                "passive": false
             }];
     }
 }