@vaadin/master-detail-layout 24.8.0-alpha3 → 24.8.0-alpha4

package/package.json

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

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

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright (c) 2025 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { css } from 'lit';
+
+export const transitionStyles = css`
+  /* Overlay - horizontal - add */
+
+  vaadin-master-detail-layout[overlay][orientation='horizontal'][transition='add']::part(detail) {
+    view-transition-name: vaadin-master-detail-layout-overlay-horizontal-detail-add;
+  }
+
+  ::view-transition-group(vaadin-master-detail-layout-overlay-horizontal-detail-add) {
+    clip-path: inset(0);
+  }
+
+  ::view-transition-new(vaadin-master-detail-layout-overlay-horizontal-detail-add) {
+    animation: 300ms ease both vaadin-master-detail-layout-overlay-horizontal-detail-add;
+  }
+
+  @keyframes vaadin-master-detail-layout-overlay-horizontal-detail-add {
+    from {
+      transform: translateX(100%);
+    }
+  }
+
+  /* Overlay - horizontal - remove */
+
+  vaadin-master-detail-layout[overlay][orientation='horizontal'][transition='remove']::part(detail) {
+    view-transition-name: vaadin-master-detail-layout-overlay-horizontal-detail-remove;
+  }
+
+  ::view-transition-group(vaadin-master-detail-layout-overlay-horizontal-detail-remove) {
+    clip-path: inset(0);
+  }
+
+  ::view-transition-old(vaadin-master-detail-layout-overlay-horizontal-detail-remove) {
+    animation: 300ms ease both vaadin-master-detail-layout-overlay-horizontal-detail-remove;
+  }
+
+  @keyframes vaadin-master-detail-layout-overlay-horizontal-detail-remove {
+    to {
+      transform: translateX(100%);
+    }
+  }
+
+  /* Stack - horizontal - add */
+
+  vaadin-master-detail-layout[stack][orientation='horizontal'][transition='add'] {
+    view-transition-name: vaadin-master-detail-layout-stack-horizontal-add;
+  }
+
+  ::view-transition-group(vaadin-master-detail-layout-stack-horizontal-add) {
+    clip-path: inset(0);
+  }
+
+  ::view-transition-new(vaadin-master-detail-layout-stack-horizontal-add) {
+    animation: 300ms ease both vaadin-master-detail-layout-stack-horizontal-add-new;
+  }
+
+  ::view-transition-old(vaadin-master-detail-layout-stack-horizontal-add) {
+    animation: 300ms ease both vaadin-master-detail-layout-stack-horizontal-add-old;
+  }
+
+  @keyframes vaadin-master-detail-layout-stack-horizontal-add-new {
+    from {
+      transform: translateX(100px);
+      opacity: 0;
+    }
+  }
+
+  @keyframes vaadin-master-detail-layout-stack-horizontal-add-old {
+    to {
+      transform: translateX(-100px);
+      opacity: 0;
+    }
+  }
+
+  /* Stack - horizontal - remove */
+
+  vaadin-master-detail-layout[stack][orientation='horizontal'][transition='remove'] {
+    view-transition-name: vaadin-master-detail-layout-stack-horizontal-remove;
+  }
+
+  ::view-transition-group(vaadin-master-detail-layout-stack-horizontal-remove) {
+    clip-path: inset(0);
+  }
+
+  ::view-transition-new(vaadin-master-detail-layout-stack-horizontal-remove) {
+    animation: 300ms ease both vaadin-master-detail-layout-stack-horizontal-remove-new;
+  }
+
+  ::view-transition-old(vaadin-master-detail-layout-stack-horizontal-remove) {
+    animation: 300ms ease both vaadin-master-detail-layout-stack-horizontal-remove-old;
+  }
+
+  @keyframes vaadin-master-detail-layout-stack-horizontal-remove-new {
+    from {
+      transform: translateX(-100px);
+      opacity: 0;
+    }
+  }
+
+  @keyframes vaadin-master-detail-layout-stack-horizontal-remove-old {
+    to {
+      transform: translateX(100px);
+      opacity: 0;
+    }
+  }
+`;

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

