@vaadin/popover 25.2.0-alpha8 → 25.2.0-alpha9

package/custom-elements.json

@@ -17,6 +17,42 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/vaadin-popover-focus-controller.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Controller that routes Tab and Shift+Tab when a non-modal popover is opened.\nThe controller's host element is the popover itself.\n\nThe popover is reachable via Tab only from its target, and its content comes\nlogically right after the target — regardless of the popover's DOM position.\nWhen the popover lives inside a focus trap (e.g. a dialog), the controller\ncooperates with the active `FocusTrapController` so the trap never lands\nfocus on the popover itself.\n\nModal popovers rely on the overlay's own focus trap; this controller bails\nout early in that case.",
+          "name": "PopoverFocusController",
+          "members": [
+            {
+              "kind": "method",
+              "name": "activate"
+            },
+            {
+              "kind": "method",
+              "name": "deactivate"
+            },
+            {
+              "kind": "field",
+              "name": "host",
+              "default": "host"
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "PopoverFocusController",
+          "declaration": {
+            "name": "PopoverFocusController",
+            "module": "src/vaadin-popover-focus-controller.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/vaadin-popover-overlay-mixin.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/popover",
-  "version": "25.2.0-alpha8",
+  "version": "25.2.0-alpha9",
   "publishConfig": {
     "access": "public"
   },
@@ -37,19 +37,19 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "25.2.0-alpha8",
-    "@vaadin/component-base": "25.2.0-alpha8",
-    "@vaadin/lit-renderer": "25.2.0-alpha8",
-    "@vaadin/overlay": "25.2.0-alpha8",
-    "@vaadin/vaadin-themable-mixin": "25.2.0-alpha8",
+    "@vaadin/a11y-base": "25.2.0-alpha9",
+    "@vaadin/component-base": "25.2.0-alpha9",
+    "@vaadin/lit-renderer": "25.2.0-alpha9",
+    "@vaadin/overlay": "25.2.0-alpha9",
+    "@vaadin/vaadin-themable-mixin": "25.2.0-alpha9",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.2.0-alpha8",
-    "@vaadin/chai-plugins": "25.2.0-alpha8",
-    "@vaadin/test-runner-commands": "25.2.0-alpha8",
+    "@vaadin/aura": "25.2.0-alpha9",
+    "@vaadin/chai-plugins": "25.2.0-alpha9",
+    "@vaadin/test-runner-commands": "25.2.0-alpha9",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.2.0-alpha8",
+    "@vaadin/vaadin-lumo-styles": "25.2.0-alpha9",
     "sinon": "^21.0.2"
   },
   "customElements": "custom-elements.json",
@@ -57,5 +57,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "2b82e20cdfc605b1187e9a24ae42869e1500ab68"
+  "gitHead": "a38a03e8a8be45821f39c14054c63634dafe08d0"
 }

package/src/vaadin-popover-focus-controller.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright (c) 2024 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Popover } from './vaadin-popover.js';
+
+/**
+ * Controller that routes Tab and Shift+Tab when a non-modal popover is opened.
+ * The controller's host element is the popover itself.
+ *
+ * The popover is reachable via Tab only from its target, and its content comes
+ * logically right after the target — regardless of the popover's DOM position.
+ * When the popover lives inside a focus trap (e.g. a dialog), the controller
+ * cooperates with the active `FocusTrapController` so the trap never lands
+ * focus on the popover itself.
+ *
+ * Modal popovers rely on the overlay's own focus trap; this controller bails
+ * out early in that case.
+ */
+export class PopoverFocusController {
+  host: Popover;
+
+  constructor(host: Popover);
+
+  /**
+   * Starts listening for Tab keystrokes. Called when the popover opens.
+   */
+  activate(): void;
+
+  /**
+   * Stops listening for Tab keystrokes. Called when the popover closes.
+   */
+  deactivate(): void;
+}

package/src/vaadin-popover-focus-controller.js

