@vaadin/popover 25.2.0-alpha1 → 25.2.0-alpha10

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",
@@ -776,6 +812,16 @@
               "description": "Set to true to disable closing popover on outside click.",
               "attribute": "no-close-on-outside-click"
             },
+            {
+              "kind": "field",
+              "name": "noTabFocus",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When true, pressing Tab on the target or a sibling element does not move\nfocus into the popover's content (including any nested popovers), and\nShift+Tab does not move focus into the popover's last focusable. Focus\nstill moves out of the popover on Tab / Shift+Tab if it was placed\ninside programmatically.\n\nHas no effect on modal popovers, which use their own focus trap.",
+              "attribute": "no-tab-focus"
+            },
             {
               "kind": "field",
               "name": "opened",
@@ -1036,6 +1082,14 @@
               "description": "Set to true to disable closing popover on outside click.",
               "fieldName": "noCloseOnOutsideClick"
             },
+            {
+              "name": "no-tab-focus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When true, pressing Tab on the target or a sibling element does not move\nfocus into the popover's content (including any nested popovers), and\nShift+Tab does not move focus into the popover's last focusable. Focus\nstill moves out of the popover on Tab / Shift+Tab if it was placed\ninside programmatically.\n\nHas no effect on modal popovers, which use their own focus trap.",
+              "fieldName": "noTabFocus"
+            },
             {
               "name": "opened",
               "type": {

package/package.json

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

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,242 @@
+/**
+ * @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();
+      if (host.noTabFocus) {
+        this.__moveLogicalNext(event, targetFocusable);
+      } else {
+        host.focus();
+      }
+      return;
+    }
+
+    const lastPopoverFocusable = this.__getLastPopoverFocusable();
+    if (isElementFocused(lastPopoverFocusable)) {
+      // With noTabFocus the popover isn't in the logical list, so the target
+      // becomes the reference for "next after the popover".
+      this.__moveLogicalNext(event, host.noTabFocus ? targetFocusable : 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();
+
+    // Clear the flag so native Shift+Tab from the target doesn't reopen. Fall
+    // through to the redirect logic: when the popover is DOM-prev of the target,
+    // case 5 steers focus away from it instead of letting the browser land on
+    // the popover host or its content.
+    if (targetFocusable && isElementFocused(targetFocusable) && host.__shouldRestoreFocus) {
+      host.__shouldRestoreFocus = false;
+    }
+
+    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);
+      } else if (host.noTabFocus) {
+        // No redirect target and no trap: still block native Shift+Tab so the
+        // popover host can never receive Shift+Tab focus.
+        event.preventDefault();
+      }
+      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, or when `noTabFocus` is set.
+   * @private
+   */
+  __buildLogicalList(scopeFocusables = this.__getScopeFocusables()) {
+    const host = this.host;
+    const targetFocusable = this.__getTargetFocusable();
+    const logicalFocusables = scopeFocusables.filter((el) => el !== host);
+
+    if (!host.noTabFocus && 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);
+
+    let focusable;
+    if (fromIdx >= 0) {
+      // 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.
+      focusable = logicalFocusables[nextIdx];
+      if (!focusable && getActiveTrappingNode(host)) {
+        focusable = logicalFocusables[0];
+      }
+    }
+
+    if (focusable) {
+      event.preventDefault();
+      focusable.focus();
+    } else if (host.noTabFocus) {
+      // No redirect target found: still block native Tab so the popover host
+      // can never receive Tab focus when it is DOM-adjacent.
+      event.preventDefault();
+    }
+  }
+
+  /** @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.d.ts

@@ -205,6 +205,19 @@ declare class Popover extends PopoverPositionMixin(PopoverTargetMixin(ThemePrope
    */
   noCloseOnEsc: boolean;
 
+  /**
+   * When true, pressing Tab on the target or a sibling element does not move
+   * focus into the popover's content (including any nested popovers), and
+   * Shift+Tab does not move focus into the popover's last focusable. Focus
+   * still moves out of the popover on Tab / Shift+Tab if it was placed
+   * inside programmatically.
+   *
+   * Has no effect on modal popovers, which use their own focus trap.
+   *
+   * @attr {boolean} no-tab-focus
+   */
+  noTabFocus: boolean;
+
   /**
    * Popover trigger mode, used to configure how the popover is opened or closed.
    * Could be set to multiple by providing an array, e.g. `trigger = ['hover', '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';
 
@@ -403,6 +398,22 @@ class Popover extends PopoverPositionMixin(
         value: false,
       },
 
+      /**
+       * When true, pressing Tab on the target or a sibling element does not move
+       * focus into the popover's content (including any nested popovers), and
+       * Shift+Tab does not move focus into the popover's last focusable. Focus
+       * still moves out of the popover on Tab / Shift+Tab if it was placed
+       * inside programmatically.
+       *
+       * Has no effect on modal popovers, which use their own focus trap.
+       *
+       * @attr {boolean} no-tab-focus
+       */
+      noTabFocus: {
+        type: Boolean,
+        value: false,
+      },
+
       /**
        * Popover trigger mode, used to configure how the popover is opened or closed.
        * Could be set to multiple by providing an array, e.g. `trigger = ['hover', 'focus']`.
@@ -486,7 +497,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 +504,7 @@ class Popover extends PopoverPositionMixin(
     this.__onTargetMouseLeave = this.__onTargetMouseLeave.bind(this);
 
     this._openedStateController = new PopoverOpenedStateController(this);
+    this._focusController = new PopoverFocusController(this);
   }
 
   /** @protected */
@@ -667,9 +678,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 +725,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;
@@ -1165,12 +952,6 @@ class Popover extends PopoverPositionMixin(
   __hasTrigger(trigger) {
     return Array.isArray(this.trigger) && this.trigger.includes(trigger);
   }
-
-  /**
-   * Fired when the popover is closed.
-   *
-   * @event closed
-   */
 }
 
 defineCustomElement(Popover);

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/popover",
-  "version": "25.2.0-alpha1",
+  "version": "25.2.0-alpha10",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -15,9 +15,7 @@
               "description": "String used to label the popover to screen reader users.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -26,9 +24,7 @@
               "description": "Id of the element used as label of the popover to screen reader users.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -37,9 +33,7 @@
               "description": "When true, the popover content automatically receives focus after\nit is opened. Modal popovers use this behavior by default.",
               "value": {
                 "type": [
-                  "boolean",
-                  "null",
-                  "undefined"
+                  "boolean"
                 ]
               }
             },
@@ -48,9 +42,7 @@
               "description": "The delay in milliseconds before the popover is opened\non focus when the corresponding trigger is used.\n\nWhen not specified, the global default (500ms) is used.",
               "value": {
                 "type": [
-                  "number",
-                  "null",
-                  "undefined"
+                  "number"
                 ]
               }
             },
