@xplortech/apollo-core 2.10.0 → 2.12.0

package/dist/collection/components/xpl-top-nav/xpl-top-nav-item/xpl-top-nav-item.js

@@ -1,36 +1,56 @@
 import { Host, h, } from "@stencil/core";
+import { TimerManager, isBrowser } from "../../../utils/lifecycle";
+import { TOP_NAV_MOBILE_MQ } from "../top-nav-constants";
+import { TOP_NAV_ITEM_HOVER_CLOSE_DELAY_MS, TOP_NAV_ITEM_HOVER_OPEN_MQ, } from "./top-nav-item-constants";
+const TIMER = {
+    hasDropdownSync: 'hasDropdownSync',
+    postRender: 'postRender',
+    focusTriggerAfterEscape: 'focusTriggerAfterEscape',
+    hoverClose: 'hoverClose',
+};
 export class TopNavItem {
     constructor() {
+        this.dropdownPanelId = `xpl-top-nav-item-dropdown-${Math.random().toString(36).slice(2, 11)}`;
+        this.hoverOpened = false;
+        this.timers = new TimerManager();
+        this.hasActiveDescendant = false;
         this.hasDropdown = false;
+        this.isLeadingIconSlotPresent = false;
+        this.isMobileViewport = false;
         this.hostListitemRole = false;
-        this.open = false;
+        this.isTrailingIconSlotPresent = false;
         this.active = false;
         this.icon = '';
+        this.open = false;
+        this.openMode = 'click';
         this.selected = false;
         this.onDocClickCapture = (e) => {
-            if (!this.hasDropdown || !this.open) {
+            if (!this.hasDropdown || !this.open)
                 return;
-            }
             const target = e.target;
             if (target && !this.el.contains(target)) {
                 this.open = false;
             }
         };
         this.onDocKeyDownCapture = (e) => {
-            if (!this.hasDropdown || !this.open) {
+            if (!this.hasDropdown || !this.open)
                 return;
-            }
             if (e.key === 'Escape') {
                 e.preventDefault();
                 e.stopPropagation();
                 this.open = false;
+                this.focusTriggerAfterEscape();
             }
         };
         this.handleClick = (e) => {
             if (this.hasDropdown) {
                 e.preventDefault();
                 e.stopPropagation();
-                this.broadcastCloseOtherDropdownHosts();
+                this.timers.clearCoalesced(TIMER.hoverClose);
+                if (this.open && this.hoverOpened && this.hoverModeActive() && e.detail > 0) {
+                    return;
+                }
+                this.hoverOpened = false;
                 this.open = !this.open;
                 return;
             }
@@ -38,44 +58,66 @@ export class TopNavItem {
         };
         this.handleKeyDown = (e) => {
             const isLinkMode = this.href != null && !this.hasDropdown;
-            if (isLinkMode) {
-                if (e.key === 'Enter') {
-                    return;
-                }
-                if (e.key === ' ') {
-                    e.preventDefault();
-                    const anchor = this.el.querySelector('.xpl-top-nav-item__inner');
-                    anchor === null || anchor === void 0 ? void 0 : anchor.click();
-                    return;
-                }
+            if (isLinkMode && e.key === ' ') {
+                e.preventDefault();
+                const anchor = this.el.querySelector('.xpl-top-nav-item__inner');
+                anchor?.click();
             }
-            if (e.key !== 'Enter' && e.key !== ' ')
+        };
+        this.onMobileViewportChange = () => {
+            this.isMobileViewport = this.mobileMq?.matches ?? false;
+        };
+        this.handleMouseEnter = () => {
+            if (!this.hasDropdown || !this.hoverModeActive()) {
                 return;
-            e.preventDefault();
-            this.handleClick(this.syntheticActivationClickFromKeyboard(e));
+            }
+            this.timers.clearCoalesced(TIMER.hoverClose);
+            if (!this.open) {
+                this.hoverOpened = true;
+                this.open = true;
+            }
+        };
+        this.handleMouseLeave = () => {
+            if (!this.hasDropdown || !this.open || !this.hoverOpened) {
+                return;
+            }
+            this.timers.scheduleCoalesced(TIMER.hoverClose, () => {
+                if (!this.hoverOpened || this.el.contains(this.el.ownerDocument.activeElement)) {
+                    return;
+                }
+                this.open = false;
+            }, TOP_NAV_ITEM_HOVER_CLOSE_DELAY_MS);
         };
     }
     onHasDropdownChanged() {
-        if (!this.hasDropdown) {
+        if (!this.hasDropdown)
             this.open = false;
-        }
         this.syncDropdownDocListeners();
     }
+    onOpenChanged(next) {
+        this.openChange.emit(next);
+        if (!next)
+            this.hoverOpened = false;
+        if (next && this.hasDropdown)
+            this.broadcastCloseOtherDropdownHosts();
+    }
     connectedCallback() {
+        if (isBrowser() && typeof window.matchMedia === 'function') {
+            this.hoverOpenMq = window.matchMedia(TOP_NAV_ITEM_HOVER_OPEN_MQ);
+            this.mobileMq = window.matchMedia(TOP_NAV_MOBILE_MQ);
+            this.mobileMq.addEventListener('change', this.onMobileViewportChange);
+            this.isMobileViewport = this.mobileMq.matches;
+        }
         this.syncHostListitemRole();
         this.syncHasDropdownFromDom();
         this.syncDropdownDocListeners();
         this.connectDropdownSlotObserver();
     }
     disconnectedCallback() {
-        if (this.deferredHasDropdownObserverSyncTimeoutId !== undefined) {
-            clearTimeout(this.deferredHasDropdownObserverSyncTimeoutId);
-            this.deferredHasDropdownObserverSyncTimeoutId = undefined;
-        }
-        if (this.deferredPostRenderTopNavItemTimeoutId !== undefined) {
-            clearTimeout(this.deferredPostRenderTopNavItemTimeoutId);
-            this.deferredPostRenderTopNavItemTimeoutId = undefined;
-        }
+        this.timers.dispose();
+        this.hoverOpenMq = undefined;
+        this.mobileMq?.removeEventListener('change', this.onMobileViewportChange);
+        this.mobileMq = undefined;
         this.disconnectDropdownSlotObserver();
         this.disconnectListitemContextObservers();
         const doc = this.el.ownerDocument;
@@ -85,7 +127,6 @@ export class TopNavItem {
     componentWillLoad() {
         this.syncHostListitemRole();
         this.syncHasDropdownFromDom();
-        this.syncDropdownDocListeners();
     }
     componentWillRender() {
         this.disconnectDropdownSlotObserver();
@@ -99,23 +140,35 @@ export class TopNavItem {
             this.open = false;
         }
     }
+    async closeMenu() {
+        if (!this.hasDropdown)
+            return;
+        this.open = false;
+    }
+    async openMenu() {
+        if (!this.hasDropdown)
+            return;
+        this.timers.clearCoalesced(TIMER.hoverClose);
+        this.hoverOpened = false;
+        this.open = true;
+    }
+    async toggleMenu() {
+        if (!this.hasDropdown)
+            return;
+        this.open = !this.open;
+    }
     scheduleHasDropdownSyncFromObserver() {
-        if (this.deferredHasDropdownObserverSyncTimeoutId !== undefined) {
-            clearTimeout(this.deferredHasDropdownObserverSyncTimeoutId);
-        }
-        this.deferredHasDropdownObserverSyncTimeoutId = setTimeout(() => {
-            this.deferredHasDropdownObserverSyncTimeoutId = undefined;
+        this.timers.scheduleCoalesced(TIMER.hasDropdownSync, () => {
             if (!this.el.isConnected) {
                 return;
             }
             this.syncHasDropdownFromDom();
-        }, 0);
+        });
     }
     connectDropdownSlotObserver() {
         this.disconnectDropdownSlotObserver();
-        if (typeof MutationObserver === 'undefined') {
+        if (typeof MutationObserver === 'undefined')
             return;
-        }
         this.dropdownSlotObserver = new MutationObserver(() => {
             this.scheduleHasDropdownSyncFromObserver();
         });
@@ -127,15 +180,13 @@ export class TopNavItem {
         });
     }
     disconnectDropdownSlotObserver() {
-        var _a;
-        (_a = this.dropdownSlotObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
+        this.dropdownSlotObserver?.disconnect();
         this.dropdownSlotObserver = undefined;
     }
     disconnectListitemContextObservers() {
-        var _a, _b;
-        (_a = this.parentListitemContextObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
+        this.parentListitemContextObserver?.disconnect();
         this.parentListitemContextObserver = undefined;
-        (_b = this.selfListitemContextObserver) === null || _b === void 0 ? void 0 : _b.disconnect();
+        this.selfListitemContextObserver?.disconnect();
         this.selfListitemContextObserver = undefined;
     }
     connectListitemContextObservers() {
@@ -160,7 +211,7 @@ export class TopNavItem {
             const leftPrimaryListHost = isTopNavLeftAside
                 ? parent.querySelector('.xpl-top-nav__left-primary')
                 : null;
-            const observeTarget = leftPrimaryListHost !== null && leftPrimaryListHost !== void 0 ? leftPrimaryListHost : parent;
+            const observeTarget = leftPrimaryListHost ?? parent;
             this.parentListitemContextObserver.observe(observeTarget, {
                 attributes: true,
                 attributeFilter: ['role'],
@@ -169,20 +220,20 @@ export class TopNavItem {
         }
     }
     schedulePostRenderTopNavItemWork() {
-        if (this.deferredPostRenderTopNavItemTimeoutId !== undefined) {
-            clearTimeout(this.deferredPostRenderTopNavItemTimeoutId);
-        }
-        this.deferredPostRenderTopNavItemTimeoutId = setTimeout(() => {
-            this.deferredPostRenderTopNavItemTimeoutId = undefined;
+        this.timers.scheduleCoalesced(TIMER.postRender, () => {
             if (!this.el.isConnected) {
                 return;
             }
             this.syncHostListitemRole();
+            this.syncHasDropdownFromDom();
             this.connectListitemContextObservers();
             this.connectDropdownSlotObserver();
-        }, 0);
+        });
     }
     syncDropdownDocListeners() {
+        if (!isBrowser()) {
+            return;
+        }
         const doc = this.el.ownerDocument;
         doc.removeEventListener('click', this.onDocClickCapture, true);
         doc.removeEventListener('keydown', this.onDocKeyDownCapture, true);
@@ -192,35 +243,54 @@ export class TopNavItem {
         doc.addEventListener('click', this.onDocClickCapture, true);
         doc.addEventListener('keydown', this.onDocKeyDownCapture, true);
     }
+    hasSlottedChildOwnedByThisHost(slotName) {
+        return Array.from(this.el.querySelectorAll(`[slot="${slotName}"]`)).some((node) => node.closest('xpl-top-nav-item') === this.el);
+    }
     syncHasDropdownFromDom() {
-        this.hasDropdown = !!this.el.querySelector('[slot="dropdown"]');
+        const nextHasDropdown = this.el.querySelector('[slot="dropdown"]') != null;
+        if (nextHasDropdown !== this.hasDropdown) {
+            this.hasDropdown = nextHasDropdown;
+        }
+        const nextLeading = this.hasSlottedChildOwnedByThisHost('leading-icon');
+        if (nextLeading !== this.isLeadingIconSlotPresent) {
+            this.isLeadingIconSlotPresent = nextLeading;
+        }
+        const nextTrailing = this.hasSlottedChildOwnedByThisHost('trailing-icon');
+        if (nextTrailing !== this.isTrailingIconSlotPresent) {
+            this.isTrailingIconSlotPresent = nextTrailing;
+        }
+        const nextActiveDescendant = nextHasDropdown
+            ? this.el.querySelector('[slot="dropdown"] .xpl-top-nav-item--active') !== null ||
+                this.el.querySelector('[slot="dropdown"] .xpl-top-nav-item--selected') !== null
+            : false;
+        if (nextActiveDescendant !== this.hasActiveDescendant) {
+            this.hasActiveDescendant = nextActiveDescendant;
+        }
     }
     getNavDropdownBroadcastRoot() {
-        var _a, _b;
-        return ((_b = (_a = this.el.closest('xpl-top-nav')) !== null && _a !== void 0 ? _a : this.el.closest('xpl-nav-header-menu')) !== null && _b !== void 0 ? _b : this.el.ownerDocument);
+        return (this.el.closest('xpl-top-nav-menu') ??
+            this.el.closest('xpl-nav-header-menu') ??
+            this.el.closest('xpl-top-nav') ??
+            this.el.ownerDocument);
     }
     broadcastCloseOtherDropdownHosts() {
         const root = this.getNavDropdownBroadcastRoot();
         root.querySelectorAll('xpl-top-nav-item').forEach((host) => {
-            if (host === this.el) {
+            if (host === this.el || host.parentElement !== this.el.parentElement) {
                 return;
             }
             host.dispatchEvent(new CustomEvent('_xplCloseNavDropdown', { bubbles: false }));
         });
     }
-    syntheticActivationClickFromKeyboard(e) {
-        var _a;
-        const inner = this.el.querySelector('.xpl-top-nav-item__inner');
-        const rect = inner === null || inner === void 0 ? void 0 : inner.getBoundingClientRect();
-        const cx = rect ? rect.left + rect.width / 2 : 0;
-        const cy = rect ? rect.top + rect.height / 2 : 0;
-        return new MouseEvent('click', {
-            bubbles: true,
-            cancelable: true,
-            button: 0,
-            clientX: cx,
-            clientY: cy,
-            view: (_a = e.view) !== null && _a !== void 0 ? _a : undefined,
+    hoverModeActive() {
+        return this.openMode === 'hover' && (this.hoverOpenMq?.matches ?? false);
+    }
+    focusTriggerAfterEscape() {
+        this.timers.scheduleCoalesced(TIMER.focusTriggerAfterEscape, () => {
+            if (!this.el.isConnected) {
+                return;
+            }
+            this.el.querySelector('.xpl-top-nav-item__inner')?.focus();
         });
     }
     static isInternalRenderedHostChild(el) {
@@ -229,54 +299,49 @@ export class TopNavItem {
     }
     hasNonDropdownLightDomChild() {
         return Array.from(this.el.childNodes).some((node) => {
-            var _a;
             if (node.nodeType === Node.TEXT_NODE) {
-                return Boolean((_a = node.textContent) === null || _a === void 0 ? void 0 : _a.trim());
+                return Boolean(node.textContent?.trim());
             }
             if (node.nodeType === Node.ELEMENT_NODE) {
                 const child = node;
                 if (TopNavItem.isInternalRenderedHostChild(child)) {
                     return false;
                 }
-                return child.getAttribute('slot') !== 'dropdown';
+                const slotName = child.getAttribute('slot');
+                return slotName == null || slotName === '';
             }
             return false;
         });
     }
     getInnerAriaLabel() {
-        var _a, _b, _c;
-        if ((_a = this.label) === null || _a === void 0 ? void 0 : _a.trim()) {
+        if (this.label?.trim())
             return undefined;
-        }
-        if (this.hasNonDropdownLightDomChild()) {
+        if (this.hasNonDropdownLightDomChild())
             return undefined;
-        }
-        const custom = (_b = this.itemAriaLabel) === null || _b === void 0 ? void 0 : _b.trim();
-        if (custom) {
+        const custom = this.itemAriaLabel?.trim();
+        if (custom)
             return custom;
-        }
-        if ((_c = this.icon) === null || _c === void 0 ? void 0 : _c.trim()) {
+        if (this.icon?.trim() || this.isLeadingIconSlotPresent)
             return 'Navigation item';
-        }
         return undefined;
     }
     computeHostListitemRole() {
         const { el } = this;
-        if (el.classList.contains('xpl-top-nav__brand')) {
+        if (el.classList.contains('xpl-top-nav__brand'))
             return false;
-        }
-        if (el.getAttribute('slot') === 'right-aside-mobile') {
+        if (el.getAttribute('slot') === 'right-aside-mobile')
             return false;
-        }
         const parent = el.parentElement;
-        if ((parent === null || parent === void 0 ? void 0 : parent.getAttribute('role')) === 'list') {
+        if (parent?.getAttribute('role') === 'list')
             return true;
-        }
         if (parent != null && parent.tagName.toLowerCase() === 'xpl-nav-header-menu') {
             return true;
         }
+        if (parent != null && parent.tagName.toLowerCase() === 'xpl-top-nav-menu') {
+            return true;
+        }
         if (el.getAttribute('slot') === 'left-aside' &&
-            (parent === null || parent === void 0 ? void 0 : parent.tagName.toLowerCase()) === 'xpl-top-nav' &&
+            parent?.tagName.toLowerCase() === 'xpl-top-nav' &&
             parent.querySelector('.xpl-top-nav__left-primary[role="list"]') != null) {
             return true;
         }
@@ -284,31 +349,69 @@ export class TopNavItem {
     }
     syncHostListitemRole() {
         const next = this.computeHostListitemRole();
-        if (this.hostListitemRole !== next) {
+        if (this.hostListitemRole !== next)
             this.hostListitemRole = next;
+    }
+    renderLabelContent() {
+        if (!this.label) {
+            return h("slot", null);
+        }
+        const description = this.description?.trim();
+        if (!description) {
+            return (h("span", { class: "xpl-top-nav-item__label", title: this.label }, this.label));
         }
+        return (h("span", { class: "xpl-top-nav-item__label-group" }, h("span", { class: "xpl-top-nav-item__label", title: this.label }, this.label), h("span", { class: "xpl-top-nav-item__description" }, description)));
+    }
+    renderLeading() {
+        if (this.isLeadingIconSlotPresent) {
+            return (h("span", { class: "xpl-top-nav-item__leading" }, h("slot", { name: "leading-icon" })));
+        }
+        if (this.icon) {
+            return (h("span", { class: "xpl-top-nav-item__leading" }, h("xpl-icon", { size: 16, icon: this.icon })));
+        }
+        return null;
+    }
+    renderTrailing() {
+        if (this.isTrailingIconSlotPresent) {
+            return (h("span", { class: "xpl-top-nav-item__trailing" }, h("slot", { name: "trailing-icon" })));
+        }
+        if (this.hasDropdown) {
+            return (h("span", { class: "xpl-top-nav-item__trailing" }, h("xpl-icon", { icon: this.isMobileViewport ? 'chevron-right' : 'chevron-down' })));
+        }
+        return null;
     }
     renderInner() {
         const tabIndex = 0;
         const ariaCurrent = this.selected ? 'page' : undefined;
         const ariaExpanded = this.hasDropdown ? (this.open ? 'true' : 'false') : undefined;
         const ariaLabel = this.getInnerAriaLabel();
-        const shared = Object.assign(Object.assign({ class: 'xpl-top-nav-item__inner', tabIndex, 'aria-current': ariaCurrent, 'aria-expanded': ariaExpanded }, (ariaLabel ? { 'aria-label': ariaLabel } : {})), { onClick: this.handleClick, onKeyDown: this.handleKeyDown });
+        const shared = {
+            class: 'xpl-top-nav-item__inner',
+            tabIndex,
+            'aria-current': ariaCurrent,
+            'aria-expanded': ariaExpanded,
+            'aria-haspopup': this.hasDropdown ? 'true' : undefined,
+            'aria-controls': this.hasDropdown ? this.dropdownPanelId : undefined,
+            ...(ariaLabel ? { 'aria-label': ariaLabel } : {}),
+            onClick: this.handleClick,
+            onKeyDown: this.handleKeyDown,
+        };
         const useAnchor = this.href != null && !this.hasDropdown;
         if (useAnchor) {
-            return (h("a", Object.assign({}, shared, { href: this.href }), this.icon && h("xpl-icon", { size: 16, icon: this.icon }), this.label ? (h("span", { class: "xpl-top-nav-item__label", title: this.label }, this.label)) : (h("slot", null))));
+            return (h("a", { ...shared, href: this.href }, this.renderLeading(), this.renderLabelContent(), this.renderTrailing()));
         }
-        return (h("div", Object.assign({}, shared, { role: "button" }), this.icon && h("xpl-icon", { size: 16, icon: this.icon }), this.label ? (h("span", { class: "xpl-top-nav-item__label", title: this.label }, this.label)) : (h("slot", null)), this.hasDropdown && h("xpl-icon", { icon: "chevron-down" })));
+        return (h("button", { ...shared, type: "button" }, this.renderLeading(), this.renderLabelContent(), this.renderTrailing()));
     }
     render() {
-        return (h(Host, Object.assign({ key: '6d68c9bb7527410185e6ecd176c7a9a887359af9', class: {
+        return (h(Host, { key: 'e1e7241e6b6f2d9d96c779b91b7fa1ba20e8e1f4', class: {
                 'xpl-top-nav-item': true,
                 'xpl-top-nav-item--active': this.active,
-                'xpl-top-nav-item--dropdown-open': this.open,
+                'xpl-top-nav-item--dropdown-open': this.hasDropdown && this.open,
+                'xpl-top-nav-item--has-active-descendant': this.hasActiveDescendant,
                 'xpl-top-nav-item--has-dropdown': this.hasDropdown,
                 'xpl-top-nav-item--selected': this.selected,
                 dark: true,
-            } }, (this.hostListitemRole ? { role: 'listitem' } : {})), this.renderInner(), this.hasDropdown && (h("div", { key: 'da5414f6573aa6eb604721c814164b9a4987091d', class: "xpl-top-nav-item__dropdown" }, h("slot", { key: '116c436b4ef2902c50c5dd78c8d292190a3c58e4', name: "dropdown" })))));
+            }, onMouseEnter: this.handleMouseEnter, onMouseLeave: this.handleMouseLeave, ...(this.hostListitemRole ? { role: 'listitem' } : {}) }, this.renderInner(), this.hasDropdown && (h("div", { key: 'ec1ed04f166670f78c205ba351911672a147d5a7', id: this.dropdownPanelId, class: "xpl-top-nav-item__dropdown" }, h("slot", { key: '01d3db348a018c43f21b24acad80e7687f8bb0e1', name: "dropdown" })))));
     }
     static get is() { return "xpl-top-nav-item"; }
     static get properties() {
@@ -333,6 +436,25 @@ export class TopNavItem {
                 "attribute": "active",
                 "defaultValue": "false"
             },
+            "description": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Optional description line shown below **`label`** (row context only, e.g. inside **`xpl-nav-header-menu`** /\n**`xpl-top-nav-menu`**). Ignored when **`label`** is not set."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "description"
+            },
             "href": {
                 "type": "string",
                 "mutable": false,
@@ -364,7 +486,7 @@ export class TopNavItem {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set)."
+                    "text": "Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set). Ignored when\n**`slot=\"leading-icon\"`** content is present."
                 },
                 "getter": false,
                 "setter": false,
@@ -410,6 +532,46 @@ export class TopNavItem {
                 "reflect": false,
                 "attribute": "label"
             },
+            "open": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Whether the **`slot=\"dropdown\"`** panel is open. Reflected to the **`open`** attribute so consumers can drive it\n(controlled) or read it back (uncontrolled, toggled internally on click / hover / keyboard activation). Prefer\n**`openMenu()`** / **`closeMenu()`** / **`toggleMenu()`** over setting this directly from event handlers."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "open",
+                "defaultValue": "false"
+            },
+            "openMode": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'click' | 'hover'",
+                    "resolved": "\"click\" | \"hover\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "How the **`slot=\"dropdown\"`** panel opens. **`hover`** is gated on **`TOP_NAV_ITEM_HOVER_OPEN_MQ`**\n(hover-capable, fine pointer, **`md`** and up) \u2014 below that, or on touch / coarse-pointer devices, **`hover`**\nfalls back to click/tap. Keyboard activation (Enter / Space) always toggles regardless of **`openMode`**."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "open-mode",
+                "defaultValue": "'click'"
+            },
             "selected": {
                 "type": "boolean",
                 "mutable": false,
@@ -434,9 +596,12 @@ export class TopNavItem {
     }
     static get states() {
         return {
+            "hasActiveDescendant": {},
             "hasDropdown": {},
+            "isLeadingIconSlotPresent": {},
+            "isMobileViewport": {},
             "hostListitemRole": {},
-            "open": {}
+            "isTrailingIconSlotPresent": {}
         };
     }
     static get events() {
@@ -448,7 +613,7 @@ export class TopNavItem {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "Emitted for plain items (button or link) on pointer **click**, or when keyboard activation produces a **`click`**\n(native for **Enter** on **`<a href>`**, or programmatic **`.click()`** for **Space** on links). **`detail`** is the\n**`MouseEvent`** from that activation (synthetic only for **`<div role=\"button\">`** via **Enter** / **Space**).\nNot emitted when **`slot=\"dropdown\"`** is used."
+                    "text": "Emitted for plain items (button or link) on pointer **click**, or when keyboard activation produces a **`click`**:\nthe native **`<button>`** fires a real **`click`** on **Enter** / **Space**, a native **`<a href>`** on **Enter**,\nand **Space** on a link maps to a programmatic **`.click()`**. **`detail`** is always the real **`MouseEvent`** from\nthat activation (keyboard-driven clicks have **`detail === 0`**). Not emitted when **`slot=\"dropdown\"`** is used."
                 },
                 "complexType": {
                     "original": "MouseEvent",
@@ -460,13 +625,86 @@ export class TopNavItem {
                         }
                     }
                 }
+            }, {
+                "method": "openChange",
+                "name": "openChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted whenever **`open`** changes (click, hover, keyboard, Escape, outside click, or programmatic)."
+                },
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                }
             }];
     }
+    static get methods() {
+        return {
+            "closeMenu": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "No-op when there is no **`slot=\"dropdown\"`** panel to open.",
+                    "tags": []
+                }
+            },
+            "openMenu": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "No-op when there is no **`slot=\"dropdown\"`** panel to open.",
+                    "tags": []
+                }
+            },
+            "toggleMenu": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "No-op when there is no **`slot=\"dropdown\"`** panel to open.",
+                    "tags": []
+                }
+            }
+        };
+    }
     static get elementRef() { return "el"; }
     static get watchers() {
         return [{
                 "propName": "hasDropdown",
                 "methodName": "onHasDropdownChanged"
+            }, {
+                "propName": "open",
+                "methodName": "onOpenChanged"
             }];
     }
     static get listeners() {