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

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

@@ -7,189 +7,288 @@ import '@vaadin/component-base/src/styles/style-props.js';
 import { css } from 'lit';
 
 export const masterDetailLayoutStyles = css`
-  /* Layout and positioning styles */
-
+  /* stylelint-disable no-duplicate-selectors */
   :host {
-    display: flex;
+    --_rtl-multiplier: 1;
+    --_transition-duration: 0s;
+    --_transition-easing: cubic-bezier(0.78, 0, 0.22, 1);
+
+    display: grid;
     box-sizing: border-box;
     height: 100%;
-    max-width: 100%;
-    max-height: 100%;
-    position: relative; /* Keep the positioning context stable across all modes */
-    z-index: 0; /* Create a new stacking context, don't let "layout contained" detail element stack outside it */
-    overflow: hidden;
+    position: relative;
+    overflow: clip;
   }
 
-  :host([hidden]) {
-    display: none !important;
+  :host:not([overlay-containment='page']) {
+    z-index: 0;
+  }
+
+  :host([dir='rtl']) {
+    --_rtl-multiplier: -1;
+  }
+
+  :host([orientation='horizontal']) {
+    --_transition-offset: calc(30px * var(--_rtl-multiplier));
   }
 
   :host([orientation='vertical']) {
-    flex-direction: column;
+    --_transition-offset: 0 30px;
   }
 
-  [part='_detail-internal'] {
-    display: contents;
-    justify-content: end;
-    /* Disable pointer events for the detail wrapper to allow clicks to pass through to the backdrop */
-    pointer-events: none;
+  :host([hidden]),
+  ::slotted([hidden]) {
+    display: none !important;
   }
 
-  [part='detail'] {
-    /* Re-enable pointer events for the actual detail content */
-    pointer-events: auto;
+  /* CSS grid template */
+
+  :host {
+    --_master-size: min(100%, 30rem);
+    --_master-extra: 0px;
+    --_detail-size: var(--_detail-cached-size);
+    --_detail-extra: 0px;
+    --_detail-cached-size: min-content;
+
+    /* prettier-ignore */
+    --_grid-template:
+      [master-start] var(--_master-size) [master-extra] var(--_master-extra)
+      [detail-start] var(--_detail-size) [detail-extra] var(--_detail-extra)
+      [detail-end];
   }
 
-  :host([orientation='vertical']) [part='_detail-internal'] {
-    align-items: end;
+  :host([force-overlay]) {
+    /* prettier-ignore */
+    --_grid-template:
+      [master-start] var(--_master-size) [master-extra] var(--_master-extra)
+      [detail-start] 0px                 [detail-extra] 0px
+      [detail-end];
   }
 
-  :host(:is([drawer], [stack])) [part='_detail-internal'],
-  :host(:is([drawer], [stack])[has-detail]) [part='backdrop'] {
-    display: flex;
-    position: absolute;
-    z-index: 1;
-    inset: 0;
-    overscroll-behavior: contain;
+  :host([orientation='horizontal']) {
+    grid-template-columns: var(--_grid-template);
+    grid-template-rows: 100%;
   }
 
-  :host(:not([has-detail])) [part='_detail-internal'],
-  [part='backdrop'] {
-    display: none;
+  :host([orientation='vertical']) {
+    grid-template-columns: 100%;
+    grid-template-rows: var(--_grid-template);
   }
 
-  :host([orientation='horizontal'][drawer]) [part='detail'] {
-    margin-inline-start: 50px;
+  /* CSS grid placement */
+
+  :host {
+    --_master-area: master-start / detail-start;
+
+    /*
+      When the detail size isn't explicitly defined and the detail is set to expand,
+      the detail column template is 'min-content 1fr'. In this case, the detail area
+      should not span both columns initially (and when recalculating the detail size)
+      as spanning both would effectively collapse them into a single '1fr' column where
+      min-content resolves to 0, making it impossible to measure the detail's intrinsic
+      minimum width from JavaScript.
+    */
+    --_detail-area: detail-start / detail-extra;
   }
 
-  :host([orientation='vertical'][drawer]) [part='detail'] {
-    margin-top: 50px;
+  :host(:is([has-detail], [has-detail-placeholder]):not([recalculating-detail-size])) {
+    --_detail-area: detail-start / detail-end;
   }
 
-  :host(:is([drawer], [stack])[containment='viewport']) :is([part='_detail-internal'], [part='backdrop']) {
-    position: fixed;
+  :host([orientation='horizontal']) #master {
+    grid-column: var(--_master-area);
+    grid-row: 1;
   }
 
-  :host(:is([drawer], [stack])[containment='viewport']) [part='detail'] {
-    padding-top: var(--safe-area-inset-top);
-    padding-bottom: var(--safe-area-inset-bottom);
+  :host([orientation='vertical']) #master {
+    grid-column: 1;
+    grid-row: var(--_master-area);
   }
 
-  :host([containment='viewport']:dir(ltr)) [part='detail'] {
-    padding-right: var(--safe-area-inset-right);
+  :host([orientation='horizontal']) :is(#detail, #detailPlaceholder, #detailOutgoing) {
+    grid-column: var(--_detail-area);
+    grid-row: 1;
   }
 
-  :host([containment='viewport']:dir(rtl)) [part='detail'] {
-    padding-left: var(--safe-area-inset-left);
+  :host([orientation='vertical']) :is(#detail, #detailPlaceholder, #detailOutgoing) {
+    grid-column: 1;
+    grid-row: var(--_detail-area);
   }
 
-  :host([stack][containment='viewport']) [part='detail'] {
-    padding-left: var(--safe-area-inset-left);
-    padding-right: var(--safe-area-inset-right);
+  /* Expand */
+
+  :host([expand-master]) {
+    --_master-extra: 1fr;
   }
 
-  /* Sizing styles */
+  :host([expand-detail]) {
+    --_detail-extra: 1fr;
+  }
 
-  [part] {
-    box-sizing: border-box;
-    max-width: 100%;
-    max-height: 100%;
+  :host([keep-detail-column-offscreen]),
+  :host([has-detail-placeholder][overlay]:not([has-detail])),
+  :host(:not([has-detail-placeholder], [has-detail])) {
+    --_master-extra: calc(100% - var(--_master-size));
+  }
+
+  /* Backdrop base styles */
+
+  #backdrop {
+    --_transition-easing: linear;
+
+    position: absolute;
+    inset: 0;
+    z-index: 2;
+    opacity: 0;
+    pointer-events: none;
+    background: var(--vaadin-overlay-backdrop-background, rgba(0, 0, 0, 0.2));
+    forced-color-adjust: none;
   }
 
-  /* No fixed size */
-  :host(:not([has-master-size])) [part='master'],
-  :host(:not([has-detail-size]):not([drawer], [stack])) [part='detail'] {
-    flex-grow: 1;
-    flex-basis: 50%;
+  /* Master base styles */
+
+  #master {
+    opacity: 0;
+    pointer-events: none;
+    box-sizing: border-box;
   }
 
-  /* Fixed size */
-  :host([has-master-size]) [part='master'],
-  :host([has-detail-size]) [part='detail'] {
-    flex-shrink: 0;
+  :host([has-master]) #master {
+    opacity: 1;
+    pointer-events: auto;
   }
 
-  :host([orientation='horizontal'][has-master-size][has-detail]) [part='master'] {
-    width: var(--_master-size);
+  /* Detail base styles */
+
+  #detail {
+    translate: var(--_transition-offset);
+    opacity: 0;
+    z-index: 4;
   }
 
-  :host([orientation='vertical'][has-master-size][has-detail]) [part='master'] {
-    height: var(--_master-size);
+  :host([has-detail]) #detail {
+    translate: none;
+    opacity: 1;
   }
 
-  :host([orientation='horizontal'][has-detail-size]:not([stack])) [part='detail'] {
-    width: var(--_detail-size);
+  #detailOutgoing {
+    position: absolute;
+    z-index: 3;
+    display: none;
   }
 
-  :host([orientation='vertical'][has-detail-size]:not([stack])) [part='detail'] {
-    height: var(--_detail-size);
+  :host([transition='replace']) #detailOutgoing {
+    display: block;
   }
 
-  :host([has-master-size][has-detail-size]) [part='master'] {
-    flex-grow: 1;
-    flex-basis: var(--_master-size);
+  #detailPlaceholder {
+    z-index: 1;
+    opacity: 0;
+    pointer-events: none;
   }
 
-  :host([has-master-size][has-detail-size]:not([drawer], [stack])) [part='detail'] {
-    flex-grow: 1;
-    flex-basis: var(--_detail-size);
+  :host([has-detail-placeholder]:not([has-detail], [overlay])) #detailPlaceholder {
+    opacity: 1;
+    pointer-events: auto;
   }
 
-  /* Min size */
-  :host([orientation='horizontal'][has-master-min-size]) [part='master'] {
-    min-width: min(100%, var(--_master-min-size));
+  :is(#detail, #detailPlaceholder, #detailOutgoing) {
+    box-sizing: border-box;
   }
 
-  :host([orientation='vertical'][has-master-min-size]) [part='master'] {
-    min-height: min(100%, var(--_master-min-size));
+  /* Detail borders */
+
+  #detail,
+  #detailPlaceholder {
+    border-color: var(--vaadin-master-detail-layout-border-color, var(--vaadin-border-color-secondary));
+    border-width: var(--vaadin-master-detail-layout-border-width, 1px);
   }
 
-  :host([orientation='horizontal'][has-detail-min-size]) [part='detail'] {
-    min-width: min(100%, var(--_detail-min-size));
+  :host([orientation='horizontal']) #detailPlaceholder,
+  :host([orientation='horizontal']:not([overlay])) #detail {
+    border-inline-start-style: solid;
   }
 
-  :host([orientation='vertical'][has-detail-min-size]) [part='detail'] {
-    min-height: min(100%, var(--_detail-min-size));
+  :host([orientation='vertical']) #detailPlaceholder,
+  :host([orientation='vertical']:not([overlay])) #detail {
+    border-block-start-style: solid;
   }
 
-  :host([drawer]) [part='master'],
-  :host([stack]) [part] {
-    width: 100% !important;
-    height: 100% !important;
-    min-width: auto !important;
-    min-height: auto !important;
-    max-width: 100% !important;
-    max-height: 100% !important;
+  /* Overlay */
+
+  :host([overlay][orientation='horizontal']) {
+    --_transition-offset: calc((100% + 30px) * var(--_rtl-multiplier));
   }
 
-  /* Decorative/visual styles */
+  :host([overlay][orientation='vertical']) {
+    --_transition-offset: 0 calc(100% + 30px);
+  }
 
-  [part='backdrop'] {
-    background: var(--vaadin-overlay-backdrop-background, rgba(0, 0, 0, 0.2));
-    forced-color-adjust: none;
+  :host([has-detail][overlay]) #backdrop {
+    opacity: 1;
+    pointer-events: auto;
   }
 
-  :host(:is([drawer], [stack])) [part='detail'] {
+  :host([has-detail][overlay]) :is(#detail, #detailOutgoing) {
+    position: absolute;
     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;
+    grid-row: none;
   }
 
-  :host([orientation='horizontal']:not([drawer], [stack])) [part='detail'] {
-    border-inline-start: var(--vaadin-master-detail-layout-border-width, 1px) solid
-      var(--vaadin-master-detail-layout-border-color, var(--vaadin-border-color-secondary));
+  :host([has-detail][overlay][orientation='horizontal']) :is(#detail, #detailOutgoing) {
+    inset-block: 0;
+    inset-inline-end: 0;
+    width: var(--_overlay-size, var(--_detail-size));
+    max-width: 100%;
   }
 
-  :host([orientation='vertical']:not([drawer], [stack])) [part='detail'] {
-    border-top: var(--vaadin-master-detail-layout-border-width, 1px) solid
-      var(--vaadin-master-detail-layout-border-color, var(--vaadin-border-color-secondary));
+  :host([has-detail][overlay][orientation='vertical']) :is(#detail, #detailOutgoing) {
+    inset-inline: 0;
+    inset-block-end: 0;
+    height: var(--_overlay-size, var(--_detail-size));
+    max-height: 100%;
   }
 
+  :host([has-detail][overlay][overlay-containment='page']) :is(#detail, #detailOutgoing, #backdrop) {
+    position: fixed;
+    padding-top: env(safe-area-inset-top);
+    padding-bottom: env(safe-area-inset-bottom);
+    padding-right: env(safe-area-inset-right);
+    --safe-area-inset-top: 0px;
+    --safe-area-inset-bottom: 0px;
+    --safe-area-inset-left: 0px;
+    --safe-area-inset-right: 0px;
+    --safe-area-inset-inline-start: 0px;
+    --safe-area-inset-inline-end: 0px;
+  }
+
+  :host([dir='rtl'][has-detail][overlay][overlay-containment='page']) :is(#detail, #detailOutgoing, #backdrop) {
+    padding-right: 0;
+    padding-left: env(safe-area-inset-left);
+  }
+
+  /* Transitions */
+
+  @media (prefers-reduced-motion: no-preference) {
+    :host(:not([no-animation], [transition='replace'])) {
+      --_transition-duration: 200ms;
+    }
+
+    :host([overlay]:not([no-animation])) {
+      --_transition-duration: 300ms;
+    }
+  }
+
+  /* Forced colors */
+
   @media (forced-colors: active) {
-    :host(:is([drawer], [stack])) [part='detail'] {
+    :host([has-detail][overlay]) :is(#detail, #detailOutgoing) {
       outline: 3px solid !important;
     }
 
-    [part='detail'] {
+    :is(#detail, #detailPlaceholder, #detailOutgoing) {
       background: Canvas !important;
     }
   }

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;
+}