@@ -5,14 +5,36 @@
  */
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 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';
 
 /**
  * `<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
  * overlaid on top of, the master area, depending on configuration and viewport size.
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name      | Description
+ * ---------------|----------------------
+ * `master`       | The master area
+ * `detail`       | The detail area
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------| -----------
+ * `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.
+ * `stack`        | Set when the layout is using the stack mode.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  */
-declare class MasterDetailLayout extends ResizeMixin(ThemableMixin(ElementMixin(HTMLElement))) {
+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
@@ -38,7 +60,6 @@ declare class MasterDetailLayout extends ResizeMixin(ThemableMixin(ElementMixin(
    * 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.
-   * Setting `100%` enforces the overlay mode to be used by default.
    *
    * @attr {string} master-size
    */
@@ -49,11 +70,55 @@ declare class MasterDetailLayout extends ResizeMixin(ThemableMixin(ElementMixin(
    * 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.
-   * Setting `100%` enforces the overlay mode to be used by default.
    *
    * @attr {string} master-min-size
    */
   masterMinSize: string | null | undefined;
+
+  /**
+   * Define how master and detail areas are shown next to each other,
+   * and the way how size and min-size properties are applied to them.
+   * Possible values are: `horizontal` or `vertical`.
+   * Defaults to horizontal.
+   */
+  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.
+   *
+   * @attr {boolean} force-overlay
+   */
+  forceOverlay: boolean;
+
+  /**
+   * Defines the containment of the detail area when the layout is in
+   * overlay mode. When set to `layout`, the overlay is confined to the
+   * layout. When set to `viewport`, the overlay is confined to the
+   * browser's viewport. Defaults to `layout`.
+   */
+  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.
+   *
+   * @attr {string} stack-threshold
+   */
+  stackThreshold: string | null | undefined;
+
+  /**
+   * Sets the detail element to be displayed in the detail area and starts a
+   * view transition that animates adding, replacing or removing the detail
+   * area. During the view transition, the element is added to the DOM and
+   * assigned to the `detail` slot. Any previous detail element is removed.
+   * When passing null as the element, the current detail element is removed.
+   *
+   * If the browser does not support view transitions, the respective updates
+   * are applied immediately without starting a transition.
+   */
+  setDetail(detail: HTMLElement | null): Promise<void>;
 }
 
 declare global {

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

@@ -3,25 +3,50 @@
  * Copyright (c) 2025 - 2025 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { css, html, LitElement } from 'lit';
+import { css, html, LitElement, nothing } from 'lit';
+import { getFocusableElements } from '@vaadin/a11y-base/src/focus-utils.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 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';
+import { transitionStyles } from './vaadin-master-detail-layout-transition-styles.js';
 
 /**
  * `<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
  * overlaid on top of, the master area, depending on configuration and viewport size.
  *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name      | Description
+ * ---------------|----------------------
+ * `master`       | The master area
+ * `detail`       | The detail area
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------| -----------
+ * `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.
+ * `stack`        | Set when the layout is using the stack mode.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ThemableMixin
  * @mixes ElementMixin
  * @mixes ResizeMixin
+ * @mixes SlotStylesMixin
  */
-class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)))) {
+class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement))))) {
   static get is() {
     return 'vaadin-master-detail-layout';
   }
@@ -43,19 +68,30 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
       }
 
       /* Overlay mode */
