@vaadin/master-detail-layout 24.8.0-alpha14 → 24.8.0-alpha16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/master-detail-layout",
-  "version": "24.8.0-alpha14",
+  "version": "24.8.0-alpha16",
   "publishConfig": {
     "access": "public"
   },
@@ -34,15 +34,15 @@
     "web-component"
   ],
   "dependencies": {
-    "@vaadin/a11y-base": "24.8.0-alpha14",
-    "@vaadin/component-base": "24.8.0-alpha14",
-    "@vaadin/vaadin-lumo-styles": "24.8.0-alpha14",
-    "@vaadin/vaadin-material-styles": "24.8.0-alpha14",
-    "@vaadin/vaadin-themable-mixin": "24.8.0-alpha14",
+    "@vaadin/a11y-base": "24.8.0-alpha16",
+    "@vaadin/component-base": "24.8.0-alpha16",
+    "@vaadin/vaadin-lumo-styles": "24.8.0-alpha16",
+    "@vaadin/vaadin-material-styles": "24.8.0-alpha16",
+    "@vaadin/vaadin-themable-mixin": "24.8.0-alpha16",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "24.8.0-alpha14",
+    "@vaadin/chai-plugins": "24.8.0-alpha16",
     "@vaadin/testing-helpers": "^1.1.0",
     "sinon": "^18.0.0"
   },
@@ -50,5 +50,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "c8a33608cf1ab377529afd0650360e349886384c"
+  "gitHead": "ac26cb142cd3d6374423ca699677d47557399d47"
 }

package/src/vaadin-master-detail-layout.d.ts

@@ -8,6 +8,14 @@ import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
 import { SlotStylesMixin } from '@vaadin/component-base/src/slot-styles-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
+export interface MasterDetailLayoutCustomEventMap {
+  'backdrop-click': Event;
+
+  'detail-escape-press': Event;
+}
+
+export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterDetailLayoutCustomEventMap {}
+
 /**
  * `<vaadin-master-detail-layout>` is a web component for building UIs with a master
  * (or primary) area and a detail (or secondary) area that is displayed next to, or
@@ -41,6 +49,9 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * `stack`        | Set when the layout is using the stack mode.
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @fires {CustomEvent} backdrop-click - Fired when the user clicks the backdrop in the overlay mode.
+ * @fires {CustomEvent} detail-escape-press - Fired when the user presses Escape in the detail area.
  */
 declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMixin(ElementMixin(HTMLElement)))) {
   /**
@@ -96,6 +107,9 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
    * there is enough space for master and detail to be shown next to
    * each other using the default (split) mode.
    *
+   * In order to enforce the stack mode, use this property together with
+   * `stackOverlay` property and set both to `true`.
+   *
    * @attr {boolean} force-overlay
    */
   forceOverlay: boolean;
@@ -109,12 +123,15 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
   containment: 'layout' | 'viewport';
 
   /**
-   * The threshold (in CSS length units) at which the layout switches to
-   * the "stack" mode, making detail area fully cover the master area.
+   * When true, the layout in the overlay mode is rendered as a "stack",
+   * making detail area fully cover the master area.
+   *
+   * In order to enforce the stack mode, use this property together with
+   * `forceOverlay` property and set both to `true`.
    *
    * @attr {string} stack-threshold
    */
-  stackThreshold: string | null | undefined;
+  stackOverlay: boolean;
 
   /**
    * When true, the layout does not use animated transitions for the detail area.
@@ -122,6 +139,18 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
    * @attr {boolean} no-animation
    */
   noAnimation: boolean;
+
+  addEventListener<K extends keyof MasterDetailLayoutEventMap>(
+    type: K,
+    listener: (this: MasterDetailLayout, ev: MasterDetailLayoutEventMap[K]) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void;
+
+  removeEventListener<K extends keyof MasterDetailLayoutEventMap>(
+    type: K,
+    listener: (this: MasterDetailLayout, ev: MasterDetailLayoutEventMap[K]) => void,
+    options?: EventListenerOptions | boolean,
+  ): void;
 }
 
 declare global {

package/src/vaadin-master-detail-layout.js

@@ -47,6 +47,9 @@ import { transitionStyles } from './vaadin-master-detail-layout-transition-style
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
+ * @fires {CustomEvent} backdrop-click - Fired when the user clicks the backdrop in the overlay mode.
+ * @fires {CustomEvent} detail-escape-press - Fired when the user presses Escape in the detail area.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ThemableMixin
@@ -207,10 +210,6 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
       :host([stack]) [part='detail'] {
         inset: 0;
       }
-
-      [part='master']::before {
-        background-position-y: var(--_stack-threshold);
-      }
     `;
   }
 
@@ -291,6 +290,9 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
        * there is enough space for master and detail to be shown next to
        * each other using the default (split) mode.
        *
+       * In order to enforce the stack mode, use this property together with
+       * `stackOverlay` property and set both to `true`.
+       *
        * @attr {boolean} force-overlay
        */
       forceOverlay: {
@@ -314,14 +316,18 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
       },
 
       /**
-       * The threshold (in CSS length units) at which the layout switches to
-       * the "stack" mode, making detail area fully cover the master area.
+       * When true, the layout in the overlay mode is rendered as a "stack",
+       * making detail area fully cover the master area.
+       *
+       * In order to enforce the stack mode, use this property together with
+       * `forceOverlay` property and set both to `true`.
        *
        * @attr {string} stack-threshold
        */
-      stackThreshold: {
-        type: String,
-        observer: '__stackThresholdChanged',
+      stackOverlay: {
+        type: Boolean,
+        value: false,
+        observer: '__stackOverlayChanged',
         sync: true,
       },
 
@@ -337,7 +343,6 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
 
       /**
        * When true, the component uses the overlay mode. This property is read-only.
-       * In order to enforce the overlay mode, use `forceOverlay` property.
        * @protected
        */
       _overlay: {
@@ -349,7 +354,6 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
 
       /**
        * When true, the component uses the stack mode. This property is read-only.
-       * In order to enforce the stack mode, use `stackThreshold` property.
        * @protected
        */
       _stack: {
@@ -384,7 +388,7 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
   /** @protected */
   render() {
     return html`
-      <div part="backdrop"></div>
+      <div part="backdrop" @click="${this.__onBackdropClick}"></div>
       <div id="master" part="master" ?inert="${this._hasDetail && this._overlay && this.containment === 'layout'}">
         <slot></slot>
       </div>
@@ -393,6 +397,7 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
         part="detail"
         role="${this._overlay || this._stack ? 'dialog' : nothing}"
         aria-modal="${this._overlay && this.containment === 'viewport' ? 'true' : nothing}"
+        @keydown="${this.__onDetailKeydown}"
       >
         <slot name="detail" @slotchange="${this.__onDetailSlotChange}"></slot>
       </div>
@@ -416,6 +421,20 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
     }
   }
 