@@ -0,0 +1,226 @@
+/**
+ * @license
+ * Copyright (c) 2024 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { getActiveTrappingNode } from '@vaadin/a11y-base/src/focus-trap-controller.js';
+import { getDeepActiveElement, getFocusableElements, isElementFocused } from '@vaadin/a11y-base/src/focus-utils.js';
+
+/**
+ * Controller that routes Tab and Shift+Tab when a non-modal popover is opened.
+ * The controller's host element is the popover itself.
+ *
+ * The popover is reachable via Tab only from its target, and its content comes
+ * logically right after the target — regardless of the popover's DOM position.
+ * When the popover lives inside a focus trap (e.g. a dialog), the controller
+ * cooperates with the active `FocusTrapController` so the trap never lands
+ * focus on the popover itself.
+ *
+ * Modal popovers rely on the overlay's own focus trap; this controller bails
+ * out early in that case.
+ */
+export class PopoverFocusController {
+  constructor(host) {
+    this.host = host;
+    this.__onKeyDown = this.__onKeyDown.bind(this);
+  }
+
+  activate() {
+    document.addEventListener('keydown', this.__onKeyDown, true);
+  }
+
+  deactivate() {
+    document.removeEventListener('keydown', this.__onKeyDown, true);
+  }
+
+  /** @private */
+  __handleTab(event) {
+    const host = this.host;
+    const targetFocusable = this.__getTargetFocusable();
+
+    if (targetFocusable && isElementFocused(targetFocusable)) {
+      event.preventDefault();
+      host.focus();
+      return;
+    }
+
+    const lastPopoverFocusable = this.__getLastPopoverFocusable();
+    if (isElementFocused(lastPopoverFocusable)) {
+      this.__moveLogicalNext(event, host);
+      return;
+    }
+
+    // Native Tab would land on the popover when DOM order places it right
+    // after the current element. Skip past it via the logical list.
+    const activeElement = getDeepActiveElement();
+    const scopeFocusables = this.__getScopeFocusables();
+    const activeIdx = scopeFocusables.indexOf(activeElement);
+    if (activeIdx >= 0 && scopeFocusables[activeIdx + 1] === host) {
+      this.__moveLogicalNext(event, activeElement, scopeFocusables);
+    }
+  }
+
+  /** @private */
+  __handleShiftTab(event) {
+    const host = this.host;
+    const targetFocusable = this.__getTargetFocusable();
+
+    // Just clear the flag so native Shift+Tab from the target doesn't reopen.
+    if (targetFocusable && isElementFocused(targetFocusable) && host.__shouldRestoreFocus) {
+      host.__shouldRestoreFocus = false;
+      return;
+    }
+
+    if (isElementFocused(host)) {
+      event.preventDefault();
+      targetFocusable.focus();
+      return;
+    }
+
+    // Browser handles Shift+Tab inside popover content.
+    const activeElement = getDeepActiveElement();
+    if (host.contains(activeElement)) {
+      return;
+    }
+
+    const scopeFocusables = this.__getScopeFocusables();
+    const logicalFocusables = this.__buildLogicalList(scopeFocusables);
+    const activeLogicalIdx = logicalFocusables.indexOf(activeElement);
+    const prevFocusable = activeLogicalIdx > 0 ? logicalFocusables[activeLogicalIdx - 1] : null;
+
+    // When the logical previous is the popover, move focus into the popover tail.
+    if (prevFocusable === host) {
+      event.preventDefault();
+      this.__getLastPopoverFocusable().focus();
+      return;
+    }
+
+    // Native Shift+Tab would land on the popover: skip it and redirect to the
+    // true logical previous, or wrap when at the logical start inside a trap.
+    const activeScopeIdx = scopeFocusables.indexOf(activeElement);
+    if (activeScopeIdx > 0 && scopeFocusables[activeScopeIdx - 1] === host) {
+      if (prevFocusable) {
+        event.preventDefault();
+        prevFocusable.focus();
+      } else if (getActiveTrappingNode(host)) {
+        this.__wrapToLogicalLast(event, logicalFocusables);
+      }
+      return;
+    }
+
+    // At the logical start of a trap: wrap to the logical last. When the
+    // popover is the logical last (target is last), this lands on the popover tail.
+    if (!prevFocusable && getActiveTrappingNode(host)) {
+      this.__wrapToLogicalLast(event, logicalFocusables);
+    }
+  }
+
+  /** @private */
+  __onKeyDown(event) {
+    // Modal popovers rely on the overlay's focus trap.
+    if (this.host.modal) {
+      return;
+    }
+    if (event.key !== 'Tab') {
+      return;
+    }
+    if (event.shiftKey) {
+      this.__handleShiftTab(event);
+    } else {
+      this.__handleTab(event);
+    }
+  }
+
+  /** @private */
+  __getTargetFocusable() {
+    const target = this.host.target;
+    if (!target) {
+      return null;
+    }
+    return target.focusElement || target;
+  }
+
+  /**
+   * The popover's tail element: the last focusable inside the popover's content
+   * area, or the popover itself when it has no focusable content.
+   * @private
+   */
+  __getLastPopoverFocusable() {
+    const lastContent = getFocusableElements(this.host._overlayElement.$.content).pop();
+    return lastContent || this.host;
+  }
+
+  /**
+   * DOM-ordered focusables in the current scope (active focus trap, or document
+   * body), with popover light-DOM descendants excluded but the popover itself
+   * retained. Used to detect DOM adjacency to the popover.
+   * @private
+   */
+  __getScopeFocusables() {
+    const host = this.host;
+    const scope = getActiveTrappingNode(host) || document.body;
+    return getFocusableElements(scope).filter((el) => el === host || !host.contains(el));
+  }
+
+  /**
+   * Scope focusables in *logical* tab order: the popover is moved from its DOM
+   * position to right after the target focusable. The popover is left out of
+   * the list entirely when there is no target.
+   * @private
+   */
+  __buildLogicalList(scopeFocusables = this.__getScopeFocusables()) {
+    const host = this.host;
+    const targetFocusable = this.__getTargetFocusable();
+    const logicalFocusables = scopeFocusables.filter((el) => el !== host);
+
+    if (targetFocusable && targetFocusable !== host) {
+      const targetIdx = logicalFocusables.indexOf(targetFocusable);
+      if (targetIdx >= 0) {
+        logicalFocusables.splice(targetIdx + 1, 0, host);
+      }
+    }
+    return logicalFocusables;
+  }
+
+  /** @private */
+  __moveLogicalNext(event, from, scopeFocusables) {
+    const host = this.host;
+    const logicalFocusables = this.__buildLogicalList(scopeFocusables);
+    const fromIdx = logicalFocusables.indexOf(from);
+    if (fromIdx < 0) {
+      return;
+    }
+
+    // The popover sits right after the target in the logical list, so it can
+    // be the logical next only when `from` is the target. Skip it: the popover
+    // is Tab-reachable only from its target (handled in __handleTab case 1).
+    let nextIdx = fromIdx + 1;
+    if (logicalFocusables[nextIdx] === host) {
+      nextIdx += 1;
+    }
+
+    // Past the end inside a trap: wrap to the first element. The popover
+    // never sits at position 0 (it only follows a target), so list[0] is real.
+    let focusable = logicalFocusables[nextIdx];
+    if (!focusable && getActiveTrappingNode(host)) {
+      focusable = logicalFocusables[0];
+    }
+
+    if (focusable) {
+      event.preventDefault();
+      focusable.focus();
+    }
+  }
+
+  /** @private */
+  __wrapToLogicalLast(event, logicalFocusables) {
+    const logicalLast = logicalFocusables.at(-1);
+    if (!logicalLast) {
+      return;
+    }
+    // When the popover is the logical last, land on the popover tail instead.
+    const focusable = logicalLast === this.host ? this.__getLastPopoverFocusable() : logicalLast;
+    event.preventDefault();
+    focusable.focus();
+  }
+}