@@ -59,9 +51,7 @@
               "description": "The id of the element to be used as `target` value.\nThe element should be in the DOM by the time when\nthe attribute is set, otherwise a warning is shown.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -70,9 +60,7 @@
               "description": "Set the height of the popover.\nIf a unitless number is provided, pixels are assumed.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -81,9 +69,7 @@
               "description": "The delay in milliseconds before the popover is closed\non losing hover, when the corresponding trigger is used.\nOn blur, the popover is closed immediately.\n\nWhen not specified, the global default (500ms) is used.",
               "value": {
                 "type": [
-                  "number",
-                  "null",
-                  "undefined"
+                  "number"
                 ]
               }
             },
@@ -92,9 +78,7 @@
               "description": "The delay in milliseconds before the popover is opened\non hover when the corresponding trigger is used.\n\nWhen not specified, the global default (500ms) is used.",
               "value": {
                 "type": [
-                  "number",
-                  "null",
-                  "undefined"
+                  "number"
                 ]
               }
             },
@@ -103,9 +87,7 @@
               "description": "When true, the popover prevents interacting with background elements\nby setting `pointer-events` style on the document body to `none`.\nThis also enables trapping focus inside the popover.",
               "value": {
                 "type": [
-                  "boolean",
-                  "null",
-                  "undefined"
+                  "boolean"
                 ]
               }
             },
@@ -114,9 +96,7 @@
               "description": "Set to true to disable closing popover on Escape press.",
               "value": {
                 "type": [
-                  "boolean",
-                  "null",
-                  "undefined"
+                  "boolean"
                 ]
               }
             },
@@ -125,9 +105,16 @@
               "description": "Set to true to disable closing popover on outside click.",
               "value": {
                 "type": [
-                  "boolean",
-                  "null",
-                  "undefined"
+                  "boolean"
+                ]
+              }
+            },
+            {
+              "name": "no-tab-focus",
+              "description": "When true, pressing Tab on the target or a sibling element does not move\nfocus into the popover's content (including any nested popovers), and\nShift+Tab does not move focus into the popover's last focusable. Focus\nstill moves out of the popover on Tab / Shift+Tab if it was placed\ninside programmatically.\n\nHas no effect on modal popovers, which use their own focus trap.",
+              "value": {
+                "type": [
+                  "boolean"
                 ]
               }
             },