-      :host([overlay][has-detail]) {
+      :host(:is([overlay], [stack])) {
         position: relative;
       }
 
-      :host([overlay]) [part='detail'] {
+      :host(:is([overlay], [stack])[containment='layout']) [part='detail'] {
         position: absolute;
+      }
+
+      :host(:is([overlay], [stack])[containment='viewport']) [part='detail'] {
+        position: fixed;
+      }
+
+      :host([overlay][orientation='horizontal']) [part='detail'] {
         inset-inline-end: 0;
         height: 100%;
         width: var(--_detail-min-size, min-content);
         max-width: 100%;
       }
 
-      :host([overlay]) [part='master'] {
+      :host([overlay][orientation='horizontal'][containment='viewport']) [part='detail'] {
+        inset-block-start: 0;
+      }
+
+      :host([overlay][orientation='horizontal']) [part='master'] {
         max-width: 100%;
       }
 
@@ -67,14 +103,17 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
       }
 
       /* Fixed size */
-      :host([has-master-size]) [part='master'] {
-        width: var(--_master-size);
+      :host([has-master-size]) [part='master'],
+      :host([has-detail-size]) [part='detail'] {
         flex-shrink: 0;
       }
 
-      :host([has-detail-size]) [part='detail'] {
+      :host([has-master-size][orientation='horizontal']) [part='master'] {
+        width: var(--_master-size);
+      }
+
+      :host([has-detail-size][orientation='horizontal']:not([stack])) [part='detail'] {
         width: var(--_detail-size);
-        flex-shrink: 0;
       }
 
       :host([has-master-size][has-detail-size]) [part='master'] {
@@ -88,11 +127,11 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
       }
 
       /* Min size */
-      :host([has-master-min-size]:not([overlay])) [part='master'] {
+      :host([has-master-min-size][orientation='horizontal']:not([overlay])) [part='master'] {
         min-width: var(--_master-min-size);
       }
 
-      :host([has-detail-min-size]:not([overlay])) [part='detail'] {
+      :host([has-detail-min-size][orientation='horizontal']:not([overlay]):not([stack])) [part='detail'] {
         min-width: var(--_detail-min-size);
       }
 
@@ -100,6 +139,57 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
       :host([has-detail-min-size]) [part='detail'] {
         flex-shrink: 0;
       }
+
+      /* Vertical */
+      :host([orientation='vertical']) {
+        flex-direction: column;
+      }
+
+      :host([orientation='vertical'][overlay]) [part='master'] {
+        max-height: 100%;
+      }
+
+      :host([orientation='vertical'][overlay]) [part='detail'] {
+        inset-block-end: 0;
+        width: 100%;
+        height: var(--_detail-min-size, min-content);
+      }
+
+      :host([overlay][orientation='vertical'][containment='viewport']) [part='detail'] {
+        inset-inline-start: 0;
+      }
+
+      /* Fixed size */
+      :host([has-master-size][orientation='vertical']) [part='master'] {
+        height: var(--_master-size);
+      }
+
+      :host([has-detail-size][orientation='vertical']:not([stack])) [part='detail'] {
+        height: var(--_detail-size);
+      }
+
+      /* Min size */
+      :host([has-master-min-size][orientation='vertical']:not([overlay])) [part='master'],
+      :host([has-master-min-size][orientation='vertical'][overlay]) {
+        min-height: var(--_master-min-size);
+      }
+
+      :host([has-detail-min-size][orientation='vertical']:not([overlay]):not([stack])) [part='detail'] {
+        min-height: var(--_detail-min-size);
+      }
+
+      /* Stack mode */
+      :host([stack]) [part='master'] {
+        max-height: 100%;
+      }
+
+      :host([stack]) [part='detail'] {
+        inset: 0;
+      }
+
+      [part='master']::before {
+        background-position-y: var(--_stack-threshold);
+      }
     `;
   }
 
@@ -138,7 +228,6 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
        * 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.
-       * Setting `100%` enforces the overlay mode to be used by default.
        *
        * @attr {string} master-size
        */
@@ -153,7 +242,6 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
        * 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.
-       * Setting `100%` enforces the overlay mode to be used by default.
        *
        * @attr {string} master-min-size
        */
@@ -162,16 +250,103 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
         sync: true,
         observer: '__masterMinSizeChanged',
       },
+
+      /**
+       * Define how master and detail areas are shown next to each other,
+       * and the way how size and min-size properties are applied to them.
+       * Possible values are: `horizontal` or `vertical`.
+       * Defaults to horizontal.
+       */
+      orientation: {
+        type: String,
+        value: 'horizontal',
+        reflectToAttribute: true,
+        observer: '__orientationChanged',
+        sync: true,
+      },
+
+      /**
+       * 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.
+       *
+       * @attr {boolean} force-overlay
+       */
+      forceOverlay: {
+        type: Boolean,
+        value: false,
+        observer: '__forceOverlayChanged',
+        sync: true,
+      },
+
+      /**
+       * Defines the containment of the detail area when the layout is in
+       * overlay mode. When set to `layout`, the overlay is confined to the
+       * layout. When set to `viewport`, the overlay is confined to the
+       * browser's viewport. Defaults to `layout`.
+       */
+      containment: {
+        type: String,
+        value: 'layout',
+        reflectToAttribute: true,
+        sync: true,
+      },
+
+      /**
+       * The threshold (in CSS length units) at which the layout switches to
+       * the "stack" mode, making detail area fully cover the master area.
+       *
+       * @attr {string} stack-threshold
+       */
+      stackThreshold: {
+        type: String,
+        observer: '__stackThresholdChanged',
+        sync: true,
+      },
+
+      /**
+       * 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: {
+        type: Boolean,
+        attribute: 'overlay',
+        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: {
+        type: Boolean,
+        attribute: 'stack',
+        reflectToAttribute: true,
+        sync: true,
+      },
     };
   }
 
+  /** @override */
+  get slotStyles() {
+    return [transitionStyles];
+  }
+
   /** @protected */
   render() {
     return html`
-      <div id="master" part="master">
+      <div id="master" part="master" ?inert="${this._overlay && this.containment === 'layout'}">
         <slot></slot>
       </div>
-      <div id="detail" part="detail">
+      <div
+        id="detail"
+        part="detail"
+        role="${this._overlay || this._stack ? 'dialog' : nothing}"
+        aria-modal="${this._overlay && this.containment === 'viewport' ? 'true' : nothing}"
+      >
         <slot name="detail" @slotchange="${this.__onDetailSlotChange}"></slot>
       </div>
     `;
@@ -179,8 +354,19 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
 
   /** @private */
   __onDetailSlotChange(e) {
-    this.toggleAttribute('has-detail', e.target.assignedNodes().length > 0);
+    const children = e.target.assignedNodes();
+
+    this.toggleAttribute('has-detail', 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) {
+      const focusables = getFocusableElements(children[0]);
+      if (focusables.length) {
+        focusables[0].focus();
+      }
+    }
   }
 
   /**
@@ -215,6 +401,33 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
     this.__detectLayoutMode();
   }
 
+  /** @private */
+  __orientationChanged(orientation, oldOrientation) {
+    if (orientation || oldOrientation) {
+      this.__detectLayoutMode();
+    }
+  }
+
+  /** @private */
+  __forceOverlayChanged(forceOverlay, oldForceOverlay) {
+    if (forceOverlay || oldForceOverlay) {
+      this.__detectLayoutMode();
+    }
+  }
+
+  /** @private */
+  __stackThresholdChanged(threshold, oldThreshold) {
+    if (threshold || oldThreshold) {
+      if (threshold) {
+        this.$.master.style.setProperty('--_stack-threshold', threshold);
+      } else {
+        this.$.master.style.removeProperty('--_stack-threshold');
+      }
+
+      this.__detectLayoutMode();
+    }
+  }
+
   /** @private */
   __updateStyleProperty(prop, size, oldSize) {
     if (size) {
@@ -228,11 +441,36 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
 
   /** @private */
   __detectLayoutMode() {
+    this._overlay = false;
+    this._stack = false;
+
+    if (this.forceOverlay) {
+      this._overlay = 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')) {
-      this.removeAttribute('overlay');
       return;
     }
 
+    if (this.orientation === 'vertical') {
+      this.__detectVerticalMode();
+    } else {
+      this.__detectHorizontalMode();
+    }
+  }
+
+  /** @private */
+  __detectHorizontalMode() {
     const detailWidth = this.$.detail.offsetWidth;
 
     // Detect minimum width needed by master content. Use max-width to ensure
@@ -245,18 +483,77 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
 
     // 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.
-    if (this.offsetWidth < masterWidth + detailWidth) {
-      this.setAttribute('overlay', '');
-    } else {
-      this.removeAttribute('overlay');
-    }
+    this._overlay = 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.setAttribute('overlay', '');
+      this._overlay = 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;
+    }
+  }
+
+  /** @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
+   * area. During the view transition, the element is added to the DOM and
+   * assigned to the `detail` slot. Any previous detail element is removed.
+   * When passing null as the element, the current detail element is removed.
+   *
+   * If the browser does not support view transitions, the respective updates
+   * are applied immediately without starting a transition.
+   *
+   * @param element the new detail element, or null to remove the current detail
+   * @returns {Promise<void>}
+   */
+  async setDetail(element) {
+    // Don't start a transition if detail didn't change
+    const currentDetail = this.querySelector('[slot="detail"]');
+    if ((element || null) === currentDetail) {
+      return;
+    }
+
+    const updateSlot = () => {
+      // Remove old content
+      this.querySelectorAll('[slot="detail"]').forEach((oldElement) => oldElement.remove());
+      // Add new content
+      if (element) {
+        element.setAttribute('slot', 'detail');
+        this.appendChild(element);
+      }
+    };
+
+    if (typeof document.startViewTransition === 'function') {
+      const hasDetail = !!currentDetail;
+      const transitionType = hasDetail && element ? 'replace' : hasDetail ? 'remove' : 'add';
+      this.setAttribute('transition', transitionType);
+      const transition = document.startViewTransition(updateSlot);
+      await transition.finished;
+      this.removeAttribute('transition');
+    } else {
+      updateSlot();
     }
   }
 }

package/web-types.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/master-detail-layout",
-  "version": "24.8.0-alpha3",
+  "version": "24.8.0-alpha4",
   "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.",
+          "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 shadow DOM parts are available for styling:\n\nPart name      | Description\n---------------|----------------------\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.",
           "attributes": [
             {
               "name": "detail-size",
@@ -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.\nSetting `100%` enforces the overlay mode to be used by default.",
+              "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.",
               "value": {
                 "type": [
                   "string",
@@ -45,7 +45,51 @@
             },
             {
               "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.\nSetting `100%` enforces the overlay mode to be used by default.",
+              "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.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "orientation",
+              "description": "Define how master and detail areas are shown next to each other,\nand the way how size and min-size properties are applied to them.\nPossible values are: `horizontal` or `vertical`.\nDefaults to horizontal.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "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.",
+              "value": {
+                "type": [
+                  "boolean",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "containment",
+              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `viewport`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "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.",
               "value": {
                 "type": [
                   "string",
@@ -92,7 +136,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.\nSetting `100%` enforces the overlay mode to be used by default.",
+                "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.",
                 "value": {
                   "type": [
                     "string",
@@ -103,7 +147,51 @@
               },
               {
                 "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.\nSetting `100%` enforces the overlay mode to be used by default.",
+                "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.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "orientation",
+                "description": "Define how master and detail areas are shown next to each other,\nand the way how size and min-size properties are applied to them.\nPossible values are: `horizontal` or `vertical`.\nDefaults to horizontal.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "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.",
+                "value": {
+                  "type": [
+                    "boolean",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "containment",
+                "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `viewport`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "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.",
                 "value": {
                   "type": [
                     "string",

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-alpha3",
+  "version": "24.8.0-alpha4",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -16,9 +16,16 @@
       "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.",
+          "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 shadow DOM parts are available for styling:\n\nPart name      | Description\n---------------|----------------------\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.",
           "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.",
+              "value": {
+                "kind": "expression"
+              }
+            },
             {
               "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.",
@@ -35,14 +42,35 @@
             },
             {
               "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.\nSetting `100%` enforces the overlay mode to be used by default.",
+              "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.",
               "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.\nSetting `100%` enforces the overlay mode to be used by default.",
+              "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.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".orientation",
+              "description": "Define how master and detail areas are shown next to each other,\nand the way how size and min-size properties are applied to them.\nPossible values are: `horizontal` or `vertical`.\nDefaults to horizontal.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".containment",
+              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `viewport`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "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.",
               "value": {
                 "kind": "expression"
               }