fix(menu): improve keyboard navigation

Since this component relies on MDC, there is already
some inbuilt keyboard interactions support for arrow keys.
We had some additional customized keyboard navigation support
for the cases when there is a searcher. But they didn't work
well-enough for keyboard users. For instance, the breadcrumbs
were completely ignored. User could press the DOWN key to
set the focus on menu items, but they could never set the focus
back to the input field again by pressing UP for instance,
to keep modifying their keywords.

Author: Kiarokh

src/components/menu/menu.tsx

@@ -195,6 +195,7 @@ export class Menu {
     private list: HTMLLimelMenuListElement;
     private searchInput: HTMLLimelInputFieldElement;
     private portalId: string;
+    private breadcrumbs: HTMLLimelBreadcrumbsElement;
     private triggerElement: HTMLSlotElement;
     private selectedMenuItem?: MenuItem;
 
@@ -322,11 +323,13 @@ export class Menu {
 
         return (
             <limel-breadcrumbs
+                ref={this.setBreadcrumbsElement}
                 style={{
                     'border-bottom': 'solid 1px rgb(var(--contrast-500))',
                     'flex-shrink': '0',
                 }}
                 onSelect={this.handleBreadcrumbsSelect}
+                onKeyDown={this.handleBreadcrumbsKeyDown}
                 items={breadcrumbsItems}
             />
         );
@@ -445,8 +448,8 @@ export class Menu {
     };
 
     // Key handler for the input search field
-    // Will change focus to the first/last item in the dropdown
-    // list to enable selection with the keyboard
+    // Will change focus to breadcrumbs (if present) or the first/last item
+    // in the dropdown list to enable selection with the keyboard
     private handleInputKeyDown = (event: KeyboardEvent) => {
         const isForwardTab =
             event.key === TAB &&
@@ -460,37 +463,71 @@ export class Menu {
             return;
         }
 
-        if (!this.list) {
-            return;
-        }
-
         event.stopPropagation();
         event.preventDefault();
 
         if (isForwardTab || isDown) {
-            const listItems =
-                this.list.shadowRoot.querySelectorAll<HTMLElement>(
-                    '.mdc-deprecated-list-item'
-                );
-            const listElement = listItems[0];
-            listElement?.focus();
+            if (this.focusBreadcrumbs()) {
+                return;
+            }
+
+            this.focusFirstListItem();
 
             return;
         }
 
         if (isUp) {
-            const listItems =
-                this.list.shadowRoot.querySelectorAll<HTMLElement>(
-                    '.mdc-deprecated-list-item'
-                );
-            const listElement = [...listItems].at(-1);
-            listElement?.focus();
+            // Focus the last list item (wrapping behavior)
+            this.focusLastListItem();
         }
     };
 
-    // Key handler for the menu list
+    // Key handler for the menu list (capture phase)
+    // Handles Up arrow on first item and Down arrow on last item
+    // Must run in capture phase to intercept before MDC Menu wraps focus
+    // Only intercepts when there's a search input or breadcrumbs to navigate to
+    private readonly handleListKeyDownCapture = (event: KeyboardEvent) => {
+        const isUp = event.key === ARROW_UP;
+        const isDown = event.key === ARROW_DOWN;
+
+        if (!isUp && !isDown) {
+            return;
+        }
+
+        // Up on first item: go to breadcrumbs or search input (if they exist)
+        if (isUp && this.isFirstListItemFocused()) {
+            // Try to focus breadcrumbs first
+            if (this.focusBreadcrumbs()) {
+                event.stopPropagation();
+                event.preventDefault();
+
+                return;
+            }
+
+            // Then try search input
+            if (this.searchInput) {
+                event.stopPropagation();
+                event.preventDefault();
+                this.searchInput.focus();
+            }
+
+            // If neither exists, let MDC Menu handle wrap-around
+            return;
+        }
+
+        // Down on last item: go to search input (if it exists)
+        if (isDown && this.isLastListItemFocused() && this.searchInput) {
+            event.stopPropagation();
+            event.preventDefault();
+            this.searchInput.focus();
+        }
+
+        // If no search input, let MDC Menu handle wrap-around
+    };
+
+    // Key handler for the menu list (bubble phase)
     // Will change focus to the search field if using shift+tab
-    // And can go forward/back with righ/left arrow keys
+    // And can go forward/back with right/left arrow keys
     private handleMenuKeyDown = (event: KeyboardEvent) => {
         const isBackwardTab =
             event.key === TAB &&
@@ -499,7 +536,6 @@ export class Menu {
             event.shiftKey;
 
         const isLeft = event.key === ARROW_LEFT;
-
         const isRight = event.key === ARROW_RIGHT;
 
         if (!isBackwardTab && !isLeft && !isRight) {
@@ -510,7 +546,11 @@ export class Menu {
             event.stopPropagation();
             event.preventDefault();
             this.searchInput?.focus();
-        } else if (!this.gridLayout) {
+
+            return;
+        }
+
+        if (!this.gridLayout && (isLeft || isRight)) {
             const currentItem = this.getCurrentItem();
 
             event.stopPropagation();
@@ -523,20 +563,60 @@ export class Menu {
         }
     };
 
+    // Key handler for breadcrumbs
+    // Up arrow: focus search input
+    // Down arrow: focus first list item
+    private handleBreadcrumbsKeyDown = (event: KeyboardEvent) => {
+        const isUp = event.key === ARROW_UP;
+        const isDown = event.key === ARROW_DOWN;
+
+        if (!isUp && !isDown) {
+            return;
+        }
+
+        event.stopPropagation();
+        event.preventDefault();
+
+        if (isUp) {
+            this.searchInput?.focus();
+
+            return;
+        }
+
+        if (isDown) {
+            this.focusFirstListItem();
+        }
+    };
+
     private clearSearch = () => {
         this.searchValue = '';
         this.searchResults = null;
         this.loadingSubItems = false;
     };
 
-    private getCurrentItem = (): MenuItem => {
-        const activeItem = this.list?.shadowRoot?.querySelector(
-            '[role="menuitem"][tabindex="0"]'
+    private readonly getCurrentItem = (): MenuItem => {
+        let menuElement =
+            (this.list?.shadowRoot?.activeElement as HTMLElement | null) ??
+            null;
+
+        if (menuElement && menuElement.getAttribute('role') !== 'menuitem') {
+            menuElement = menuElement.closest<HTMLElement>('[role="menuitem"]');
+        }
+
+        if (!menuElement) {
+            menuElement = this.list?.shadowRoot?.querySelector<HTMLElement>(
+                '[role="menuitem"][tabindex="0"]'
+            );
+        }
+
+        const dataIndex = Number.parseInt(
+            menuElement?.dataset.index ?? '0',
+            10
         );
-        const attrIndex = activeItem?.attributes?.getNamedItem('data-index');
-        const dataIndex = Number.parseInt(attrIndex?.value || '0', 10);
 
-        return this.visibleItems[dataIndex] as MenuItem;
+        const item = this.visibleItems[dataIndex];
+
+        return (item ?? this.visibleItems[0]) as MenuItem;
     };
 
     private goForward = (currentItem: MenuItem) => {
@@ -673,7 +753,23 @@ export class Menu {
     }
 
     private setListElement = (element: HTMLLimelMenuListElement) => {
+        if (this.list) {
+            this.list.removeEventListener(
+                'keydown',
+                this.handleListKeyDownCapture,
+                true
+            );
+        }
+
         this.list = element;
+
+        if (this.list) {
+            this.list.addEventListener(
+                'keydown',
+                this.handleListKeyDownCapture,
+                true
+            );
+        }
     };
 
     private setFocus = () => {
@@ -702,7 +798,88 @@ export class Menu {
         this.searchInput = element;
     };
 
-    private focusMenuItem = () => {
+    private readonly setBreadcrumbsElement = (
+        element: HTMLLimelBreadcrumbsElement
+    ) => {
+        this.breadcrumbs = element;
+    };
+
+    /**
+     * Focuses the first focusable element inside breadcrumbs.
+     * Returns true if breadcrumbs exist and were focused,
+     * false otherwise.
+     */
+    private readonly focusBreadcrumbs = (): boolean => {
+        if (!this.breadcrumbs) {
+            return false;
+        }
+
+        const focusableElement =
+            this.breadcrumbs.shadowRoot?.querySelector<HTMLElement>(
+                'button, a'
+            );
+        if (focusableElement) {
+            focusableElement.focus();
+
+            return true;
+        }
+
+        return false;
+    };
+
+    private readonly focusFirstListItem = () => {
+        const listItems = this.getListItems();
+        const firstItem = listItems?.[0];
+        firstItem?.focus();
+    };
+
+    private readonly focusLastListItem = () => {
+        const listItems = this.getListItems();
+        const lastItem = listItems?.at(-1);
+        lastItem?.focus();
+    };
+
+    private readonly isFirstListItemFocused = (): boolean => {
+        const listItems = this.getListItems();
+        if (!listItems) {
+            return false;
+        }
+
+        const firstItem = listItems[0];
+        const activeElement = this.list.shadowRoot?.activeElement;
+
+        return firstItem === activeElement;
+    };
+
+    private readonly isLastListItemFocused = (): boolean => {
+        const listItems = this.getListItems();
+        if (!listItems) {
+            return false;
+        }
+
+        const lastItem = listItems.at(-1);
+        const activeElement = this.list.shadowRoot?.activeElement;
+
+        return lastItem === activeElement;
+    };
+
+    private readonly getListItems = (): HTMLElement[] | null => {
+        if (!this.list) {
+            return null;
+        }
+
+        const items = this.list.shadowRoot?.querySelectorAll<HTMLElement>(
+            '.mdc-deprecated-list-item'
+        );
+
+        if (!items?.length) {
+            return null;
+        }
+
+        return [...items];
+    };
+
+    private readonly focusMenuItem = () => {
         if (!this.list) {
             return;
         }