@vaadin/overlay 24.0.0-alpha12 → 24.0.0-alpha13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/overlay",
-  "version": "24.0.0-alpha12",
+  "version": "24.0.0-alpha13",
   "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-alpha12",
-    "@vaadin/vaadin-lumo-styles": "24.0.0-alpha12",
-    "@vaadin/vaadin-material-styles": "24.0.0-alpha12",
-    "@vaadin/vaadin-themable-mixin": "24.0.0-alpha12"
+    "@vaadin/component-base": "24.0.0-alpha13",
+    "@vaadin/vaadin-lumo-styles": "24.0.0-alpha13",
+    "@vaadin/vaadin-material-styles": "24.0.0-alpha13",
+    "@vaadin/vaadin-themable-mixin": "24.0.0-alpha13"
   },
   "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": "7e29eee4d522fb7b03ac8e7e385e9057d71c79ce"
+  "gitHead": "a423ad309c12b4e4f847737ee9f491f83ea60ff0"
 }

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))) {
   /**
@@ -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
@@ -352,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', {
@@ -411,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
    */
@@ -426,7 +434,8 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
       this._mouseUpInside = false;
       return;
     }
-    if (!this._last) {
+
+    if (!this._shouldCloseOnOutsideClick(event)) {
       return;
     }
 
@@ -443,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) {
@@ -472,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.
@@ -522,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`;
@@ -560,7 +563,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     }
   }
 
-  /** @protected */
+  /** @private */
   _animatedOpening() {
     if (this.parentNode === document.body && this.hasAttribute('closing')) {
       this._flushAnimation('closing');
@@ -580,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);
@@ -588,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');
@@ -646,7 +645,7 @@ class Overlay extends ThemableMixin(DirMixin(ControllerMixin(PolymerElement))) {
     }
   }
 
-  /** @protected */
+  /** @private */
   _detachOverlay() {
     this._placeholder.parentNode.insertBefore(this, this._placeholder);
     this._placeholder.parentNode.removeChild(this._placeholder);
@@ -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);