@vaadin/master-detail-layout 25.1.2 → 25.2.0-alpha10

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

@@ -4,40 +4,74 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { html, LitElement, nothing } from 'lit';
-import { getFocusableElements } from '@vaadin/a11y-base/src/focus-utils.js';
+import { getFocusableElements, isKeyboardActive } from '@vaadin/a11y-base/src/focus-utils.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
+import { getClosestElement } from '@vaadin/component-base/src/dom-utils.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 { masterDetailLayoutStyles } from './styles/vaadin-master-detail-layout-base-styles.js';
-import { masterDetailLayoutTransitionStyles } from './styles/vaadin-master-detail-layout-transition-base-styles.js';
+import {
+  animateIn,
+  animateOut,
+  cancelAnimations,
+  detectOverflow,
+  getCurrentAnimationProgress,
+  parseTrackSizes,
+} from './vaadin-master-detail-layout-helpers.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.
  *
+ * ### Slots
+ *
+ * The component has two main content areas: the master area (default slot)
+ * and the detail area (`detail` slot). When the detail doesn't fit next to
+ * the master, it is shown as an overlay on top of the master area:
+ *
+ * ```html
+ * <vaadin-master-detail-layout>
+ *   <div>Master content</div>
+ *   <div slot="detail">Detail content</div>
+ * </vaadin-master-detail-layout>
+ * ```
+ *
+ * The component also supports a `detail-placeholder` slot for content shown
+ * in the detail area when no detail is selected. Unlike the `detail` slot,
+ * the placeholder is simply hidden when it doesn't fit next to the master area,
+ * rather than shown as an overlay:
+ *
+ * ```html
+ * <vaadin-master-detail-layout>
+ *   <div>Master content</div>
+ *   <div slot="detail-placeholder">Select an item</div>
+ * </vaadin-master-detail-layout>
+ * ```
+ *
  * ### Styling
  *
  * The following shadow DOM parts are available for styling:
  *
- * Part name      | Description
- * ---------------|----------------------
- * `backdrop`     | Backdrop covering the master area in the drawer mode
- * `master`       | The master area
- * `detail`       | The detail area
+ * Part name             | Description
+ * ----------------------|----------------------
+ * `backdrop`            | Backdrop covering the master area in the overlay mode
+ * `master`              | The master area
+ * `detail`              | The detail area
+ * `detail-placeholder`  | The detail placeholder 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.
- * `drawer`       | Set when the layout is using the drawer mode.
- * `stack`        | Set when the layout is using the stack mode.
+ * Attribute                 | Description
+ * --------------------------|----------------------
+ * `expand-master`           | Set when the master area expands to fill available space.
+ * `expand-detail`           | Set when the detail area expands to fill available space.
+ * `orientation`             | Set to `horizontal` or `vertical` depending on the orientation.
+ * `has-detail`              | Set when the detail content is provided and visible.
+ * `has-detail-placeholder`  | Set when the detail placeholder content is provided.
+ * `overlay`                 | Set when columns don't fit and the detail is shown as an overlay.
+ * `overlay-containment`     | Set to `layout` or `page`.
  *
  * The following custom CSS properties are available for styling:
  *
@@ -51,17 +85,15 @@ import { masterDetailLayoutTransitionStyles } from './styles/vaadin-master-detai
  *
  * 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} backdrop-click - Fired when the user clicks the backdrop in the overlay mode.
  * @fires {CustomEvent} detail-escape-press - Fired when the user presses Escape in the detail area.
  *
  * @customElement vaadin-master-detail-layout
  * @extends HTMLElement
  * @mixes ThemableMixin
  * @mixes ElementMixin
- * @mixes ResizeMixin
- * @mixes SlotStylesMixin
  */