package/src/vaadin-popover.js

@@ -6,13 +6,7 @@
 import './vaadin-popover-overlay.js';
 import { css, html, LitElement } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
-import { getActiveTrappingNode } from '@vaadin/a11y-base/src/focus-trap-controller.js';
-import {
-  getDeepActiveElement,
-  getFocusableElements,
-  isElementFocused,
-  isKeyboardActive,
-} from '@vaadin/a11y-base/src/focus-utils.js';
+import { isKeyboardActive } from '@vaadin/a11y-base/src/focus-utils.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
@@ -22,6 +16,7 @@ import {
   isLastOverlay as isLastOverlayBase,
 } from '@vaadin/overlay/src/vaadin-overlay-stack-mixin.js';
 import { ThemePropertyMixin } from '@vaadin/vaadin-themable-mixin/vaadin-theme-property-mixin.js';
+import { PopoverFocusController } from './vaadin-popover-focus-controller.js';
 import { PopoverPositionMixin } from './vaadin-popover-position-mixin.js';
 import { PopoverTargetMixin } from './vaadin-popover-target-mixin.js';
 
@@ -486,7 +481,6 @@ class Popover extends PopoverPositionMixin(
 
     this.__generatedId = `vaadin-popover-${generateUniqueId()}`;
 
-    this.__onGlobalKeyDown = this.__onGlobalKeyDown.bind(this);
     this.__onTargetClick = this.__onTargetClick.bind(this);
     this.__onTargetFocusIn = this.__onTargetFocusIn.bind(this);
     this.__onTargetFocusOut = this.__onTargetFocusOut.bind(this);
@@ -494,6 +488,7 @@ class Popover extends PopoverPositionMixin(
     this.__onTargetMouseLeave = this.__onTargetMouseLeave.bind(this);
 
     this._openedStateController = new PopoverOpenedStateController(this);
+    this._focusController = new PopoverFocusController(this);
   }
 
   /** @protected */
@@ -667,9 +662,9 @@ class Popover extends PopoverPositionMixin(
   /** @private */
   __openedChanged(opened, oldOpened) {
     if (opened) {
-      document.addEventListener('keydown', this.__onGlobalKeyDown, true);
+      this._focusController.activate();
     } else if (oldOpened) {
-      document.removeEventListener('keydown', this.__onGlobalKeyDown, true);
+      this._focusController.deactivate();
     }
   }
 
@@ -714,230 +709,6 @@ class Popover extends PopoverPositionMixin(
     }
   }
 
-  /**
-   * Overlay's global Escape press listener doesn't work when
-   * the overlay is modeless, so we use a separate listener.
-   * @private
-   */
-  __onGlobalKeyDown(event) {
-    // Modal popover uses overlay logic focus trap.
-    if (this.modal) {
-      return;
-    }
-
-    // Include popover content in the Tab order after the target.
-    if (event.key === 'Tab') {
-      if (event.shiftKey) {
-        this.__onGlobalShiftTab(event);
-      } else {
-        this.__onGlobalTab(event);
-      }
-    }
-  }
-
-  /** @private */
-  __onGlobalTab(event) {
-    // Move focus to the popover on target element Tab
-    if (this.target && isElementFocused(this.__getTargetFocusable())) {
-      event.preventDefault();
-      this.focus();
-      return;
-    }
-
-    // Cache filtered focusable list for this keystroke to avoid redundant DOM traversals
-    const focusables = this.__getScopeFocusables();
-
-    // Move focus to the next element after target on last content Tab,
-    // or when popover itself is focused and has no focusable content
-    const lastFocusable = this.__getLastFocusable();
-    const isFocusOut = lastFocusable ? isElementFocused(lastFocusable) : isElementFocused(this);
-    if (isFocusOut) {
-      let focusable = this.__getNextScopeFocusable(this.__getTargetFocusable(), focusables);
-      // If the next element after the target is the popover itself (DOM position
-      // differs from logical position), skip past it to the actual next element.
-      if (focusable === this) {
-        focusable = this.__getNextScopeFocusable(this, focusables);
-      }
-      if (focusable) {
-        event.preventDefault();
-        focusable.focus();
-        return;
-      }
-      // No next element after the target in the scope. When inside a focus trap,
-      // wrap explicitly to the first focusable. Don't fall through - the
-      // FocusTrapController uses DOM order which may differ from the popover's
-      // logical tab position.
-      if (getActiveTrappingNode(this) && focusables[0]) {
-        event.preventDefault();
-        focusables[0].focus();
-        return;
-      }
-    }
-
-    // Handle cases where Tab from the current element would land on the popover
-    const activeElement = getDeepActiveElement();
-    const nextFocusable = this.__getNextScopeFocusable(activeElement, focusables);
-    if (nextFocusable === this) {
-      // The popover should only be Tab-reachable from its target (handled above).
-      // Skip the popover when Tab from any other element would land on it
-      // due to its DOM position.
-      const focusableAfterPopover = this.__getNextScopeFocusable(this, focusables);
-      if (focusableAfterPopover) {
-        event.preventDefault();
-        focusableAfterPopover.focus();
-      } else if (getActiveTrappingNode(this) && focusables[0]) {
-        // Popover is last in DOM scope but shouldn't be Tab-reachable from
-        // non-target elements. Wrap to first focusable in focus trap.
-        event.preventDefault();
-        focusables[0].focus();
-      }
-    }
-  }
-
-  /** @private */
-  __onGlobalShiftTab(event) {
-    // Prevent restoring focus after target blur on Shift + Tab
-    if (this.target && isElementFocused(this.__getTargetFocusable()) && this.__shouldRestoreFocus) {
-      this.__shouldRestoreFocus = false;
-      return;
-    }
-
-    // Move focus back to the target on popover Shift + Tab
-    if (this.target && isElementFocused(this)) {
-      event.preventDefault();
-      this.__getTargetFocusable().focus();
-      return;
-    }
-
-    // Don't intercept if focus is inside the popover content.
-    // The browser's native Shift+Tab handles navigation within
-    // the overlay (e.g. between focusable content and the popover element itself).
-    const activeElement = getDeepActiveElement();
-    if (this.contains(activeElement)) {
-      return;
-    }
-
-    // Cache filtered focusable list for this keystroke to avoid redundant DOM traversals
-    const focusables = this.__getScopeFocusables();
-
-    // Get previous focusable element excluding the popover
-    const prevFocusable = this.__getPrevScopeFocusable(activeElement, focusables);
-    const targetFocusable = this.__getTargetFocusable();
-
-    // Intercept Shift+Tab when the previous focusable (excluding the popover)
-    // is the target. Instead of moving to the target, redirect focus into
-    // the popover's last focusable content (or the popover itself).
-    if (prevFocusable === targetFocusable) {
-      event.preventDefault();
-      this.__focusLastOrSelf();
-      return;
-    }
-
-    // Move focus into the popover when:
-    // 1. There is no previous focusable element in the focus trap (at the
-    //    beginning, would wrap around), and
-    // 2. The target is the last focusable in the focus trap (making the
-    //    popover logically last).
-    // Don't fall through - the FocusTrapController uses DOM order which
-    // may differ from the popover's logical tab position.
-    if (!prevFocusable && getActiveTrappingNode(this)) {
-      const list = focusables.filter((el) => el !== this);
-      if (list.at(-1) === targetFocusable) {
-        event.preventDefault();
-        this.__focusLastOrSelf();
-        return;
-      }
-      // Popover is last in DOM but target is not the last focusable.
-      // Wrap to last non-popover focusable to prevent FocusTrapController
-      // from landing on the popover.
-      const last = list.at(-1);
-      if (last) {
-        event.preventDefault();
-        last.focus();
-        return;
-      }
-    }
-
-    // Get previous focusable element including the popover (simulates native Tab order)
-    const prevFocusableNative = this.__getPrevScopeFocusable(activeElement, focusables, true);
-    // Skip the popover when native Shift+Tab would land on it
-    // and redirect to the actual previous element
-    if (prevFocusableNative === this) {
-      if (prevFocusable) {
-        event.preventDefault();
-        prevFocusable.focus();
-      } else if (getActiveTrappingNode(this)) {
-        // Popover is first in DOM scope but shouldn't be Shift+Tab-reachable
-        // from non-target elements. Wrap to last non-popover focusable.
-        const list = focusables.filter((el) => el !== this);
-        const last = list.at(-1);
-        if (last) {
-          event.preventDefault();
-          last.focus();
-        }
-      }
-    }
-  }
-
-  /**
-   * Returns whether the element is a light DOM child of this popover
-   * (i.e. slotted popover content, excluding the popover element itself).
-   * @param {Element} el
-   * @return {boolean}
-   * @private
-   */
-  __isPopoverContent(el) {
-    return el !== this && this.contains(el);
-  }
-
-  /**
-   * Returns focusable elements within the current scope (active focus trap or
-   * document body) with popover light DOM children filtered out.
-   * @return {Element[]}
-   * @private
-   */
-  __getScopeFocusables() {
-    const scope = getActiveTrappingNode(this) || document.body;
-    return getFocusableElements(scope).filter((el) => !this.__isPopoverContent(el));
-  }
-
-  /** @private */
-  __getNextScopeFocusable(target, focusables = this.__getScopeFocusables()) {
-    const idx = focusables.findIndex((el) => el === target);
-    return idx >= 0 ? focusables[idx + 1] : undefined;
-  }
-
-  /** @private */
-  __getPrevScopeFocusable(target, focusables = this.__getScopeFocusables(), includePopover = false) {
-    const list = includePopover ? focusables : focusables.filter((el) => el !== this);
-    const idx = list.findIndex((el) => el === target);
-    // Returns null both when target is the first element (idx === 0)
-    // and when target is not found in the list (idx === -1)
-    return idx > 0 ? list[idx - 1] : null;
-  }
-
-  /** @private */
-  __getLastFocusable() {
-    // Search within the overlay's content area to avoid returning the popover element itself
-    const focusables = getFocusableElements(this._overlayElement.$.content);
-    return focusables.pop();
-  }
-
-  /** @private */
-  __focusLastOrSelf() {
-    (this.__getLastFocusable() || this).focus();
-  }
-
-  /** @private */
-  __getTargetFocusable() {
-    if (!this.target) {
-      return null;
-    }
-
-    // If target has `focusElement`, check if that one is focused.
-    return this.target.focusElement || this.target;
-  }
-
   /** @private */
   __onTargetFocusIn() {
     this.__focusInside = true;

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/popover",
-  "version": "25.2.0-alpha8",
+  "version": "25.2.0-alpha9",
   "description-markup": "markdown",
   "contributions": {
     "html": {

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/popover",
-  "version": "25.2.0-alpha8",
+  "version": "25.2.0-alpha9",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {