@vaadin/overlay 25.0.0-alpha2 → 25.0.0-alpha21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/overlay",
-  "version": "25.0.0-alpha2",
+  "version": "25.0.0-alpha21",
   "publishConfig": {
     "access": "public"
   },
@@ -21,9 +21,6 @@
   "type": "module",
   "files": [
     "src",
-    "!src/*-base-styles.d.ts",
-    "!src/*-base-styles.js",
-    "theme",
     "vaadin-*.d.ts",
     "vaadin-*.js"
   ],
@@ -36,17 +33,17 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "25.0.0-alpha2",
-    "@vaadin/component-base": "25.0.0-alpha2",
-    "@vaadin/vaadin-lumo-styles": "25.0.0-alpha2",
-    "@vaadin/vaadin-themable-mixin": "25.0.0-alpha2",
+    "@vaadin/a11y-base": "25.0.0-alpha21",
+    "@vaadin/component-base": "25.0.0-alpha21",
+    "@vaadin/vaadin-themable-mixin": "25.0.0-alpha21",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "25.0.0-alpha2",
-    "@vaadin/test-runner-commands": "25.0.0-alpha2",
+    "@vaadin/chai-plugins": "25.0.0-alpha21",
+    "@vaadin/test-runner-commands": "25.0.0-alpha21",
     "@vaadin/testing-helpers": "^2.0.0",
-    "sinon": "^18.0.0"
+    "@vaadin/vaadin-lumo-styles": "25.0.0-alpha21",
+    "sinon": "^21.0.0"
   },
-  "gitHead": "67ffcd5355cf21ce1b5039c598525109fc4c164b"
+  "gitHead": "8fb9e9710c01449edf623a1aaac4655cdc11a933"
 }

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

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import '@vaadin/component-base/src/styles/style-props.js';
+import { css } from 'lit';
+
+export const overlayStyles = css`
+  :host {
+    z-index: 200;
+    position: fixed;
+
+    /* Despite of what the names say, <vaadin-overlay> is just a container
+          for position/sizing/alignment. The actual overlay is the overlay part. */
+
+    /* Default position constraints. Themes can
+          override this to adjust the gap between the overlay and the viewport. */
+    inset: var(--vaadin-overlay-viewport-inset, 8px);
+    bottom: var(--vaadin-overlay-viewport-bottom);
+
+    /* Override native [popover] user agent styles */
+    width: auto;
+    height: auto;
+    border: none;
+    padding: 0;
+    background-color: transparent;
+    overflow: visible;
+
+    /* Use flexbox alignment for the overlay part. */
+    display: flex;
+    flex-direction: column; /* makes dropdowns sizing easier */
+    /* Align to center by default. */
+    align-items: center;
+    justify-content: center;
+
+    /* Allow centering when max-width/max-height applies. */
+    margin: auto;
+
+    /* The host is not clickable, only the overlay part is. */
+    pointer-events: none;
+
+    /* Remove tap highlight on touch devices. */
+    -webkit-tap-highlight-color: transparent;
+
+    /* CSS API for host */
+    --vaadin-overlay-viewport-bottom: 8px;
+  }
+
+  :host([hidden]),
+  :host(:not([opened]):not([closing])),
+  :host(:not([opened]):not([closing])) [part='overlay'] {
+    display: none !important;
+  }
+
+  [part='overlay'] {
+    background: var(--vaadin-overlay-background, var(--vaadin-background-color));
+    border: var(--vaadin-overlay-border-width, 1px) solid
+      var(--vaadin-overlay-border-color, var(--vaadin-border-color-secondary));
+    border-radius: var(--vaadin-overlay-border-radius, var(--vaadin-radius-m));
+    box-shadow: var(--vaadin-overlay-shadow, 0 8px 24px -4px rgba(0, 0, 0, 0.3));
+    box-sizing: border-box;
+    max-width: 100%;
+    overflow: auto;
+    overscroll-behavior: contain;
+    pointer-events: auto;
+    -webkit-tap-highlight-color: initial;
+
+    /* CSS reset for font styles */
+    color: initial;
+    font: initial;
+    letter-spacing: initial;
+    text-align: initial;
+    text-decoration: initial;
+    text-indent: initial;
+    text-transform: initial;
+    user-select: text;
+    white-space: initial;
+    word-spacing: initial;
+  }
+
+  [part='backdrop'] {
+    background: var(--vaadin-overlay-backdrop-background, rgba(0, 0, 0, 0.2));
+    content: '';
+    inset: 0;
+    pointer-events: auto;
+    position: fixed;
+    z-index: -1;
+  }
+
+  [part='overlay']:focus-visible {
+    outline: var(--vaadin-focus-ring-width) solid var(--vaadin-focus-ring-color);
+  }
+
+  @media (forced-colors: active) {
+    [part='overlay'] {
+      border: 3px solid !important;
+    }
+  }
+`;

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

@@ -3,7 +3,6 @@
  * Copyright (c) 2017 - 2025 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { AriaModalController } from '@vaadin/a11y-base/src/aria-modal-controller.js';
 import { FocusRestorationController } from '@vaadin/a11y-base/src/focus-restoration-controller.js';
 import { FocusTrapController } from '@vaadin/a11y-base/src/focus-trap-controller.js';
 import { getDeepActiveElement, isKeyboardActive } from '@vaadin/a11y-base/src/focus-utils.js';
@@ -48,20 +47,36 @@ export const OverlayFocusMixin = (superClass) =>
     constructor() {
       super();
 
-      this.__ariaModalController = new AriaModalController(this);
       this.__focusTrapController = new FocusTrapController(this);
       this.__focusRestorationController = new FocusRestorationController();
     }
 
+    /**
+     * Override to specify another element used as a content root,
+     * e.g. slotted into the overlay, rather than overlay itself.
+     * @protected
+     */
+    get _contentRoot() {
+      return this;
+    }
+
     /** @protected */
     ready() {
       super.ready();
 
-      this.addController(this.__ariaModalController);
       this.addController(this.__focusTrapController);
       this.addController(this.__focusRestorationController);
     }
 
+    /**
+     * Override to specify another element used as a focus trap root,
+     * e.g. the overlay's owner element, rather than overlay part.
+     * @protected
+     */
+    get _focusTrapRoot() {
+      return this.$.overlay;
+    }
+
     /**
      * Release focus and restore focus after the overlay is closed.
      *
@@ -69,13 +84,13 @@ export const OverlayFocusMixin = (superClass) =>
      */
     _resetFocus() {
       if (this.focusTrap) {
-        this.__ariaModalController.close();
         this.__focusTrapController.releaseFocus();
       }
 
       if (this.restoreFocusOnClose && this._shouldRestoreFocus()) {
-        const preventScroll = !isKeyboardActive();
-        this.__focusRestorationController.restoreFocus({ preventScroll });
+        const focusVisible = isKeyboardActive();
+        const preventScroll = !focusVisible;
+        this.__focusRestorationController.restoreFocus({ preventScroll, focusVisible });
       }
     }
 
@@ -97,8 +112,7 @@ export const OverlayFocusMixin = (superClass) =>
      */
     _trapFocus() {
       if (this.focusTrap) {
-        this.__ariaModalController.showModal();
-        this.__focusTrapController.trapFocus(this.$.overlay);
+        this.__focusTrapController.trapFocus(this._focusTrapRoot);
       }
     }
 
@@ -127,15 +141,15 @@ export const OverlayFocusMixin = (superClass) =>
      * @protected
      */
     _deepContains(node) {
-      if (this.contains(node)) {
+      if (this._contentRoot.contains(node)) {
         return true;
       }
       let n = node;
       const doc = node.ownerDocument;
-      // Walk from node to `this` or `document`
-      while (n && n !== doc && n !== this) {
+      // Walk from node to content root or `document`
+      while (n && n !== doc && n !== this._contentRoot) {
         n = n.parentNode || n.host;
       }
-      return n === this;
+      return n === this._contentRoot;
     }
   };

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

@@ -7,6 +7,13 @@ import type { Constructor } from '@open-wc/dedupe-mixin';
 import type { OverlayFocusMixinClass } from './vaadin-overlay-focus-mixin.js';
 import type { OverlayStackMixinClass } from './vaadin-overlay-stack-mixin.js';
 
+export type OverlayBounds = {
+  top?: number | string;
+  left?: number | string;
+  width?: number | string;
+  height?: number | string;
+};
+
 export type OverlayRenderer = (root: HTMLElement, owner: HTMLElement, model?: object) => void;
 
 export declare function OverlayMixin<T extends Constructor<HTMLElement>>(
@@ -58,6 +65,11 @@ export declare class OverlayMixinClass {
 
   close(sourceEvent?: Event | null): void;
 
+  /**
+   * Updates the coordinates of the overlay.
+   */
+  setBounds(bounds: OverlayBounds, absolute?: boolean): void;
+
   /**
    * Requests an update for the content of the overlay.
    * While performing the update, it invokes the renderer passed in the `renderer` property.

package/src/vaadin-overlay-mixin.js

@@ -6,6 +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';
 
 /**
  * @polymerMixin
@@ -91,6 +92,7 @@ export const OverlayMixin = (superClass) =>
           type: Boolean,
           value: false,
           reflectToAttribute: true,
+          observer: '_withBackdropChanged',
           sync: true,
         },
       };
@@ -115,15 +117,20 @@ export const OverlayMixin = (superClass) =>
     }
 
     /** @protected */
-    ready() {
-      super.ready();
+    firstUpdated() {
+      super.firstUpdated();
+
+      // Set popover in firstUpdated before opened observers are called
+      this.popover = 'manual';
 
       // Need to add dummy click listeners to this and the backdrop or else
       // the document click event listener (_outsideClickListener) may never
       // get invoked on iOS Safari (reproducible in <vaadin-dialog>
       // and <vaadin-context-menu>).
       this.addEventListener('click', () => {});
-      this.$.backdrop.addEventListener('click', () => {});
+      if (this.$.backdrop) {
+        this.$.backdrop.addEventListener('click', () => {});
+      }
 
       this.addEventListener('mouseup', () => {
         // In Chrome, focus moves to body on overlay content mousedown
@@ -149,6 +156,11 @@ export const OverlayMixin = (superClass) =>
     disconnectedCallback() {
       super.disconnectedCallback();
 
+      if (this.__scheduledOpen) {
+        cancelAnimationFrame(this.__scheduledOpen);
+        this.__scheduledOpen = null;
+      }
+
       /* c8 ignore next 3 */
       if (this._boundIosResizeListener) {
         window.removeEventListener('resize', this._boundIosResizeListener);
@@ -163,7 +175,7 @@ export const OverlayMixin = (superClass) =>
      */
     requestContentUpdate() {
       if (this.renderer) {
-        this.renderer.call(this.owner, this, this.owner, this.model);
+        this.renderer.call(this.owner, this._contentRoot, this.owner, this.model);
       }
     }
 
@@ -171,17 +183,44 @@ export const OverlayMixin = (superClass) =>
      * @param {Event=} sourceEvent
      */
     close(sourceEvent) {
-      const evt = new CustomEvent('vaadin-overlay-close', {
+      // Dispatch the event on the overlay. Not using composed, as propagating the event through shadow roots could have
+      // side effects when nesting overlays
+      const event = new CustomEvent('vaadin-overlay-close', {
         bubbles: true,
         cancelable: true,
-        detail: { sourceEvent },
+        detail: { overlay: this, sourceEvent },
       });
-      this.dispatchEvent(evt);
-      if (!evt.defaultPrevented) {
+      this.dispatchEvent(event);
+      // To allow listening for the event globally, also dispatch it on the document body
+      document.body.dispatchEvent(event);
+      if (!event.defaultPrevented) {
         this.opened = false;
       }
     }
 
+    /**
+     * Updates the coordinates of the overlay.
+     * @param {!OverlayBoundsParam} bounds
+     * @param {boolean} absolute
+     */
+    setBounds(bounds, absolute = true) {
+      const overlay = this.$.overlay;
+      const parsedBounds = { ...bounds };
+
+      if (absolute && overlay.style.position !== 'absolute') {
+        overlay.style.position = 'absolute';
+      }
+
+      Object.keys(parsedBounds).forEach((arg) => {
+        // Allow setting width or height to `null`
+        if (parsedBounds[arg] !== null && !isNaN(parsedBounds[arg])) {
+          parsedBounds[arg] = `${parsedBounds[arg]}px`;
+        }
+      });
+
+      Object.assign(overlay.style, parsedBounds);
+    }
+
     /** @private */
     _detectIosNavbar() {
       /* c8 ignore next 15 */
@@ -203,8 +242,25 @@ export const OverlayMixin = (superClass) =>
       }
     }
 
+    /**
+     * Whether to add global listeners for closing on outside click.
+     * By default, listeners are not added for a modeless overlay.
+     *
+     * @return {boolean}
+     * @protected
+     */
+    _shouldAddGlobalListeners() {
+      return !this.modeless;
+    }
+
     /** @private */
     _addGlobalListeners() {
+      if (this.__hasGlobalListeners) {
+        return;
+      }
+
+      this.__hasGlobalListeners = true;
+
       document.addEventListener('mousedown', this._boundMouseDownListener);
       document.addEventListener('mouseup', this._boundMouseUpListener);
       // Firefox leaks click to document on contextmenu even if prevented
@@ -214,6 +270,12 @@ export const OverlayMixin = (superClass) =>
 
     /** @private */
     _removeGlobalListeners() {
+      if (!this.__hasGlobalListeners) {
+        return;
+      }
+
+      this.__hasGlobalListeners = false;
+
       document.removeEventListener('mousedown', this._boundMouseDownListener);
       document.removeEventListener('mouseup', this._boundMouseUpListener);
       document.documentElement.removeEventListener('click', this._boundOutsideClickListener, true);
@@ -233,11 +295,11 @@ export const OverlayMixin = (superClass) =>
       this._oldOpened = opened;
 
       if (rendererChanged && hasOldRenderer) {
-        this.innerHTML = '';
+        this._contentRoot.innerHTML = '';
         // Whenever a Lit-based renderer is used, it assigns a Lit part to the node it was rendered into.
         // When clearing the rendered content, this part needs to be manually disposed of.
         // Otherwise, using a Lit-based renderer on the same node will throw an exception or render nothing afterward.
-        delete this._$litPart$;
+        delete this._contentRoot._$litPart$;
       }
 
       if (opened && renderer && (rendererChanged || openedChanged || ownerOrModelChanged)) {
@@ -247,20 +309,39 @@ export const OverlayMixin = (superClass) =>
 
     /** @private */
     _modelessChanged(modeless) {
+      if (this.opened) {
+        // Add / remove listeners if modeless is changed while opened
+        if (this._shouldAddGlobalListeners()) {
+          this._addGlobalListeners();
+        } else {
+          this._removeGlobalListeners();
+        }
+      }
+
       if (!modeless) {
         if (this.opened) {
-          this._addGlobalListeners();
           this._enterModalState();
         }
       } else {
-        this._removeGlobalListeners();
         this._exitModalState();
       }
+      setOverlayStateAttribute(this, 'modeless', modeless);
+    }
+
+    /** @private */
+    _withBackdropChanged(withBackdrop) {
+      setOverlayStateAttribute(this, 'with-backdrop', withBackdrop);
     }
 
     /** @private */
     _openedChanged(opened, wasOpened) {
       if (opened) {
+        // Prevent possible errors on setting `opened` to `true` while disconnected
+        if (!this.isConnected) {
+          this.opened = false;
+          return;
+        }
+
         this._saveFocus();
 
         this._animatedOpening();
@@ -269,13 +350,18 @@ export const OverlayMixin = (superClass) =>
           setTimeout(() => {
             this._trapFocus();
 
-            this.dispatchEvent(new CustomEvent('vaadin-overlay-open', { bubbles: true }));
+            // Dispatch the event on the overlay. Not using composed, as propagating the event through shadow roots
+            // could have side effects when nesting overlays
+            const event = new CustomEvent('vaadin-overlay-open', { detail: { overlay: this }, bubbles: true });
+            this.dispatchEvent(event);
+            // To allow listening for the event globally, also dispatch it on the document body
+            document.body.dispatchEvent(event);
           });
         });
 
         document.addEventListener('keydown', this._boundKeydownListener);
 
-        if (!this.modeless) {
+        if (this._shouldAddGlobalListeners()) {
           this._addGlobalListeners();
         }
       } else if (wasOpened) {
@@ -290,7 +376,7 @@ export const OverlayMixin = (superClass) =>
 
         document.removeEventListener('keydown', this._boundKeydownListener);
 
-        if (!this.modeless) {
+        if (this._shouldAddGlobalListeners()) {
           this._removeGlobalListeners();
         }
       }
@@ -346,14 +432,16 @@ export const OverlayMixin = (superClass) =>
 
     /** @private */
     _animatedOpening() {
-      if (this.parentNode === document.body && this.hasAttribute('closing')) {
+      if (this._isAttached && this.hasAttribute('closing')) {
         this._flushAnimation('closing');
       }
       this._attachOverlay();
+      this._appendAttachedInstance();
+      this.bringToFront();
       if (!this.modeless) {
         this._enterModalState();
       }
-      this.setAttribute('opening', '');
+      setOverlayStateAttribute(this, 'opening', true);
 
       if (this._shouldAnimate()) {
         this._enqueueAnimation('opening', () => {
@@ -366,22 +454,20 @@ export const OverlayMixin = (superClass) =>
 
     /** @private */
     _attachOverlay() {
-      this._placeholder = document.createComment('vaadin-overlay-placeholder');
-      this.parentNode.insertBefore(this._placeholder, this);
-      document.body.appendChild(this);
-      this.bringToFront();
+      this.showPopover();
     }
 
     /** @private */
     _finishOpening() {
-      this.removeAttribute('opening');
+      setOverlayStateAttribute(this, 'opening', false);
     }
 
     /** @private */
     _finishClosing() {
       this._detachOverlay();
+      this._removeAttachedInstance();
       this.$.overlay.style.removeProperty('pointer-events');
-      this.removeAttribute('closing');
+      setOverlayStateAttribute(this, 'closing', false);
       this.dispatchEvent(new CustomEvent('vaadin-overlay-closed'));
     }
 
@@ -390,9 +476,9 @@ export const OverlayMixin = (superClass) =>
       if (this.hasAttribute('opening')) {
         this._flushAnimation('opening');
       }
-      if (this._placeholder) {
+      if (this._isAttached) {
         this._exitModalState();
-        this.setAttribute('closing', '');
+        setOverlayStateAttribute(this, 'closing', true);
         this.dispatchEvent(new CustomEvent('vaadin-overlay-closing'));
 
         if (this._shouldAnimate()) {
@@ -407,8 +493,7 @@ export const OverlayMixin = (superClass) =>
 
     /** @private */
     _detachOverlay() {
-      this._placeholder.parentNode.insertBefore(this, this._placeholder);
-      this._placeholder.parentNode.removeChild(this._placeholder);
+      this.hidePopover();
     }
 
     /** @private */
@@ -452,7 +537,6 @@ export const OverlayMixin = (superClass) =>
       }
 
       const evt = new CustomEvent('vaadin-overlay-outside-click', {
-        bubbles: true,
         cancelable: true,
         detail: { sourceEvent: event },
       });
@@ -473,13 +557,12 @@ export const OverlayMixin = (superClass) =>
       }
 
       // Only close modeless overlay on Esc press when it contains focus
-      if (this.modeless && !event.composedPath().includes(this.$.overlay)) {
+      if (!this._shouldAddGlobalListeners() && !event.composedPath().includes(this._focusTrapRoot)) {
         return;
       }
 
       if (event.key === 'Escape') {
         const evt = new CustomEvent('vaadin-overlay-escape-press', {
-          bubbles: true,
           cancelable: true,
           detail: { sourceEvent: event },
         });

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

@@ -4,7 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { getAncestorRootNodes } from '@vaadin/component-base/src/dom-utils.js';
-import { observeMove } from './vaadin-overlay-utils.js';
+import { observeMove, setOverlayStateAttribute } from './vaadin-overlay-utils.js';
 
 const PROP_NAMES_VERTICAL = {
   start: 'top',
@@ -116,13 +116,6 @@ export const PositionMixin = (superClass) =>
       };
     }
 
-    static get observers() {
-      return [
-        '__positionSettingsChanged(horizontalAlign, verticalAlign, noHorizontalOverlap, noVerticalOverlap, requiredVerticalSpace)',
-        '__overlayOpenedChanged(opened, positionTarget)',
-      ];
-    }
-
     constructor() {
       super();
 
@@ -145,6 +138,36 @@ export const PositionMixin = (superClass) =>
       this.__removeUpdatePositionEventListeners();
     }
 
+    /** @protected */
+    updated(props) {
+      super.updated(props);
+
+      if (props.has('positionTarget')) {
+        const oldTarget = props.get('positionTarget');
+
+        // 1. When position target is removed, always reset position settings
+        // 2. When position target is set, reset if overlay was opened before
+        if ((!this.positionTarget && oldTarget) || (this.positionTarget && !oldTarget && !!this.__margins)) {
+          this.__resetPosition();
+        }
+      }
+
+      if (props.has('opened') || props.has('positionTarget')) {
+        this.__updatePositionSettings(this.opened, this.positionTarget);
+      }
+
+      const positionProps = [
+        'horizontalAlign',
+        'verticalAlign',
+        'noHorizontalOverlap',
+        'noVerticalOverlap',
+        'requiredVerticalSpace',
+      ];
+      if (positionProps.some((prop) => props.has(prop))) {
+        this._updatePosition();
+      }
+    }
+
     /** @private */
     __addUpdatePositionEventListeners() {
       window.visualViewport.addEventListener('resize', this._updatePosition);
@@ -181,7 +204,7 @@ export const PositionMixin = (superClass) =>
     }
 
     /** @private */
-    __overlayOpenedChanged(opened, positionTarget) {
+    __updatePositionSettings(opened, positionTarget) {
       this.__removeUpdatePositionEventListeners();
 
       if (positionTarget) {
@@ -210,20 +233,35 @@ export const PositionMixin = (superClass) =>
       }
     }
 
-    __positionSettingsChanged() {
-      this._updatePosition();
-    }
-
     /** @private */
     __onScroll(e) {
       // If the scroll event occurred inside the overlay, ignore it.
-      if (e.target instanceof Node && this.contains(e.target)) {
+      if (e.target instanceof Node && this._deepContains(e.target)) {
         return;
       }
 
       this._updatePosition();
     }
 
+    /** @private */
+    __resetPosition() {
+      this.__margins = null;
+
+      Object.assign(this.style, {
+        justifyContent: '',
+        alignItems: '',
+        top: '',
+        bottom: '',
+        left: '',
+        right: '',
+      });
+
+      setOverlayStateAttribute(this, 'bottom-aligned', false);
+      setOverlayStateAttribute(this, 'top-aligned', false);
+      setOverlayStateAttribute(this, 'end-aligned', false);
+      setOverlayStateAttribute(this, 'start-aligned', false);
+    }
+
     _updatePosition() {
       if (!this.positionTarget || !this.opened || !this.__margins) {
         return;
@@ -271,11 +309,11 @@ export const PositionMixin = (superClass) =>
       // Apply the positioning properties to the overlay
       Object.assign(this.style, verticalProps, horizontalProps);
 
-      this.toggleAttribute('bottom-aligned', !shouldAlignStartVertically);
-      this.toggleAttribute('top-aligned', shouldAlignStartVertically);
+      setOverlayStateAttribute(this, 'bottom-aligned', !shouldAlignStartVertically);
+      setOverlayStateAttribute(this, 'top-aligned', shouldAlignStartVertically);
 
-      this.toggleAttribute('end-aligned', !flexStart);
-      this.toggleAttribute('start-aligned', flexStart);
+      setOverlayStateAttribute(this, 'end-aligned', !flexStart);
+      setOverlayStateAttribute(this, 'start-aligned', flexStart);
     }
 
     __shouldAlignStartHorizontally(targetRect, rtl) {

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

@@ -4,45 +4,43 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 
+/** @type {Set<HTMLElement>} */
+const attachedInstances = new Set();
+
 /**
  * Returns all attached overlays in visual stacking order.
  * @private
  */
-const getAttachedInstances = () =>
-  Array.from(document.body.children)
-    .filter((el) => el instanceof HTMLElement && el._hasOverlayStackMixin && !el.hasAttribute('closing'))
-    .sort((a, b) => a.__zIndex - b.__zIndex || 0);
+const getAttachedInstances = () => [...attachedInstances].filter((el) => !el.hasAttribute('closing'));
 
 /**
- * Returns all attached overlay instances excluding notification container,
- * which only needs to be in the stack for zIndex but not pointer-events.
+ * Returns true if all the instances on top of the overlay are nested overlays.
  * @private
  */
-const getOverlayInstances = () => getAttachedInstances().filter((el) => el.$.overlay);
+const hasOnlyNestedOverlays = (overlay) => {
+  const instances = getAttachedInstances();
+  const next = instances[instances.indexOf(overlay) + 1];
+  if (!next) {
+    return true;
+  }
+
+  if (!overlay._deepContains(next)) {
+    return false;
+  }
+
+  return hasOnlyNestedOverlays(next);
+};
 
 /**
  * Returns true if the overlay is the last one in the opened overlays stack.
  * @param {HTMLElement} overlay
+ * @param {function(HTMLElement): boolean} filter
  * @return {boolean}
  * @protected
  */
-export const isLastOverlay = (overlay) => overlay === getOverlayInstances().pop();
-
-const overlayMap = new WeakMap();
-
-/**
- * Stores the reference to the nested overlay for given parent,
- * or removes it when the nested overlay is null.
- * @param {HTMLElement} parent
- * @param {HTMLElement} nested
- * @protected
- */
-export const setNestedOverlay = (parent, nested) => {
-  if (nested != null) {
-    overlayMap.set(parent, nested);
-  } else {
-    overlayMap.delete(parent);
-  }
+export const isLastOverlay = (overlay, filter = (_overlay) => true) => {
+  const filteredOverlays = getAttachedInstances().filter(filter);
+  return overlay === filteredOverlays.pop();
 };
 
 /**
@@ -50,12 +48,6 @@ export const setNestedOverlay = (parent, nested) => {
  */
 export const OverlayStackMixin = (superClass) =>
   class OverlayStackMixin extends superClass {
-    constructor() {
-      super();
-
-      this._hasOverlayStackMixin = true;
-    }
-
     /**
      * Returns true if this is the last one in the opened overlays stack.
      *
@@ -66,25 +58,36 @@ export const OverlayStackMixin = (superClass) =>
       return isLastOverlay(this);
     }
 
+    /**
+     * Returns true if this is overlay is attached.
+     *
+     * @return {boolean}
+     * @protected
+     */
+    get _isAttached() {
+      return attachedInstances.has(this);
+    }
+
     /**
      * Brings the overlay as visually the frontmost one.
      */
     bringToFront() {
-      let zIndex = '';
-      const frontmost = getAttachedInstances()
-        .filter((o) => o !== this)
-        .pop();
-      if (frontmost) {
-        const frontmostZIndex = frontmost.__zIndex;
-        zIndex = frontmostZIndex + 1;
+      // If the overlay is the last one, or if all other overlays shown above
+      // are nested overlays (e.g. date-picker inside a dialog), do not call
+      // `showPopover()` unnecessarily to avoid scroll position being reset.
+      if (isLastOverlay(this) || hasOnlyNestedOverlays(this)) {
+        return;
       }
-      this.style.zIndex = zIndex;
-      this.__zIndex = zIndex || parseFloat(getComputedStyle(this).zIndex);
 
-      // If there is a nested overlay, call `bringToFront()` for it as well.
-      if (overlayMap.has(this)) {
-        overlayMap.get(this).bringToFront();
+      // Update stacking order of native popover-based overlays
+      if (this.matches(':popover-open')) {
+        this.hidePopover();
+        this.showPopover();
       }
+
+      // Update order of attached instances
+      this._removeAttachedInstance();
+      this._appendAttachedInstance();
     }
 
     /** @protected */
@@ -97,7 +100,7 @@ export const OverlayStackMixin = (superClass) =>
       }
 
       // Disable pointer events in other attached overlays
-      getOverlayInstances().forEach((el) => {
+      getAttachedInstances().forEach((el) => {
         if (el !== this) {
           el.$.overlay.style.pointerEvents = 'none';
         }
@@ -113,7 +116,7 @@ export const OverlayStackMixin = (superClass) =>
       }
 
       // Restore pointer events in the previous overlay(s)
-      const instances = getOverlayInstances();
+      const instances = getAttachedInstances();
 
       let el;
       // Use instances.pop() to ensure the reverse order
@@ -129,4 +132,16 @@ export const OverlayStackMixin = (superClass) =>
         }
       }
     }
+
+    /** @protected */
+    _appendAttachedInstance() {
+      attachedInstances.add(this);
+    }
+
+    /** @protected */
+    _removeAttachedInstance() {
+      if (this._isAttached) {
+        attachedInstances.delete(this);
+      }
+    }
   };

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

@@ -11,3 +11,9 @@
  * https://github.com/floating-ui/floating-ui/blob/58ed169/packages/dom/src/autoUpdate.ts#L45
  */
 export function observeMove(element: HTMLElement, callback: () => void): () => void;
+
+/**
+ * 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.
+ */
+export function setOverlayStateAttribute(overlay: HTMLElement, name: string, value: string | boolean): void;

package/src/vaadin-overlay-utils.js

@@ -16,10 +16,12 @@
  */
 export function observeMove(element, callback) {
   let io = null;
+  let timeout;
 
   const root = document.documentElement;
 
   function cleanup() {
+    timeout && clearTimeout(timeout);
     io && io.disconnect();
     io = null;
   }
@@ -52,27 +54,22 @@ export function observeMove(element, callback) {
     let isFirstUpdate = true;
 
     function handleObserve(entries) {
-      let ratio = entries[0].intersectionRatio;
+      const ratio = entries[0].intersectionRatio;
 
       if (ratio !== threshold) {
         if (!isFirstUpdate) {
           return refresh();
         }
 
-        // It's possible for the watched element to not be at perfect 1.0 visibility when we create
-        // the IntersectionObserver. This has a couple of causes:
-        //   - elements being on partial pixels
-        //   - elements being hidden offscreen (e.g., <html> has `overflow: hidden`)
-        //   - delays: if your DOM change occurs due to e.g., page resize, you can see elements
-        //     behind their actual position
-        //
-        // In all of these cases, refresh but with this lower ratio of threshold. When the element
-        // moves beneath _that_ new value, the user will get notified.
-        if (ratio === 0.0) {
-          ratio = 0.0000001; // Just needs to be non-zero
+        if (!ratio) {
+          // If the reference is clipped, the ratio is 0. Throttle the refresh
+          // to prevent an infinite loop of updates.
+          timeout = setTimeout(() => {
+            refresh(false, 1e-7);
+          }, 1000);
+        } else {
+          refresh(false, ratio);
         }
-
-        refresh(false, ratio);
       }
 
       isFirstUpdate = false;
@@ -87,3 +84,32 @@ export function observeMove(element, callback) {
 
   return cleanup;
 }
+
+/**
+ * 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.
+ * @param {HTMLElement} overlay The overlay element on which to toggle the attribute.
+ * @param {string} name The name of the attribute to toggle.
+ * @param {string|boolean} value The value of the attribute. If a string is provided, it will be set as the attribute
+ * value. Otherwise, the attribute will be added or removed depending on whether `value` is truthy or falsy.
+ */
+export function setOverlayStateAttribute(overlay, name, value) {
+  const elements = [overlay];
+  if (overlay.owner) {
+    elements.push(overlay.owner);
+  }
+
+  if (typeof value === 'string') {
+    elements.forEach((element) => {
+      element.setAttribute(name, value);
+    });
+  } else if (value) {
+    elements.forEach((element) => {
+      element.setAttribute(name, '');
+    });
+  } else {
+    elements.forEach((element) => {
+      element.removeAttribute(name);
+    });
+  }
+}

package/src/vaadin-overlay.d.ts

@@ -17,13 +17,13 @@ export type OverlayOpenedChangedEvent = CustomEvent<{ value: boolean }>;
 /**
  * Fired after the overlay is opened.
  */
-export type OverlayOpenEvent = CustomEvent;
+export type OverlayOpenEvent = CustomEvent<{ overlay: HTMLElement }>;
 
 /**
  * Fired when the opened overlay is about to be closed.
  * Calling `preventDefault()` on the event cancels the closing.
  */
-export type OverlayCloseEvent = CustomEvent;
+export type OverlayCloseEvent = CustomEvent<{ overlay: HTMLElement }>;
 
 /**
  * Fired after the overlay is closed.
@@ -98,10 +98,10 @@ export type OverlayEventMap = HTMLElementEventMap & OverlayCustomEventMap;
  *
  * The following state attributes are available for styling:
  *
- * Attribute | Description | Part
- * ---|---|---
- * `opening` | Applied just after the overlay is attached to the DOM. You can apply a CSS @keyframe animation for this state. | `:host`
- * `closing` | Applied just before the overlay is detached from the DOM. You can apply a CSS @keyframe animation for this state. | `:host`
+ * Attribute | Description
+ * ----------|------------
+ * `opening` | Applied just after the overlay is opened. You can apply a CSS animation for this state.
+ * `closing` | Applied just before the overlay is closed. You can apply a CSS animation for this state.
  *
  * The following custom CSS properties are available for styling:
  *

package/src/vaadin-overlay.js

@@ -7,9 +7,10 @@ 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 { 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';
 import { OverlayMixin } from './vaadin-overlay-mixin.js';
-import { overlayStyles } from './vaadin-overlay-styles.js';
 
 /**
  * `<vaadin-overlay>` is a Web Component for creating overlays. The content of the overlay
@@ -49,10 +50,10 @@ import { overlayStyles } from './vaadin-overlay-styles.js';
  *
  * The following state attributes are available for styling:
  *
- * Attribute | Description | Part
- * ---|---|---
- * `opening` | Applied just after the overlay is attached to the DOM. You can apply a CSS @keyframe animation for this state. | `:host`
- * `closing` | Applied just before the overlay is detached from the DOM. You can apply a CSS @keyframe animation for this state. | `:host`
+ * Attribute | Description
+ * ----------|------------
+ * `opening` | Applied just after the overlay is opened. You can apply a CSS animation for this state.
+ * `closing` | Applied just before the overlay is closed. You can apply a CSS animation for this state.
  *
  * The following custom CSS properties are available for styling:
  *
@@ -76,7 +77,7 @@ import { overlayStyles } from './vaadin-overlay-styles.js';
  * @mixes DirMixin
  * @mixes OverlayMixin
  */
-class Overlay extends OverlayMixin(DirMixin(ThemableMixin(PolylitMixin(LitElement)))) {
+class Overlay extends OverlayMixin(DirMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement))))) {
   static get is() {
     return 'vaadin-overlay';
   }

package/vaadin-overlay.js

@@ -1,2 +1,2 @@
-import './theme/lumo/vaadin-overlay.js';
+import './src/vaadin-overlay.js';
 export * from './src/vaadin-overlay.js';

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

@@ -1,82 +0,0 @@
-/**
- * @license
- * Copyright (c) 2017 - 2025 Vaadin Ltd.
- * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
- */
-import '@vaadin/component-base/src/style-props.js';
-import { css } from 'lit';
-
-export const overlayStyles = css`
-  @layer base {
-    :host {
-      z-index: 200;
-      position: fixed;
-
-      /* Despite of what the names say, <vaadin-overlay> is just a container
-          for position/sizing/alignment. The actual overlay is the overlay part. */
-
-      /* Default position constraints. Themes can
-          override this to adjust the gap between the overlay and the viewport. */
-      inset: 8px;
-      bottom: var(--vaadin-overlay-viewport-bottom);
-
-      /* Use flexbox alignment for the overlay part. */
-      display: flex;
-      flex-direction: column; /* makes dropdowns sizing easier */
-      /* Align to center by default. */
-      align-items: center;
-      justify-content: center;
-
-      /* Allow centering when max-width/max-height applies. */
-      margin: auto;
-
-      /* The host is not clickable, only the overlay part is. */
-      pointer-events: none;
-
-      /* Remove tap highlight on touch devices. */
-      -webkit-tap-highlight-color: transparent;
-
-      /* CSS API for host */
-      --vaadin-overlay-viewport-bottom: 8px;
-    }
-
-    :host([hidden]),
-    :host(:not([opened]):not([closing])),
-    :host(:not([opened]):not([closing])) [part='overlay'] {
-      display: none !important;
-    }
-
-    [part='overlay'] {
-      background: var(--vaadin-overlay-background, var(--_vaadin-background));
-      border: var(--vaadin-overlay-border, 1px solid var(--_vaadin-border-color));
-      border-radius: var(--vaadin-overlay-border-radius, var(--_vaadin-radius-m));
-      box-shadow: var(--vaadin-overlay-box-shadow, 0 8px 24px -4px hsl(0 0 0 / 0.3));
-      box-sizing: border-box;
-      max-width: 100%;
-      overflow: auto;
-      overscroll-behavior: contain;
-      pointer-events: auto;
-      -webkit-tap-highlight-color: initial;
-    }
-
-    [part='backdrop'] {
-      background: var(--vaadin-overlay-backdrop-background, rgba(0, 0, 0, 0.5));
-      content: '';
-      inset: 0;
-      pointer-events: auto;
-      position: fixed;
-      z-index: -1;
-    }
-
-    @media (forced-colors: active) {
-      [part='overlay'] {
-        border: 3px solid;
-      }
-
-      [part='overlay']:focus-visible {
-        outline: var(--vaadin-focus-ring-width) solid;
-        outline-offset: 1px;
-      }
-    }
-  }
-`;

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

@@ -1,67 +0,0 @@
-/**
- * @license
- * Copyright (c) 2017 - 2025 Vaadin Ltd.
- * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
- */
-import { css } from 'lit';
-
-export const overlayStyles = css`
-  :host {
-    z-index: 200;
-    position: fixed;
-
-    /* Despite of what the names say, <vaadin-overlay> is just a container
-          for position/sizing/alignment. The actual overlay is the overlay part. */
-
-    /* Default position constraints: the entire viewport. Note: themes can
-          override this to introduce gaps between the overlay and the viewport. */
-    inset: 0;
-    bottom: var(--vaadin-overlay-viewport-bottom);
-
-    /* Use flexbox alignment for the overlay part. */
-    display: flex;
-    flex-direction: column; /* makes dropdowns sizing easier */
-    /* Align to center by default. */
-    align-items: center;
-    justify-content: center;
-
-    /* Allow centering when max-width/max-height applies. */
-    margin: auto;
-
-    /* The host is not clickable, only the overlay part is. */
-    pointer-events: none;
-
-    /* Remove tap highlight on touch devices. */
-    -webkit-tap-highlight-color: transparent;
-
-    /* CSS API for host */
-    --vaadin-overlay-viewport-bottom: 0;
-  }
-
-  :host([hidden]),
-  :host(:not([opened]):not([closing])),
-  :host(:not([opened]):not([closing])) [part='overlay'] {
-    display: none !important;
-  }
-
-  [part='overlay'] {
-    -webkit-overflow-scrolling: touch;
-    overflow: auto;
-    pointer-events: auto;
-
-    /* Prevent overflowing the host */
-    max-width: 100%;
-    box-sizing: border-box;
-
-    -webkit-tap-highlight-color: initial; /* reenable tap highlight inside */
-  }
-
-  [part='backdrop'] {
-    z-index: -1;
-    content: '';
-    background: rgba(0, 0, 0, 0.5);
-    position: fixed;
-    inset: 0;
-    pointer-events: auto;
-  }
-`;

package/src/vaadin-overlay-styles.js

@@ -1,6 +0,0 @@
-/**
- * @license
- * Copyright (c) 2017 - 2025 Vaadin Ltd.
- * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
- */
-export { overlayStyles } from './vaadin-overlay-core-styles.js';

package/theme/lumo/vaadin-overlay-styles.d.ts

@@ -1 +0,0 @@
-export {};

package/theme/lumo/vaadin-overlay-styles.js

@@ -1,4 +0,0 @@
-import { overlay } from '@vaadin/vaadin-lumo-styles/mixins/overlay.js';
-import { registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
-
-registerStyles('vaadin-overlay', overlay, { moduleId: 'lumo-vaadin-overlay' });

package/theme/lumo/vaadin-overlay.d.ts

@@ -1,2 +0,0 @@
-import './vaadin-overlay-styles.js';
-import '../../src/vaadin-overlay.js';

package/theme/lumo/vaadin-overlay.js

@@ -1,2 +0,0 @@
-import './vaadin-overlay-styles.js';
-import '../../src/vaadin-overlay.js';