@vaadin/master-detail-layout 25.2.0-alpha4 → 25.2.0-alpha6

package/custom-elements.json

@@ -17,6 +17,226 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/vaadin-master-detail-layout-helpers.js",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "getCurrentAnimation",
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "HTMLElement"
+              }
+            }
+          ],
+          "description": "Returns the currently running master-detail-layout animation on the\nelement, if any. Matches by the shared animation ID and `'running'`\nplay state.",
+          "return": {
+            "type": {
+              "text": "Animation | undefined"
+            }
+          }
+        },
+        {
+          "kind": "function",
+          "name": "getCurrentAnimationProgress",
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "HTMLElement"
+              }
+            }
+          ],
+          "description": "Returns the overall progress (0–1) of the current animation on the\nelement, computed as `currentTime / duration`. Returns 0 when no\nanimation is running.",
+          "return": {
+            "type": {
+              "text": "number"
+            }
+          }
+        },
+        {
+          "kind": "function",
+          "name": "animateIn",
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "HTMLElement"
+              }
+            },
+            {
+              "name": "effects",
+              "type": {
+                "text": "Array<'fade' | 'slide'>"
+              }
+            },
+            {
+              "name": "progress",
+              "description": "starting progress (0–1) for interrupted resumption",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Runs an enter animation on the element.",
+          "return": {
+            "type": {
+              "text": "Promise<void>"
+            }
+          }
+        },
+        {
+          "kind": "function",
+          "name": "animateOut",
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "HTMLElement"
+              }
+            },
+            {
+              "name": "effects",
+              "type": {
+                "text": "Array<'fade' | 'slide'>"
+              }
+            },
+            {
+              "name": "progress",
+              "description": "starting progress (0–1) for interrupted resumption",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Runs an exit animation on the element.",
+          "return": {
+            "type": {
+              "text": "Promise<void>"
+            }
+          }
+        },
+        {
+          "kind": "function",
+          "name": "cancelAnimations",
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "HTMLElement"
+              }
+            }
+          ],
+          "description": "Cancels all running animations on the element that match the shared animation ID."
+        },
+        {
+          "kind": "function",
+          "name": "parseTrackSizes",
+          "parameters": [
+            {
+              "name": "gridTemplate",
+              "description": "computed grid template string (e.g. `\"200px [gap] 10px 400px\"`)",
+              "type": {
+                "text": "string"
+              }
+            }
+          ],
+          "description": "Parses a computed `gridTemplateColumns` / `gridTemplateRows` value\ninto an array of track sizes in pixels. Line names (e.g. `[name]`)\nare stripped before parsing.",
+          "return": {
+            "type": {
+              "text": "number[]"
+            }
+          }
+        },
+        {
+          "kind": "function",
+          "name": "detectOverflow",
+          "parameters": [
+            {
+              "name": "hostSize",
+              "description": "the host element's width or height in pixels",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "trackSizes",
+              "description": "[masterSize, masterExtra, detailSize] in pixels",
+              "type": {
+                "text": "number[]"
+              }
+            }
+          ],
+          "description": "Determines whether the detail area overflows the host element,\nmeaning it should be shown as an overlay instead of side-by-side.\n\nReturns `false` when all tracks fit within the host, or when the\nmaster's extra space (flexible portion) is large enough to absorb\nthe detail column.",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "getCurrentAnimation",
+          "declaration": {
+            "name": "getCurrentAnimation",
+            "module": "src/vaadin-master-detail-layout-helpers.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "getCurrentAnimationProgress",
+          "declaration": {
+            "name": "getCurrentAnimationProgress",
+            "module": "src/vaadin-master-detail-layout-helpers.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "animateIn",
+          "declaration": {
+            "name": "animateIn",
+            "module": "src/vaadin-master-detail-layout-helpers.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "animateOut",
+          "declaration": {
+            "name": "animateOut",
+            "module": "src/vaadin-master-detail-layout-helpers.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "cancelAnimations",
+          "declaration": {
+            "name": "cancelAnimations",
+            "module": "src/vaadin-master-detail-layout-helpers.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "parseTrackSizes",
+          "declaration": {
+            "name": "parseTrackSizes",
+            "module": "src/vaadin-master-detail-layout-helpers.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "detectOverflow",
+          "declaration": {
+            "name": "detectOverflow",
+            "module": "src/vaadin-master-detail-layout-helpers.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/vaadin-master-detail-layout.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/master-detail-layout",
-  "version": "25.2.0-alpha4",
+  "version": "25.2.0-alpha6",
   "publishConfig": {
     "access": "public"
   },
@@ -34,16 +34,16 @@
     "web-component"
   ],
   "dependencies": {
-    "@vaadin/a11y-base": "25.2.0-alpha4",
-    "@vaadin/component-base": "25.2.0-alpha4",
-    "@vaadin/vaadin-themable-mixin": "25.2.0-alpha4",
+    "@vaadin/a11y-base": "25.2.0-alpha6",
+    "@vaadin/component-base": "25.2.0-alpha6",
+    "@vaadin/vaadin-themable-mixin": "25.2.0-alpha6",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.2.0-alpha4",
-    "@vaadin/chai-plugins": "25.2.0-alpha4",
+    "@vaadin/aura": "25.2.0-alpha6",
+    "@vaadin/chai-plugins": "25.2.0-alpha6",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.2.0-alpha4",
+    "@vaadin/vaadin-lumo-styles": "25.2.0-alpha6",
     "sinon": "^21.0.2"
   },
   "customElements": "custom-elements.json",
@@ -51,5 +51,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "fc054a1bed540874ef3b5000828c191cc12044ec"
+  "gitHead": "30f23c65765f27616f2db292406d5759a7e987c3"
 }

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

@@ -14,10 +14,10 @@ export const masterDetailLayoutStyles = css`
     --_detail-extra: 0px;
     --_detail-cached-size: min-content;
 
+    --_rtl-multiplier: 1;
     --_transition-duration: 0s;
     --_transition-easing: cubic-bezier(0.78, 0, 0.22, 1);
-    --_rtl-multiplier: 1;
-    --_detail-offscreen: calc(30px * var(--_rtl-multiplier));
+    --_transition-offset: calc(30px * var(--_rtl-multiplier));
 
     display: grid;
     box-sizing: border-box;
@@ -42,7 +42,7 @@ export const masterDetailLayoutStyles = css`
   }
 
   :host([orientation='vertical']) {
-    --_detail-offscreen: 0 30px;
+    --_transition-offset: 0 30px;
 
     grid-template-columns: 100%;
     grid-template-rows:
@@ -56,11 +56,14 @@ export const masterDetailLayoutStyles = css`
   }
 
   #detail-placeholder {
-    visibility: hidden;
+    z-index: 1;
+    opacity: 0;
+    pointer-events: none;
   }
 
   :host([has-detail-placeholder]:not([has-detail], [overlay])) #detail-placeholder {
-    visibility: visible;
+    opacity: 1;
+    pointer-events: auto;
   }
 
   #master {
@@ -84,9 +87,11 @@ export const masterDetailLayoutStyles = css`
   }
 
   #backdrop {
+    --_transition-easing: linear;
+
     position: absolute;
     inset: 0;
-    z-index: 1;
+    z-index: 2;
     opacity: 0;
     pointer-events: none;
     background: var(--vaadin-overlay-backdrop-background, rgba(0, 0, 0, 0.2));
@@ -125,32 +130,33 @@ export const masterDetailLayoutStyles = css`
       var(--vaadin-master-detail-layout-border-color, var(--vaadin-border-color-secondary));
   }
 
+  #outgoing {
+    position: absolute;
+    z-index: 3;
+  }
+
   /* Detail transition: off-screen by default, on-screen when has-detail */
   #detail {
-    translate: var(--_detail-offscreen);
-    visibility: hidden;
+    translate: var(--_transition-offset);
+    opacity: 0;
+    z-index: 4;
   }
 
   :host([has-detail]) #detail {
     translate: none;
-    visibility: visible;
-  }
-
-  #outgoing:not([hidden]) {
-    z-index: 1;
+    opacity: 1;
   }
 
   :host([overlay]) {
-    --_detail-offscreen: calc((100% + 30px) * var(--_rtl-multiplier));
+    --_transition-offset: calc((100% + 30px) * var(--_rtl-multiplier));
   }
 
   :host([overlay][orientation='vertical']) {
-    --_detail-offscreen: 0 calc(100% + 30px);
+    --_transition-offset: 0 calc(100% + 30px);
   }
 
   :host([has-detail][overlay]) :is(#detail, #outgoing) {
     position: absolute;
-    z-index: 2;
     background: var(--vaadin-master-detail-layout-detail-background, var(--vaadin-background-color));
     box-shadow: var(--vaadin-master-detail-layout-detail-shadow, 0 0 20px 0 rgba(0, 0, 0, 0.3));
     grid-column: none;

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

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright (c) 2025 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+const ANIMATION_ID = 'vaadin-master-detail-layout';
+
+/**
+ * Reads CSS custom properties from the element that control
+ * animation keyframes and timing.
+ *
+ * @param {HTMLElement} element
+ * @return {{ offset: string, easing: string, duration: number }}
+ */
+function getAnimationParams(element) {
+  const computedStyle = getComputedStyle(element);
+  const offset = computedStyle.getPropertyValue('--_transition-offset');
+  const easing = computedStyle.getPropertyValue('--_transition-easing');
+  const durationStr = computedStyle.getPropertyValue('--_transition-duration');
+  const duration = durationStr.endsWith('ms') ? parseFloat(durationStr) : parseFloat(durationStr) * 1000;
+  return { offset, easing, duration };
+}
+
+/**
+ * Returns the currently running master-detail-layout animation on the
+ * element, if any. Matches by the shared animation ID and `'running'`
+ * play state.
+ *
+ * @param {HTMLElement} element
+ * @return {Animation | undefined}
+ */
+export function getCurrentAnimation(element) {
+  return element
+    .getAnimations()
+    .find((animation) => animation.id === ANIMATION_ID && animation.playState !== 'finished');
+}
+
+/**
+ * Returns the overall progress (0–1) of the current animation on the
+ * element, computed as `currentTime / duration`. Returns 0 when no
+ * animation is running.
+ *
+ * @param {HTMLElement} element
+ * @return {number}
+ */
+export function getCurrentAnimationProgress(element) {
+  const animation = getCurrentAnimation(element);
+  if (!animation) {
+    return 0;
+  }
+  const currentTime = animation.currentTime;
+  if (currentTime == null) {
+    return 0;
+  }
+  return currentTime / animation.effect.getTiming().duration;
+}
+
+/**
+ * Animates the element using the Web Animations API. Cancels any
+ * previous animation and resumes from the given progress for a
+ * smooth handoff. No-op when CSS params are missing or progress is 1.
+ *
+ * @param {HTMLElement} element
+ * @param {'in' | 'out'} direction
+ * @param {Array<'fade' | 'slide'>} effects
+ * @param {number} progress starting progress (0–1) for interrupted resumption
+ * @return {Promise<void>} resolves when the animation finishes
+ */
+function animate(element, direction, effects, progress) {
+  const { offset, easing, duration } = getAnimationParams(element);
+  if (!offset || !duration || progress === 1) {
+    return Promise.resolve();
+  }
+
+  const oldAnimation = getCurrentAnimation(element);
+  if (oldAnimation) {
+    oldAnimation.cancel();
+  }
+
+  const keyframes = {};
+  if (effects.includes('fade')) {
+    keyframes.opacity = [0, 1];
+  }
+  if (effects.includes('slide')) {
+    keyframes.translate = [offset, 0];
+  }
+
+  const newAnimation = element.animate(keyframes, { id: ANIMATION_ID, easing, duration });
+  newAnimation.pause();
+  newAnimation.currentTime = duration * progress;
+  newAnimation.playbackRate = direction === 'in' ? 1 : -1;
+  newAnimation.play();
+  return newAnimation.finished;
+}
+
+/**
+ * Runs an enter animation on the element.
+ *
+ * @param {HTMLElement} element
+ * @param {Array<'fade' | 'slide'>} effects
+ * @param {number} progress starting progress (0–1) for interrupted resumption
+ * @return {Promise<void>} resolves when the animation finishes
+ */
+export function animateIn(element, effects, progress) {
+  return animate(element, 'in', effects, progress);
+}
+
+/**
+ * Runs an exit animation on the element.
+ *
+ * @param {HTMLElement} element
+ * @param {Array<'fade' | 'slide'>} effects
+ * @param {number} progress starting progress (0–1) for interrupted resumption
+ * @return {Promise<void>} resolves when the animation finishes
+ */
+export function animateOut(element, effects, progress) {
+  return animate(element, 'out', effects, progress);
+}
+
+/**
+ * Cancels all running animations on the element that match the shared animation ID.
+ *
+ * @param {HTMLElement} element
+ */
+export function cancelAnimations(element) {
+  element.getAnimations({ subtree: true }).forEach((animation) => {
+    if (animation.id === ANIMATION_ID) {
+      animation.cancel();
+    }
+  });
+}
+
+/**
+ * Parses a computed `gridTemplateColumns` / `gridTemplateRows` value
+ * into an array of track sizes in pixels. Line names (e.g. `[name]`)
+ * are stripped before parsing.
+ *
+ * @param {string} gridTemplate computed grid template string (e.g. `"200px [gap] 10px 400px"`)
+ * @return {number[]} track sizes in pixels
+ */
+export function parseTrackSizes(gridTemplate) {
+  return gridTemplate
+    .replace(/\[[^\]]+\]/gu, '')
+    .replace(/\s+/gu, ' ')
+    .trim()
+    .split(' ')
+    .map(parseFloat);
+}
+
+/**
+ * Determines whether the detail area overflows the host element,
+ * meaning it should be shown as an overlay instead of side-by-side.
+ *
+ * Returns `false` when all tracks fit within the host, or when the
+ * master's extra space (flexible portion) is large enough to absorb
+ * the detail column.
+ *
+ * @param {number} hostSize the host element's width or height in pixels
+ * @param {number[]} trackSizes [masterSize, masterExtra, detailSize] in pixels
+ * @return {boolean} `true` if the detail overflows and should be overlaid
+ */
+export function detectOverflow(hostSize, trackSizes) {
+  const [masterSize, masterExtra, detailSize] = trackSizes;
+
+  if (Math.floor(masterSize + masterExtra + detailSize) <= Math.floor(hostSize)) {
+    return false;
+  }
+  if (Math.floor(masterExtra) >= Math.floor(detailSize)) {
+    return false;
+  }
+  return true;
+}

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

@@ -11,27 +11,14 @@ import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { masterDetailLayoutStyles } from './styles/vaadin-master-detail-layout-base-styles.js';
-
-function parseTrackSizes(gridTemplate) {
-  return gridTemplate
-    .replace(/\[[^\]]+\]/gu, '')
-    .replace(/\s+/gu, ' ')
-    .trim()
-    .split(' ')
-    .map(parseFloat);
-}
-
-function detectOverflow(hostSize, trackSizes) {
-  const [masterSize, masterExtra, detailSize] = trackSizes;
-
-  if (Math.floor(masterSize + masterExtra + detailSize) <= Math.floor(hostSize)) {
-    return false;
-  }
-  if (Math.floor(masterExtra) >= Math.floor(detailSize)) {
-    return false;
-  }
-  return true;
-}
+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
@@ -274,7 +261,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     super.disconnectedCallback();
     this.__resizeObserver.disconnect();
     cancelAnimationFrame(this.__resizeRaf);
-    this.__endTransition();
+    cancelAnimations(this);
   }
 
   /** @private */
@@ -507,282 +494,130 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
    * @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.querySelector('[slot="detail"]');
+    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 && oldDetail.slot === 'detail') {
+        oldDetail.remove();
       }
-    };
 
-    if (skipTransition || this.noAnimation) {
-      updateSlot();
-      queueMicrotask(() => this.recalculateLayout());
-      return Promise.resolve();
-    }
+      if (newDetail) {
+        newDetail.setAttribute('slot', 'detail');
+        this.appendChild(newDetail);
+      }
 
-    const transitionType = this.__getTransitionType(currentDetail, element);
+      // Wait for Lit elements to render
+      await Promise.resolve();
 
-    return this._startTransition(transitionType, () => {
-      // Update the DOM
-      updateSlot();
-      // Finish the transition
-      this._finishTransition();
-    });
-  }
+      this.recalculateLayout();
+    };
 
-  /**
-   * 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';
+    if (skipTransition || this.noAnimation) {
+      await updateSlot();
+      return;
     }
 
     const hasPlaceholder = !!this.querySelector('[slot="detail-placeholder"]');
-    if (hasPlaceholder && !this.hasAttribute('overlay')) {
-      return 'replace';
+    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);
     }
-
-    return currentDetail ? 'remove' : 'add';
   }
 
   /**
    * Starts an animated transition for adding, replacing or removing the
    * detail area using the Web Animations API.
    *
-   * 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.
+   * 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).
    *
-   * Animations are interruptible: starting a new transition cancels any
-   * in-progress animation and the new animation picks up from the
-   * interrupted position (see `__captureDetailState`).
+   * 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
+   * @param updateSlot
    * @return {Promise<void>}
    * @protected
    */
-  _startTransition(transitionType, updateCallback) {
+  async _startTransition(transitionType, updateSlot) {
     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);
-
-    if (transitionType !== 'remove') {
-      updateCallback();
+      await updateSlot();
+      return;
     }
 
-    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());
+    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;
       }
 
-      // 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',
-        });
+      this.removeAttribute('transition');
+    } catch (e) {
+      if (e instanceof DOMException && e.name === 'AbortError') {
+        return; // Animation was cancelled
       }
-    });
-  }
-
-  /**
-   * Finishes the current transition by detecting and applying the layout
-   * state. This method should be called after the DOM has been updated.
-   *
-   * @protected
-   */
-  _finishTransition() {
-    queueMicrotask(() => this.recalculateLayout());
-  }
-
-  /**
-   * 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;
+      throw e;
     }
-    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 };
-  }
-
-  /**
-   * 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();
-    }
-
-    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;
+  /** @private */
+  async __addTransition(updateSlot) {
+    await updateSlot();
 
-    return this.__animate(
-      element,
-      [
-        { translate: start, opacity: opacityStart },
-        { translate: end, opacity: opacityEnd },
-      ],
-      { duration, easing },
-    );
+    const progress = getCurrentAnimationProgress(this.$.detail);
+    await Promise.all([
+      animateIn(this.$.detail, ['fade', 'slide'], progress),
+      animateIn(this.$.backdrop, ['fade'], this.hasAttribute('overlay') ? progress : 1),
+    ]);
   }
 
-  /**
-   * 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, fill: 'forwards' });
+  /** @private */
+  async __replaceTransition(updateSlot) {
+    try {
+      this.__snapshotOutgoing();
 
-    this.__activeAnimations = this.__activeAnimations || [];
-    this.__activeAnimations.push(animation);
+      await updateSlot();
 
-    return animation.finished.catch(() => {});
+      const progress = getCurrentAnimationProgress(this.$.detail);
+      await Promise.all([
+        animateIn(this.$.detail, ['fade', 'slide'], progress),
+        animateOut(this.$.outgoing, ['fade', 'slide'], progress),
+      ]);
+    } finally {
+      this.__clearOutgoing();
+    }
   }
 
-  /**
-   * 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.__clearOutgoing();
-    if (this.__transitionResolve) {
-      this.__transitionResolve();
-      this.__transitionResolve = null;
-    }
+  /** @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();
   }
 
   /**
@@ -797,6 +632,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
       return;
     }
     currentDetail.setAttribute('slot', 'detail-outgoing');
+    this.$.outgoing.style.width = this.__detailCachedSize;
     this.__replacing = true;
   }
 
@@ -806,6 +642,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
    */
   __clearOutgoing() {
     this.querySelectorAll('[slot="detail-outgoing"]').forEach((el) => el.remove());
+    this.$.outgoing.style.width = '';
     this.__replacing = false;
   }
 

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/master-detail-layout",
-  "version": "25.2.0-alpha4",
+  "version": "25.2.0-alpha6",
   "description-markup": "markdown",
   "contributions": {
     "html": {

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/master-detail-layout",
-  "version": "25.2.0-alpha4",
+  "version": "25.2.0-alpha6",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {