@reliability-design/web 1.4.4 → 1.4.5

package/dist/components/rel-menubar/rel-menubar.ts

@@ -1,5 +1,6 @@
-import { LitElement, html } from "lit";
-import { customElement, state } from "lit/decorators.js";
+import { LitElement, html, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { matchesShortcut, isEditableTarget } from "../../utils/shortcuts.js";
 import { RelMenubarMenu } from "./rel-menubar-menu";
 import "@reliability-design/icons/rel-icon";
 import "../rel-checkbox/rel-checkbox.js";
@@ -13,15 +14,29 @@ interface MenuState {
 
 @customElement("rel-menubar")
 export class RelMenubar extends LitElement {
+  /**
+   * Opt-in: actually BIND the keys declared via data-shortcut (e.g.
+   * data-shortcut="Ctrl+Z"), not just display them. "Ctrl" matches Cmd on
+   * Apple platforms when written as "Mod". Keystrokes originating in
+   * inputs/textareas/contenteditable are ignored.
+   */
+  @property({ type: Boolean, attribute: "bind-shortcuts" }) bindShortcuts = false;
+
   @state() private menus: MenuState[] = [];
   @state() private openMenuIndex: number = -1;
   @state() private focusedTriggerIndex: number = 0;
   @state() private focusedItemIndex: number = -1;
+  /** Virtual-focus index inside the open submenu; -1 = focus is in the panel. */
+  @state() private focusedSubItemIndex: number = -1;
   @state() private openSubmenuElement: HTMLElement | null = null;
 
   private hoverSwitchEnabled = false;
   private _onScroll?: () => void;
 
+  /** Stable id prefix for aria-activedescendant targets (light DOM, so ids
+   *  must be unique per menubar instance on the page). */
+  private menubarId = `rel-menubar-${Math.random().toString(36).slice(2)}`;
+
   public static readonly _css = `
     /* This component renders into LIGHT DOM (createRenderRoot returns this), so
        :host / <slot> don't work here — the raw <rel-menubar-menu> definitions
@@ -190,6 +205,7 @@ export class RelMenubar extends LitElement {
     super.connectedCallback();
     this.discoverMenus();
     document.addEventListener("click", this.handleOutsideClick);
+    document.addEventListener("keydown", this.handleShortcutKeyDown);
     this._onScroll = () => {
       this._repositionOpenMenu();
       this._repositionOpenSubmenu();
@@ -200,6 +216,7 @@ export class RelMenubar extends LitElement {
   disconnectedCallback() {
     super.disconnectedCallback();
     document.removeEventListener("click", this.handleOutsideClick);
+    document.removeEventListener("keydown", this.handleShortcutKeyDown);
     if (this._onScroll) {
       window.removeEventListener('scroll', this._onScroll, { capture: true });
     }
@@ -235,6 +252,24 @@ export class RelMenubar extends LitElement {
     this.menus = menuElements.map((menu) => ({ menu, open: false }));
   }
 
+  private handleShortcutKeyDown = (e: KeyboardEvent) => {
+    if (!this.bindShortcuts || e.defaultPrevented) return;
+    if (isEditableTarget(e)) return;
+
+    for (const { menu } of this.menus) {
+      for (const item of this.getFocusableItems(menu)) {
+        const shortcut = item.getAttribute("data-shortcut");
+        if (!shortcut) continue;
+        if ((item as HTMLButtonElement).disabled) continue;
+        if (matchesShortcut(e, shortcut)) {
+          e.preventDefault();
+          this.handleItemClick(item as HTMLElement);
+          return;
+        }
+      }
+    }
+  };
+
   private handleOutsideClick = (e: MouseEvent) => {
     // composedPath (NOT e.target): a document-level listener sees e.target
     // retargeted to the shadow host when the menubar lives inside a shadow root
@@ -249,13 +284,28 @@ export class RelMenubar extends LitElement {
   private closeAllMenus() {
     this.openMenuIndex = -1;
     this.openSubmenuElement = null;
+    this.focusedItemIndex = -1;
+    this.focusedSubItemIndex = -1;
     this.hoverSwitchEnabled = false;
     this.requestUpdate();
   }
 
+  /** Close everything and put DOM focus back on the trigger that owned the
+   *  open menu. (Capturing the index BEFORE closing — closeAllMenus resets
+   *  openMenuIndex to -1, which used to drop focus to <body>.) */
+  private closeAllMenusAndRefocusTrigger() {
+    const idx = this.openMenuIndex;
+    this.closeAllMenus();
+    if (idx !== -1) {
+      this.focusedTriggerIndex = idx;
+      this.focusTrigger(idx);
+    }
+  }
+
   private openMenu(index: number, triggerElement: HTMLElement) {
     this.openMenuIndex = index;
     this.focusedItemIndex = -1;
+    this.focusedSubItemIndex = -1;
     this.openSubmenuElement = null;
     this.requestUpdate();
 
@@ -303,27 +353,20 @@ export class RelMenubar extends LitElement {
       event.preventDefault();
       this.focusedTriggerIndex = Math.max(0, this.focusedTriggerIndex - 1);
       this.focusTrigger(this.focusedTriggerIndex);
-    } else if (key === "Enter" || key === " ") {
+    } else if (key === "Enter" || key === " " || key === "ArrowDown") {
       event.preventDefault();
       const trigger = this.querySelector(
         `.menubar-trigger[data-index="${this.focusedTriggerIndex}"]`
       ) as HTMLElement;
       if (trigger) {
-        this.openMenu(this.focusedTriggerIndex, trigger);
-        this.updateComplete.then(() => {
-          const focusTarget = this.querySelector<HTMLElement>(
-            "[autofocus], [role='menuitem']"
-          );
-          if (focusTarget) {
-            focusTarget.focus();
-          } else {
-            this.focusMenuItem(0);
-          }
-        });
+        if (this.openMenuIndex !== this.focusedTriggerIndex) {
+          this.openMenu(this.focusedTriggerIndex, trigger);
+        }
+        this.updateComplete.then(() => this.focusMenuItem(0));
       }
-    } else if (key === "ArrowDown" && this.openMenuIndex !== -1) {
+    } else if (key === "Escape" && this.openMenuIndex !== -1) {
       event.preventDefault();
-      this.focusMenuItem(0);
+      this.closeAllMenusAndRefocusTrigger();
     }
   }
 
@@ -339,6 +382,40 @@ export class RelMenubar extends LitElement {
     const menuContent = this.menus[this.openMenuIndex]?.menu;
     if (!menuContent) return;
 
+    // ── Virtual focus is inside an open submenu ──
+    if (this.openSubmenuElement) {
+      const subItems = this.getSubmenuItems(this.openSubmenuElement);
+      if (key === "ArrowDown") {
+        event.preventDefault();
+        this.focusedSubItemIndex = Math.min(
+          subItems.length - 1,
+          this.focusedSubItemIndex + 1
+        );
+      } else if (key === "ArrowUp") {
+        event.preventDefault();
+        this.focusedSubItemIndex = Math.max(0, this.focusedSubItemIndex - 1);
+      } else if (key === "Home") {
+        event.preventDefault();
+        this.focusedSubItemIndex = 0;
+      } else if (key === "End") {
+        event.preventDefault();
+        this.focusedSubItemIndex = subItems.length - 1;
+      } else if (key === "ArrowLeft" || key === "Escape") {
+        // Close only the submenu; keep the parent panel open and focused.
+        event.preventDefault();
+        event.stopPropagation();
+        this.openSubmenuElement = null;
+        this.focusedSubItemIndex = -1;
+      } else if (key === "Enter" || key === " ") {
+        event.preventDefault();
+        const subItem = subItems[this.focusedSubItemIndex];
+        if (subItem) this.handleSubmenuItemClick(subItem as HTMLElement);
+      }
+      this.requestUpdate();
+      return;
+    }
+
+    // ── Virtual focus is in the panel's main list ──
     const items = this.getFocusableItems(menuContent);
 
     if (key === "ArrowDown") {
@@ -349,31 +426,60 @@ export class RelMenubar extends LitElement {
       event.preventDefault();
       this.focusedItemIndex = Math.max(0, this.focusedItemIndex - 1);
       this.requestUpdate();
+    } else if (key === "Home") {
+      event.preventDefault();
+      this.focusedItemIndex = 0;
+      this.requestUpdate();
+    } else if (key === "End") {
+      event.preventDefault();
+      this.focusedItemIndex = items.length - 1;
+      this.requestUpdate();
     } else if (key === "ArrowRight") {
       event.preventDefault();
       const currentItem = items[this.focusedItemIndex];
       if (currentItem?.hasAttribute("data-submenu")) {
-        this.openSubmenu(currentItem as HTMLElement);
+        // Position against the RENDERED row, not the display:none source
+        // element inside <rel-menubar-menu> (whose rect is 0×0).
+        const panel = this.querySelector<HTMLElement>(
+          `.menubar-panel[data-menu-index="${this.openMenuIndex}"]`
+        );
+        const renderedTrigger = panel?.querySelector<HTMLElement>(
+          `[data-focus-index="${this.focusedItemIndex}"]`
+        );
+        this.focusedSubItemIndex = 0;
+        this.openSubmenu(currentItem as HTMLElement, renderedTrigger ?? undefined);
       }
     } else if (key === "ArrowLeft") {
       event.preventDefault();
-      if (this.openSubmenuElement) {
-        this.openSubmenuElement = null;
-        this.requestUpdate();
-      }
     } else if (key === "Escape") {
       event.preventDefault();
-      this.closeAllMenus();
-      this.focusTrigger(this.openMenuIndex);
+      this.closeAllMenusAndRefocusTrigger();
     } else if (key === "Enter" || key === " ") {
       event.preventDefault();
       const currentItem = items[this.focusedItemIndex];
       if (currentItem) {
-        this.handleItemClick(currentItem as HTMLElement);
+        if (currentItem.hasAttribute("data-submenu")) {
+          const panel = this.querySelector<HTMLElement>(
+            `.menubar-panel[data-menu-index="${this.openMenuIndex}"]`
+          );
+          const renderedTrigger = panel?.querySelector<HTMLElement>(
+            `[data-focus-index="${this.focusedItemIndex}"]`
+          );
+          this.focusedSubItemIndex = 0;
+          this.openSubmenu(currentItem as HTMLElement, renderedTrigger ?? undefined);
+        } else {
+          this.handleItemClick(currentItem as HTMLElement);
+        }
       }
     }
   }
 
+  private getSubmenuItems(submenuElement: HTMLElement): Element[] {
+    return Array.from(submenuElement.children).filter((el) =>
+      el.hasAttribute("data-item")
+    );
+  }
+
   private getFocusableItems(menuContent: RelMenubarMenu): Element[] {
     return Array.from(menuContent.children).filter(
       (el) =>
@@ -425,32 +531,51 @@ export class RelMenubar extends LitElement {
     } else if (item.hasAttribute("data-submenu")) {
       this.openSubmenu(item);
     } else {
-      // Regular item click
-      this.closeAllMenus();
+      // Regular item: notify (clicks, Enter, and bound shortcuts all land
+      // here — without this event none of them were observable) and close.
+      this.dispatchSelectEvent(item);
+      this.closeAllMenusAndRefocusTrigger();
     }
   }
 
-  private openSubmenu(submenuTrigger: HTMLElement, renderedTrigger?: HTMLElement, submenuIndex?: number) {
+  private dispatchSelectEvent(item: HTMLElement) {
+    this.dispatchEvent(
+      new CustomEvent("rel-menubar-select", {
+        detail: {
+          label: item.textContent?.trim() ?? "",
+          value: item.getAttribute("value") ?? undefined,
+          shortcut: item.getAttribute("data-shortcut") ?? undefined,
+        },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  private openSubmenu(submenuTrigger: HTMLElement, renderedTrigger?: HTMLElement) {
     this.openSubmenuElement = submenuTrigger;
     this.requestUpdate();
 
     this.updateComplete.then(() => {
-      const submenuId = `submenu-${submenuIndex ?? 0}`;
-      const submenuPanel = this.querySelector(
-        `.submenu-panel[data-submenu-id="${submenuId}"]`
-      ) as HTMLElement;
+      // Only one submenu is ever open; its rendered trigger row is its
+      // previous sibling in the panel template.
+      const submenuPanel = this.querySelector(".submenu-panel.open") as HTMLElement;
       if (submenuPanel) {
-        const positionTarget = renderedTrigger ?? submenuTrigger;
-        const rect = positionTarget.getBoundingClientRect();
-        submenuPanel.style.top = `${rect.top}px`;
-        submenuPanel.style.left = `${rect.right + 4}px`;
+        const positionTarget =
+          renderedTrigger ?? (submenuPanel.previousElementSibling as HTMLElement);
+        const rect = positionTarget?.getBoundingClientRect();
+        if (rect) {
+          submenuPanel.style.top = `${rect.top}px`;
+          submenuPanel.style.left = `${rect.right + 4}px`;
+        }
       }
     });
   }
 
-  private handleSubmenuItemClick(_item: HTMLElement) {
-    // Regular item - just close
-    this.closeAllMenus();
+  private handleSubmenuItemClick(item: HTMLElement) {
+    // Regular item - notify, close, and hand focus back to the trigger
+    this.dispatchSelectEvent(item);
+    this.closeAllMenusAndRefocusTrigger();
   }
 
   private dispatchChangeEvent(type: "checkbox" | "radio", labelOrName: string, value: string | boolean) {
@@ -467,8 +592,13 @@ export class RelMenubar extends LitElement {
     );
   }
 
-  private renderMenuItem(item: Element, index: number): any {
-    const isFocused = index === this.focusedItemIndex;
+  private renderMenuItem(item: Element, focusIndex: number, menuIndex: number): any {
+    // focusIndex is the index within getFocusableItems() — the same list the
+    // keyboard handler walks. Comparing raw child indexes against
+    // focusedItemIndex highlighted the wrong row once separators existed.
+    const isFocused = focusIndex >= 0 && focusIndex === this.focusedItemIndex;
+    const itemId =
+      focusIndex >= 0 ? `${this.menubarId}-m${menuIndex}-i${focusIndex}` : nothing;
 
     if (item.hasAttribute("data-item")) {
       const button = item as HTMLButtonElement;
@@ -477,8 +607,12 @@ export class RelMenubar extends LitElement {
 
       return html`
         <div
+          id="${itemId}"
           class="menu-item ${isFocused ? "focused" : ""}"
+          role="menuitem"
+          data-focus-index="${focusIndex}"
           data-disabled="${disabled}"
+          aria-disabled="${disabled ? "true" : nothing}"
           @click="${() => !disabled && this.handleItemClick(item as HTMLElement)}"
         >
           <span>${button.textContent}</span>
@@ -488,7 +622,7 @@ export class RelMenubar extends LitElement {
     }
 
     if (item.hasAttribute("data-separator")) {
-      return html`<div class="menu-separator"></div>`;
+      return html`<div class="menu-separator" role="separator"></div>`;
     }
 
     if (item.hasAttribute("data-checkbox")) {
@@ -502,6 +636,8 @@ export class RelMenubar extends LitElement {
 
       return html`
         <rel-checkbox
+          id="${itemId}"
+          data-focus-index="${focusIndex}"
           label=${labelText}
           .status=${checkbox?.checked ? "checked" : "unchecked"}
           @rel-change=${(e: CustomEvent) => {
@@ -514,18 +650,22 @@ export class RelMenubar extends LitElement {
 
     if (item.hasAttribute("data-submenu")) {
       const label = item.getAttribute("label") || item.textContent?.trim() || "";
-      const submenuId = `submenu-${index}`;
 
       return html`
         <div
+          id="${itemId}"
           class="menu-item menu-submenu-trigger ${isFocused ? "focused" : ""}"
-          @click="${(e: Event) => this.openSubmenu(item as HTMLElement, e.currentTarget as HTMLElement, index)}"
-          @mouseenter="${(e: Event) => this.openSubmenu(item as HTMLElement, e.currentTarget as HTMLElement, index)}"
+          role="menuitem"
+          data-focus-index="${focusIndex}"
+          aria-haspopup="menu"
+          aria-expanded="${this.openSubmenuElement === item}"
+          @click="${(e: Event) => this.openSubmenu(item as HTMLElement, e.currentTarget as HTMLElement)}"
+          @mouseenter="${(e: Event) => this.openSubmenu(item as HTMLElement, e.currentTarget as HTMLElement)}"
         >
           <span>${label}</span>
           <rel-icon name="chevron-right"></rel-icon>
         </div>
-        ${this.renderSubmenu(item as HTMLElement, submenuId)}
+        ${this.renderSubmenu(item as HTMLElement)}
       `;
     }
 
@@ -555,25 +695,24 @@ export class RelMenubar extends LitElement {
     return null;
   }
 
-  private renderSubmenu(submenuElement: HTMLElement, submenuId: string) {
+  private renderSubmenu(submenuElement: HTMLElement) {
     const isOpen = this.openSubmenuElement === submenuElement;
-    const submenuItems = Array.from(submenuElement.children);
+    const submenuItems = this.getSubmenuItems(submenuElement);
 
     return html`
-      <div class="submenu-panel ${isOpen ? "open" : ""}" data-submenu-id="${submenuId}">
-        ${submenuItems.map((subItem) => {
-          if (subItem.hasAttribute("data-item")) {
-            const button = subItem as HTMLButtonElement;
-            return html`
-              <div
-                class="menu-item"
-                @click="${() => this.handleSubmenuItemClick(subItem as HTMLElement)}"
-              >
-                <span>${button.textContent}</span>
-              </div>
-            `;
-          }
-          return null;
+      <div class="submenu-panel ${isOpen ? "open" : ""}" role="menu">
+        ${submenuItems.map((subItem, subIdx) => {
+          const button = subItem as HTMLButtonElement;
+          return html`
+            <div
+              id="${isOpen ? `${this.menubarId}-sub-${subIdx}` : nothing}"
+              class="menu-item ${isOpen && subIdx === this.focusedSubItemIndex ? "focused" : ""}"
+              role="menuitem"
+              @click="${() => this.handleSubmenuItemClick(subItem as HTMLElement)}"
+            >
+              <span>${button.textContent}</span>
+            </div>
+          `;
         })}
       </div>
     `;
@@ -582,15 +721,30 @@ export class RelMenubar extends LitElement {
   private renderMenuPanel(menuState: MenuState, index: number) {
     const isOpen = index === this.openMenuIndex;
     const items = Array.from(menuState.menu.children);
+    const focusables = this.getFocusableItems(menuState.menu);
+
+    // DOM focus stays on the panel; this tells AT which row virtual focus is
+    // on as the user arrows around (panel list or open submenu).
+    const activeDescendant = !isOpen
+      ? nothing
+      : this.focusedSubItemIndex >= 0
+      ? `${this.menubarId}-sub-${this.focusedSubItemIndex}`
+      : this.focusedItemIndex >= 0
+      ? `${this.menubarId}-m${index}-i${this.focusedItemIndex}`
+      : nothing;
 
     return html`
       <div
         class="menubar-panel ${isOpen ? "open" : ""}"
         data-menu-index="${index}"
         tabindex="-1"
+        role="menu"
+        aria-activedescendant="${activeDescendant}"
         @keydown="${this.handlePanelKeyDown}"
       >
-        ${items.map((item, idx) => this.renderMenuItem(item, idx))}
+        ${items.map((item) =>
+          this.renderMenuItem(item, focusables.indexOf(item), index)
+        )}
       </div>
     `;
   }
@@ -598,14 +752,18 @@ export class RelMenubar extends LitElement {
   render() {
     return html`
       <style>${RelMenubar._css}</style>
-      <div class="menubar-container">
+      <div class="menubar-container" role="menubar">
         ${this.menus.map(
           (menuState, index) => html`
             <button
               class="menubar-trigger ${index === this.openMenuIndex ? "active" : ""}"
               data-index="${index}"
+              role="menuitem"
+              aria-haspopup="menu"
+              aria-expanded="${index === this.openMenuIndex}"
               @click="${(e: Event) => this.handleTriggerClick(index, e)}"
               @mouseenter="${(e: Event) => this.handleTriggerMouseEnter(index, e)}"
+              @focus="${() => { this.focusedTriggerIndex = index; }}"
               @keydown="${this.handleTriggerKeyDown}"
             >
               ${menuState.menu.label}

package/dist/components/rel-nav-menu/rel-nav-menu.ts

@@ -7,7 +7,7 @@ type DensityType = "comfortable" | "compact";
 /**
  * @deprecated rel-nav-menu has no Figma design in RelDS 2.0 and is excluded
  * from the parity contract. Use rel-menu (with the select-option/fixed/fit
- * types) or the App Topbar recipe instead. It remains exported for
+ * types) or the Navbar recipe instead. It remains exported for
  * compatibility but will be removed in a future major version.
  */
 @customElement("rel-nav-menu")
@@ -168,6 +168,32 @@ export class RelNavMenu extends LitElement {
 
     const { key } = event;
     const focusableItems = this.items.filter((item) => !item.disabled);
+    const path = event.composedPath();
+    const currentItem = focusableItems.find((item) => path.includes(item));
+    const inPanel = path.some(
+      (el) => el instanceof HTMLElement && el.classList.contains("panel")
+    );
+
+    // Sync the index to where focus ACTUALLY is — Tab moves focus without
+    // going through the arrow handlers, so focusedIndex went stale and
+    // Enter/arrows acted on the wrong item.
+    if (currentItem && !inPanel) {
+      this.focusedIndex = focusableItems.indexOf(currentItem);
+    }
+
+    // Keys originating from inside an open panel: let its links/buttons
+    // behave natively; only Escape is ours (close + refocus the trigger).
+    if (inPanel) {
+      if (key === "Escape" && this.open) {
+        event.preventDefault();
+        const openItemId = this.open;
+        this.closePanel();
+        const openItem = this.items.find((i) => i.itemId === openItemId);
+        const trigger = openItem?.shadowRoot?.querySelector(".trigger") as HTMLElement;
+        trigger?.focus();
+      }
+      return;
+    }
 
     if (key === "ArrowRight") {
       event.preventDefault();
@@ -177,10 +203,20 @@ export class RelNavMenu extends LitElement {
       event.preventDefault();
       this.focusedIndex = Math.max(0, this.focusedIndex - 1);
       this.focusItem(this.focusedIndex);
-    } else if (key === "Enter" || key === " ") {
+    } else if (key === "Home") {
       event.preventDefault();
-      const item = focusableItems[this.focusedIndex];
+      this.focusedIndex = 0;
+      this.focusItem(this.focusedIndex);
+    } else if (key === "End") {
+      event.preventDefault();
+      this.focusedIndex = focusableItems.length - 1;
+      this.focusItem(this.focusedIndex);
+    } else if (key === "Enter" || key === " ") {
+      const item = currentItem ?? focusableItems[this.focusedIndex];
       if (item && item.hasContent) {
+        // Only intercept panel triggers — plain link items keep their
+        // native Enter activation (preventDefault used to suppress it).
+        event.preventDefault();
         this.openPanel(item.itemId);
       }
     } else if (key === "Escape") {

package/dist/components/rel-otp/rel-otp.ts

@@ -58,7 +58,7 @@ export class RelOtp extends LitElement {
       display: flex;
       align-items: center;
       justify-content: center;
-      color: var(--rel-border-default);
+      color: var(--rel-border-default);
       user-select: none;
       padding: 0 var(--rel-spacing-3xs);
       font-family: var(--rel-action-xl-font-family);
@@ -77,7 +77,7 @@ export class RelOtp extends LitElement {
       height: 48px;
       border: var(--rel-stroke-sm) solid var(--rel-border-default);
       border-radius: var(--rel-border-radius-sm);
-      background: var(--rel-bg-neutral);
+      background: var(--rel-bg-neutral);
       text-align: center;
       color: var(--rel-text-default);
       outline: none;
@@ -471,7 +471,7 @@ export class RelOtp extends LitElement {
                     data-index="${index}"
                     type="${this.mask ? "password" : "text"}"
                     inputmode="${this.getInputMode()}"
-                    autocomplete="new-password"
+                    autocomplete="one-time-code"
                     pattern="${this.pattern || ""}"
                     placeholder="${this.placeholder}"
                     maxlength="1"

package/dist/components/rel-popover/rel-popover.ts

@@ -1,5 +1,6 @@
 import { LitElement, html, css } from "lit";
 import { customElement, property, state, query } from "lit/decorators.js";
+import { getDeepActiveElement, getFocusableElements } from "../../utils/focus.js";
 
 type SideType = "top" | "right" | "bottom" | "left";
 type AlignType = "start" | "center" | "end";
@@ -86,13 +87,15 @@ export class RelPopover extends LitElement {
     super.connectedCallback();
     this.internalOpen = this.isControlled() ? !!this.open : this.defaultOpen;
 
-    // ONE interaction entry point — capture phase
+    // ONE interaction entry point per input method — capture phase
     this.addEventListener("pointerdown", this.onHostPointerDown, true);
+    this.addEventListener("keydown", this.onHostKeyDown, true);
   }
 
   disconnectedCallback() {
     super.disconnectedCallback();
     this.removeEventListener("pointerdown", this.onHostPointerDown, true);
+    this.removeEventListener("keydown", this.onHostKeyDown, true);
     this.removeGlobalListeners();
     this.hideNativePopover();
   }
@@ -159,13 +162,25 @@ export class RelPopover extends LitElement {
     this.setOpen(!this.activeOpen);
   };
 
+  private onHostKeyDown = (e: KeyboardEvent) => {
+    if (this.disabled) return;
+    if (e.key !== "Enter" && e.key !== " ") return;
+    if (!this.triggerEl || !e.composedPath().includes(this.triggerEl)) return;
+
+    // Keyboard twin of onHostPointerDown. preventDefault also suppresses the
+    // native synthetic click of a <button> trigger, which would toggle twice.
+    e.preventDefault();
+    e.stopPropagation();
+
+    this.setOpen(!this.activeOpen);
+  };
+
   /* =======================
    * OPEN / CLOSE
    * ======================= */
 
   private onOpen() {
-    this.returnFocusEl =
-      (document.activeElement as HTMLElement) ?? this.triggerEl;
+    this.returnFocusEl = getDeepActiveElement() ?? this.triggerEl;
 
     this.addGlobalListeners();
     this.showNativePopover();
@@ -386,6 +401,19 @@ export class RelPopover extends LitElement {
     this.triggerEl.setAttribute("aria-haspopup", "dialog");
     this.triggerEl.setAttribute("aria-expanded", String(this.activeOpen));
     this.triggerEl.setAttribute("aria-controls", this.uniqueId);
+
+    // A bare <div>/<span> trigger must be Tab-reachable. Skip anything that
+    // is (or contains) natively focusable so buttons don't get a second stop.
+    if (
+      this.triggerEl.tabIndex < 0 &&
+      !this.triggerEl.hasAttribute("tabindex") &&
+      getFocusableElements(this.triggerEl).length === 0
+    ) {
+      this.triggerEl.setAttribute("tabindex", "0");
+      if (!this.triggerEl.hasAttribute("role")) {
+        this.triggerEl.setAttribute("role", "button");
+      }
+    }
   }
 
   /* =======================