@@ -136,9 +123,7 @@
               "description": "True if the popover is visible and available for interaction.",
               "value": {
                 "type": [
-                  "boolean",
-                  "null",
-                  "undefined"
+                  "boolean"
                 ]
               }
             },
@@ -147,9 +132,7 @@
               "description": "The `role` attribute value to be set on the popover.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -158,9 +141,7 @@
               "description": "Position of the overlay with respect to the target.\nSupported values: `top-start`, `top`, `top-end`,\n`bottom-start`, `bottom`, `bottom-end`, `start-top`,\n`start`, `start-bottom`, `end-top`, `end`, `end-bottom`.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -169,9 +150,7 @@
               "description": "The `role` attribute value to be set on the popover.\nWhen not specified, defaults to 'dialog'.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -191,9 +170,7 @@
               "description": "Set the width of the popover.\nIf a unitless number is provided, pixels are assumed.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -202,9 +179,7 @@
               "description": "When true, the popover has a backdrop (modality curtain) on top of the\nunderlying page content, covering the whole viewport.",
               "value": {
                 "type": [
-                  "boolean",
-                  "null",
-                  "undefined"
+                  "boolean"
                 ]
               }
             }
@@ -216,9 +191,7 @@
                 "description": "String used to label the popover to screen reader users.",
                 "value": {
                   "type": [
-                    "string",
-                    "null",
-                    "undefined"
+                    "string"
                   ]
                 }
               },
@@ -227,9 +200,7 @@
                 "description": "Id of the element used as label of the popover to screen reader users.",
                 "value": {
                   "type": [
-                    "string",
-                    "null",
-                    "undefined"
+                    "string"
                   ]
                 }
               },
@@ -238,9 +209,7 @@
                 "description": "When true, the popover content automatically receives focus after\nit is opened. Modal popovers use this behavior by default.",
                 "value": {
                   "type": [
-                    "boolean",
-                    "null",
-                    "undefined"
+                    "boolean"
                   ]
                 }
               },
@@ -249,9 +218,7 @@
                 "description": "The delay in milliseconds before the popover is opened\non focus when the corresponding trigger is used.\n\nWhen not specified, the global default (500ms) is used.",
                 "value": {
                   "type": [
-                    "number",
-                    "null",
-                    "undefined"
+                    "number"
                   ]
                 }
               },
@@ -260,9 +227,7 @@
                 "description": "The id of the element to be used as `target` value.\nThe element should be in the DOM by the time when\nthe attribute is set, otherwise a warning is shown.",
                 "value": {
                   "type": [
-                    "string",
-                    "null",
-                    "undefined"
+                    "string"
                   ]
                 }
               },
@@ -271,9 +236,7 @@
                 "description": "Set the height of the popover.\nIf a unitless number is provided, pixels are assumed.",
                 "value": {
                   "type": [
-                    "string",
-                    "null",
-                    "undefined"
+                    "string"
                   ]
                 }
               },
@@ -282,9 +245,7 @@
                 "description": "The delay in milliseconds before the popover is closed\non losing hover, when the corresponding trigger is used.\nOn blur, the popover is closed immediately.\n\nWhen not specified, the global default (500ms) is used.",
                 "value": {
                   "type": [
-                    "number",
-                    "null",
-                    "undefined"
+                    "number"
                   ]
                 }
               },
@@ -293,9 +254,7 @@
                 "description": "The delay in milliseconds before the popover is opened\non hover when the corresponding trigger is used.\n\nWhen not specified, the global default (500ms) is used.",
                 "value": {
                   "type": [
-                    "number",
-                    "null",
-                    "undefined"
+                    "number"
                   ]
                 }
               },
@@ -304,9 +263,7 @@
                 "description": "When true, the popover prevents interacting with background elements\nby setting `pointer-events` style on the document body to `none`.\nThis also enables trapping focus inside the popover.",
                 "value": {
                   "type": [
-                    "boolean",
-                    "null",
-                    "undefined"
+                    "boolean"
                   ]
                 }
               },
@@ -315,9 +272,7 @@
                 "description": "Set to true to disable closing popover on Escape press.",
                 "value": {
                   "type": [
-                    "boolean",
-                    "null",
-                    "undefined"
+                    "boolean"
                   ]
                 }
               },
