@vaadin/master-detail-layout 24.8.0-alpha8 → 24.8.0-beta1

package/README.md

@@ -2,6 +2,8 @@
 
 A web component for building UIs with a master (or primary) area and a detail (or secondary) area.
 
+> ⚠️ This component is experimental and the API may change. In order to use it, enable the feature flag by setting `window.Vaadin.featureFlags.masterDetailLayoutComponent = true`.
+
 ```html
 <vaadin-master-detail-layout>
   <div>Master content</div>

package/package.json

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

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

@@ -23,43 +23,43 @@ export const transitionStyles = css`
     animation-duration: var(--vaadin-master-detail-layout-transition-duration, 300ms);
   }
 
-  /* Overlay - horizontal - add */
+  /* Drawer - horizontal - add */
 
-  vaadin-master-detail-layout[overlay][orientation='horizontal'][transition='add']::part(detail) {
-    view-transition-name: vaadin-master-detail-layout-overlay-horizontal-detail-add;
+  vaadin-master-detail-layout[drawer][orientation='horizontal'][transition='add']::part(detail) {
+    view-transition-name: vaadin-master-detail-layout-drawer-horizontal-detail-add;
   }
 
-  ::view-transition-group(vaadin-master-detail-layout-overlay-horizontal-detail-add) {
+  ::view-transition-group(vaadin-master-detail-layout-drawer-horizontal-detail-add) {
     clip-path: inset(0);
   }
 
-  ::view-transition-new(vaadin-master-detail-layout-overlay-horizontal-detail-add) {
+  ::view-transition-new(vaadin-master-detail-layout-drawer-horizontal-detail-add) {
     animation: var(--vaadin-master-detail-layout-transition-duration, 300ms) ease both
-      vaadin-master-detail-layout-overlay-horizontal-detail-add;
+      vaadin-master-detail-layout-drawer-horizontal-detail-add;
   }
 
-  @keyframes vaadin-master-detail-layout-overlay-horizontal-detail-add {
+  @keyframes vaadin-master-detail-layout-drawer-horizontal-detail-add {
     from {
       transform: translateX(calc(100% * var(--_vaadin-master-detail-layout-dir-multiplier)));
     }
   }
 
-  /* Overlay - horizontal - remove */
+  /* Drawer - horizontal - remove */
 
-  vaadin-master-detail-layout[overlay][orientation='horizontal'][transition='remove']::part(detail) {
-    view-transition-name: vaadin-master-detail-layout-overlay-horizontal-detail-remove;
+  vaadin-master-detail-layout[drawer][orientation='horizontal'][transition='remove']::part(detail) {
+    view-transition-name: vaadin-master-detail-layout-drawer-horizontal-detail-remove;
   }
 
-  ::view-transition-group(vaadin-master-detail-layout-overlay-horizontal-detail-remove) {
+  ::view-transition-group(vaadin-master-detail-layout-drawer-horizontal-detail-remove) {
     clip-path: inset(0);
   }
 
-  ::view-transition-old(vaadin-master-detail-layout-overlay-horizontal-detail-remove) {
+  ::view-transition-old(vaadin-master-detail-layout-drawer-horizontal-detail-remove) {
     animation: var(--vaadin-master-detail-layout-transition-duration, 300ms) ease both
-      vaadin-master-detail-layout-overlay-horizontal-detail-remove;
+      vaadin-master-detail-layout-drawer-horizontal-detail-remove;
   }
 
-  @keyframes vaadin-master-detail-layout-overlay-horizontal-detail-remove {
+  @keyframes vaadin-master-detail-layout-drawer-horizontal-detail-remove {
     to {
       transform: translateX(calc(100% * var(--_vaadin-master-detail-layout-dir-multiplier)));
     }
@@ -133,43 +133,65 @@ export const transitionStyles = css`
     }
   }
 
-  /* Overlay - vertical - add */
+  /* Stack - horizontal - viewport - add */
 
-  vaadin-master-detail-layout[overlay][orientation='vertical'][transition='add']::part(detail) {
-    view-transition-name: vaadin-master-detail-layout-overlay-vertical-detail-add;
+  vaadin-master-detail-layout[stack][orientation='horizontal'][containment='viewport'][transition='add'] {
+    view-transition-name: vaadin-master-detail-layout-stack-horizontal-viewport-add;
   }
 
-  ::view-transition-group(vaadin-master-detail-layout-overlay-vertical-detail-add) {
+  ::view-transition-new(vaadin-master-detail-layout-stack-horizontal-viewport-add) {
+    animation: var(--vaadin-master-detail-layout-transition-duration, 300ms) ease both
+      vaadin-master-detail-layout-stack-horizontal-add-new;
+  }
+
+  /* Stack - horizontal - viewport - remove */
+
+  vaadin-master-detail-layout[stack][orientation='horizontal'][containment='viewport'][transition='remove'] {
+    view-transition-name: vaadin-master-detail-layout-stack-horizontal-viewport-remove;
+  }
+
+  ::view-transition-old(vaadin-master-detail-layout-stack-horizontal-viewport-remove) {
+    animation: var(--vaadin-master-detail-layout-transition-duration, 300ms) ease both
+      vaadin-master-detail-layout-stack-horizontal-remove-old;
+  }
+
+  /* Drawer - vertical - add */
+
+  vaadin-master-detail-layout[drawer][orientation='vertical'][transition='add']::part(detail) {
+    view-transition-name: vaadin-master-detail-layout-drawer-vertical-detail-add;
+  }
+
+  ::view-transition-group(vaadin-master-detail-layout-drawer-vertical-detail-add) {
     clip-path: inset(0);
   }
 
-  ::view-transition-new(vaadin-master-detail-layout-overlay-vertical-detail-add) {
+  ::view-transition-new(vaadin-master-detail-layout-drawer-vertical-detail-add) {
     animation: var(--vaadin-master-detail-layout-transition-duration, 300ms) ease both
-      vaadin-master-detail-layout-overlay-vertical-detail-add;
+      vaadin-master-detail-layout-drawer-vertical-detail-add;
   }
 
-  @keyframes vaadin-master-detail-layout-overlay-vertical-detail-add {
+  @keyframes vaadin-master-detail-layout-drawer-vertical-detail-add {
     from {
       transform: translateY(100%);
     }
   }
 
-  /* Overlay - vertical - remove */
+  /* Drawer - vertical - remove */
 
-  vaadin-master-detail-layout[overlay][orientation='vertical'][transition='remove']::part(detail) {
-    view-transition-name: vaadin-master-detail-layout-overlay-vertical-detail-remove;
+  vaadin-master-detail-layout[drawer][orientation='vertical'][transition='remove']::part(detail) {
+    view-transition-name: vaadin-master-detail-layout-drawer-vertical-detail-remove;
   }
 
-  ::view-transition-group(vaadin-master-detail-layout-overlay-vertical-detail-remove) {
+  ::view-transition-group(vaadin-master-detail-layout-drawer-vertical-detail-remove) {
     clip-path: inset(0);
   }
 
-  ::view-transition-old(vaadin-master-detail-layout-overlay-vertical-detail-remove) {
+  ::view-transition-old(vaadin-master-detail-layout-drawer-vertical-detail-remove) {
     animation: var(--vaadin-master-detail-layout-transition-duration, 300ms) ease both
-      vaadin-master-detail-layout-overlay-vertical-detail-remove;
+      vaadin-master-detail-layout-drawer-vertical-detail-remove;
   }
 
-  @keyframes vaadin-master-detail-layout-overlay-vertical-detail-remove {
+  @keyframes vaadin-master-detail-layout-drawer-vertical-detail-remove {
     to {
       transform: translateY(100%);
     }
@@ -242,4 +264,26 @@ export const transitionStyles = css`
       opacity: 0;
     }
   }
+
+  /* Stack - vertical - viewport - add */
+
+  vaadin-master-detail-layout[stack][orientation='vertical'][containment='viewport'][transition='add'] {
+    view-transition-name: vaadin-master-detail-layout-stack-vertical-viewport-add;
+  }
+
+  ::view-transition-new(vaadin-master-detail-layout-stack-vertical-viewport-add) {
+    animation: var(--vaadin-master-detail-layout-transition-duration, 300ms) ease both
+      vaadin-master-detail-layout-stack-vertical-add-new;
+  }
+
+  /* Stack - vertical - viewport - remove */
+
+  vaadin-master-detail-layout[stack][orientation='vertical'][containment='viewport'][transition='remove'] {
+    view-transition-name: vaadin-master-detail-layout-stack-vertical-viewport-remove;
+  }
+
+  ::view-transition-old(vaadin-master-detail-layout-stack-vertical-viewport-remove) {
+    animation: var(--vaadin-master-detail-layout-transition-duration, 300ms) ease both
+      vaadin-master-detail-layout-stack-vertical-remove-old;
+  }
 `;

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
@@ -26,7 +34,7 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  *
  * Part name      | Description
  * ---------------|----------------------
- * `backdrop`     | Backdrop covering the master area in the overlay mode
+ * `backdrop`     | Backdrop covering the master area in the drawer mode
  * `master`       | The master area
  * `detail`       | The detail area
  *
@@ -37,17 +45,21 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * `containment`  | Set to `layout` or `viewport` depending on the containment.
  * `orientation`  | Set to `horizontal` or `vertical` depending on the orientation.
  * `has-detail`   | Set when the detail content is provided.
- * `overlay`      | Set when the layout is using the overlay mode.
+ * `drawer`       | Set when the layout is using the drawer mode.
  * `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 drawer 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)))) {
   /**
    * Fixed size (in CSS length units) to be set on the detail area.
    * When specified, it prevents the detail area from growing or
    * shrinking. If there is not enough space to show master and detail
-   * areas next to each other, the layout switches to the overlay mode.
+   * areas next to each other, the details are shown as an overlay:
+   * either as drawer or stack, depending on the `stackOverlay` property.
    *
    * @attr {string} detail-size
    */
@@ -57,7 +69,8 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
    * Minimum size (in CSS length units) to be set on the detail area.
    * When specified, it prevents the detail area from shrinking below
    * this size. If there is not enough space to show master and detail
-   * areas next to each other, the layout switches to the overlay mode.
+   * areas next to each other, the details are shown as an overlay:
+   * either as drawer or stack, depending on the `stackOverlay` property.
    *
    * @attr {string} detail-min-size
    */
@@ -67,7 +80,8 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
    * Fixed size (in CSS length units) to be set on the master area.
    * When specified, it prevents the master area from growing or
    * shrinking. If there is not enough space to show master and detail
-   * areas next to each other, the layout switches to the overlay mode.
+   * areas next to each other, the details are shown as an overlay:
+   * either as drawer or stack, depending on the `stackOverlay` property.
    *
    * @attr {string} master-size
    */
@@ -77,7 +91,8 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
    * Minimum size (in CSS length units) to be set on the master area.
    * When specified, it prevents the master area from shrinking below
    * this size. If there is not enough space to show master and detail
-   * areas next to each other, the layout switches to the overlay mode.
+   * areas next to each other, the details are shown as an overlay:
+   * either as drawer or stack, depending on the `stackOverlay` property.
    *
    * @attr {string} master-min-size
    */
@@ -92,9 +107,13 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
   orientation: 'horizontal' | 'vertical';
 
   /**
-   * When specified, forces the layout to use overlay mode, even if
-   * there is enough space for master and detail to be shown next to
-   * each other using the default (split) mode.
+   * When specified, forces the details to be shown as an overlay
+   * (either as drawer or stack), even if 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
    */
@@ -109,12 +128,16 @@ 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. Otherwise, it is
+   * rendered as a drawer and has a visual backdrop.
+   *
+   * 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 +145,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

@@ -31,7 +31,7 @@ import { transitionStyles } from './vaadin-master-detail-layout-transition-style
  *
  * Part name      | Description
  * ---------------|----------------------
- * `backdrop`     | Backdrop covering the master area in the overlay mode
+ * `backdrop`     | Backdrop covering the master area in the drawer mode
  * `master`       | The master area
  * `detail`       | The detail area
  *
@@ -42,11 +42,14 @@ import { transitionStyles } from './vaadin-master-detail-layout-transition-style
  * `containment`  | Set to `layout` or `viewport` depending on the containment.
  * `orientation`  | Set to `horizontal` or `vertical` depending on the orientation.
  * `has-detail`   | Set when the detail content is provided.
- * `overlay`      | Set when the layout is using the overlay mode.
+ * `drawer`       | Set when the layout is using the drawer mode.
  * `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 drawer mode.
+ * @fires {CustomEvent} detail-escape-press - Fired when the user presses Escape in the detail area.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ThemableMixin
@@ -76,41 +79,46 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
         display: none;
       }
 
-      /* Overlay mode */
-      :host(:is([overlay], [stack])) {
+      :host([orientation='horizontal']) [part='master'] {
+        max-width: 100%;
+      }
+
+      /* Drawer mode */
+      :host(:is([drawer], [stack])) {
         position: relative;
       }
 
-      :host(:is([overlay], [stack])[containment='layout']) [part='detail'],
-      :host([overlay][containment='layout']) [part='backdrop'] {
+      :host(:is([drawer], [stack])[containment='layout']) [part='detail'],
+      :host([drawer][containment='layout']) [part='backdrop'] {
         position: absolute;
       }
 
-      :host(:is([overlay], [stack])[containment='viewport']) [part='detail'],
-      :host([overlay][containment='viewport']) [part='backdrop'] {
+      :host(:is([drawer], [stack])[containment='viewport']) [part='detail'],
+      :host([drawer][containment='viewport']) [part='backdrop'] {
         position: fixed;
       }
 
-      :host([overlay][has-detail]) [part='backdrop'] {
+      :host([drawer][has-detail]) [part='backdrop'] {
         display: block;
         inset: 0;
+        z-index: 1;
       }
 
-      :host([overlay][orientation='horizontal']) [part='detail'] {
+      :host(:is([drawer], [stack])) [part='detail'] {
+        z-index: 1;
+      }
+
+      :host([drawer][orientation='horizontal']) [part='detail'] {
         inset-inline-end: 0;
         height: 100%;
         width: var(--_detail-min-size, min-content);
         max-width: 100%;
       }
 
-      :host([overlay][orientation='horizontal'][containment='viewport']) [part='detail'] {
+      :host([drawer][orientation='horizontal'][containment='viewport']) [part='detail'] {
         inset-block-start: 0;
       }
 
-      :host([overlay][orientation='horizontal']) [part='master'] {
-        max-width: 100%;
-      }
-
       /* No fixed size */
       :host(:not([has-master-size])) [part='master'],
       :host(:not([has-detail-size])) [part='detail'] {
@@ -143,11 +151,11 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
       }
 
       /* Min size */
-      :host([has-master-min-size][orientation='horizontal']:not([overlay])) [part='master'] {
+      :host([has-master-min-size][has-detail][orientation='horizontal']:not([drawer]):not([stack])) [part='master'] {
         min-width: var(--_master-min-size);
       }
 
-      :host([has-detail-min-size][orientation='horizontal']:not([overlay]):not([stack])) [part='detail'] {
+      :host([has-detail-min-size][orientation='horizontal']:not([drawer]):not([stack])) [part='detail'] {
         min-width: var(--_detail-min-size);
       }
 
@@ -161,17 +169,17 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
         flex-direction: column;
       }
 
-      :host([orientation='vertical'][overlay]) [part='master'] {
+      :host([orientation='vertical'][drawer]) [part='master'] {
         max-height: 100%;
       }
 
-      :host([orientation='vertical'][overlay]) [part='detail'] {
+      :host([orientation='vertical'][drawer]) [part='detail'] {
         inset-block-end: 0;
         width: 100%;
         height: var(--_detail-min-size, min-content);
       }
 
-      :host([overlay][orientation='vertical'][containment='viewport']) [part='detail'] {
+      :host([drawer][orientation='vertical'][containment='viewport']) [part='detail'] {
         inset-inline-start: 0;
       }
 
@@ -185,12 +193,12 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
       }
 
       /* Min size */
-      :host([has-master-min-size][orientation='vertical']:not([overlay])) [part='master'],
-      :host([has-master-min-size][orientation='vertical'][overlay]) {
+      :host([has-master-min-size][orientation='vertical']:not([drawer])) [part='master'],
+      :host([has-master-min-size][orientation='vertical'][drawer]) {
         min-height: var(--_master-min-size);
       }
 
-      :host([has-detail-min-size][orientation='vertical']:not([overlay]):not([stack])) [part='detail'] {
+      :host([has-detail-min-size][orientation='vertical']:not([drawer]):not([stack])) [part='detail'] {
         min-height: var(--_detail-min-size);
       }
 
@@ -202,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);
-      }
     `;
   }
 
@@ -215,7 +219,8 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
        * Fixed size (in CSS length units) to be set on the detail area.
        * When specified, it prevents the detail area from growing or
        * shrinking. If there is not enough space to show master and detail
-       * areas next to each other, the layout switches to the overlay mode.
+       * areas next to each other, the details are shown as an overlay:
+       * either as drawer or stack, depending on the `stackOverlay` property.
        *
        * @attr {string} detail-size
        */
@@ -229,7 +234,8 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
        * Minimum size (in CSS length units) to be set on the detail area.
        * When specified, it prevents the detail area from shrinking below
        * this size. If there is not enough space to show master and detail
-       * areas next to each other, the layout switches to the overlay mode.
+       * areas next to each other, the details are shown as an overlay:
+       * either as drawer or stack, depending on the `stackOverlay` property.
        *
        * @attr {string} detail-min-size
        */
@@ -243,7 +249,8 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
        * Fixed size (in CSS length units) to be set on the master area.
        * When specified, it prevents the master area from growing or
        * shrinking. If there is not enough space to show master and detail
-       * areas next to each other, the layout switches to the overlay mode.
+       * areas next to each other, the details are shown as an overlay:
+       * either as drawer or stack, depending on the `stackOverlay` property.
        *
        * @attr {string} master-size
        */
@@ -257,7 +264,8 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
        * Minimum size (in CSS length units) to be set on the master area.
        * When specified, it prevents the master area from shrinking below
        * this size. If there is not enough space to show master and detail
-       * areas next to each other, the layout switches to the overlay mode.
+       * areas next to each other, the details are shown as an overlay:
+       * either as drawer or stack, depending on the `stackOverlay` property.
        *
        * @attr {string} master-min-size
        */
@@ -282,9 +290,13 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
       },
 
       /**
-       * When specified, forces the layout to use overlay mode, even if
-       * there is enough space for master and detail to be shown next to
-       * each other using the default (split) mode.
+       * When specified, forces the details to be shown as an overlay
+       * (either as drawer or stack), even if 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
        */
@@ -309,14 +321,19 @@ 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. Otherwise, it is
+       * rendered as a drawer and has a visual backdrop.
+       *
+       * 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,
       },
 
@@ -331,20 +348,18 @@ 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.
+       * When true, the component uses the drawer mode. This property is read-only.
        * @protected
        */
-      _overlay: {
+      _drawer: {
         type: Boolean,
-        attribute: 'overlay',
+        attribute: 'drawer',
         reflectToAttribute: true,
         sync: true,
       },
 
       /**
        * 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: {
@@ -353,9 +368,24 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
         reflectToAttribute: true,
         sync: true,
       },
+
+      /**
+       * When true, the component has the detail content provided.
+       * @protected
+       */
+      _hasDetail: {
+        type: Boolean,
+        attribute: 'has-detail',
+        reflectToAttribute: true,
+        sync: true,
+      },
     };
   }
 
