@vaadin/overlay 24.0.0-alpha9 → 24.0.0-beta2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/overlay",
-  "version": "24.0.0-alpha9",
+  "version": "24.0.0-beta2",
   "publishConfig": {
     "access": "public"
   },
@@ -36,16 +36,16 @@
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/component-base": "24.0.0-alpha9",
-    "@vaadin/vaadin-lumo-styles": "24.0.0-alpha9",
-    "@vaadin/vaadin-material-styles": "24.0.0-alpha9",
-    "@vaadin/vaadin-themable-mixin": "24.0.0-alpha9"
+    "@vaadin/component-base": "24.0.0-beta2",
+    "@vaadin/vaadin-lumo-styles": "24.0.0-beta2",
+    "@vaadin/vaadin-material-styles": "24.0.0-beta2",
+    "@vaadin/vaadin-themable-mixin": "24.0.0-beta2"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.3.2",
+    "@vaadin/testing-helpers": "^0.4.0",
     "lit": "^2.0.0",
     "sinon": "^13.0.2"
   },
-  "gitHead": "cc3f747164041566b300bde4b105d2475649e93f"
+  "gitHead": "00086f1f6d487f042f189c9b9ecd7ba736960888"
 }

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

@@ -54,4 +54,14 @@ export declare class PositionMixinClass {
    * @attr {boolean} no-vertical-overlap
    */
   noVerticalOverlap: boolean;
+
+  /**
+   * If the overlay content has no intrinsic height, this property can be used to set
+   * the minimum vertical space (in pixels) required by the overlay. Setting a value to
+   * the property effectively disables the content measurement in favor of using this
+   * fixed value for determining the open direction.
+   *
+   * @attr {number} required-vertical-space
+   */
+  requiredVerticalSpace: number;
 }

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

@@ -93,12 +93,25 @@ export const PositionMixin = (superClass) =>
           type: Boolean,
           value: false,
         },
+
+        /**
+         * If the overlay content has no intrinsic height, this property can be used to set
+         * the minimum vertical space (in pixels) required by the overlay. Setting a value to
+         * the property effectively disables the content measurement in favor of using this
+         * fixed value for determining the open direction.
+         *
+         * @attr {number} required-vertical-space
+         */
+        requiredVerticalSpace: {
+          type: Number,
+          value: 0,
+        },
       };
     }
 
     static get observers() {
       return [
-        '__positionSettingsChanged(horizontalAlign, verticalAlign, noHorizontalOverlap, noVerticalOverlap)',
+        '__positionSettingsChanged(horizontalAlign, verticalAlign, noHorizontalOverlap, noVerticalOverlap, requiredVerticalSpace)',
         '__overlayOpenedChanged(opened, positionTarget)',
       ];
     }