@@ -326,9 +281,16 @@
                 "description": "Set to true to disable closing popover on outside click.",
                 "value": {
                   "type": [
-                    "boolean",
-                    "null",
-                    "undefined"
+                    "boolean"
+                  ]
+                }
+              },
+              {
+                "name": "noTabFocus",
+                "description": "When true, pressing Tab on the target or a sibling element does not move\nfocus into the popover's content (including any nested popovers), and\nShift+Tab does not move focus into the popover's last focusable. Focus\nstill moves out of the popover on Tab / Shift+Tab if it was placed\ninside programmatically.\n\nHas no effect on modal popovers, which use their own focus trap.",
+                "value": {
+                  "type": [
+                    "boolean"
                   ]
                 }
               },
@@ -337,9 +299,7 @@
                 "description": "True if the popover is visible and available for interaction.",
                 "value": {
                   "type": [
-                    "boolean",
-                    "null",
-                    "undefined"
+                    "boolean"
                   ]
                 }
               },
@@ -348,9 +308,7 @@
                 "description": "The `role` attribute value to be set on the popover.",
                 "value": {
                   "type": [
-                    "string",
-                    "null",
-                    "undefined"
+                    "string"
                   ]
                 }
               },
@@ -359,9 +317,7 @@
                 "description": "Position of the overlay with respect to the target.\nSupported values: `top-start`, `top`, `top-end`,\n`bottom-start`, `bottom`, `bottom-end`, `start-top`,\n`start`, `start-bottom`, `end-top`, `end`, `end-bottom`.",
                 "value": {
                   "type": [
-                    "string",
-                    "null",
-                    "undefined"
+                    "string"
                   ]
                 }
               },
@@ -370,9 +326,7 @@
                 "description": "Custom function for rendering the content of the popover.\nReceives two arguments:\n\n- `root` The root container DOM element. Append your content to it.\n- `popover` The reference to the `vaadin-popover` element.",
                 "value": {
                   "type": [
-                    "Object",
-                    "null",
-                    "undefined"
+                    "object"
                   ]
                 }
               },
@@ -381,9 +335,7 @@
                 "description": "The `role` attribute value to be set on the popover.\nWhen not specified, defaults to 'dialog'.",
                 "value": {
                   "type": [
-                    "string",
-                    "null",
-                    "undefined"
+                    "string"
                   ]
                 }
               },
@@ -392,9 +344,7 @@
                 "description": "Reference to the DOM element used both to trigger the overlay\nby user interaction and to visually position it on the screen.\n\nDefaults to an element referenced with `for` attribute, in\nwhich case it must be located in the same shadow scope.",
                 "value": {
                   "type": [
-                    "Object",
-                    "null",
-                    "undefined"
+                    "object"
                   ]
                 }
               },
@@ -403,9 +353,7 @@
                 "description": "Popover trigger mode, used to configure how the popover is opened or closed.\nCould be set to multiple by providing an array, e.g. `trigger = ['hover', 'focus']`.\n\nSupported values:\n- `click` (default) - opens and closes on target click.\n- `hover` - opens on target mouseenter, closes on target mouseleave. Moving mouse\nto the popover content keeps the popover opened.\n- `focus` - opens on target focus, closes on target blur. Moving focus to the\npopover content keeps the popover opened.\n\nIn addition to the behavior specified by `trigger`, the popover can be closed by:\n- pressing Escape key (unless `noCloseOnEsc` property is true)\n- outside click (unless `noCloseOnOutsideClick` property is true)\n\nWhen setting `trigger` property to `null`, `undefined` or empty array, the popover\ncan be only opened programmatically by changing `opened` property. Note, closing\non Escape press or outside click is still allowed unless explicitly disabled.",
                 "value": {
                   "type": [
-                    "Array",
-                    "null",
-                    "undefined"
+                    "array"
                   ]
                 }
               },
@@ -414,9 +362,7 @@
                 "description": "Set the width of the popover.\nIf a unitless number is provided, pixels are assumed.",
                 "value": {
                   "type": [
-                    "string",
-                    "null",
-                    "undefined"
+                    "string"
                   ]
                 }
               },