+  static get experimental() {
+    return true;
+  }
+
   /** @override */
   get slotStyles() {
     return [transitionStyles];
@@ -364,15 +394,16 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
   /** @protected */
   render() {
     return html`
-      <div part="backdrop"></div>
-      <div id="master" part="master" ?inert="${this._overlay && this.containment === 'layout'}">
+      <div part="backdrop" @click="${this.__onBackdropClick}"></div>
+      <div id="master" part="master" ?inert="${this._hasDetail && this._drawer && this.containment === 'layout'}">
         <slot></slot>
       </div>
       <div
         id="detail"
         part="detail"
-        role="${this._overlay || this._stack ? 'dialog' : nothing}"
-        aria-modal="${this._overlay && this.containment === 'viewport' ? 'true' : nothing}"
+        role="${this._drawer || this._stack ? 'dialog' : nothing}"
+        aria-modal="${this._drawer && this.containment === 'viewport' ? 'true' : nothing}"
+        @keydown="${this.__onDetailKeydown}"
       >
         <slot name="detail" @slotchange="${this.__onDetailSlotChange}"></slot>
       </div>
@@ -383,12 +414,12 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
   __onDetailSlotChange(e) {
     const children = e.target.assignedNodes();
 
-    this.toggleAttribute('has-detail', children.length > 0);
+    this._hasDetail = children.length > 0;
     this.__detectLayoutMode();
 
     // Move focus to the detail area when it is added to the DOM,
-    // in case if the layout is using overlay or stack mode.
-    if ((this.hasAttribute('overlay') || this.hasAttribute('stack')) && children.length > 0) {
+    // in case if the layout is using drawer or stack mode.
+    if ((this._drawer || this._stack) && children.length > 0) {
       const focusables = getFocusableElements(children[0]);
       if (focusables.length) {
         focusables[0].focus();
@@ -396,6 +427,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
@@ -443,14 +488,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();
     }
   }
@@ -466,26 +505,26 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
     this.toggleAttribute(`has-${prop}`, !!size);
   }
 
+  /** @private */
+  __setOverlayMode(value) {
+    if (this.stackOverlay) {
+      this._stack = value;
+    } else {
+      this._drawer = value;
+    }
+  }
+
   /** @private */
   __detectLayoutMode() {
-    this._overlay = false;
+    this._drawer = false;
     this._stack = false;
 
     if (this.forceOverlay) {
-      this._overlay = true;
+      this.__setOverlayMode(true);
       return;
     }
 
-    if (this.stackThreshold != null) {
-      const threshold = this.__getStackThresholdInPixels();
-      const size = this.orientation === 'vertical' ? this.offsetHeight : this.offsetWidth;
-      if (size <= threshold) {
-        this._stack = true;
-        return;
-      }
-    }
-
-    if (!this.hasAttribute('has-detail')) {
+    if (!this._hasDetail) {
       return;
     }
 
@@ -510,38 +549,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
@@ -650,6 +679,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 drawer mode.
+   */
+
+  /**
+   * @event detail-escape-press
+   * Fired when the user presses Escape in the detail area.
+   */
 }
 
 defineCustomElement(MasterDetailLayout);

package/theme/lumo/vaadin-master-detail-layout-styles.js

@@ -4,23 +4,23 @@ import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themab
 registerStyles(
   'vaadin-master-detail-layout',
   css`
-    :host(:is([overlay], [stack])) [part='detail'] {
+    :host(:is([drawer], [stack])) [part='detail'] {
       background-color: var(--lumo-base-color);
     }
 
-    :host([overlay]) [part='detail'] {
+    :host([drawer]) [part='detail'] {
       box-shadow: var(--lumo-box-shadow-s);
     }
 
-    :host([overlay][orientation='horizontal']) [part='detail'] {
+    :host([drawer][orientation='horizontal']) [part='detail'] {
       border-inline-start: 1px solid var(--lumo-contrast-10pct);
     }
 
-    :host([overlay][orientation='vertical']) [part='detail'] {
+    :host([drawer][orientation='vertical']) [part='detail'] {
       border-block-start: 1px solid var(--lumo-contrast-10pct);
     }
 
-    :host([overlay]) [part='backdrop'] {
+    :host([drawer]) [part='backdrop'] {
       background-color: var(--lumo-shade-20pct);
     }
   `,

package/theme/material/vaadin-master-detail-layout-styles.js

@@ -5,23 +5,23 @@ import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themab
 registerStyles(
   'vaadin-master-detail-layout',
   css`
-    :host(:is([overlay], [stack])) [part='detail'] {
+    :host(:is([drawer], [stack])) [part='detail'] {
       background-color: var(--material-background-color);
     }
 
-    :host([overlay]) [part='detail'] {
+    :host([drawer]) [part='detail'] {
       box-shadow: var(--material-shadow-elevation-4dp);
     }
 
-    :host([overlay][orientation='horizontal']) [part='detail'] {
+    :host([drawer][orientation='horizontal']) [part='detail'] {
       border-inline-start: 1px solid var(--material-divider-color);
     }
 
-    :host([overlay][orientation='vertical']) [part='detail'] {
+    :host([drawer][orientation='vertical']) [part='detail'] {
       border-block-start: 1px solid var(--material-divider-color);
     }
 
-    :host([overlay]) [part='backdrop'] {
+    :host([drawer]) [part='backdrop'] {
       background-color: var(--material-secondary-background-color);
       opacity: 0.5;
     }

package/web-types.json

@@ -1,18 +1,18 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/master-detail-layout",
-  "version": "24.8.0-alpha8",
+  "version": "24.8.0-beta1",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "vaadin-master-detail-layout",
-          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Styling\n\nThe following custom CSS properties are available for styling (needed to be set\non the `<html>` element since they are used by the global view transitions):\n\nCustom CSS property                                  | Description         | Default\n-----------------------------------------------------|---------------------|--------\n`--vaadin-master-detail-layout-transition-duration`  | Transition duration | 300ms\n\nThe following shadow DOM parts are available for styling:\n\nPart name      | Description\n---------------|----------------------\n`backdrop`     | Backdrop covering the master area in the overlay mode\n`master`       | The master area\n`detail`       | The detail area\n\nThe following state attributes are available for styling:\n\nAttribute      | Description\n---------------| -----------\n`containment`  | Set to `layout` or `viewport` depending on the containment.\n`orientation`  | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`   | Set when the detail content is provided.\n`overlay`      | Set when the layout is using the overlay mode.\n`stack`        | Set when the layout is using the stack mode.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Styling\n\nThe following custom CSS properties are available for styling (needed to be set\non the `<html>` element since they are used by the global view transitions):\n\nCustom CSS property                                  | Description         | Default\n-----------------------------------------------------|---------------------|--------\n`--vaadin-master-detail-layout-transition-duration`  | Transition duration | 300ms\n\nThe following shadow DOM parts are available for styling:\n\nPart name      | Description\n---------------|----------------------\n`backdrop`     | Backdrop covering the master area in the drawer mode\n`master`       | The master area\n`detail`       | The detail area\n\nThe following state attributes are available for styling:\n\nAttribute      | Description\n---------------| -----------\n`containment`  | Set to `layout` or `viewport` depending on the containment.\n`orientation`  | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`   | Set when the detail content is provided.\n`drawer`       | Set when the layout is using the drawer mode.\n`stack`        | Set when the layout is using the stack mode.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
           "attributes": [
             {
               "name": "detail-size",
-              "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
               "value": {
                 "type": [
                   "string",
@@ -23,7 +23,7 @@
             },
             {
               "name": "detail-min-size",
-              "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
               "value": {
                 "type": [
                   "string",
@@ -34,7 +34,7 @@
             },
             {
               "name": "master-size",
-              "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
               "value": {
                 "type": [
                   "string",
@@ -45,7 +45,7 @@
             },
             {
               "name": "master-min-size",
-              "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
               "value": {
                 "type": [
                   "string",
@@ -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 details to be shown as an overlay\n(either as drawer or stack), even if there is enough space for\nmaster and detail to be shown next to each other using the default\n(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. Otherwise, it is\nrendered as a drawer and has a visual backdrop.\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"
                 ]
@@ -125,7 +125,7 @@
             "properties": [
               {
                 "name": "detailSize",
-                "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+                "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
                 "value": {
                   "type": [
                     "string",
@@ -136,7 +136,7 @@
               },
               {
                 "name": "detailMinSize",
-                "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+                "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
                 "value": {
                   "type": [
                     "string",
@@ -147,7 +147,7 @@
               },
               {
                 "name": "masterSize",
-                "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+                "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
                 "value": {
                   "type": [
                     "string",
@@ -158,7 +158,7 @@
               },
               {
                 "name": "masterMinSize",
-                "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+                "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
                 "value": {
                   "type": [
                     "string",
@@ -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 details to be shown as an overlay\n(either as drawer or stack), even if there is enough space for\nmaster and detail to be shown next to each other using the default\n(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. Otherwise, it is\nrendered as a drawer and has a visual backdrop.\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 drawer 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-alpha8",
+  "version": "24.8.0-beta1",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -16,12 +16,19 @@
       "elements": [
         {
           "name": "vaadin-master-detail-layout",
-          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Styling\n\nThe following custom CSS properties are available for styling (needed to be set\non the `<html>` element since they are used by the global view transitions):\n\nCustom CSS property                                  | Description         | Default\n-----------------------------------------------------|---------------------|--------\n`--vaadin-master-detail-layout-transition-duration`  | Transition duration | 300ms\n\nThe following shadow DOM parts are available for styling:\n\nPart name      | Description\n---------------|----------------------\n`backdrop`     | Backdrop covering the master area in the overlay mode\n`master`       | The master area\n`detail`       | The detail area\n\nThe following state attributes are available for styling:\n\nAttribute      | Description\n---------------| -----------\n`containment`  | Set to `layout` or `viewport` depending on the containment.\n`orientation`  | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`   | Set when the detail content is provided.\n`overlay`      | Set when the layout is using the overlay mode.\n`stack`        | Set when the layout is using the stack mode.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Styling\n\nThe following custom CSS properties are available for styling (needed to be set\non the `<html>` element since they are used by the global view transitions):\n\nCustom CSS property                                  | Description         | Default\n-----------------------------------------------------|---------------------|--------\n`--vaadin-master-detail-layout-transition-duration`  | Transition duration | 300ms\n\nThe following shadow DOM parts are available for styling:\n\nPart name      | Description\n---------------|----------------------\n`backdrop`     | Backdrop covering the master area in the drawer mode\n`master`       | The master area\n`detail`       | The detail area\n\nThe following state attributes are available for styling:\n\nAttribute      | Description\n---------------| -----------\n`containment`  | Set to `layout` or `viewport` depending on the containment.\n`orientation`  | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`   | Set when the detail content is provided.\n`drawer`       | Set when the layout is using the drawer mode.\n`stack`        | Set when the layout is using the stack mode.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
           "extension": true,
           "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 details to be shown as an overlay\n(either as drawer or stack), even if there is enough space for\nmaster and detail to be shown next to each other using the default\n(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. Otherwise, it is\nrendered as a drawer and has a visual backdrop.\n\nIn order to enforce the stack mode, use this property together with\n`forceOverlay` property and set both to `true`.",
               "value": {
                 "kind": "expression"
               }
@@ -35,28 +42,28 @@
             },
             {
               "name": ".detailSize",
-              "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
               "value": {
                 "kind": "expression"
               }
             },
             {
               "name": ".detailMinSize",
-              "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
               "value": {
                 "kind": "expression"
               }
             },
             {
               "name": ".masterSize",
-              "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
               "value": {
                 "kind": "expression"
               }
             },
             {
               "name": ".masterMinSize",
-              "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the details are shown as an overlay:\neither as drawer or stack, depending on the `stackOverlay` property.",
               "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 drawer 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"
               }