+  /** @private */
+  __onBackdropClick() {
+    this.dispatchEvent(new CustomEvent('backdrop-click'));
+  }
+
+  /** @private */
+  __onDetailKeydown(event) {
+    if (event.key === 'Escape') {
+      // Prevent firing on parent layout when using nested layouts
+      event.stopPropagation();
+      this.dispatchEvent(new CustomEvent('detail-escape-press'));
+    }
+  }
+
   /**
    * @protected
    * @override
@@ -463,14 +482,8 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
   }
 
   /** @private */
-  __stackThresholdChanged(threshold, oldThreshold) {
-    if (threshold || oldThreshold) {
-      if (threshold) {
-        this.$.master.style.setProperty('--_stack-threshold', threshold);
-      } else {
-        this.$.master.style.removeProperty('--_stack-threshold');
-      }
-
+  __stackOverlayChanged(stackOverlay, oldStackOverlay) {
+    if (stackOverlay || oldStackOverlay) {
       this.__detectLayoutMode();
     }
   }
@@ -486,30 +499,25 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
     this.toggleAttribute(`has-${prop}`, !!size);
   }
 
+  /** @private */
+  __setOverlayMode(value) {
+    if (this.stackOverlay) {
+      this._stack = value;
+    } else {
+      this._overlay = value;
+    }
+  }
+
   /** @private */
   __detectLayoutMode() {
     this._overlay = false;
     this._stack = false;
 
     if (this.forceOverlay) {
-      this._overlay = true;
+      this.__setOverlayMode(true);
       return;
     }
 
-    if (this.stackThreshold != null) {
-      // Set stack to true to disable masterMinSize and detailMinSize
-      // that would affect size measurements below when in split mode
-      this._stack = true;
-
-      const threshold = this.__getStackThresholdInPixels();
-      const size = this.orientation === 'vertical' ? this.offsetHeight : this.offsetWidth;
-      if (size > threshold) {
-        this._stack = false;
-      } else {
-        return;
-      }
-    }
-
     if (!this._hasDetail) {
       return;
     }
@@ -535,38 +543,28 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
 
     // If the combined minimum size of both the master and the detail content
     // exceeds the size of the layout, the layout changes to the overlay mode.
-    this._overlay = this.offsetWidth < masterWidth + detailWidth;
+    this.__setOverlayMode(this.offsetWidth < masterWidth + detailWidth);
 
     // Toggling the overlay resizes master content, which can cause document
     // scroll bar to appear or disappear, and trigger another resize of the
     // layout which can affect previous measurements and end up in horizontal
     // scroll. Check if that is the case and if so, preserve the overlay mode.
     if (this.offsetWidth < this.scrollWidth) {
-      this._overlay = true;
+      this.__setOverlayMode(true);
     }
   }
 
   /** @private */
   __detectVerticalMode() {
-    // Remove overlay attribute temporarily to detect if there is enough space
-    // for both areas so that layout could switch back to the split mode.
-    this._overlay = false;
-
     const masterHeight = this.$.master.clientHeight;
 
     // If the combined minimum size of both the master and the detail content
     // exceeds the available height, the layout changes to the overlay mode.
     if (this.offsetHeight < masterHeight + this.$.detail.clientHeight) {
-      this._overlay = true;
+      this.__setOverlayMode(true);
     }
   }
 
-  /** @private */
-  __getStackThresholdInPixels() {
-    const { backgroundPositionY } = getComputedStyle(this.$.master, '::before');
-    return parseFloat(backgroundPositionY);
-  }
-
   /**
    * Sets the detail element to be displayed in the detail area and starts a
    * view transition that animates adding, replacing or removing the detail
@@ -675,6 +673,16 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
     this.__transition = null;
     this.__resolveUpdateCallback = null;
   }
+
+  /**
+   * @event backdrop-click
+   * Fired when the user clicks the backdrop in the overlay mode.
+   */
+
+  /**
+   * @event detail-escape-press
+   * Fired when the user presses Escape in the detail area.
+   */
 }
 
 defineCustomElement(MasterDetailLayout);

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/master-detail-layout",
-  "version": "24.8.0-alpha14",
+  "version": "24.8.0-alpha16",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -67,7 +67,7 @@
             },
             {
               "name": "force-overlay",
-              "description": "When specified, forces the layout to use overlay mode, even if\nthere is enough space for master and detail to be shown next to\neach other using the default (split) mode.",
+              "description": "When specified, forces the layout to use overlay mode, even if\nthere is enough space for master and detail to be shown next to\neach other using the default (split) mode.\n\nIn order to enforce the stack mode, use this property together with\n`stackOverlay` property and set both to `true`.",
               "value": {
                 "type": [
                   "boolean",
@@ -88,11 +88,11 @@
               }
             },
             {
-              "name": "stack-threshold",
-              "description": "The threshold (in CSS length units) at which the layout switches to\nthe \"stack\" mode, making detail area fully cover the master area.",
+              "name": "stack-overlay",
+              "description": "When true, the layout in the overlay mode is rendered as a \"stack\",\nmaking detail area fully cover the master area.\n\nIn order to enforce the stack mode, use this property together with\n`forceOverlay` property and set both to `true`.",
               "value": {
                 "type": [
-                  "string",
+                  "boolean",
                   "null",
                   "undefined"
                 ]
@@ -180,7 +180,7 @@
               },
               {
                 "name": "forceOverlay",
-                "description": "When specified, forces the layout to use overlay mode, even if\nthere is enough space for master and detail to be shown next to\neach other using the default (split) mode.",
+                "description": "When specified, forces the layout to use overlay mode, even if\nthere is enough space for master and detail to be shown next to\neach other using the default (split) mode.\n\nIn order to enforce the stack mode, use this property together with\n`stackOverlay` property and set both to `true`.",
                 "value": {
                   "type": [
                     "boolean",
@@ -201,11 +201,11 @@
                 }
               },
               {
-                "name": "stackThreshold",
-                "description": "The threshold (in CSS length units) at which the layout switches to\nthe \"stack\" mode, making detail area fully cover the master area.",
+                "name": "stackOverlay",
+                "description": "When true, the layout in the overlay mode is rendered as a \"stack\",\nmaking detail area fully cover the master area.\n\nIn order to enforce the stack mode, use this property together with\n`forceOverlay` property and set both to `true`.",
                 "value": {
                   "type": [
-                    "string",
+                    "boolean",
                     "null",
                     "undefined"
                   ]
@@ -223,7 +223,16 @@
                 }
               }
             ],
-            "events": []
+            "events": [
+              {
+                "name": "backdrop-click",
+                "description": "backdrop-click\nFired when the user clicks the backdrop in the overlay mode."
+              },
+              {
+                "name": "detail-escape-press",
+                "description": "detail-escape-press\nFired when the user presses Escape in the detail area."
+              }
+            ]
           }
         }
       ]

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/master-detail-layout",
-  "version": "24.8.0-alpha14",
+  "version": "24.8.0-alpha16",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -21,7 +21,14 @@
           "attributes": [
             {
               "name": "?forceOverlay",
-              "description": "When specified, forces the layout to use overlay mode, even if\nthere is enough space for master and detail to be shown next to\neach other using the default (split) mode.",
+              "description": "When specified, forces the layout to use overlay mode, even if\nthere is enough space for master and detail to be shown next to\neach other using the default (split) mode.\n\nIn order to enforce the stack mode, use this property together with\n`stackOverlay` property and set both to `true`.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": "?stackOverlay",
+              "description": "When true, the layout in the overlay mode is rendered as a \"stack\",\nmaking detail area fully cover the master area.\n\nIn order to enforce the stack mode, use this property together with\n`forceOverlay` property and set both to `true`.",
               "value": {
                 "kind": "expression"
               }
@@ -76,8 +83,15 @@
               }
             },
             {
-              "name": ".stackThreshold",
-              "description": "The threshold (in CSS length units) at which the layout switches to\nthe \"stack\" mode, making detail area fully cover the master area.",
+              "name": "@backdrop-click",
+              "description": "backdrop-click\nFired when the user clicks the backdrop in the overlay mode.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": "@detail-escape-press",
+              "description": "detail-escape-press\nFired when the user presses Escape in the detail area.",
               "value": {
                 "kind": "expression"
               }