@@ -425,9 +371,7 @@
                 "description": "When true, the popover has a backdrop (modality curtain) on top of the\nunderlying page content, covering the whole viewport.",
                 "value": {
                   "type": [
-                    "boolean",
-                    "null",
-                    "undefined"
+                    "boolean"
                   ]
                 }
               }

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/popover",
-  "version": "25.2.0-alpha1",
+  "version": "25.2.0-alpha10",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -20,92 +20,92 @@
           "extension": true,
           "attributes": [
             {
-              "name": "?autofocus",
-              "description": "When true, the popover content automatically receives focus after\nit is opened. Modal popovers use this behavior by default.",
+              "name": ".accessibleName",
+              "description": "String used to label the popover to screen reader users.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": "?modal",
-              "description": "When true, the popover prevents interacting with background elements\nby setting `pointer-events` style on the document body to `none`.\nThis also enables trapping focus inside the popover.",
+              "name": ".accessibleNameRef",
+              "description": "Id of the element used as label of the popover to screen reader users.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": "?noCloseOnEsc",
-              "description": "Set to true to disable closing popover on Escape press.",
+              "name": "?autofocus",
+              "description": "When true, the popover content automatically receives focus after\nit is opened. Modal popovers use this behavior by default.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": "?noCloseOnOutsideClick",
-              "description": "Set to true to disable closing popover on outside click.",
+              "name": ".focusDelay",
+              "description": "The delay in milliseconds before the popover is opened\non focus when the corresponding trigger is used.\n\nWhen not specified, the global default (500ms) is used.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": "?opened",
-              "description": "True if the popover is visible and available for interaction.",
+              "name": ".for",
+              "description": "The id of the element to be used as `target` value.\nThe element should be in the DOM by the time when\nthe attribute is set, otherwise a warning is shown.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": "?withBackdrop",
-              "description": "When true, the popover has a backdrop (modality curtain) on top of the\nunderlying page content, covering the whole viewport.",
+              "name": ".height",
+              "description": "Set the height of the popover.\nIf a unitless number is provided, pixels are assumed.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".accessibleName",
-              "description": "String used to label the popover to screen reader users.",
+              "name": ".hideDelay",
+              "description": "The delay in milliseconds before the popover is closed\non losing hover, when the corresponding trigger is used.\nOn blur, the popover is closed immediately.\n\nWhen not specified, the global default (500ms) is used.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".accessibleNameRef",
-              "description": "Id of the element used as label of the popover to screen reader users.",
+              "name": ".hoverDelay",
+              "description": "The delay in milliseconds before the popover is opened\non hover when the corresponding trigger is used.\n\nWhen not specified, the global default (500ms) is used.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".focusDelay",
-              "description": "The delay in milliseconds before the popover is opened\non focus when the corresponding trigger is used.\n\nWhen not specified, the global default (500ms) is used.",
+              "name": "?modal",
+              "description": "When true, the popover prevents interacting with background elements\nby setting `pointer-events` style on the document body to `none`.\nThis also enables trapping focus inside the popover.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".for",
-              "description": "The id of the element to be used as `target` value.\nThe element should be in the DOM by the time when\nthe attribute is set, otherwise a warning is shown.",
+              "name": "?noCloseOnEsc",
+              "description": "Set to true to disable closing popover on Escape press.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".height",
-              "description": "Set the height of the popover.\nIf a unitless number is provided, pixels are assumed.",
+              "name": "?noCloseOnOutsideClick",
+              "description": "Set to true to disable closing popover on outside click.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".hideDelay",
-              "description": "The delay in milliseconds before the popover is closed\non losing hover, when the corresponding trigger is used.\nOn blur, the popover is closed immediately.\n\nWhen not specified, the global default (500ms) is used.",
+              "name": "?noTabFocus",
+              "description": "When true, pressing Tab on the target or a sibling element does not move\nfocus into the popover's content (including any nested popovers), and\nShift+Tab does not move focus into the popover's last focusable. Focus\nstill moves out of the popover on Tab / Shift+Tab if it was placed\ninside programmatically.\n\nHas no effect on modal popovers, which use their own focus trap.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".hoverDelay",
-              "description": "The delay in milliseconds before the popover is opened\non hover when the corresponding trigger is used.\n\nWhen not specified, the global default (500ms) is used.",
+              "name": "?opened",
+              "description": "True if the popover is visible and available for interaction.",
               "value": {
                 "kind": "expression"
               }
@@ -159,6 +159,13 @@
                 "kind": "expression"
               }
             },
+            {
+              "name": "?withBackdrop",
+              "description": "When true, the popover has a backdrop (modality curtain) on top of the\nunderlying page content, covering the whole viewport.",
+              "value": {
+                "kind": "expression"
+              }
+            },
             {
               "name": "@closed",
               "description": "Fired when the popover is closed.",