@vaadin/overlay 25.2.14 → 25.2.15

package/custom-elements.json

@@ -33,7 +33,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.",
+              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.\n\nAn element inside the overlay that has `autofocus` set, such as\n`<vaadin-text-field autofocus>`, receives focus on open instead.",
               "attribute": "focus-trap"
             },
             {
@@ -63,7 +63,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.",
+              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.\n\nAn element inside the overlay that has `autofocus` set, such as\n`<vaadin-text-field autofocus>`, receives focus on open instead.",
               "fieldName": "focusTrap"
             },
             {
@@ -138,7 +138,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.",
+              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.\n\nAn element inside the overlay that has `autofocus` set, such as\n`<vaadin-text-field autofocus>`, receives focus on open instead.",
               "attribute": "focus-trap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",
@@ -289,7 +289,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.",
+              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.\n\nAn element inside the overlay that has `autofocus` set, such as\n`<vaadin-text-field autofocus>`, receives focus on open instead.",
               "fieldName": "focusTrap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",
@@ -682,7 +682,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.",
+              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.\n\nAn element inside the overlay that has `autofocus` set, such as\n`<vaadin-text-field autofocus>`, receives focus on open instead.",
               "attribute": "focus-trap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",
@@ -942,7 +942,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.",
+              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.\n\nAn element inside the overlay that has `autofocus` set, such as\n`<vaadin-text-field autofocus>`, receives focus on open instead.",
               "fieldName": "focusTrap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/overlay",
-  "version": "25.2.14",
+  "version": "25.2.15",
   "publishConfig": {
     "access": "public"
   },
@@ -34,19 +34,19 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "~25.2.14",
-    "@vaadin/component-base": "~25.2.14",
-    "@vaadin/vaadin-themable-mixin": "~25.2.14",
+    "@vaadin/a11y-base": "~25.2.15",
+    "@vaadin/component-base": "~25.2.15",
+    "@vaadin/vaadin-themable-mixin": "~25.2.15",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "~25.2.14",
-    "@vaadin/chai-plugins": "~25.2.14",
-    "@vaadin/test-runner-commands": "~25.2.14",
+    "@vaadin/aura": "~25.2.15",
+    "@vaadin/chai-plugins": "~25.2.15",
+    "@vaadin/test-runner-commands": "~25.2.15",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "~25.2.14",
+    "@vaadin/vaadin-lumo-styles": "~25.2.15",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
-  "gitHead": "7f2566cacb4ca4f83c44fbcc79776b4a3aa0823e"
+  "gitHead": "e0f3c1f28d7393af441fe3c9a790dba3e6ce3912"
 }

package/src/vaadin-overlay-focus-mixin.d.ts

