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

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

@@ -7,125 +7,286 @@ import '@vaadin/component-base/src/styles/style-props.js';
 import { css } from 'lit';
 
 export const masterDetailLayoutStyles = css`
+  /* stylelint-disable no-duplicate-selectors */
   :host {
-    --_master-size: 30em;
-    --_detail-size: 15em;
-    --_master-column: var(--_master-size) 0;
-    --_detail-column: var(--_detail-size) 0;
+    --_rtl-multiplier: 1;
+    --_transition-duration: 0s;
+    --_transition-easing: cubic-bezier(0.78, 0, 0.22, 1);
 
     display: grid;
     box-sizing: border-box;
     height: 100%;
     position: relative;
+    overflow: clip;
+  }
+
+  :host:not([overlay-containment='page']) {
     z-index: 0;
-    overflow: hidden;
-    grid-template-columns: [master-start] var(--_master-column) [detail-start] var(--_detail-column) [detail-end];
-    grid-template-rows: 100%;
   }
 
-  :host([hidden]) {
+  :host([dir='rtl']) {
+    --_rtl-multiplier: -1;
+  }
+
+  :host([orientation='horizontal']) {
+    --_transition-offset: calc(30px * var(--_rtl-multiplier));
+  }
+
+  :host([orientation='vertical']) {
+    --_transition-offset: 0 30px;
+  }
+
+  :host([hidden]),
+  ::slotted([hidden]) {
     display: none !important;
   }
 
+  /* 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([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([orientation='horizontal']) {
+    grid-template-columns: var(--_grid-template);
+    grid-template-rows: 100%;
+  }
+
   :host([orientation='vertical']) {
     grid-template-columns: 100%;
-    grid-template-rows: [master-start] var(--_master-column) [detail-start] var(--_detail-column) [detail-end];
+    grid-template-rows: var(--_grid-template);
   }
 
-  [part~='master'],
-  [part~='detail'] {
-    box-sizing: border-box;
+  /* 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;
   }
 
-  [part~='master'] {
-    grid-column: master-start / detail-start;
+  :host(:is([has-detail], [has-detail-placeholder]):not([recalculating-detail-size])) {
+    --_detail-area: detail-start / detail-end;
   }
 
-  [part~='detail'] {
-    grid-column: detail-start / detail-end;
+  :host([orientation='horizontal']) #master {
+    grid-column: var(--_master-area);
+    grid-row: 1;
   }
 
-  :host([orientation='vertical']) [part~='master'] {
-    grid-column: auto;
-    grid-row: master-start / detail-start;
+  :host([orientation='vertical']) #master {
+    grid-column: 1;
+    grid-row: var(--_master-area);
   }
 
-  :host([orientation='vertical']) [part~='detail'] {
-    grid-column: auto;
-    grid-row: detail-start / detail-end;
+  :host([orientation='horizontal']) :is(#detail, #detailPlaceholder, #detailOutgoing) {
+    grid-column: var(--_detail-area);
+    grid-row: 1;
   }
 
-  [part~='backdrop'] {
+  :host([orientation='vertical']) :is(#detail, #detailPlaceholder, #detailOutgoing) {
+    grid-column: 1;
+    grid-row: var(--_detail-area);
+  }
+
+  /* Expand */
+
+  :host([expand-master]) {
+    --_master-extra: 1fr;
+  }
+
+  :host([expand-detail]) {
+    --_detail-extra: 1fr;
+  }
+
+  :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: 1;
-    display: none;
+    z-index: 2;
+    opacity: 0;
+    pointer-events: none;
     background: var(--vaadin-overlay-backdrop-background, rgba(0, 0, 0, 0.2));
     forced-color-adjust: none;
   }
 
-  :host([expand='both']),
-  :host([expand='master']) {
-    --_master-column: var(--_master-size) 1fr;
+  /* Master base styles */
+
+  #master {
+    opacity: 0;
+    pointer-events: none;
+    box-sizing: border-box;
   }
 
-  :host(:not([has-detail])),
-  :host([keep-detail-column-offscreen]) {
-    --_master-column: var(--_master-size) calc(100% - var(--_master-size));
+  :host([has-master]) #master {
+    opacity: 1;
+    pointer-events: auto;
   }
 
-  :host([expand='both']),
-  :host([expand='detail']) {
-    --_detail-column: var(--_detail-size) 1fr;
+  /* Detail base styles */
+
+  #detail {
+    translate: var(--_transition-offset);
+    opacity: 0;
+    z-index: 4;
   }
 
-  :host([orientation='horizontal'][has-detail]:not([overflow])) [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]) #detail {
+    translate: none;
+    opacity: 1;
   }
 
-  :host([orientation='vertical'][has-detail]:not([overflow])) [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));
+  #detailOutgoing {
+    position: absolute;
+    z-index: 3;
+    display: none;
+  }
+
+  :host([transition='replace']) #detailOutgoing {
+    display: block;
   }
 
-  :host([overflow]) [part~='detail'] {
+  #detailPlaceholder {
+    z-index: 1;
+    visibility: hidden;
+  }
+
+  :host([has-detail-placeholder]:not([has-detail], [overlay])) #detailPlaceholder {
+    visibility: visible;
+  }
+
+  :is(#detail, #detailPlaceholder, #detailOutgoing) {
+    box-sizing: border-box;
+  }
+
+  /* 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']) #detailPlaceholder,
+  :host([orientation='horizontal']:not([overlay])) #detail {
+    border-inline-start-style: solid;
+  }
+
+  :host([orientation='vertical']) #detailPlaceholder,
+  :host([orientation='vertical']:not([overlay])) #detail {
+    border-block-start-style: solid;
+  }
+
+  /* Overlay */
+
+  :host([overlay][orientation='horizontal']) {
+    --_transition-offset: calc((100% + 30px) * var(--_rtl-multiplier));
+  }
+
+  :host([overlay][orientation='vertical']) {
+    --_transition-offset: 0 calc(100% + 30px);
+  }
+
+  :host([has-detail][overlay]) #backdrop {
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  :host([has-detail][overlay]) :is(#detail, #detailOutgoing) {
     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;
+    grid-row: none;
   }
 
-  :host([overflow]) [part~='backdrop'] {
-    display: block;
-  }
-
-  :host([overflow]:not([orientation='vertical'])) [part~='detail'] {
+  :host([has-detail][overlay][orientation='horizontal']) :is(#detail, #detailOutgoing) {
     inset-block: 0;
-    width: var(--_overlay-size, var(--_detail-size, min-content));
     inset-inline-end: 0;
+    width: var(--_overlay-size, var(--_detail-size));
+    max-width: 100%;
   }
 
-  :host([overflow][orientation='vertical']) [part~='detail'] {
-    grid-column: auto;
-    grid-row: none;
+  :host([has-detail][overlay][orientation='vertical']) :is(#detail, #detailOutgoing) {
     inset-inline: 0;
-    height: var(--_overlay-size, var(--_detail-size, min-content));
     inset-block-end: 0;
+    height: var(--_overlay-size, var(--_detail-size));
+    max-height: 100%;
   }
 
-  :host([overflow][overlay-containment='viewport']) [part~='detail'],
-  :host([overflow][overlay-containment='viewport']) [part~='backdrop'] {
+  :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([overflow]) [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;
+}

package/src/vaadin-master-detail-layout.d.ts

@@ -4,7 +4,6 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
-import { SlotStylesMixin } from '@vaadin/component-base/src/slot-styles-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 export interface MasterDetailLayoutCustomEventMap {
@@ -20,25 +19,53 @@ export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterD
  * (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:
  *
@@ -55,12 +82,18 @@ export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterD
  * @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.
  */
-declare class MasterDetailLayout extends SlotStylesMixin(ThemableMixin(ElementMixin(HTMLElement))) {
+declare class MasterDetailLayout extends ThemableMixin(ElementMixin(HTMLElement)) {
   /**
    * 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
    */
@@ -96,19 +129,30 @@ declare class MasterDetailLayout extends SlotStylesMixin(ThemableMixin(ElementMi
   /**
    * 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
    */
-  overlayContainment: 'layout' | 'viewport';
+  overlayContainment: 'layout' | 'page';
+
+  /**
+   * 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
+   */
+  expandMaster: boolean;
 
   /**
-   * Controls which column(s) expand to fill available space.
-   * Possible values: `'master'`, `'detail'`, `'both'`.
-   * Defaults to `'both'`.
+   * 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
    */
-  expand: 'master' | 'detail' | 'both';
+  expandDetail: boolean;
 
   /**
    * When true, the layout does not use animated transitions for the detail area.
@@ -117,6 +161,30 @@ declare class MasterDetailLayout extends SlotStylesMixin(ThemableMixin(ElementMi
    */
   noAnimation: boolean;
 
+  /**
+   * 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: boolean;
+
+  /**
+   * 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(): void;
+
   addEventListener<K extends keyof MasterDetailLayoutEventMap>(
     type: K,
     listener: (this: MasterDetailLayout, ev: MasterDetailLayoutEventMap[K]) => void,