@vaadin/popover 25.2.0-alpha1 → 25.2.0-alpha11

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-alpha11",
   "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-alpha11",
+    "@vaadin/component-base": "25.2.0-alpha11",
+    "@vaadin/lit-renderer": "25.2.0-alpha11",
+    "@vaadin/overlay": "25.2.0-alpha11",
+    "@vaadin/vaadin-themable-mixin": "25.2.0-alpha11",
     "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-alpha11",
+    "@vaadin/chai-plugins": "25.2.0-alpha11",
+    "@vaadin/test-runner-commands": "25.2.0-alpha11",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.2.0-alpha1",
+    "@vaadin/vaadin-lumo-styles": "25.2.0-alpha11",
     "sinon": "^21.0.2"
   },
   "customElements": "custom-elements.json",
@@ -57,5 +57,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "866f813f89655a351cbd25328eba1fcb317e267d"
+  "gitHead": "fdc37e932709f95491a027aeb2090911cb7528c6"
 }

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-overlay-mixin.js

@@ -8,10 +8,6 @@ import { PositionMixin } from '@vaadin/overlay/src/vaadin-overlay-position-mixin
 
 /**
  * A mixin providing common popover overlay functionality.
- *
- * @polymerMixin
- * @mixes PositionMixin
- * @mixes OverlayMixin
  */
 export const PopoverOverlayMixin = (superClass) =>
   class PopoverOverlayMixinClass extends PositionMixin(OverlayMixin(superClass)) {

package/src/vaadin-popover-overlay.js

@@ -18,9 +18,6 @@ import { PopoverOverlayMixin } from './vaadin-popover-overlay-mixin.js';
  *
  * @customElement vaadin-popover-overlay
  * @extends HTMLElement
- * @mixes DirMixin
- * @mixes PopoverOverlayMixin
- * @mixes ThemableMixin
  * @private
  */
 class PopoverOverlay extends PopoverOverlayMixin(

package/src/vaadin-popover-position-mixin.js

@@ -6,8 +6,6 @@
 
 /**
  * A mixin providing popover position functionality.
- *
- * @polymerMixin
  */
 export const PopoverPositionMixin = (superClass) =>
   class PopoverPositionMixinClass extends superClass {

package/src/vaadin-popover-target-mixin.js

@@ -8,8 +8,6 @@ import { Debouncer } from '@vaadin/component-base/src/debounce.js';
 
 /**
  * A mixin providing popover target functionality.
- *
- * @polymerMixin
  */
 export const PopoverTargetMixin = (superClass) =>
   class PopoverTargetMixinClass extends superClass {

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']`.