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

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

@@ -4,48 +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 { 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);
-}
+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 overlay 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
- * ----------------------|----------------------
- * `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.
- * `overflow`            | Set when columns don't fit and the detail is shown as an overlay.
- * `overlay-containment` | Set to `layout` or `viewport`.
+ * 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:
  *
@@ -66,9 +92,8 @@ function parseTrackSizes(gridTemplate) {
  * @extends HTMLElement
  * @mixes ThemableMixin
  * @mixes ElementMixin
- * @mixes SlotStylesMixin
  */
-class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)))) {
+class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
   static get is() {
     return 'vaadin-master-detail-layout';
   }
@@ -81,16 +106,21 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
     return {
       /**
        * 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
+       * 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. Defaults to 15em.
+       * 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',
       },
 
       /**
@@ -104,7 +134,6 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
       masterSize: {
         type: String,
         sync: true,
-        observer: '__masterSizeChanged',
       },
 
       /**
@@ -136,7 +165,7 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
       /**
        * 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
@@ -149,13 +178,29 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
       },
 
       /**
-       * Controls which column(s) expand to fill available space.
-       * Possible values: `'master'`, `'detail'`, `'both'`.
-       * Defaults to `'both'`.
+       * When true, the master area grows to fill the available space.
+       * If `expandDetail` is also true, both areas share the available
+       * space equally.
+       *
+       * @attr {boolean} expand-master
        */
-      expand: {
-        type: String,
-        value: 'both',
+      expandMaster: {
+        type: Boolean,
+        value: false,
+        reflectToAttribute: true,
+        sync: true,
+      },
+
+      /**
+       * 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} expand-detail
+       */
+      expandDetail: {
+        type: Boolean,
+        value: false,
         reflectToAttribute: true,
         sync: true,
       },
@@ -168,6 +213,28 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
       noAnimation: {
         type: Boolean,
         value: false,
+        reflectToAttribute: true,
+      },
+
+      /**
+       * 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
+       */
+      forceOverlay: {
+        type: Boolean,
+        value: false,
+        reflectToAttribute: true,
+        sync: true,
+      },
+
+      /** @private */
+      __detailCachedSize: {
+        type: String,
+        observer: '__detailCachedSizeChanged',
+        sync: true,
       },
     };
   }
@@ -176,31 +243,32 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
     return true;
   }
 
-  /** @return {!Array<!CSSResult>} */
-  get slotStyles() {
-    return [masterDetailLayoutTransitionStyles];
-  }
-
   /** @protected */
   render() {
-    const isOverlay = this.hasAttribute('has-detail') && this.hasAttribute('overflow');
-    const isViewport = isOverlay && this.overlayContainment === 'viewport';
-    const isLayoutContained = isOverlay && !isViewport;
+    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="detail"
         part="detail"
         role="${isOverlay ? 'dialog' : nothing}"
-        aria-modal="${isViewport ? 'true' : nothing}"
+        aria-modal="${isPage ? 'true' : nothing}"
         @keydown="${this.__onDetailKeydown}"
       >
         <slot name="detail" @slotchange="${this.__onSlotChange}"></slot>
       </div>
+      <div id="detailPlaceholder" part="detail-placeholder">
+        <slot name="detail-placeholder" @slotchange="${this.__onSlotChange}"></slot>
+      </div>
     `;
   }
 
@@ -208,6 +276,17 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
   connectedCallback() {
     super.connectedCallback();
     this.__initResizeObserver();
+
+    const ancestorLayouts = this.__ancestorLayouts;
+    if (ancestorLayouts.length > 0) {
+      ancestorLayouts.forEach((layout) => {
+        cancelAnimationFrame(layout.__initialRaf);
+      });
+
+      this.__initialRaf = requestAnimationFrame(() => {
+        this.recalculateLayout();
+      });
+    }
   }
 
   /** @protected */
@@ -215,30 +294,40 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
     super.disconnectedCallback();
     this.__resizeObserver.disconnect();
     cancelAnimationFrame(this.__resizeRaf);
+    cancelAnimationFrame(this.__initialRaf);
+    cancelAnimations(this);
   }
 
-  /** @private */
-  __masterSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('master-size', size, oldSize);
-  }
+  /** @protected */
+  updated(props) {
+    super.updated(props);
 
-  /** @private */
-  __detailSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('detail-size', size, oldSize);
+    if (props.has('masterSize')) {
+      this.style.setProperty('--_master-size', this.masterSize);
+    }
+
+    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 */
-  __overlaySizeChanged(size, oldSize) {
-    this.__updateStyleProperty('overlay-size', size, oldSize);
+  __overlaySizeChanged(size) {
+    this.style.setProperty('--_overlay-size', size);
   }
 
   /** @private */
-  __updateStyleProperty(prop, size, oldSize) {
-    if (size) {
-      this.style.setProperty(`--_${prop}`, size);
-    } else if (oldSize) {
-      this.style.removeProperty(`--_${prop}`);
-    }
+  __detailCachedSizeChanged(size) {
+    this.style.setProperty('--_detail-cached-size', size);
   }
 
   /** @private */
@@ -248,12 +337,13 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
 
   /** @private */
   __initResizeObserver() {
-    this.__resizeObserver = this.__resizeObserver || new ResizeObserver(() => this.__onResize());
+    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);
+    [this, this.$.master, this.$.detail, this.__slottedMaster, this.__slottedDetail].forEach((node) => {
+      if (node) {
+        this.__resizeObserver.observe(node);
+      }
     });
   }
 
@@ -264,9 +354,9 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
    * @private
    */
   __onResize() {
-    const state = this.__computeLayoutState();
+    const state = this.__readLayoutState();
     cancelAnimationFrame(this.__resizeRaf);
-    this.__resizeRaf = requestAnimationFrame(() => this.__applyLayoutState(state));
+    this.__resizeRaf = requestAnimationFrame(() => this.__writeLayoutState(state));
   }
 
   /**
@@ -274,57 +364,133 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
    * ResizeObserver callback where layout is already computed (no forced reflow).
    * @private
    */
-  __computeLayoutState() {
-    const detailContent = this.querySelector('[slot="detail"]');
+  __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 = detailContent != null && detailContent.checkVisibility();
-    const hasOverflow = hasDetail && this.__checkOverflow();
-    const focusTarget = !hadDetail && hasDetail && hasOverflow ? getFocusableElements(detailContent)[0] : null;
-    return { hadDetail, hasDetail, hasOverflow, focusTarget };
+    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,
+    };
   }
 
   /**
    * Applies layout state to DOM attributes. Pure writes, no reads.
    * @private
    */
-  __applyLayoutState({ hadDetail, hasDetail, hasOverflow, focusTarget }) {
-    // Set keep-detail-column-offscreen when detail first appears with overflow
-    // to prevent master width from jumping.
+  __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;
+    }
+
+    // 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('overlay', hasOverflow);
+    this.toggleAttribute('has-master', hasMaster);
     this.toggleAttribute('has-detail', hasDetail);
-    this.toggleAttribute('overflow', hasOverflow);
+    this.toggleAttribute('has-detail-placeholder', hasDetailPlaceholder);
 
     // Re-render to update ARIA attributes (role, aria-modal, inert)
-    // which depend on has-detail and overflow state.
+    // which depend on has-detail and overlay state.
     this.requestUpdate();
 
     if (focusTarget) {
-      focusTarget.focus();
+      focusTarget.focus({ preventScroll: true, focusVisible: isKeyboardActive() });
     }
   }
 
-  /** @private */
-  __checkOverflow() {
-    const isVertical = this.orientation === 'vertical';
-    const computedStyle = getComputedStyle(this);
+  /**
+   * 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];
 
-    const hostSize = parseFloat(computedStyle[isVertical ? 'height' : 'width']);
-    const [masterSize, masterExtra, detailSize] = parseTrackSizes(
-      computedStyle[isVertical ? 'gridTemplateRows' : 'gridTemplateColumns'],
-    );
+    // 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 (Math.floor(masterSize + masterExtra + detailSize) <= Math.floor(hostSize)) {
-      return false;
-    }
-    if (Math.floor(masterExtra) >= Math.floor(detailSize)) {
-      return false;
-    }
-    return true;
+      layout.__detailCachedSize = null;
+
+      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 */
+  get __isDetailAutoSized() {
+    return this.detailSize == null;
+  }
+
+  /** @private */
+  get __ancestorLayouts() {
+    const parent = getClosestElement(this.constructor.is, this.parentNode);
+    return parent ? [...parent.__ancestorLayouts, parent] : [];
   }
 
   /** @private */
@@ -342,128 +508,169 @@ class MasterDetailLayout extends SlotStylesMixin(ElementMixin(ThemableMixin(Poly
   }
 
   /**
-   * 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 layout mode before resolving the transition, so the browser's
-    // "new" snapshot includes the correct overlay state. The microtask runs
-    // before the Promise resolution propagates to startViewTransition.
-    queueMicrotask(() => {
-      const state = this.__computeLayoutState();
-      this.__applyLayoutState(state);
-    });
+  /** @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';
+    }
 
-    if (!this.__transition) {
-      return Promise.resolve();
+    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 overlay 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);