@@ -262,7 +275,8 @@ export const PositionMixin = (superClass) =>
     __shouldAlignStartVertically(targetRect) {
       // Using previous size to fix a case where window resize may cause the overlay to be squeezed
       // smaller than its current space before the fit-calculations.
-      const contentHeight = Math.max(this.__oldContentHeight || 0, this.$.overlay.offsetHeight);
+      const contentHeight =
+        this.requiredVerticalSpace || Math.max(this.__oldContentHeight || 0, this.$.overlay.offsetHeight);
       this.__oldContentHeight = this.$.overlay.offsetHeight;
 
       const viewportHeight = Math.min(window.innerHeight, document.documentElement.clientHeight);

package/src/vaadin-overlay.d.ts

@@ -20,25 +20,31 @@ export type OverlayOpenedChangedEvent = CustomEvent<{ value: boolean }>;
 export type OverlayOpenEvent = CustomEvent;
 
 /**
- * Fired before the overlay will be closed.
- * If canceled the closing of the overlay is canceled as well.
+ * Fired when the opened overlay is about to be closed.
+ * Calling `preventDefault()` on the event cancels the closing.
  */
 export type OverlayCloseEvent = CustomEvent;
 
 /**
- * Fired when the overlay will be closed.
+ * Fired after the overlay is closed.
+ */
+export type OverlayClosedEvent = CustomEvent;
+
+/**
+ * Fired when the overlay starts to close.
+ * Closing the overlay can be asynchronous depending on the animation.
  */
 export type OverlayClosingEvent = CustomEvent;
 
 /**
- * Fired before the overlay will be closed on outside click.
- * If canceled the closing of the overlay is canceled as well.
+ * Fired before the overlay is closed on outside click.
+ * Calling `preventDefault()` on the event cancels the closing.
  */
 export type OverlayOutsideClickEvent = CustomEvent<{ sourceEvent: MouseEvent }>;
 
 /**
- * Fired before the overlay will be closed on ESC button press.
- * If canceled the closing of the overlay is canceled as well.
+ * Fired before the overlay is closed on Escape key press.
+ * Calling `preventDefault()` on the event cancels the closing.
  */
 export type OverlayEscapePressEvent = CustomEvent<{ sourceEvent: KeyboardEvent }>;
 
@@ -46,6 +52,7 @@ export interface OverlayCustomEventMap {
   'opened-changed': OverlayOpenedChangedEvent;
   'vaadin-overlay-open': OverlayOpenEvent;
   'vaadin-overlay-close': OverlayCloseEvent;
+  'vaadin-overlay-closed': OverlayClosedEvent;
   'vaadin-overlay-closing': OverlayClosingEvent;
   'vaadin-overlay-outside-click': OverlayOutsideClickEvent;
   'vaadin-overlay-escape-press': OverlayEscapePressEvent;
@@ -106,10 +113,11 @@ export type OverlayEventMap = HTMLElementEventMap & OverlayCustomEventMap;
  *
  * @fires {CustomEvent} opened-changed - Fired when the `opened` property changes.
  * @fires {CustomEvent} vaadin-overlay-open - Fired after the overlay is opened.
- * @fires {CustomEvent} vaadin-overlay-close - Fired before the overlay will be closed. If canceled the closing of the overlay is canceled as well.
- * @fires {CustomEvent} vaadin-overlay-closing - Fired when the overlay will be closed.
- * @fires {CustomEvent} vaadin-overlay-outside-click - Fired before the overlay will be closed on outside click. If canceled the closing of the overlay is canceled as well.
- * @fires {CustomEvent} vaadin-overlay-escape-press - Fired before the overlay will be closed on ESC button press. If canceled the closing of the overlay is canceled as well.
+ * @fires {CustomEvent} vaadin-overlay-close - Fired when the opened overlay is about to be closed. Calling `preventDefault()` on the event cancels the closing.
+ * @fires {CustomEvent} vaadin-overlay-closing - Fired when the overlay starts to close. Closing the overlay can be asynchronous depending on the animation.
+ * @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.
  */
 declare class Overlay extends ThemableMixin(DirMixin(ControllerMixin(HTMLElement))) {
   /**
@@ -144,7 +152,7 @@ declare class Overlay extends ThemableMixin(DirMixin(ControllerMixin(HTMLElement
 
   /**
    * When true the overlay won't disable the main content, showing
-   * it doesn’t change the functionality of the user interface.
+   * it doesn't change the functionality of the user interface.
    */
   modeless: boolean;
 
@@ -171,6 +179,11 @@ declare class Overlay extends ThemableMixin(DirMixin(ControllerMixin(HTMLElement
    */
   restoreFocusNode?: HTMLElement;
 
+  /**
+   * Returns true if this is the last one in the opened overlays stack.
+   */
+  protected readonly _last: boolean;
+
   close(sourceEvent?: Event | null): void;
 
   /**
@@ -197,6 +210,14 @@ declare class Overlay extends ThemableMixin(DirMixin(ControllerMixin(HTMLElement
     listener: (this: Overlay, ev: OverlayEventMap[K]) => void,
     options?: EventListenerOptions | boolean,
   ): void;
+
+  protected _flushAnimation(type: 'closing' | 'opening'): void;
+
+  /**
+   * Whether to close the overlay on outside click or not.
+   * Override this method to customize the closing logic.
+   */
+  protected _shouldCloseOnOutsideClick(event: Event): boolean;
 }
 
 declare global {

package/src/vaadin-overlay.js

@@ -65,10 +65,11 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  *
  * @fires {CustomEvent} opened-changed - Fired when the `opened` property changes.
  * @fires {CustomEvent} vaadin-overlay-open - Fired after the overlay is opened.
- * @fires {CustomEvent} vaadin-overlay-close - Fired before the overlay will be closed. If canceled the closing of the overlay is canceled as well.
- * @fires {CustomEvent} vaadin-overlay-closing - Fired when the overlay will be closed.
- * @fires {CustomEvent} vaadin-overlay-outside-click - Fired before the overlay will be closed on outside click. If canceled the closing of the overlay is canceled as well.
- * @fires {CustomEvent} vaadin-overlay-escape-press - Fired before the overlay will be closed on ESC button press. If canceled the closing of the overlay is canceled as well.
+ * @fires {CustomEvent} vaadin-overlay-close - Fired when the opened overlay is about to be closed. Calling `preventDefault()` on the event cancels the closing.
+ * @fires {CustomEvent} vaadin-overlay-closing - Fired when the overlay starts to close. Closing the overlay can be asynchronous depending on the animation.
+ * @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.
  *
  * @extends HTMLElement
  * @mixes ThemableMixin
@@ -202,7 +203,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
 
       /**
        * When true the overlay won't disable the main content, showing
-       * it doesn’t change the functionality of the user interface.
+       * it doesn't change the functionality of the user interface.
        * @type {boolean}
        */
       modeless: {
@@ -279,6 +280,16 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     return ['_rendererOrDataChanged(renderer, owner, model, opened)'];
   }
 
+  /**
+   * Returns all attached overlays in visual stacking order.
+   * @private
+   */
+  static get __attachedInstances() {
+    return Array.from(document.body.children)
+      .filter((el) => el instanceof Overlay && !el.hasAttribute('closing'))
+      .sort((a, b) => a.__zIndex - b.__zIndex || 0);
+  }
+
   constructor() {
     super();
     this._boundMouseDownListener = this._mouseDownListener.bind(this);
@@ -294,6 +305,15 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     this.__focusTrapController = new FocusTrapController(this);
   }
 
+  /**
+   * Returns true if this is the last one in the opened overlays stack
+   * @return {boolean}
+   * @protected
+   */
+  get _last() {
+    return this === Overlay.__attachedInstances.pop();
+  }
+
   /** @protected */
   ready() {
     super.ready();
@@ -333,8 +353,6 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
 
   /**
    * @param {Event=} sourceEvent
-   * @event vaadin-overlay-close
-   * fired before the `vaadin-overlay` will be closed. If canceled the closing of the overlay is canceled as well.
    */
   close(sourceEvent) {
     const evt = new CustomEvent('vaadin-overlay-close', {
@@ -392,12 +410,21 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
   }
 
   /**
-   * We need to listen on 'click' / 'tap' event and capture it and close the overlay before
-   * propagating the event to the listener in the button. Otherwise, if the clicked button would call
-   * open(), this would happen: https://www.youtube.com/watch?v=Z86V_ICUCD4
+   * Whether to close the overlay on outside click or not.
+   * Override this method to customize the closing logic.
    *
-   * @event vaadin-overlay-outside-click
-   * fired before the `vaadin-overlay` will be closed on outside click. If canceled the closing of the overlay is canceled as well.
+   * @param {Event} _event
+   * @return {boolean}
+   * @protected
+   */
+  _shouldCloseOnOutsideClick(_event) {
+    return this._last;
+  }
+
+  /**
+   * Outside click listener used in capture phase to close the overlay before
+   * propagating the event to the listener on the element that triggered it.
+   * Otherwise, calling `open()` would result in closing and re-opening.
    *
    * @private
    */
@@ -407,7 +434,8 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
       this._mouseUpInside = false;
       return;
     }
-    if (!this._last) {
+
+    if (!this._shouldCloseOnOutsideClick(event)) {
       return;
     }
 
@@ -424,9 +452,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
   }
 
   /**
-   * @event vaadin-overlay-escape-press
-   * fired before the `vaadin-overlay` will be closed on ESC button press. If canceled the closing of the overlay is canceled as well.
-   *
+   * Listener used to close whe overlay on Escape press, if it is the last one.
    * @private
    */
   _keydownListener(event) {
@@ -453,12 +479,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     }
   }
 
-  /**
-   * @event vaadin-overlay-open
-   * fired after the `vaadin-overlay` is opened.
-   *
-   * @private
-   */
+  /** @private */
   _openedChanged(opened, wasOpened) {
     if (opened) {
       // Store focused node.
@@ -503,18 +524,19 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
 
   /**
    * @return {boolean}
-   * @protected
+   * @private
    */
   _shouldAnimate() {
-    const name = getComputedStyle(this).getPropertyValue('animation-name');
-    const hidden = getComputedStyle(this).getPropertyValue('display') === 'none';
+    const style = getComputedStyle(this);
+    const name = style.getPropertyValue('animation-name');
+    const hidden = style.getPropertyValue('display') === 'none';
     return !hidden && name && name !== 'none';
   }
 
   /**
    * @param {string} type
    * @param {Function} callback
-   * @protected
+   * @private
    */
   _enqueueAnimation(type, callback) {
     const handler = `__${type}Handler`;
@@ -541,7 +563,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     }
   }
 
-  /** @protected */
+  /** @private */
   _animatedOpening() {
     if (this.parentNode === document.body && this.hasAttribute('closing')) {
       this._flushAnimation('closing');
@@ -561,7 +583,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     }
   }
 
-  /** @protected */
+  /** @private */
   _attachOverlay() {
     this._placeholder = document.createComment('vaadin-overlay-placeholder');
     this.parentNode.insertBefore(this._placeholder, this);
@@ -569,24 +591,20 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     this.bringToFront();
   }
 
-  /** @protected */
+  /** @private */
   _finishOpening() {
     this.removeAttribute('opening');
   }
 
-  /** @protected */
+  /** @private */
   _finishClosing() {
     this._detachOverlay();
     this.$.overlay.style.removeProperty('pointer-events');
     this.removeAttribute('closing');
+    this.dispatchEvent(new CustomEvent('vaadin-overlay-closed'));
   }
 
-  /**
-   * @event vaadin-overlay-closing
-   * Fired when the overlay will be closed.
-   *
-   * @protected
-   */
+  /** @private */
   _animatedClosing() {
     if (this.hasAttribute('opening')) {
       this._flushAnimation('opening');
@@ -627,31 +645,12 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     }
   }
 
-  /** @protected */
+  /** @private */
   _detachOverlay() {
     this._placeholder.parentNode.insertBefore(this, this._placeholder);
     this._placeholder.parentNode.removeChild(this._placeholder);
   }
 
-  /**
-   * Returns all attached overlays in visual stacking order.
-   * @private
-   */
-  static get __attachedInstances() {
-    return Array.from(document.body.children)
-      .filter((el) => el instanceof Overlay && !el.hasAttribute('closing'))
-      .sort((a, b) => a.__zIndex - b.__zIndex || 0);
-  }
-
-  /**
-   * Returns true if this is the last one in the opened overlays stack
-   * @return {boolean}
-   * @protected
-   */
-  get _last() {
-    return this === Overlay.__attachedInstances.pop();
-  }
-
   /** @private */
   _modelessChanged(modeless) {
     if (!modeless) {
@@ -665,7 +664,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     }
   }
 
-  /** @protected */
+  /** @private */
   _addGlobalListeners() {
     document.addEventListener('mousedown', this._boundMouseDownListener);
     document.addEventListener('mouseup', this._boundMouseUpListener);
@@ -674,7 +673,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     document.documentElement.addEventListener('click', this._boundOutsideClickListener, true);
   }
 
-  /** @protected */
+  /** @private */
   _enterModalState() {
     if (document.body.style.pointerEvents !== 'none') {
       // Set body pointer-events to 'none' to disable mouse interactions with
@@ -691,14 +690,14 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     });
   }
 
-  /** @protected */
+  /** @private */
   _removeGlobalListeners() {
     document.removeEventListener('mousedown', this._boundMouseDownListener);
     document.removeEventListener('mouseup', this._boundMouseUpListener);
     document.documentElement.removeEventListener('click', this._boundOutsideClickListener, true);
   }
 
-  /** @protected */
+  /** @private */
   _exitModalState() {
     if (this._previousDocumentPointerEvents !== undefined) {
       // Restore body pointer-events
@@ -750,7 +749,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
 
   /**
    * @return {!Element}
-   * @protected
+   * @private
    */
   _getActiveElement() {
     // Document.activeElement can be null
@@ -765,7 +764,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
   /**
    * @param {!Node} node
    * @return {boolean}
-   * @protected
+   * @private
    */
   _deepContains(node) {
     if (this.contains(node)) {
@@ -793,6 +792,40 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     this.style.zIndex = zIndex;
     this.__zIndex = zIndex || parseFloat(getComputedStyle(this).zIndex);
   }
+
+  /**
+   * @event vaadin-overlay-open
+   * Fired after the overlay is opened.
+   */
+
+  /**
+   * @event vaadin-overlay-close
+   * Fired when the opened overlay is about to be closed.
+   * Calling `preventDefault()` on the event cancels the closing.
+   */
+
+  /**
+   * @event vaadin-overlay-closing
+   * Fired when the overlay starts to close.
+   * Closing the overlay can be asynchronous depending on the animation.
+   */
+
+  /**
+   * @event vaadin-overlay-closed
+   * Fired after the overlay is closed.
+   */
+
+  /**
+   * @event vaadin-overlay-escape-press
+   * Fired before the overlay is closed on Escape key press.
+   * Calling `preventDefault()` on the event cancels the closing.
+   */
+
+  /**
+   * @event vaadin-overlay-outside-click
+   * Fired before the overlay is closed on outside click.
+   * Calling `preventDefault()` on the event cancels the closing.
+   */
 }
 
 customElements.define(Overlay.is, Overlay);