@vaadin/overlay 25.3.0-dev.1fa5a51482 → 25.3.0-rc1

package/custom-elements.json

@@ -26,6 +26,16 @@
           "description": "",
           "name": "OverlayFocusMixin",
           "members": [
+            {
+              "kind": "field",
+              "name": "autofocus",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set to true to move focus into the overlay automatically on open.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
+              "attribute": "autofocus"
+            },
             {
               "kind": "field",
               "name": "focusTrap",
@@ -33,7 +43,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": "Set to true to move focus into the overlay automatically on open\nand keep it inside: Tab and Shift+Tab cycle through the overlay's\ncontent until the overlay is closed.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
               "attribute": "focus-trap"
             },
             {
@@ -58,12 +68,20 @@
             }
           ],
           "attributes": [
+            {
+              "name": "autofocus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set to true to move focus into the overlay automatically on open.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
+              "fieldName": "autofocus"
+            },
             {
               "name": "focus-trap",
               "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": "Set to true to move focus into the overlay automatically on open\nand keep it inside: Tab and Shift+Tab cycle through the overlay's\ncontent until the overlay is closed.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
               "fieldName": "focusTrap"
             },
             {
@@ -110,6 +128,20 @@
           "description": "",
           "name": "OverlayMixin",
           "members": [
+            {
+              "kind": "field",
+              "name": "autofocus",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set to true to move focus into the overlay automatically on open.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
+              "attribute": "autofocus",
+              "inheritedFrom": {
+                "name": "OverlayFocusMixin",
+                "module": "src/vaadin-overlay-focus-mixin.js"
+              }
+            },
             {
               "kind": "method",
               "name": "bringToFront",
@@ -138,7 +170,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": "Set to true to move focus into the overlay automatically on open\nand keep it inside: Tab and Shift+Tab cycle through the overlay's\ncontent until the overlay is closed.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
               "attribute": "focus-trap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",
@@ -284,12 +316,24 @@
             }
           ],
           "attributes": [
+            {
+              "name": "autofocus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set to true to move focus into the overlay automatically on open.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
+              "fieldName": "autofocus",
+              "inheritedFrom": {
+                "name": "OverlayFocusMixin",
+                "module": "src/vaadin-overlay-focus-mixin.js"
+              }
+            },
             {
               "name": "focus-trap",
               "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": "Set to true to move focus into the overlay automatically on open\nand keep it inside: Tab and Shift+Tab cycle through the overlay's\ncontent until the overlay is closed.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
               "fieldName": "focusTrap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",
@@ -593,6 +637,24 @@
           "name": "rootMargin",
           "default": "`${-insetTop}px ${-insetRight}px ${-insetBottom}px ${-insetLeft}px`"
         },
+        {
+          "kind": "function",
+          "name": "getStateAnimations",
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "HTMLElement"
+              }
+            }
+          ],
+          "description": "Collect the animations that report the state of the given element, so that their end can be\nawaited before the element is hidden or removed. The animations are read instead of the\ncomputed style, so that the decision to wait cannot disagree with what the browser actually\ncreated: a keyframes rule that does not exist and an element that is not rendered both give\nan empty list.\n\nOnly CSS animations count, as the transitions and the script animations that `getAnimations()`\nalso returns do not report the state. Animations of any content are already left out, as\n`getAnimations()` only descends into the subtree when asked to. Animations that take no time\nare dropped as well, so that a delay on its own does not hold the state.",
+          "return": {
+            "type": {
+              "text": "!Array<!Animation>"
+            }
+          }
+        },
         {
           "kind": "function",
           "name": "setOverlayStateAttribute",
@@ -631,6 +693,14 @@
             "module": "src/vaadin-overlay-utils.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "getStateAnimations",
+          "declaration": {
+            "name": "getStateAnimations",
+            "module": "src/vaadin-overlay-utils.js"
+          }
+        },
         {
           "kind": "js",
           "name": "setOverlayStateAttribute",
@@ -650,6 +720,20 @@
           "description": "`<vaadin-overlay>` is a Web Component for creating overlays. The content of the overlay\ncan be populated imperatively by using `renderer` callback function.\n\n### Rendering\n\nThe renderer function provides `root`, `owner`, `model` arguments when applicable.\nGenerate DOM content by using `model` object properties if needed, append it to the `root`\nelement and control the state of the host element by accessing `owner`. Before generating new\ncontent, users are able to check if there is already content in `root` for reusing it.\n\n```html\n<vaadin-overlay id=\"overlay\"></vaadin-overlay>\n```\n```js\nconst overlay = document.querySelector('#overlay');\noverlay.renderer = function(root) {\n root.textContent = \"Overlay content\";\n};\n```\n\nRenderer is called on the opening of the overlay and each time the related model is updated.\nDOM generated during the renderer call can be reused\nin the next renderer call and will be provided with the `root` argument.\nOn first call it will be empty.\n\n### Styling\n\nThe following Shadow DOM parts are available for styling:\n\nPart name  | Description\n-----------|---------------------------------------------------------|\n`backdrop` | Backdrop of the overlay\n`overlay`  | Container for position/sizing/alignment of the content\n`content`  | Content of the overlay\n\nThe following state attributes are available for styling:\n\nAttribute | Description\n----------|------------\n`opening` | Applied just after the overlay is opened. You can apply a CSS animation for this state.\n`closing` | Applied just before the overlay is closed. You can apply a CSS animation for this state.\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property | Description | Default value\n---|---|---\n`--vaadin-overlay-viewport-bottom` | Bottom offset of the visible viewport area | `0` or detected offset\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
           "name": "Overlay",
           "members": [
+            {
+              "kind": "field",
+              "name": "autofocus",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set to true to move focus into the overlay automatically on open.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
+              "attribute": "autofocus",
+              "inheritedFrom": {
+                "name": "OverlayFocusMixin",
+                "module": "src/vaadin-overlay-focus-mixin.js"
+              }
+            },
             {
               "kind": "method",
               "name": "bringToFront",
@@ -682,7 +766,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": "Set to true to move focus into the overlay automatically on open\nand keep it inside: Tab and Shift+Tab cycle through the overlay's\ncontent until the overlay is closed.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
               "attribute": "focus-trap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",
@@ -936,13 +1020,26 @@
           },
           "tagName": "vaadin-overlay",
           "customElement": true,
+          "deprecated": "`<vaadin-overlay>` is deprecated and will be removed in Vaadin 26. Consider using `OverlayMixin` and `PositionMixin` instead.",
           "attributes": [
+            {
+              "name": "autofocus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set to true to move focus into the overlay automatically on open.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
+              "fieldName": "autofocus",
+              "inheritedFrom": {
+                "name": "OverlayFocusMixin",
+                "module": "src/vaadin-overlay-focus-mixin.js"
+              }
+            },
             {
               "name": "focus-trap",
               "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": "Set to true to move focus into the overlay automatically on open\nand keep it inside: Tab and Shift+Tab cycle through the overlay's\ncontent until the overlay is closed.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
               "fieldName": "focusTrap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",

package/package.json

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

package/src/styles/vaadin-overlay-animation-base-styles.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { CSSResult } from 'lit';
+
+export const overlayAnimationProperties: CSSResult;
+
+export const overlayAnimationStyles: CSSResult;

package/src/styles/vaadin-overlay-animation-base-styles.js

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { css, unsafeCSS } from 'lit';
+import { registerCSSProperty } from '@vaadin/component-base/src/css-utils.js';
+
+/**
+ * The custom properties that make up the overlay animation CSS API. Both the
+ * property registrations and the `overlayAnimationProperties` snippet below are
+ * derived from this list, so a new property only needs to be added here.
+ *
+ * Only the closed state is part of the API. The opened state is left out of the
+ * keyframes so that it comes from the part itself, see the keyframes below.
+ *
+ * `--vaadin-overlay-transform-closed` has no initial value, which makes it resolve
+ * to `none` in the keyframes unless a theme sets it.
+ */
+const animationProperties = [
+  { name: '--vaadin-overlay-animation-duration', syntax: '<time>', initialValue: '0s' },
+  { name: '--vaadin-overlay-animation-delay', syntax: '<time>', initialValue: '0s' },
+  { name: '--vaadin-overlay-animation-timing-function', syntax: '*', initialValue: 'ease' },
+  { name: '--vaadin-overlay-opacity-closed', syntax: '<number>', initialValue: '0' },
+  { name: '--vaadin-overlay-translate-closed', syntax: '<length>+ | <percentage>+', initialValue: '0px' },
+  { name: '--vaadin-overlay-scale-closed', syntax: '<number> | <percentage>', initialValue: '1' },
+  { name: '--vaadin-overlay-transform-closed', syntax: '*' },
+];
+
+animationProperties.forEach((property) => {
+  registerCSSProperty({ inherits: false, ...property });
+});
+
+/**
+ * The overlay animation properties as a set of `inherit` declarations. The properties are
+ * registered as non-inheriting, so components with more than one shadow root boundary
+ * between the host and the overlay need to forward them explicitly.
+ */
+export const overlayAnimationProperties = unsafeCSS(
+  animationProperties.map(({ name }) => `${name}: inherit;`).join('\n'),
+);
+
+export const overlayAnimationStyles = css`
+  :host,
+  [part='overlay'],
+  [part='backdrop'] {
+    ${overlayAnimationProperties}
+  }
+
+  :host(:where([opening], [closing])) {
+    /* This empty animation only reports the state, the parts run the visible animation */
+    animation-name: --no-op;
+    animation-duration: var(--vaadin-overlay-animation-duration);
+    animation-delay: var(--vaadin-overlay-animation-delay);
+  }
+
+  :host(:where([closing])) [part='overlay'],
+  :host(:where([closing])) ::slotted(*) {
+    pointer-events: none !important;
+  }
+
+  :host(:where([opening], [closing])) :is([part='overlay'], [part='backdrop']) {
+    animation-name: --fade, --transform;
+    animation-duration: var(--vaadin-overlay-animation-duration);
+    animation-timing-function: var(--vaadin-overlay-animation-timing-function);
+    animation-delay: var(--vaadin-overlay-animation-delay);
+    /* Fill backwards only, so the closed value applies during the delay without overriding theme styles */
+    animation-fill-mode: backwards;
+
+    @media (prefers-reduced-motion) {
+      animation-name: --fade;
+    }
+  }
+
+  :host(:where([opening], [closing])) [part='backdrop'] {
+    animation-name: --fade;
+    animation-timing-function: linear;
+    --vaadin-overlay-opacity-closed: 0;
+  }
+
+  :host(:where([closing])) :is([part='overlay'], [part='backdrop']) {
+    animation-direction: reverse;
+    animation-fill-mode: both;
+  }
+
+  @keyframes --no-op {
+  }
+
+  /* Only the closed state is declared, so the animations end at the value the part already has */
+  @keyframes --transform {
+    0% {
+      transform: var(--vaadin-overlay-transform-closed);
+      translate: var(--vaadin-overlay-translate-closed);
+      scale: var(--vaadin-overlay-scale-closed);
+    }
+  }
+
+  @keyframes --fade {
+    0% {
+      opacity: var(--vaadin-overlay-opacity-closed);
+    }
+  }
+`;

package/src/styles/vaadin-overlay-base-styles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { CSSResult } from 'lit';
+
+export const overlayStyles: CSSResult[];

package/src/styles/vaadin-overlay-base-styles.js

@@ -5,8 +5,9 @@
  */
 import '@vaadin/component-base/src/styles/style-props.js';
 import { css } from 'lit';
+import { overlayAnimationStyles } from './vaadin-overlay-animation-base-styles.js';
 
-export const overlayStyles = css`
+const overlayBase = css`
   :host {
     z-index: 200;
     position: fixed;
@@ -55,6 +56,11 @@ export const overlayStyles = css`
     display: none !important;
   }
 
+  :host([suppressed]) [part='overlay'],
+  :host([suppressed]) ::slotted(*) {
+    pointer-events: none !important;
+  }
+
   [part='overlay'] {
     color: var(--vaadin-overlay-text-color, var(--vaadin-text-color));
     background: var(--vaadin-overlay-background, var(--vaadin-background-color));
@@ -103,3 +109,5 @@ export const overlayStyles = css`
     }
   }
 `;
+
+export const overlayStyles = [overlayBase, overlayAnimationStyles];

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

@@ -11,12 +11,27 @@ export declare function OverlayFocusMixin<T extends Constructor<HTMLElement>>(
 
 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.
+   * Set to true to move focus into the overlay automatically on open
+   * and keep it inside: Tab and Shift+Tab cycle through the overlay's
+   * content until the overlay is closed.
+   *
+   * Focus moves to the first tabbable element in the tab order. This
+   * can be the overlay itself if it has `tabindex` attribute set to `0`
+   * on the host element or the `overlay` shadow DOM part.
+   *
    * @attr {boolean} focus-trap
    */
   focusTrap: boolean;
 
+  /**
+   * Set to true to move focus into the overlay automatically on open.
+   *
+   * Focus moves to the first tabbable element in the tab order. This
+   * can be the overlay itself if it has `tabindex` attribute set to `0`
+   * on the host element or the `overlay` shadow DOM part.
+   */
+  autofocus: boolean;
+
   /**
    * Set to true to enable restoring of focus when overlay is closed.
    * @attr {boolean} restore-focus-on-close
@@ -40,8 +55,9 @@ export declare class OverlayFocusMixinClass {
   protected _saveFocus(): void;
 
   /**
-   * Sets up focus after the overlay opening has completed: traps focus
-   * within the overlay if `focusTrap` is enabled.
+   * Sets up focus after the overlay opening has completed: moves focus into
+   * the overlay if `autofocus` is enabled, and traps focus within the overlay
+   * if `focusTrap` is enabled.
    */
   protected _initFocus(): void;
 

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

@@ -5,15 +5,27 @@
  */
 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,
+  getTabbableElements,
+  isElementFocused,
+  isElementHidden,
+  isKeyboardActive,
+} from '@vaadin/a11y-base/src/focus-utils.js';
 
 export const OverlayFocusMixin = (superClass) =>
   class OverlayFocusMixin extends superClass {
     static get properties() {
       return {
         /**
-         * 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.
+         * Set to true to move focus into the overlay automatically on open
+         * and keep it inside: Tab and Shift+Tab cycle through the overlay's
+         * content until the overlay is closed.
+         *
+         * Focus moves to the first tabbable element in the tab order. This
+         * can be the overlay itself if it has `tabindex` attribute set to `0`
+         * on the host element or the `overlay` shadow DOM part.
+         *
          * @attr {boolean} focus-trap
          */
         focusTrap: {
@@ -21,6 +33,18 @@ export const OverlayFocusMixin = (superClass) =>
           value: false,
         },
 
+        /**
+         * Set to true to move focus into the overlay automatically on open.
+         *
+         * Focus moves to the first tabbable element in the tab order. This
+         * can be the overlay itself if it has `tabindex` attribute set to `0`
+         * on the host element or the `overlay` shadow DOM part.
+         */
+        autofocus: {
+          type: Boolean,
+          value: false,
+        },
+
         /**
          * Set to true to enable restoring of focus when overlay is closed.
          * @attr {boolean} restore-focus-on-close
@@ -103,13 +127,25 @@ export const OverlayFocusMixin = (superClass) =>
     }
 
     /**
-     * Sets up focus after the overlay opening has completed: traps focus
-     * within the overlay if `focusTrap` is enabled.
+     * Sets up focus after the overlay opening has completed: moves focus into
+     * the overlay if `autofocus` is enabled, and traps focus within the overlay
+     * if `focusTrap` is enabled.
      *
      * @protected
      */
     _initFocus() {
-      if (this.focusTrap && !isElementHidden(this._focusRoot)) {
+      if (isElementHidden(this._focusRoot)) {
+        return;
+      }
+
+      if (this.autofocus) {
+        const tabbables = getTabbableElements(this._focusRoot);
+        if (!tabbables.some(isElementFocused)) {
+          tabbables[0]?.focus({ focusVisible: isKeyboardActive() });
+        }
+      }
+
+      if (this.focusTrap) {
         this.__focusTrapController.trapFocus(this._focusRoot);
       }
     }

package/src/vaadin-overlay-mixin.js

@@ -6,7 +6,7 @@
 import { isIOS } from '@vaadin/component-base/src/browser-utils.js';
 import { OverlayFocusMixin } from './vaadin-overlay-focus-mixin.js';
 import { OverlayStackMixin } from './vaadin-overlay-stack-mixin.js';
-import { setOverlayStateAttribute } from './vaadin-overlay-utils.js';
+import { getStateAnimations, setOverlayStateAttribute } from './vaadin-overlay-utils.js';
 
 export const OverlayMixin = (superClass) =>
   class OverlayMixin extends OverlayFocusMixin(OverlayStackMixin(superClass)) {
@@ -132,19 +132,6 @@ export const OverlayMixin = (superClass) =>
       if (this.$.backdrop) {
         this.$.backdrop.addEventListener('click', () => {});
       }
-
-      this.addEventListener('mouseup', () => {
-        // In Chrome, focus moves to body on overlay content mousedown
-        // See https://github.com/vaadin/flow-components/issues/5507
-        if (document.activeElement === document.body && this.$.overlay.getAttribute('tabindex') === '0') {
-          this.$.overlay.focus();
-        }
-      });
-
-      this.addEventListener('animationcancel', () => {
-        this._flushAnimation('opening');
-        this._flushAnimation('closing');
-      });
     }
 
     /** @protected */
@@ -401,37 +388,35 @@ export const OverlayMixin = (superClass) =>
     }
 
     /**
-     * @return {boolean}
-     * @private
-     */
-    _shouldAnimate() {
-      const style = getComputedStyle(this);
-      const name = style.getPropertyValue('animation-name');
-      const hasDuration = style
-        .getPropertyValue('animation-duration')
-        .split(',')
-        .some((duration) => parseFloat(duration) > 0);
-      const hidden = style.getPropertyValue('display') === 'none';
-      return !hidden && name && name !== 'none' && hasDuration;
-    }
-
-    /**
+     * Run the callback once every animation reporting the state has ended, or right away when
+     * there is none.
+     *
      * @param {string} type
      * @param {Function} callback
      * @private
      */
     _enqueueAnimation(type, callback) {
+      const animations = getStateAnimations(this);
+      if (animations.length === 0) {
+        callback();
+        return;
+      }
+
       const handler = `__${type}Handler`;
-      const listener = (event) => {
-        if (event && event.target !== this) {
+      const finish = () => {
+        // The phase may already have been finished by _flushAnimation(), or superseded by a
+        // later one of the same type, in which case this callback no longer applies
+        if (this[handler] !== finish) {
           return;
         }
-        callback();
-        this.removeEventListener('animationend', listener);
+        // Cleared before the callback, so that a listener reopening the overlay synchronously
+        // installs its own handler rather than having it deleted afterwards
         delete this[handler];
+        callback();
       };
-      this[handler] = listener;
-      this.addEventListener('animationend', listener);
+      this[handler] = finish;
+      // A cancelled animation rejects, which ends the phase just as finishing does
+      Promise.all(animations.map((animation) => animation.finished)).then(finish, finish);
     }
 
     /**
@@ -452,19 +437,14 @@ export const OverlayMixin = (superClass) =>
       }
       this._attachOverlay();
       this._appendAttachedInstance();
-      this.bringToFront();
       if (!this.modeless) {
         this._enterModalState();
       }
       setOverlayStateAttribute(this, 'opening', true);
 
-      if (this._shouldAnimate()) {
-        this._enqueueAnimation('opening', () => {
-          this._finishOpening();
-        });
-      } else {
+      this._enqueueAnimation('opening', () => {
         this._finishOpening();
-      }
+      });
     }
 
     /** @private */
@@ -483,7 +463,7 @@ export const OverlayMixin = (superClass) =>
     _finishClosing() {
       this._detachOverlay();
       this._removeAttachedInstance();
-      this.$.overlay.style.removeProperty('pointer-events');
+      this.toggleAttribute('suppressed', false);
       setOverlayStateAttribute(this, 'closing', false);
       this.dispatchEvent(new CustomEvent('vaadin-overlay-closed'));
     }
@@ -498,13 +478,9 @@ export const OverlayMixin = (superClass) =>
         setOverlayStateAttribute(this, 'closing', true);
         this.dispatchEvent(new CustomEvent('vaadin-overlay-closing'));
 
-        if (this._shouldAnimate()) {
-          this._enqueueAnimation('closing', () => {
-            this._finishClosing();
-          });
-        } else {
+        this._enqueueAnimation('closing', () => {
           this._finishClosing();
-        }
+        });
       }
     }
 
@@ -561,6 +537,11 @@ export const OverlayMixin = (superClass) =>
 
       if (this.opened && !evt.defaultPrevented) {
         this.close(event);
+
+        // Only for modal overlays which make underlying content non-interactive.
+        if (!this.opened && !this.modeless) {
+          event.preventDefault();
+        }
       }
     }
 

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

@@ -106,10 +106,10 @@ export const OverlayStackMixin = (superClass) =>
         document.body.style.pointerEvents = 'none';
       }
 
-      // Disable pointer events in other attached overlays
+      // Suppress pointer events in other attached overlays
       getAttachedInstances().forEach((el) => {
         if (el !== this) {
-          el.$.overlay.style.pointerEvents = 'none';
+          el.toggleAttribute('suppressed', true);
         }
       });
     }
@@ -122,7 +122,7 @@ export const OverlayStackMixin = (superClass) =>
         delete this._previousDocumentPointerEvents;
       }
 
-      // Restore pointer events in the previous overlay(s)
+      // Stop suppressing pointer events in the previous overlay(s)
       const instances = getAttachedInstances();
 
       let el;
@@ -132,7 +132,7 @@ export const OverlayStackMixin = (superClass) =>
           // Skip the current instance
           continue;
         }
-        el.$.overlay.style.removeProperty('pointer-events');
+        el.toggleAttribute('suppressed', false);
         if (!el.modeless) {
           // Stop after the last modal
           break;

package/src/vaadin-overlay-utils.d.ts

@@ -12,6 +12,20 @@
  */
 export function observeMove(element: HTMLElement, callback: () => void): () => void;
 
+/**
+ * Collect the animations that report the state of the given element, so that their end can be
+ * awaited before the element is hidden or removed. The animations are read instead of the
+ * computed style, so that the decision to wait cannot disagree with what the browser actually
+ * created: a keyframes rule that does not exist and an element that is not rendered both give
+ * an empty list.
+ *
+ * Only CSS animations count, as the transitions and the script animations that `getAnimations()`
+ * also returns do not report the state. Animations of any content are already left out, as
+ * `getAnimations()` only descends into the subtree when asked to. Animations that take no time
+ * are dropped as well, so that a delay on its own does not hold the state.
+ */
+export function getStateAnimations(element: HTMLElement): Animation[];
+
 /**
  * Toggle the state attribute on the overlay element and also its owner element. This allows targeting state attributes
  * in the light DOM in case the overlay is in the shadow DOM of its owner.

package/src/vaadin-overlay-utils.js

@@ -85,6 +85,29 @@ export function observeMove(element, callback) {
   return cleanup;
 }
 
+/**
+ * Collect the animations that report the state of the given element, so that their end can be
+ * awaited before the element is hidden or removed. The animations are read instead of the
+ * computed style, so that the decision to wait cannot disagree with what the browser actually
+ * created: a keyframes rule that does not exist and an element that is not rendered both give
+ * an empty list.
+ *
+ * Only CSS animations count, as the transitions and the script animations that `getAnimations()`
+ * also returns do not report the state. Animations of any content are already left out, as
+ * `getAnimations()` only descends into the subtree when asked to. Animations that take no time
+ * are dropped as well, so that a delay on its own does not hold the state.
+ *
+ * @param {HTMLElement} element
+ * @return {!Array<!Animation>}
+ */
+export function getStateAnimations(element) {
+  return element
+    .getAnimations()
+    .filter(
+      (animation) => animation instanceof CSSAnimation && animation.effect.getComputedTiming().activeDuration > 0,
+    );
+}
+
 /**
  * Toggle the state attribute on the overlay element and also its owner element. This allows targeting state attributes
  * in the light DOM in case the overlay is in the shadow DOM of its owner.

package/src/vaadin-overlay.d.ts

@@ -118,6 +118,8 @@ export type OverlayEventMap = HTMLElementEventMap & OverlayCustomEventMap;
  * @fires {CustomEvent} vaadin-overlay-closed - Fired after the overlay is closed.
  * @fires {CustomEvent} vaadin-overlay-outside-click - Fired before the overlay is closed on outside click. Calling `preventDefault()` on the event cancels the closing.
  * @fires {CustomEvent} vaadin-overlay-escape-press - Fired before the overlay is closed on Escape key press. Calling `preventDefault()` on the event cancels the closing.
+ * @deprecated `<vaadin-overlay>` is deprecated and will be removed in Vaadin 26.
+ * Consider using `OverlayMixin` and `PositionMixin` instead.
  */
 declare class Overlay extends OverlayMixin(ThemableMixin(DirMixin(HTMLElement))) {
   addEventListener<K extends keyof OverlayEventMap>(

package/src/vaadin-overlay.js

@@ -7,6 +7,7 @@ import { html, LitElement } from 'lit';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { issueWarning } from '@vaadin/component-base/src/warnings.js';
 import { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { overlayStyles } from './styles/vaadin-overlay-base-styles.js';
@@ -73,6 +74,8 @@ import { OverlayMixin } from './vaadin-overlay-mixin.js';
  *
  * @customElement vaadin-overlay
  * @extends HTMLElement
+ * @deprecated `<vaadin-overlay>` is deprecated and will be removed in Vaadin 26.
+ * Consider using `OverlayMixin` and `PositionMixin` instead.
  */
 class Overlay extends OverlayMixin(DirMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement))))) {
   static get is() {
@@ -94,6 +97,15 @@ class Overlay extends OverlayMixin(DirMixin(ThemableMixin(PolylitMixin(LumoInjec
       </div>
     `;
   }
+
+  /** @protected */
+  firstUpdated() {
+    super.firstUpdated();
+
+    issueWarning(
+      '`<vaadin-overlay>` is deprecated and will be removed in Vaadin 26. Consider using `OverlayMixin` and `PositionMixin` instead.',
+    );
+  }
 }
 
 defineCustomElement(Overlay);