@vaadin/master-detail-layout 25.1.0 → 25.2.0-alpha2

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

@@ -8,36 +8,69 @@ 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 { masterDetailLayoutStyles } from './styles/vaadin-master-detail-layout-base-styles.js';
-import { masterDetailLayoutTransitionStyles } from './styles/vaadin-master-detail-layout-transition-base-styles.js';
+
+function parseTrackSizes(gridTemplate) {
+  return gridTemplate
+    .replace(/\[[^\]]+\]/gu, '')
+    .replace(/\s+/gu, ' ')
+    .trim()
+    .split(' ')
+    .map(parseFloat);
+}
 
 /**
  * `<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`                  | Set to `master`, `detail`, or `both`.
+ * `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 `viewport`.
  *
  * The following custom CSS properties are available for styling:
  *
@@ -51,17 +84,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,11 +104,10 @@ 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. 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 15em.
        *
        * @attr {string} detail-size
        */
@@ -88,26 +118,10 @@ 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 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
        */
@@ -118,18 +132,16 @@ 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 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,25 +154,6 @@ 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,
       },
 
@@ -169,8 +162,10 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
        * 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`.
+       *
+       * @attr {string} overlay-containment
        */
-      containment: {
+      overlayContainment: {
         type: String,
         value: 'layout',
         reflectToAttribute: true,
@@ -178,19 +173,14 @@ 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`.
-       *
-       * @attr {string} stack-threshold
+       * Controls which column(s) expand to fill available space.
+       * Possible values: `'master'`, `'detail'`, `'both'`.
+       * Defaults to `'master'`.
        */
-      stackOverlay: {
-        type: Boolean,
-        value: false,
-        observer: '__stackOverlayChanged',
+      expand: {
+        type: String,
+        value: 'master',
+        reflectToAttribute: true,
         sync: true,
       },
 
@@ -202,38 +192,12 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
       noAnimation: {
         type: Boolean,
         value: false,
-      },
-
-      /**
-       * When true, the component uses the drawer mode. This property is read-only.
-       * @protected
-       */
-      _drawer: {
-        type: Boolean,
-        attribute: 'drawer',
-        reflectToAttribute: true,
-        sync: true,
-      },
-
-      /**
-       * When true, the component uses the stack mode. This property is read-only.
-       * @protected
-       */
-      _stack: {
-        type: Boolean,
-        attribute: 'stack',
         reflectToAttribute: true,
-        sync: true,
       },
 
-      /**
-       * When true, the component has the detail content provided.
-       * @protected
-       */
-      _hasDetail: {
+      /** @private */
+      __replacing: {
         type: Boolean,
-        attribute: 'has-detail',
-        reflectToAttribute: true,
         sync: true,
       },
     };
@@ -243,211 +207,191 @@ 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 isViewport = isOverlay && this.overlayContainment === 'viewport';
+    const isLayoutContained = isOverlay && !isViewport;
+
     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="outgoing" inert ?hidden="${!this.__replacing}">
+        <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="${isViewport ? '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="detail-placeholder" 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();
   }
 
-  /** @private */
-  __onBackdropClick() {
-    this.dispatchEvent(new CustomEvent('backdrop-click'));
+  /** @protected */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.__resizeObserver.disconnect();
+    cancelAnimationFrame(this.__resizeRaf);
+    this.__endTransition();
   }
 
   /** @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
-   * @override
-   */
-  _onResize() {
-    this.__detectLayoutMode();
+  __masterSizeChanged(size, oldSize) {
+    this.__updateStyleProperty('master-size', size, oldSize);
   }
 
   /** @private */
   __detailSizeChanged(size, oldSize) {
     this.__updateStyleProperty('detail-size', size, oldSize);
-    this.__detectLayoutMode();
   }
 
   /** @private */
-  __detailMinSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('detail-min-size', size, oldSize);
-    this.__detectLayoutMode();
+  __overlaySizeChanged(size, oldSize) {
+    this.__updateStyleProperty('overlay-size', size, oldSize);
   }
 
   /** @private */
-  __masterSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('master-size', size, oldSize);
-    this.__detectLayoutMode();
+  __updateStyleProperty(prop, size, oldSize) {
+    if (size) {
+      this.style.setProperty(`--_${prop}`, size);
+    } else if (oldSize) {
+      this.style.removeProperty(`--_${prop}`);
+    }
   }
 
   /** @private */
-  __masterMinSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('master-min-size', size, oldSize);
-    this.__detectLayoutMode();
+  __onSlotChange() {
+    this.__initResizeObserver();
   }
 
   /** @private */
-  __orientationChanged(orientation, oldOrientation) {
-    if (orientation || oldOrientation) {
-      this.__detectLayoutMode();
-    }
+  __initResizeObserver() {
+    this.__resizeObserver = this.__resizeObserver || new ResizeObserver(() => this.__onResize());
+    this.__resizeObserver.disconnect();
+
+    const children = this.querySelectorAll(':scope > [slot="detail"], :scope >:not([slot])');
+    [this, this.$.master, this.$.detail, ...children].forEach((node) => {
+      this.__resizeObserver.observe(node);
+    });
   }
 
-  /** @private */
-  __forceOverlayChanged(forceOverlay, oldForceOverlay) {
-    if (forceOverlay || oldForceOverlay) {
-      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.__computeLayoutState();
+    cancelAnimationFrame(this.__resizeRaf);
+    this.__resizeRaf = requestAnimationFrame(() => this.__applyLayoutState(state));
   }
 
-  /** @private */
-  __stackOverlayChanged(stackOverlay, oldStackOverlay) {
-    if (stackOverlay || oldStackOverlay) {
-      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
+   */
+  __computeLayoutState() {
+    const detailContent = this.querySelector(':scope > [slot="detail"]');
+    const detailPlaceholder = this.querySelector(':scope > [slot="detail-placeholder"]');
+
+    const hadDetail = this.hasAttribute('has-detail');
+    const hasDetail = detailContent != null && detailContent.checkVisibility();
+    const hasDetailPlaceholder = !!detailPlaceholder;
+    const hasOverflow = (hasDetail || hasDetailPlaceholder) && this.__checkOverflow();
+
+    const focusTarget = !hadDetail && hasDetail && hasOverflow ? getFocusableElements(detailContent)[0] : null;
+    return { hadDetail, hasDetail, hasDetailPlaceholder, hasOverflow, focusTarget };
   }
 
-  /** @private */
-  __updateStyleProperty(prop, size, oldSize) {
-    if (size) {
-      this.style.setProperty(`--_${prop}`, size);
-    } else if (oldSize) {
-      this.style.removeProperty(`--_${prop}`);
+  /**
+   * Applies layout state to DOM attributes. Pure writes, no reads.
+   * @private
+   */
+  __applyLayoutState({ hadDetail, hasDetail, hasDetailPlaceholder, hasOverflow, focusTarget }) {
+    // Set keep-detail-column-offscreen when detail first appears with overlay
+    // to prevent master width from jumping.
+    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-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 });
     }
   }
 
   /** @private */
-  __detectLayoutMode() {
-    this._drawer = false;
-    this._stack = false;
+  __checkOverflow() {
+    const isVertical = this.orientation === 'vertical';
+    const computedStyle = getComputedStyle(this);
 
-    if (this.forceOverlay) {
-      this.__setOverlayMode(true);
-      return;
-    }
+    const hostSize = parseFloat(computedStyle[isVertical ? 'height' : 'width']);
+    const [masterSize, masterExtra, detailSize] = parseTrackSizes(
+      computedStyle[isVertical ? 'gridTemplateRows' : 'gridTemplateColumns'],
+    );
 
-    if (!this._hasDetail) {
-      return;
+    if (Math.floor(masterSize + masterExtra + detailSize) <= Math.floor(hostSize)) {
+      return false;
     }
-
-    if (this.orientation === 'vertical') {
-      this.__detectVerticalMode();
-    } else {
-      this.__detectHorizontalMode();
+    if (Math.floor(masterExtra) >= Math.floor(detailSize)) {
+      return false;
     }
+    return true;
   }
 
   /** @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);
-    }
+  __onBackdropClick() {
+    this.dispatchEvent(new CustomEvent('backdrop-click'));
   }
 
   /** @private */
-  __detectVerticalMode() {
-    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.__setOverlayMode(true);
+  __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) {
@@ -467,13 +411,17 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
       }
     };
 
-    if (skipTransition) {
+    if (skipTransition || this.noAnimation) {
       updateSlot();
+      queueMicrotask(() => {
+        const state = this.__computeLayoutState();
+        this.__applyLayoutState(state);
+      });
       return Promise.resolve();
     }
 
-    const hasDetail = !!currentDetail;
-    const transitionType = hasDetail && element ? 'replace' : hasDetail ? 'remove' : 'add';
+    const transitionType = this.__getTransitionType(currentDetail, element);
+
     return this._startTransition(transitionType, () => {
       // Update the DOM
       updateSlot();
@@ -483,71 +431,278 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
   }
 
   /**
-   * 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.
+   * Determines the transition type for a detail change.
+   *
+   * Returns 'replace' in two cases:
+   * - Swapping one detail for another (standard replace).
+   * - Swapping between placeholder and detail in split mode,
+   *   so the swap appears instant (replace has 0ms duration in split).
+   *   In overlay mode, placeholder doesn't participate in transitions,
+   *   so standard 'add'/'remove' are used instead.
+   *
+   * @param {Element | null} currentDetail
+   * @param {Element | null} newDetail
+   * @return {string}
+   * @private
+   */
+  __getTransitionType(currentDetail, newDetail) {
+    if (currentDetail && newDetail) {
+      return 'replace';
+    }
+
+    const hasPlaceholder = !!this.querySelector('[slot="detail-placeholder"]');
+    if (hasPlaceholder && !this.hasAttribute('overlay')) {
+      return 'replace';
+    }
+
+    return currentDetail ? 'remove' : 'add';
+  }
+
+  /**
+   * Starts an animated transition for adding, replacing or removing the
+   * detail area using the Web Animations API.
    *
-   * 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', the DOM update is deferred until the slide-out completes.
+   * For 'add'/'replace', the DOM is updated immediately and the slide-in
+   * plays on the new content.
+   *
+   * Animations are interruptible: starting a new transition cancels any
+   * in-progress animation and the new animation picks up from the
+   * interrupted position (see `__captureDetailState`).
    *
    * @param transitionType
    * @param updateCallback
-   * @returns {Promise<void>}
+   * @return {Promise<void>}
    * @protected
    */
   _startTransition(transitionType, updateCallback) {
-    const useTransition = typeof document.startViewTransition === 'function' && !this.noAnimation;
-    if (!useTransition) {
+    if (this.noAnimation) {
       updateCallback();
       return Promise.resolve();
     }
 
+    // Capture mid-flight state before cancelling active animations
+    const interrupted = this.__captureDetailState();
+
+    this.__endTransition();
+
+    if (transitionType === 'replace') {
+      this.__snapshotOutgoing();
+    }
+
     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();
-      });
+
+    if (transitionType !== 'remove') {
+      updateCallback();
+    }
+
+    const opts = this.__getAnimationParams();
+    opts.interrupted = interrupted;
+    opts.overlay = this.hasAttribute('overlay');
+
+    return this.__animateTransition(transitionType, opts, updateCallback);
+  }
+
+  /**
+   * Creates slide animation(s) for the given transition type and returns
+   * a promise that resolves when the primary animation completes.
+   * A version counter prevents stale callbacks from executing after
+   * a newer transition has started.
+   *
+   * @param {string} transitionType
+   * @param {{ offscreen: string, duration: number, easing: string, interrupted?: { translate: string, opacity: string }, overlay?: boolean }} opts
+   * @param {Function} updateCallback
+   * @return {Promise<void>}
+   * @private
+   */
+  __animateTransition(transitionType, opts, updateCallback) {
+    const version = (this.__transitionVersion = (this.__transitionVersion || 0) + 1);
+
+    return new Promise((resolve) => {
+      this.__transitionResolve = resolve;
+
+      const onFinish = (callback) => {
+        if (this.__transitionVersion === version) {
+          if (callback) {
+            callback();
+          }
+          this.__endTransition();
+        }
+      };
+
+      if (transitionType === 'remove') {
+        this.__slide(this.$.detail, false, opts).then(() => onFinish(updateCallback));
+      } else if (transitionType === 'replace') {
+        // Outgoing slides out on top (z-index), revealing incoming underneath.
+        // In overlay mode, the incoming also slides in simultaneously.
+        this.__slide(this.$.outgoing, false, opts).then(() => onFinish());
+        if (opts.overlay) {
+          this.__slide(this.$.detail, true, { ...opts, interrupted: null });
+        }
+      } else {
+        this.__slide(this.$.detail, true, opts).then(() => onFinish());
+      }
+
+      // Fade backdrop in/out for overlay add/remove (not replace — backdrop stays visible)
+      if (opts.overlay && transitionType !== 'replace') {
+        const fadeIn = transitionType !== 'remove';
+        this.__animate(this.$.backdrop, [{ opacity: fadeIn ? 0 : 1 }, { opacity: fadeIn ? 1 : 0 }], {
+          duration: opts.duration,
+          easing: 'linear',
+        });
+      }
     });
-    return this.__transition.finished;
   }
 
   /**
-   * 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.
+   * Finishes the current transition by detecting and applying the layout
+   * state. This method should be called after the DOM has been updated.
    *
-   * @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());
+  _finishTransition() {
+    const state = this.__computeLayoutState();
+    this.__applyLayoutState(state);
+  }
+
+  /**
+   * Captures the detail panel's current animated state (translate and
+   * opacity). Must be called BEFORE `animation.cancel()`, because
+   * cancel removes the animation effect and the element reverts to
+   * its CSS resting state.
+   *
+   * Returns null when there is no active animation.
+   *
+   * @return {{ translate: string, opacity: string } | null}
+   * @private
+   */
+  __captureDetailState() {
+    if (!this.__activeAnimations || this.__activeAnimations.length === 0) {
+      return null;
+    }
+    const { translate, opacity } = getComputedStyle(this.$.detail);
+    return { translate, opacity };
+  }
+
+  /**
+   * Reads animation parameters from CSS custom properties. Called once
+   * per transition so that animating stays free of layout reads.
+   *
+   * @return {{ offscreen: string, duration: number, easing: string }}
+   * @private
+   */
+  __getAnimationParams() {
+    const cs = getComputedStyle(this);
+    const offscreen = cs.getPropertyValue('--_detail-offscreen').trim();
+    const durationStr = cs.getPropertyValue('--_transition-duration').trim();
+    const duration = durationStr.endsWith('ms') ? parseFloat(durationStr) : parseFloat(durationStr) * 1000;
+    const easing = cs.getPropertyValue('--_transition-easing').trim();
+    return { offscreen, duration, easing };
+  }
 
-    if (!this.__transition) {
+  /**
+   * Creates a slide animation on the element's `translate` property
+   * using the Web Animations API. Returns a promise that resolves when
+   * the animation finishes, or immediately if the duration is 0.
+   *
+   * @param {HTMLElement} element - The element to animate
+   * @param {boolean} slideIn - If true, slide in (off-screen → on-screen);
+   *   otherwise slide out (on-screen → off-screen)
+   * @param {{ offscreen: string, duration: number, easing: string, interrupted?: { translate: string, opacity: string }, overlay?: boolean }} opts
+   *   Animation parameters. `interrupted` overrides the default starting
+   *   keyframe for interrupted animations (captured mid-flight before cancel).
+   * @return {Promise<void>}
+   * @private
+   */
+  __slide(element, slideIn, { offscreen, duration, easing, interrupted, overlay }) {
+    if (!offscreen || duration <= 0) {
       return Promise.resolve();
     }
-    // Resolve the update callback to finish the transition
-    this.__resolveUpdateCallback();
-    await this.__transition.finished;
+
+    const defaultTranslate = slideIn ? offscreen : 'none';
+    const defaultOpacity = !overlay && slideIn ? 0 : 1;
+
+    const start = interrupted ? interrupted.translate : defaultTranslate;
+    const end = slideIn ? 'none' : offscreen;
+
+    const opacityStart = interrupted ? Number(interrupted.opacity) : defaultOpacity;
+    const opacityEnd = !overlay && !slideIn ? 0 : 1;
+
+    return this.__animate(
+      element,
+      [
+        { translate: start, opacity: opacityStart },
+        { translate: end, opacity: opacityEnd },
+      ],
+      { duration, easing },
+    );
+  }
+
+  /**
+   * Runs a Web Animation on the given element, tracks it for cancellation,
+   * and returns a promise that resolves when finished (or swallows the
+   * rejection if cancelled).
+   *
+   * @param {HTMLElement} element
+   * @param {Keyframe[]} keyframes
+   * @param {KeyframeAnimationOptions} options
+   * @return {Promise<void>}
+   * @private
+   */
+  __animate(element, keyframes, options) {
+    const animation = element.animate(keyframes, options);
+
+    this.__activeAnimations = this.__activeAnimations || [];
+    this.__activeAnimations.push(animation);
+
+    return animation.finished.catch(() => {});
+  }
+
+  /**
+   * Cancels in-progress animations, cleans up state, and resolves the
+   * pending transition promise.
+   * @private
+   */
+  __endTransition() {
+    if (this.__activeAnimations) {
+      this.__activeAnimations.forEach((a) => a.cancel());
+      this.__activeAnimations = null;
+    }
     this.removeAttribute('transition');
-    this.__transition = null;
-    this.__resolveUpdateCallback = null;
+    this.__clearOutgoing();
+    if (this.__transitionResolve) {
+      this.__transitionResolve();
+      this.__transitionResolve = null;
+    }
+  }
+
+  /**
+   * Moves the current detail content to the outgoing slot so it can
+   * slide out while the new content slides in. Keeps the element in
+   * light DOM so light DOM styles continue to apply.
+   * @private
+   */
+  __snapshotOutgoing() {
+    const currentDetail = this.querySelector('[slot="detail"]');
+    if (!currentDetail) {
+      return;
+    }
+    currentDetail.setAttribute('slot', 'detail-outgoing');
+    this.__replacing = true;
+  }
+
+  /**
+   * Clears the outgoing container after the replace transition completes.
+   * @private
+   */
+  __clearOutgoing() {
+    this.querySelectorAll('[slot="detail-outgoing"]').forEach((el) => el.remove());
+    this.__replacing = false;
   }
 
   /**
    * @event backdrop-click
-   * Fired when the user clicks the backdrop in the drawer mode.
+   * Fired when the user clicks the backdrop in the overlay mode.
    */
 
   /**