-class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement))))) {
+class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
   static get is() {
     return 'vaadin-master-detail-layout';
   }
@@ -73,63 +105,48 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
   static get properties() {
     return {
       /**
-       * 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 details are shown as an overlay:
-       * either as drawer or stack, depending on the `stackOverlay` property.
+       * Size (in CSS length units) to be set on the detail area in
+       * the CSS grid layout. When there is not enough space to show
+       * master and detail areas next to each other, the detail area
+       * is shown as an overlay.
+       * <p>
+       * If not specified, the size is determined automatically by measuring
+       * the detail content in a `min-content` CSS grid column when it first
+       * becomes visible, and then caching the resulting intrinsic size. To
+       * recalculate the cached intrinsic size, use the `recalculateLayout`
+       * method.
        *
        * @attr {string} detail-size
        */
       detailSize: {
         type: String,
         sync: true,
-        observer: '__detailSizeChanged',
-      },
-
-      /**
-       * 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 details are shown as an overlay:
-       * either as drawer or stack, depending on the `stackOverlay` property.
-       *
-       * @attr {string} detail-min-size
-       */
-      detailMinSize: {
-        type: String,
-        sync: true,
-        observer: '__detailMinSizeChanged',
       },
 
       /**
-       * 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 details are shown as an overlay:
-       * either as drawer or stack, depending on the `stackOverlay` property.
+       * Size (in CSS length units) to be set on the master area in
+       * the CSS grid layout. If there is not enough space to show
+       * master and detail areas next to each other, the detail area
+       * is shown as an overlay. Defaults to 30em.
        *
        * @attr {string} master-size
        */
       masterSize: {
         type: String,
         sync: true,
-        observer: '__masterSizeChanged',
       },
 
       /**
-       * 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 details are shown as an overlay:
-       * either as drawer or stack, depending on the `stackOverlay` property.
+       * Size (in CSS length units) for the detail area when shown as an
+       * overlay. When not set, falls back to `detailSize`. Set to `100%`
+       * to make the detail cover the full layout.
        *
-       * @attr {string} master-min-size
+       * @attr {string} overlay-size
        */
-      masterMinSize: {
+      overlaySize: {
         type: String,
         sync: true,
-        observer: '__masterMinSizeChanged',
+        observer: '__overlaySizeChanged',
       },
 
       /**
@@ -142,35 +159,18 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
         type: String,
         value: 'horizontal',
         reflectToAttribute: true,
-        observer: '__orientationChanged',
-        sync: true,
-      },
-
-      /**
-       * 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
-       */
-      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
+       * layout. When set to `page`, the overlay is confined to the
        * browser's viewport. Defaults to `layout`.
+       *
+       * @attr {string} overlay-containment
        */
-      containment: {
+      overlayContainment: {
         type: String,
         value: 'layout',
         reflectToAttribute: true,
@@ -178,62 +178,62 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
       },
 
       /**
-       * 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`.
+       * When true, the master area grows to fill the available space.
+       * If `expandDetail` is also true, both areas share the available
+       * space equally.
        *
-       * @attr {string} stack-threshold
+       * @attr {boolean} expand-master
        */
-      stackOverlay: {
+      expandMaster: {
         type: Boolean,
         value: false,
-        observer: '__stackOverlayChanged',
+        reflectToAttribute: true,
         sync: true,
       },
 
       /**
-       * When true, the layout does not use animated transitions for the detail area.
+       * When true, the detail area grows to fill the available space.
+       * If `expandMaster` is also true, both areas share the available
+       * space equally.
        *
-       * @attr {boolean} no-animation
+       * @attr {boolean} expand-detail
        */
-      noAnimation: {
+      expandDetail: {
         type: Boolean,
         value: false,
+        reflectToAttribute: true,
+        sync: true,
       },
 
       /**
-       * When true, the component uses the drawer mode. This property is read-only.
-       * @protected
+       * When true, the layout does not use animated transitions for the detail area.
+       *
+       * @attr {boolean} no-animation
        */
-      _drawer: {
+      noAnimation: {
         type: Boolean,
-        attribute: 'drawer',
+        value: false,
         reflectToAttribute: true,
-        sync: true,
       },
 
       /**
-       * When true, the component uses the stack mode. This property is read-only.
-       * @protected
+       * When true, the layout forces the detail area to be shown as an overlay,
+       * 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
        */
-      _stack: {
+      forceOverlay: {
         type: Boolean,
-        attribute: 'stack',
+        value: false,
         reflectToAttribute: true,
         sync: true,
       },
 
-      /**
-       * When true, the component has the detail content provided.
-       * @protected
-       */
-      _hasDetail: {
-        type: Boolean,
-        attribute: 'has-detail',
-        reflectToAttribute: true,
+      /** @private */
+      __detailCachedSize: {
+        type: String,
+        observer: '__detailCachedSizeChanged',
         sync: true,
       },
     };
@@ -243,317 +243,434 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
     return true;
   }
 
-  /** @override */
-  get slotStyles() {
-    return [masterDetailLayoutTransitionStyles];
-  }
-
   /** @protected */
   render() {
+    const isOverlay = this.hasAttribute('has-detail') && this.hasAttribute('overlay');
+    const isPage = isOverlay && this.overlayContainment === 'page';
+    const isLayoutContained = isOverlay && !isPage;
+
     return html`
-      <div part="backdrop" @click="${this.__onBackdropClick}"></div>
+      <div id="backdrop" part="backdrop" @click="${this.__onBackdropClick}"></div>
+      <div id="master" part="master" ?inert="${isLayoutContained}">
+        <slot @slotchange="${this.__onSlotChange}"></slot>
+      </div>
+      <div id="detailOutgoing" inert>
+        <slot name="detail-outgoing"></slot>
+      </div>
       <div
-        id="master"
-        part="master"
-        ?inert="${this._hasDetail && (this._stack || (this._drawer && this.containment === 'layout'))}"
+        id="detail"
+        part="detail"
+        role="${isOverlay ? 'dialog' : nothing}"
+        aria-modal="${isPage ? 'true' : nothing}"
+        @keydown="${this.__onDetailKeydown}"
       >
-        <slot></slot>
+        <slot name="detail" @slotchange="${this.__onSlotChange}"></slot>
       </div>
-      <div part="_detail-internal">
-        <div
-          id="detail"
-          part="detail"
-          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>
+      <div id="detailPlaceholder" part="detail-placeholder">
+        <slot name="detail-placeholder" @slotchange="${this.__onSlotChange}"></slot>
       </div>
     `;
   }
 
-  /** @private */
-  __onDetailSlotChange(e) {
-    const children = e.target.assignedNodes();
-
-    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 drawer or stack mode.
-    if ((this._drawer || this._stack) && children.length > 0) {
-      const focusables = getFocusableElements(children[0]);
-      if (focusables.length) {
-        focusables[0].focus();
-      }
+  /** @protected */
+  connectedCallback() {
+    super.connectedCallback();
+    this.__initResizeObserver();
+
+    const ancestorLayouts = this.__ancestorLayouts;
+    if (ancestorLayouts.length > 0) {
+      ancestorLayouts.forEach((layout) => {
+        cancelAnimationFrame(layout.__initialRaf);
+      });
+
+      this.__initialRaf = requestAnimationFrame(() => {
+        this.recalculateLayout();
+      });
     }
   }
 
-  /** @private */
-  __onBackdropClick() {
-    this.dispatchEvent(new CustomEvent('backdrop-click'));
+  /** @protected */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.__resizeObserver.disconnect();
+    cancelAnimationFrame(this.__resizeRaf);
+    cancelAnimationFrame(this.__initialRaf);
+    cancelAnimations(this);
   }
 
-  /** @private */
-  __onDetailKeydown(event) {
-    if (event.key === 'Escape' && !event.defaultPrevented) {
-      // Prevent firing on parent layout when using nested layouts
-      event.preventDefault();
-      this.dispatchEvent(new CustomEvent('detail-escape-press'));
+  /** @protected */
+  updated(props) {
+    super.updated(props);
+
+    if (props.has('masterSize')) {
+      this.style.setProperty('--_master-size', this.masterSize);
     }
-  }
 
-  /**
-   * @protected
-   * @override
-   */
-  _onResize() {
-    this.__detectLayoutMode();
+    if (props.has('detailSize')) {
+      this.style.setProperty('--_detail-size', this.detailSize);
+    }
+
+    if (
+      (props.has('masterSize') && props.get('masterSize') != null) ||
+      (props.has('detailSize') && props.get('detailSize') != null) ||
+      (props.has('orientation') && props.get('orientation') != null) ||
+      (props.has('forceOverlay') && props.get('forceOverlay') != null)
+    ) {
+      this.recalculateLayout();
+    }
   }
 
   /** @private */
-  __detailSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('detail-size', size, oldSize);
-    this.__detectLayoutMode();
+  __overlaySizeChanged(size) {
+    this.style.setProperty('--_overlay-size', size);
   }
 
   /** @private */
-  __detailMinSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('detail-min-size', size, oldSize);
-    this.__detectLayoutMode();
+  __detailCachedSizeChanged(size) {
+    this.style.setProperty('--_detail-cached-size', size);
   }
 
   /** @private */
-  __masterSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('master-size', size, oldSize);
-    this.__detectLayoutMode();
+  __onSlotChange() {
+    this.__initResizeObserver();
   }
 
   /** @private */
-  __masterMinSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('master-min-size', size, oldSize);
-    this.__detectLayoutMode();
+  __initResizeObserver() {
+    this.__resizeObserver ||= new ResizeObserver(() => this.__onResize());
+    this.__resizeObserver.disconnect();
+
+    [this, this.$.master, this.$.detail, this.__slottedMaster, this.__slottedDetail].forEach((node) => {
+      if (node) {
+        this.__resizeObserver.observe(node);
+      }
+    });
   }
 
-  /** @private */
-  __orientationChanged(orientation, oldOrientation) {
-    if (orientation || oldOrientation) {
-      this.__detectLayoutMode();
-    }
+  /**
+   * Called by the ResizeObserver. Reads layout state synchronously (no forced
+   * reflow since layout is already computed), then defers writes to rAF.
+   * Cancels any pending rAF so the write phase always uses the latest state.
+   * @private
+   */
+  __onResize() {
+    const state = this.__readLayoutState();
+    cancelAnimationFrame(this.__resizeRaf);
+    this.__resizeRaf = requestAnimationFrame(() => this.__writeLayoutState(state));
   }
 
-  /** @private */
-  __forceOverlayChanged(forceOverlay, oldForceOverlay) {
-    if (forceOverlay || oldForceOverlay) {
-      this.__detectLayoutMode();
-    }
+  /**
+   * Reads DOM/style state needed for layout detection. Safe to call in
+   * ResizeObserver callback where layout is already computed (no forced reflow).
+   * @private
+   */
+  __readLayoutState() {
+    const isVertical = this.orientation === 'vertical';
+
+    const slottedMaster = this.__slottedMaster;
+    const slottedDetail = this.__slottedDetail;
+    const slottedDetailPlaceholder = this.__slottedDetailPlaceholder;
+
+    const hasMaster = !!slottedMaster;
+    const hadDetail = this.hasAttribute('has-detail');
+    const hasDetail = slottedDetail != null && slottedDetail.checkVisibility();
+    const hasDetailPlaceholder = !!slottedDetailPlaceholder;
+
+    const computedStyle = getComputedStyle(this);
+    const hostSizeProp = isVertical ? 'height' : 'width';
+    const hostSize = parseFloat(computedStyle[hostSizeProp]);
+
+    const trackSizesProp = isVertical ? 'gridTemplateRows' : 'gridTemplateColumns';
+    const trackSizes = parseTrackSizes(computedStyle[trackSizesProp]);
+
+    const hasOverflow =
+      (hasDetail || hasDetailPlaceholder) && (this.forceOverlay || detectOverflow(hostSize, trackSizes));
+    const focusTarget = !hadDetail && hasDetail && hasOverflow ? getFocusableElements(slottedDetail)[0] : null;
+
+    return {
+      hasMaster,
+      hadDetail,
+      hasDetail,
+      hasDetailPlaceholder,
+      hasOverflow,
+      focusTarget,
+      hostSize,
+      trackSizes,
+    };
   }
 
-  /** @private */
-  __stackOverlayChanged(stackOverlay, oldStackOverlay) {
-    if (stackOverlay || oldStackOverlay) {
-      this.__detectLayoutMode();
+  /**
+   * Applies layout state to DOM attributes. Pure writes, no reads.
+   * @private
+   */
+  __writeLayoutState({ hasMaster, hadDetail, hasDetail, hasDetailPlaceholder, hasOverflow, focusTarget, trackSizes }) {
+    const [_masterSize, _masterExtra, detailSize] = trackSizes;
+
+    // If no detailSize is explicitily set, cache the intrinsic size (min-content) of
+    // the slotted detail content to use as a fallback for the detail column size
+    // while the detail content is rendered in an overlay.
+    if ((hasDetail || hasDetailPlaceholder) && this.__isDetailAutoSized && detailSize > 0) {
+      this.__detailCachedSize ||= `${Math.ceil(detailSize)}px`;
+    } else {
+      this.__detailCachedSize = null;
     }
-  }
 
-  /** @private */
-  __updateStyleProperty(prop, size, oldSize) {
-    if (size) {
-      this.style.setProperty(`--_${prop}`, size);
-    } else if (oldSize) {
-      this.style.removeProperty(`--_${prop}`);
+    // Force the detail column offscreen when it first appears and overflow
+    // is already detected. This prevents unnecessary master column shrinking,
+    // as the detail content is rendered in an overlay anyway.
+    if (!hadDetail && hasDetail && hasOverflow) {
+      this.setAttribute('keep-detail-column-offscreen', '');
+    } else if (!hasDetail || !hasOverflow) {
+      this.removeAttribute('keep-detail-column-offscreen');
     }
 
-    this.toggleAttribute(`has-${prop}`, !!size);
-  }
+    this.toggleAttribute('overlay', hasOverflow);
+    this.toggleAttribute('has-master', hasMaster);
+    this.toggleAttribute('has-detail', hasDetail);
+    this.toggleAttribute('has-detail-placeholder', hasDetailPlaceholder);
 
-  /** @private */
-  __setOverlayMode(value) {
-    if (this.stackOverlay) {
-      this._stack = value;
-    } else {
-      this._drawer = value;
+    // Re-render to update ARIA attributes (role, aria-modal, inert)
+    // which depend on has-detail and overlay state.
+    this.requestUpdate();
+
+    if (focusTarget) {
+      focusTarget.focus({ preventScroll: true, focusVisible: isKeyboardActive() });
     }
   }
 
-  /** @private */
-  __detectLayoutMode() {
-    this._drawer = false;
-    this._stack = false;
+  /**
+   * When `detailSize` is not explicitly set, re-measures the cached intrinsic size of
+   * the detail content by placing it in a min-content CSS grid column, then repeats
+   * this process for ancestor master-detail layouts without an explicit `detailSize`,
+   * if any, so that their detail areas also adapt.
+   *
+   * Call this method after changing the detail content in a way that affects its intrinsic
+   * size — for example, when opening a detail in a nested master-detail layout that was
+   * not previously visible.
+   *
+   * NOTE: This method can be expensive in large layouts as it triggers consecutive
+   * synchronous DOM reads and writes.
+   */
+  recalculateLayout() {
+    const invalidatedLayouts = [...this.__ancestorLayouts, this];
 
-    if (this.forceOverlay) {
-      this.__setOverlayMode(true);
-      return;
-    }
+    // Write
+    invalidatedLayouts.forEach((layout) => {
+      // Cancel any pending ResizeObserver rAF to prevent it from potentially
+      // overriding the layout state with stale measurements.
+      cancelAnimationFrame(layout.__resizeRaf);
 
-    if (!this._hasDetail) {
-      return;
-    }
+      layout.__detailCachedSize = null;
 
-    if (this.orientation === 'vertical') {
-      this.__detectVerticalMode();
-    } else {
-      this.__detectHorizontalMode();
-    }
+      if (layout.__isDetailAutoSized) {
+        layout.removeAttribute('overlay');
+        layout.toggleAttribute('recalculating-detail-size', true);
+      }
+    });
+
+    // Read/Write
+    invalidatedLayouts.forEach((layout) => {
+      const state = layout.__readLayoutState();
+      layout.__writeLayoutState(state);
+    });
+
+    // Write
+    invalidatedLayouts.forEach((layout) => {
+      if (layout.__isDetailAutoSized) {
+        layout.toggleAttribute('recalculating-detail-size', false);
+      }
+    });
   }
 
   /** @private */
-  __detectHorizontalMode() {
-    const detailWidth = this.$.detail.offsetWidth;
-
-    // Detect minimum width needed by master content. Use max-width to ensure
-    // the layout can switch back to split mode once there is enough space.
-    // If there is master  size or min-size set, use that instead to force the
-    // overlay mode by setting `masterSize` / `masterMinSize` to 100%/
-    this.$.master.style.maxWidth = this.masterSize || this.masterMinSize || 'min-content';
-    const masterWidth = this.$.master.offsetWidth;
-    this.$.master.style.maxWidth = '';
-
-    // 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.__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.__setOverlayMode(true);
-    }
+  get __isDetailAutoSized() {
+    return this.detailSize == null;
   }
 
   /** @private */
-  __detectVerticalMode() {
-    const masterHeight = this.$.master.clientHeight;
+  get __ancestorLayouts() {
+    const parent = getClosestElement(this.constructor.is, this.parentNode);
+    return parent ? [...parent.__ancestorLayouts, parent] : [];
+  }
 
-    // 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.__setOverlayMode(true);
+  /** @private */
+  __onBackdropClick() {
+    this.dispatchEvent(new CustomEvent('backdrop-click'));
+  }
+
+  /** @private */
+  __onDetailKeydown(event) {
+    if (event.key === 'Escape' && !event.defaultPrevented) {
+      // Prevent firing on parent layout when using nested layouts
+      event.preventDefault();
+      this.dispatchEvent(new CustomEvent('detail-escape-press'));
     }
   }
 
   /**
-   * 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.
+   * Sets the detail element to be displayed in the detail area and starts an
+   * animated transition for adding, replacing or removing the detail area.
+   * 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. The transition can
-   * also be skipped using the `skipTransition` parameter.
+   * The transition can be skipped using the `skipTransition` parameter or
+   * the `noAnimation` property.
    *
    * @param element the new detail element, or null to remove the current detail
    * @param skipTransition whether to skip the transition
-   * @returns {Promise<void>}
+   * @return {Promise<void>}
    * @protected
    */
-  _setDetail(element, skipTransition) {
+  async _setDetail(newDetail, skipTransition) {
     // Don't start a transition if detail didn't change
-    const currentDetail = this.querySelector('[slot="detail"]');
-    if ((element || null) === currentDetail) {
-      return Promise.resolve();
+    const oldDetail = this.__slottedDetail;
+    if (oldDetail === (newDetail || null)) {
+      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);
+    const updateSlot = async () => {
+      if (oldDetail?.slot === 'detail') {
+        oldDetail.remove();
       }
+
+      if (newDetail) {
+        newDetail.setAttribute('slot', 'detail');
+        this.appendChild(newDetail);
+      }
+
+      // Wait for Lit elements to render
+      await Promise.resolve();
+
+      this.recalculateLayout();
     };
 
-    if (skipTransition) {
-      updateSlot();
-      return Promise.resolve();
+    if (skipTransition || this.noAnimation) {
+      await updateSlot();
+      return;
     }
 
-    const hasDetail = !!currentDetail;
-    const transitionType = hasDetail && element ? 'replace' : hasDetail ? 'remove' : 'add';
-    return this._startTransition(transitionType, () => {
-      // Update the DOM
-      updateSlot();
-      // Finish the transition
-      this._finishTransition();
-    });
+    const hasPlaceholder = !!this.__slottedDetailPlaceholder;
+    if ((oldDetail && newDetail) || (hasPlaceholder && !this.hasAttribute('overlay'))) {
+      await this._startTransition('replace', updateSlot);
+    } else if (!oldDetail && newDetail) {
+      await this._startTransition('add', updateSlot);
+    } else if (oldDetail && !newDetail) {
+      await this._startTransition('remove', updateSlot);
+    }
   }
 
   /**
-   * Starts a view transition that animates adding, replacing or removing the
-   * detail area. Once the transition is ready and the browser has taken a
-   * snapshot of the current layout, the provided update callback is called.
-   * The callback should update the DOM, which can happen asynchronously.
-   * Once the DOM is updated, the caller must call `_finishTransition`,
-   * which results in the browser taking a snapshot of the new layout and
-   * animating the transition.
+   * Starts an animated transition for adding, replacing or removing the
+   * detail area using the Web Animations API.
+   *
+   * For 'add'/'replace': DOM is updated immediately, then animation
+   * starts after a microtask (so Lit elements render and layout is
+   * recalculated before animation params are read).
    *
-   * If the browser does not support view transitions, or the `noAnimation`
-   * property is set, the update callback is called immediately without
-   * starting a transition.
+   * For 'remove': animation plays first, then DOM is updated after
+   * the slide-out completes.
+   *
+   * Interruptible: a new transition cancels any in-progress animation
+   * and picks up from the interrupted position.
    *
    * @param transitionType
-   * @param updateCallback
-   * @returns {Promise<void>}
+   * @param updateSlot
+   * @return {Promise<void>}
    * @protected
    */
-  _startTransition(transitionType, updateCallback) {
-    const useTransition = typeof document.startViewTransition === 'function' && !this.noAnimation;
-    if (!useTransition) {
-      updateCallback();
-      return Promise.resolve();
+  async _startTransition(transitionType, updateSlot) {
+    if (this.noAnimation) {
+      await updateSlot();
+      return;
     }
 
-    this.setAttribute('transition', transitionType);
-    this.__transition = document.startViewTransition(() => {
-      // Return a promise that can be resolved once the DOM is updated
-      return new Promise((resolve) => {
-        this.__resolveUpdateCallback = resolve;
-        // Notify the caller that the transition is ready, so that they can
-        // update the DOM
-        updateCallback();
-      });
-    });
-    return this.__transition.finished;
+    try {
+      this.setAttribute('transition', transitionType);
+
+      switch (transitionType) {
+        case 'add':
+          await this.__addTransition(updateSlot);
+          break;
+        case 'remove':
+          await this.__removeTransition(updateSlot);
+          break;
+        default:
+          await this.__replaceTransition(updateSlot);
+          break;
+      }
+
+      this.removeAttribute('transition');
+    } catch (e) {
+      if (e instanceof DOMException && e.name === 'AbortError') {
+        return; // Animation was cancelled
+      }
+      throw e;
+    }
   }
 
-  /**
-   * Finishes the current view transition, if any. This method should be called
-   * after the DOM has been updated to finish the transition and animate the
-   * change in the layout.
-   *
-   * @returns {Promise<void>}
-   * @protected
-   */
-  async _finishTransition() {
-    // Detect new layout mode after DOM has been updated.
-    // The detection is wrapped in queueMicroTask in order to allow custom Lit elements to render before measurement.
-    // https://github.com/vaadin/web-components/issues/8969
-    queueMicrotask(() => this.__detectLayoutMode());
-
-    if (!this.__transition) {
-      return Promise.resolve();
+  /** @private */
+  async __addTransition(updateSlot) {
+    await updateSlot();
+
+    const progress = getCurrentAnimationProgress(this.$.detail);
+    await Promise.all([
+      animateIn(this.$.detail, ['fade', 'slide'], progress),
+      animateIn(this.$.backdrop, ['fade'], this.hasAttribute('overlay') ? progress : 1),
+    ]);
+  }
+
+  /** @private */
+  async __replaceTransition(updateSlot) {
+    const oldDetail = this.__slottedDetail;
+    if (oldDetail) {
+      oldDetail.slot = 'detail-outgoing';
+    }
+
+    try {
+      this.$.detailOutgoing.style.width = this.__detailCachedSize;
+
+      await updateSlot();
+
+      const progress = getCurrentAnimationProgress(this.$.detail);
+      await Promise.all([
+        animateIn(this.$.detail, ['fade', 'slide'], progress),
+        animateOut(this.$.detailOutgoing, ['fade', 'slide'], progress),
+      ]);
+    } finally {
+      // Skip removal if the slot was reassigned during the transition.
+      // The React component does this to let React handle the removal.
+      if (oldDetail?.slot === 'detail-outgoing') {
+        oldDetail.remove();
+      }
     }
-    // Resolve the update callback to finish the transition
-    this.__resolveUpdateCallback();
-    await this.__transition.finished;
-    this.removeAttribute('transition');
-    this.__transition = null;
-    this.__resolveUpdateCallback = null;
   }
 
-  /**
-   * @event backdrop-click
-   * Fired when the user clicks the backdrop in the drawer mode.
-   */
+  /** @private */
+  async __removeTransition(updateSlot) {
+    const progress = getCurrentAnimationProgress(this.$.detail);
+    await Promise.all([
+      animateOut(this.$.detail, ['fade', 'slide'], progress),
+      animateOut(this.$.backdrop, ['fade'], this.hasAttribute('overlay') ? progress : 1),
+    ]);
+
+    await updateSlot();
+  }
 
-  /**
-   * @event detail-escape-press
-   * Fired when the user presses Escape in the detail area.
-   */
+  /** @private */
+  get __slottedMaster() {
+    return this.querySelector(':scope > :is([slot=""], :not([slot]))');
+  }
+
+  /** @private */
+  get __slottedDetail() {
+    return this.querySelector(':scope > [slot="detail"]');
+  }
+
+  /** @private */
+  get __slottedDetailPlaceholder() {
+    return this.querySelector(':scope > [slot="detail-placeholder"]');
+  }
 }
 
 defineCustomElement(MasterDetailLayout);