@@ -13,6 +13,9 @@ export declare class OverlayFocusMixinClass {
   /**
    * When true, opening the overlay moves focus to the first focusable child,
    * or to the overlay part with tabindex if there are no focusable children.
+   *
+   * An element inside the overlay that has `autofocus` set, such as
+   * `<vaadin-text-field autofocus>`, receives focus on open instead.
    * @attr {boolean} focus-trap
    */
   focusTrap: boolean;

package/src/vaadin-overlay-focus-mixin.js

@@ -5,7 +5,13 @@
  */
 import { FocusRestorationController } from '@vaadin/a11y-base/src/focus-restoration-controller.js';
 import { FocusTrapController } from '@vaadin/a11y-base/src/focus-trap-controller.js';
-import { getDeepActiveElement, isElementHidden, isKeyboardActive } from '@vaadin/a11y-base/src/focus-utils.js';
+import {
+  getDeepActiveElement,
+  getFocusableElements,
+  isElementFocused,
+  isElementHidden,
+  isKeyboardActive,
+} from '@vaadin/a11y-base/src/focus-utils.js';
 
 export const OverlayFocusMixin = (superClass) =>
   class OverlayFocusMixin extends superClass {
@@ -14,6 +20,9 @@ export const OverlayFocusMixin = (superClass) =>
         /**
          * When true, opening the overlay moves focus to the first focusable child,
          * or to the overlay part with tabindex if there are no focusable children.
+         *
+         * An element inside the overlay that has `autofocus` set, such as
+         * `<vaadin-text-field autofocus>`, receives focus on open instead.
          * @attr {boolean} focus-trap
          */
         focusTrap: {
@@ -41,11 +50,25 @@ export const OverlayFocusMixin = (superClass) =>
       };
     }
 
+    /**
+     * Whether the overlay moves, traps and restores focus. Override to return
+     * false in overlays that never do: focus properties are then ignored and
+     * the focus controllers are not created.
+     * @protected
+     */
+    static get manageFocus() {
+      return true;
+    }
+
     constructor() {
       super();
 
-      this.__focusTrapController = new FocusTrapController(this);
-      this.__focusRestorationController = new FocusRestorationController();
+      this.__manageFocus = this.constructor.manageFocus;
+
+      if (this.__manageFocus) {
+        this.__focusTrapController = new FocusTrapController(this);
+        this.__focusRestorationController = new FocusRestorationController();
+      }
     }
 
     /**
@@ -61,8 +84,10 @@ export const OverlayFocusMixin = (superClass) =>
     ready() {
       super.ready();
 
-      this.addController(this.__focusTrapController);
-      this.addController(this.__focusRestorationController);
+      if (this.__manageFocus) {
+        this.addController(this.__focusTrapController);
+        this.addController(this.__focusRestorationController);
+      }
     }
 
     /**
@@ -80,6 +105,10 @@ export const OverlayFocusMixin = (superClass) =>
      * @protected
      */
     _resetFocus() {
+      if (!this.__manageFocus) {
+        return;
+      }
+
       if (this.focusTrap) {
         this.__focusTrapController.releaseFocus();
       }
@@ -97,18 +126,34 @@ export const OverlayFocusMixin = (superClass) =>
      * @protected
      */
     _saveFocus() {
+      if (!this.__manageFocus) {
+        return;
+      }
+
       if (this.restoreFocusOnClose) {
         this.__focusRestorationController.saveFocus(this.restoreFocusNode);
       }
     }
 
     /**
-     * Trap focus within the overlay after opening has completed.
+     * Trap focus within the overlay after opening has completed. Focus moves
+     * to the first element with `autofocus` inside the overlay, otherwise to
+     * the first focusable element.
      *
      * @protected
      */
     _trapFocus() {
+      if (!this.__manageFocus) {
+        return;
+      }
+
       if (this.focusTrap && !isElementHidden(this._focusTrapRoot)) {
+        const focusables = getFocusableElements(this._focusTrapRoot);
+        if (!focusables.some(isElementFocused)) {
+          const target = focusables.find((el) => this.#hasAutofocus(el));
+          target?.focus({ focusVisible: isKeyboardActive() });
+        }
+
         this.__focusTrapController.trapFocus(this._focusTrapRoot);
       }
     }
@@ -149,4 +194,27 @@ export const OverlayFocusMixin = (superClass) =>
       }
       return n === this._contentRoot;
     }
+
+    /**
+     * Returns true if the element has `autofocus`, or belongs to a custom
+     * element that has it (e.g. the input of `<vaadin-text-field autofocus>`).
+     * As with native `autofocus`, a plain `<div autofocus>` does not apply to
+     * its children. Stops at the focus trap root, whose `autofocus` refers to the overlay.
+     * Walks the flat tree, the same way focusable elements are collected from the
+     * focus trap root, so it never leaves the overlay when content is slotted from the owner.
+     *
+     * @param {HTMLElement} element
+     * @return {boolean}
+     */
+    #hasAutofocus(element) {
+      const focusTrapRoot = this._focusTrapRoot;
+      let node = element;
+      while (node && node !== focusTrapRoot && node !== this) {
+        if (node.autofocus && (node === element || customElements.get(node.localName))) {
+          return true;
+        }
+        node = node.assignedSlot || node.parentNode || node.host;
+      }
+      return false;
+    }
   };