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

package/custom-elements.json

@@ -243,7 +243,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Slots\n\nThe component has two main content areas: the master area (default slot)\nand the detail area (`detail` slot). When the detail doesn't fit next to\nthe master, it is shown as an overlay on top of the master area:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail\">Detail content</div>\n</vaadin-master-detail-layout>\n```\n\nThe component also supports a `detail-placeholder` slot for content shown\nin the detail area when no detail is selected. Unlike the `detail` slot,\nthe placeholder is simply hidden when it doesn't fit next to the master area,\nrather than shown as an overlay:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail-placeholder\">Select an item</div>\n</vaadin-master-detail-layout>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name             | Description\n----------------------|----------------------\n`backdrop`            | Backdrop covering the master area in the overlay mode\n`master`              | The master area\n`detail`              | The detail area\n`detail-placeholder`  | The detail placeholder area\n\nThe following state attributes are available for styling:\n\nAttribute                 | Description\n--------------------------|----------------------\n`expand`                  | Set to `master`, `detail`, or `both`.\n`orientation`             | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`              | Set when the detail content is provided and visible.\n`has-detail-placeholder`  | Set when the detail placeholder content is provided.\n`overlay`                 | Set when columns don't fit and the detail is shown as an overlay.\n`overlay-containment`     | Set to `layout` or `viewport`.\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                  |\n:----------------------------------------------------|\n| `--vaadin-master-detail-layout-border-color`       |\n| `--vaadin-master-detail-layout-border-width`       |\n| `--vaadin-master-detail-layout-detail-background`  |\n| `--vaadin-master-detail-layout-detail-shadow`      |\n| `--vaadin-overlay-backdrop-background`             |\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Slots\n\nThe component has two main content areas: the master area (default slot)\nand the detail area (`detail` slot). When the detail doesn't fit next to\nthe master, it is shown as an overlay on top of the master area:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail\">Detail content</div>\n</vaadin-master-detail-layout>\n```\n\nThe component also supports a `detail-placeholder` slot for content shown\nin the detail area when no detail is selected. Unlike the `detail` slot,\nthe placeholder is simply hidden when it doesn't fit next to the master area,\nrather than shown as an overlay:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail-placeholder\">Select an item</div>\n</vaadin-master-detail-layout>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name             | Description\n----------------------|----------------------\n`backdrop`            | Backdrop covering the master area in the overlay mode\n`master`              | The master area\n`detail`              | The detail area\n`detail-placeholder`  | The detail placeholder area\n\nThe following state attributes are available for styling:\n\nAttribute                 | Description\n--------------------------|----------------------\n`expand-master`           | Set when the master area expands to fill available space.\n`expand-detail`           | Set when the detail area expands to fill available space.\n`orientation`             | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`              | Set when the detail content is provided and visible.\n`has-detail-placeholder`  | Set when the detail placeholder content is provided.\n`overlay`                 | Set when columns don't fit and the detail is shown as an overlay.\n`overlay-containment`     | Set to `layout` or `page`.\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                  |\n:----------------------------------------------------|\n| `--vaadin-master-detail-layout-border-color`       |\n| `--vaadin-master-detail-layout-border-width`       |\n| `--vaadin-master-detail-layout-detail-background`  |\n| `--vaadin-master-detail-layout-detail-shadow`      |\n| `--vaadin-overlay-backdrop-background`             |\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
           "name": "MasterDetailLayout",
           "members": [
             {
@@ -258,13 +258,33 @@
             },
             {
               "kind": "field",
-              "name": "expand",
+              "name": "expandDetail",
               "privacy": "public",
               "type": {
-                "text": "string"
+                "text": "boolean"
+              },
+              "description": "When true, the detail area grows to fill the available space.\nIf `expandMaster` is also true, both areas share the available\nspace equally.",
+              "attribute": "expand-detail"
+            },
+            {
+              "kind": "field",
+              "name": "expandMaster",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When true, the master area grows to fill the available space.\nIf `expandDetail` is also true, both areas share the available\nspace equally.",
+              "attribute": "expand-master"
+            },
+            {
+              "kind": "field",
+              "name": "forceOverlay",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
               },
-              "description": "Controls which column(s) expand to fill available space.\nPossible values: `'master'`, `'detail'`, `'both'`.\nDefaults to `'master'`.",
-              "attribute": "expand"
+              "description": "When true, the layout forces the detail area to be shown as an overlay,\neven if there is enough space for master and detail to be shown next to\neach other using the default (split) mode.",
+              "attribute": "force-overlay"
             },
             {
               "kind": "field",
@@ -303,7 +323,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `viewport`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
+              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `page`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
               "attribute": "overlay-containment"
             },
             {
@@ -348,12 +368,28 @@
               "fieldName": "detailSize"
             },
             {
-              "name": "expand",
+              "name": "expand-detail",
               "type": {
-                "text": "string"
+                "text": "boolean"
+              },
+              "description": "When true, the detail area grows to fill the available space.\nIf `expandMaster` is also true, both areas share the available\nspace equally.",
+              "fieldName": "expandDetail"
+            },
+            {
+              "name": "expand-master",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When true, the master area grows to fill the available space.\nIf `expandDetail` is also true, both areas share the available\nspace equally.",
+              "fieldName": "expandMaster"
+            },
+            {
+              "name": "force-overlay",
+              "type": {
+                "text": "boolean"
               },
-              "description": "Controls which column(s) expand to fill available space.\nPossible values: `'master'`, `'detail'`, `'both'`.\nDefaults to `'master'`.",
-              "fieldName": "expand"
+              "description": "When true, the layout forces the detail area to be shown as an overlay,\neven if there is enough space for master and detail to be shown next to\neach other using the default (split) mode.",
+              "fieldName": "forceOverlay"
             },
             {
               "name": "master-size",
@@ -384,7 +420,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `viewport`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
+              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `page`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
               "fieldName": "overlayContainment"
             },
             {

package/package.json

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

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

@@ -7,85 +7,132 @@ 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: 30rem;
-    --_master-extra: 0px;
-    --_detail-size: var(--_detail-cached-size);
-    --_detail-extra: 0px;
-    --_detail-cached-size: min-content;
-
     --_rtl-multiplier: 1;
     --_transition-duration: 0s;
     --_transition-easing: cubic-bezier(0.78, 0, 0.22, 1);
-    --_transition-offset: calc(30px * var(--_rtl-multiplier));
 
     display: grid;
     box-sizing: border-box;
     height: 100%;
     position: relative;
-    z-index: 0;
     overflow: clip;
-    grid-template-columns:
-      [master-start] var(--_master-size) var(--_master-extra)
-      [detail-start] var(--_detail-size) var(--_detail-extra)
-      [detail-end];
-    grid-template-rows: 100%;
   }
 
-  :host([hidden]),
-  ::slotted([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']) {
     --_transition-offset: 0 30px;
+  }
 
-    grid-template-columns: 100%;
-    grid-template-rows:
-      [master-start] var(--_master-size) var(--_master-extra)
-      [detail-start] var(--_detail-size) var(--_detail-extra)
+  :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];
   }
 
-  :is(#master, #detail, #detail-placeholder, #outgoing) {
-    box-sizing: border-box;
+  :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];
   }
 
-  #detail-placeholder {
-    z-index: 1;
-    opacity: 0;
-    pointer-events: none;
+  :host([orientation='horizontal']) {
+    grid-template-columns: var(--_grid-template);
+    grid-template-rows: 100%;
   }
 
-  :host([has-detail-placeholder]:not([has-detail], [overlay])) #detail-placeholder {
-    opacity: 1;
-    pointer-events: auto;
+  :host([orientation='vertical']) {
+    grid-template-columns: 100%;
+    grid-template-rows: var(--_grid-template);
   }
 
-  #master {
-    grid-column: master-start / detail-start;
-    grid-row: 1;
+  /* 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(:is([has-detail], [has-detail-placeholder]):not([recalculating-detail-size])) {
+    --_detail-area: detail-start / detail-end;
   }
 
-  :is(#detail, #detail-placeholder, #outgoing) {
-    grid-column: detail-start / detail-end;
+  :host([orientation='horizontal']) #master {
+    grid-column: var(--_master-area);
     grid-row: 1;
   }
 
   :host([orientation='vertical']) #master {
     grid-column: 1;
-    grid-row: master-start / detail-start;
+    grid-row: var(--_master-area);
+  }
+
+  :host([orientation='horizontal']) :is(#detail, #detailPlaceholder, #detailOutgoing) {
+    grid-column: var(--_detail-area);
+    grid-row: 1;
   }
 
-  :host([orientation='vertical']) :is(#detail, #detail-placeholder, #outgoing) {
+  :host([orientation='vertical']) :is(#detail, #detailPlaceholder, #detailOutgoing) {
     grid-column: 1;
-    grid-row: detail-start / detail-end;
+    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;
 
@@ -98,56 +145,78 @@ export const masterDetailLayoutStyles = css`
     forced-color-adjust: none;
   }
 
-  :host([expand='both']),
-  :host([expand='master']) {
-    --_master-extra: 1fr;
-  }
+  /* Master base styles */
 
-  :host([expand='both']:is([has-detail], [has-detail-placeholder])),
-  :host([expand='detail']:is([has-detail], [has-detail-placeholder])) {
-    --_detail-extra: 1fr;
+  #master {
+    opacity: 0;
+    pointer-events: none;
+    box-sizing: border-box;
   }
 
-  :host([recalculating-detail-size]:is([has-detail], [has-detail-placeholder])) {
-    --_detail-extra: 0px;
+  :host([has-master]) #master {
+    opacity: 1;
+    pointer-events: auto;
   }
 
-  :host([keep-detail-column-offscreen]),
-  :host([has-detail-placeholder][overlay]),
-  :host(:not([has-detail-placeholder], [has-detail])) {
-    --_master-extra: calc(100% - var(--_master-size));
-  }
+  /* Detail base styles */
 
-  :host([orientation='horizontal']) #detail-placeholder,
-  :host([orientation='horizontal']:not([overlay])) #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));
+  #detail {
+    translate: var(--_transition-offset);
+    opacity: 0;
+    z-index: 4;
   }
 
-  :host([orientation='vertical']) #detail-placeholder,
-  :host([orientation='vertical']:not([overlay])) #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]) #detail {
+    translate: none;
+    opacity: 1;
   }
 
-  #outgoing {
+  #detailOutgoing {
     position: absolute;
     z-index: 3;
+    display: none;
   }
 
-  /* Detail transition: off-screen by default, on-screen when has-detail */
-  #detail {
-    translate: var(--_transition-offset);
+  :host([transition='replace']) #detailOutgoing {
+    display: block;
+  }
+
+  #detailPlaceholder {
+    z-index: 1;
     opacity: 0;
-    z-index: 4;
+    pointer-events: none;
   }
 
-  :host([has-detail]) #detail {
-    translate: none;
+  :host([has-detail-placeholder]:not([has-detail], [overlay])) #detailPlaceholder {
     opacity: 1;
+    pointer-events: auto;
+  }
+
+  :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([overlay]) {
+  :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));
   }
 
@@ -155,7 +224,12 @@ export const masterDetailLayoutStyles = css`
     --_transition-offset: 0 calc(100% + 30px);
   }
 
-  :host([has-detail][overlay]) :is(#detail, #outgoing) {
+  :host([has-detail][overlay]) #backdrop {
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  :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));
@@ -163,40 +237,40 @@ export const masterDetailLayoutStyles = css`
     grid-row: none;
   }
 
-  :host([has-detail][overlay]) #backdrop {
-    opacity: 1;
-    pointer-events: auto;
-  }
-
-  :host([has-detail][overlay]:not([orientation='vertical'])) :is(#detail, #outgoing) {
+  :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([has-detail][overlay][orientation='vertical']) :is(#detail, #outgoing) {
+  :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='viewport']) :is(#detail, #outgoing, #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;
   }
 
-  @media (forced-colors: active) {
-    :host([has-detail][overlay]) :is(#detail, #outgoing) {
-      outline: 3px solid !important;
-    }
-
-    :is(#detail, #detail-placeholder, #outgoing) {
-      background: Canvas !important;
-    }
+  :host([dir='rtl'][has-detail][overlay][overlay-containment='page']) :is(#detail, #detailOutgoing, #backdrop) {
+    padding-right: 0;
+    padding-left: env(safe-area-inset-left);
   }
 
-  /* Enable transitions when motion is allowed */
+  /* Transitions */
+
   @media (prefers-reduced-motion: no-preference) {
     :host(:not([no-animation], [transition='replace'])) {
       --_transition-duration: 200ms;
@@ -206,4 +280,16 @@ export const masterDetailLayoutStyles = css`
       --_transition-duration: 300ms;
     }
   }
+
+  /* Forced colors */
+
+  @media (forced-colors: active) {
+    :host([has-detail][overlay]) :is(#detail, #detailOutgoing) {
+      outline: 3px solid !important;
+    }
+
+    :is(#detail, #detailPlaceholder, #detailOutgoing) {
+      background: Canvas !important;
+    }
+  }
 `;

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

@@ -59,12 +59,13 @@ export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterD
  *
  * Attribute                 | Description
  * --------------------------|----------------------
- * `expand`                  | Set to `master`, `detail`, or `both`.
+ * `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 `viewport`.
+ * `overlay-containment`     | Set to `layout` or `page`.
  *
  * The following custom CSS properties are available for styling:
  *
@@ -128,19 +129,30 @@ declare class MasterDetailLayout extends ThemableMixin(ElementMixin(HTMLElement)
   /**
    * 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';
 
   /**
-   * Controls which column(s) expand to fill available space.
-   * Possible values: `'master'`, `'detail'`, `'both'`.
-   * Defaults to `'master'`.
+   * 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;
+
+  /**
+   * 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.
@@ -149,6 +161,15 @@ declare class MasterDetailLayout extends ThemableMixin(ElementMixin(HTMLElement)
    */
   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

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

@@ -4,7 +4,7 @@
  * 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';
@@ -65,12 +65,13 @@ import {
  *
  * Attribute                 | Description
  * --------------------------|----------------------
- * `expand`                  | Set to `master`, `detail`, or `both`.
+ * `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 `viewport`.
+ * `overlay-containment`     | Set to `layout` or `page`.
  *
  * The following custom CSS properties are available for styling:
  *
@@ -120,7 +121,6 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
       detailSize: {
         type: String,
         sync: true,
-        observer: '__detailSizeChanged',
       },
 
       /**
@@ -134,7 +134,6 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
       masterSize: {
         type: String,
         sync: true,
-        observer: '__masterSizeChanged',
       },
 
       /**
@@ -161,13 +160,12 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
         value: 'horizontal',
         reflectToAttribute: true,
         sync: true,
-        observer: '__orientationChanged',
       },
 
       /**
        * 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
@@ -180,13 +178,29 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
       },
 
       /**
-       * Controls which column(s) expand to fill available space.
-       * Possible values: `'master'`, `'detail'`, `'both'`.
-       * Defaults to `'master'`.
+       * 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: 'master',
+      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,
       },
@@ -202,9 +216,17 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
         reflectToAttribute: true,
       },
 
-      /** @private */
-      __replacing: {
+      /**
+       * 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,
       },
 
@@ -224,27 +246,27 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
   /** @protected */
   render() {
     const isOverlay = this.hasAttribute('has-detail') && this.hasAttribute('overlay');
-    const isViewport = isOverlay && this.overlayContainment === 'viewport';
-    const isLayoutContained = isOverlay && !isViewport;
+    const isPage = isOverlay && this.overlayContainment === 'page';
+    const isLayoutContained = isOverlay && !isPage;
 
     return html`
       <div id="backdrop" part="backdrop" @click="${this.__onBackdropClick}"></div>
       <div id="master" part="master" ?inert="${isLayoutContained}">
         <slot @slotchange="${this.__onSlotChange}"></slot>
       </div>
-      <div id="outgoing" inert ?hidden="${!this.__replacing}">
+      <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="detail-placeholder" part="detail-placeholder">
+      <div id="detailPlaceholder" part="detail-placeholder">
         <slot name="detail-placeholder" @slotchange="${this.__onSlotChange}"></slot>
       </div>
     `;
@@ -254,6 +276,17 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
   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 */
@@ -261,51 +294,40 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     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);
 
-    if (oldSize != null) {
-      this.recalculateLayout();
+    if (props.has('masterSize')) {
+      this.style.setProperty('--_master-size', this.masterSize);
     }
-  }
-
-  /** @private */
-  __detailSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('detail-size', size, oldSize);
 
-    if (oldSize != null) {
-      this.recalculateLayout();
+    if (props.has('detailSize')) {
+      this.style.setProperty('--_detail-size', this.detailSize);
     }
-  }
 
-  /** @private */
-  __orientationChanged(_orientation, oldOrientation) {
-    if (oldOrientation != null) {
+    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 */
-  __detailCachedSizeChanged(size, oldSize) {
-    this.__updateStyleProperty('detail-cached-size', size, oldSize);
-  }
-
-  /** @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 */
@@ -318,9 +340,10 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     this.__resizeObserver = this.__resizeObserver || new ResizeObserver(() => this.__onResize());
     this.__resizeObserver.disconnect();
 
-    const children = this.querySelectorAll(':scope > [slot="detail"], :scope >:not([slot])');
-    [this, this.$.master, this.$.detail, ...children].forEach((node) => {
-      this.__resizeObserver.observe(node);
+    [this, this.$.master, this.$.detail, this.__slottedMaster, this.__slottedDetail].forEach((node) => {
+      if (node) {
+        this.__resizeObserver.observe(node);
+      }
     });
   }
 
@@ -344,12 +367,14 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
   __readLayoutState() {
     const isVertical = this.orientation === 'vertical';
 
-    const detailContent = this.querySelector(':scope > [slot="detail"]');
-    const detailPlaceholder = this.querySelector(':scope > [slot="detail-placeholder"]');
+    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 hasDetailPlaceholder = !!detailPlaceholder;
+    const hasDetail = slottedDetail != null && slottedDetail.checkVisibility();
+    const hasDetailPlaceholder = !!slottedDetailPlaceholder;
 
     const computedStyle = getComputedStyle(this);
     const hostSizeProp = isVertical ? 'height' : 'width';
@@ -358,10 +383,12 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     const trackSizesProp = isVertical ? 'gridTemplateRows' : 'gridTemplateColumns';
     const trackSizes = parseTrackSizes(computedStyle[trackSizesProp]);
 
-    const hasOverflow = (hasDetail || hasDetailPlaceholder) && detectOverflow(hostSize, trackSizes);
-    const focusTarget = !hadDetail && hasDetail && hasOverflow ? getFocusableElements(detailContent)[0] : null;
+    const hasOverflow =
+      (hasDetail || hasDetailPlaceholder) && (this.forceOverlay || detectOverflow(hostSize, trackSizes));
+    const focusTarget = !hadDetail && hasDetail && hasOverflow ? getFocusableElements(slottedDetail)[0] : null;
 
     return {
+      hasMaster,
       hadDetail,
       hasDetail,
       hasDetailPlaceholder,
@@ -376,7 +403,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
    * Applies layout state to DOM attributes. Pure writes, no reads.
    * @private
    */
-  __writeLayoutState({ hadDetail, hasDetail, hasDetailPlaceholder, hasOverflow, focusTarget, trackSizes }) {
+  __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
@@ -398,6 +425,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     }
 
     this.toggleAttribute('overlay', hasOverflow);
+    this.toggleAttribute('has-master', hasMaster);
     this.toggleAttribute('has-detail', hasDetail);
     this.toggleAttribute('has-detail-placeholder', hasDetailPlaceholder);
 
@@ -406,7 +434,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     this.requestUpdate();
 
     if (focusTarget) {
-      focusTarget.focus({ preventScroll: true });
+      focusTarget.focus({ preventScroll: true, focusVisible: isKeyboardActive() });
     }
   }
 
@@ -424,14 +452,14 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
    * synchronous DOM reads and writes.
    */
   recalculateLayout() {
-    // Cancel any pending ResizeObserver rAF to prevent it from potentially
-    // overriding the layout state with stale measurements.
-    cancelAnimationFrame(this.__resizeRaf);
-
-    const invalidatedLayouts = [...this.__ancestorLayouts.filter((layout) => layout.__isDetailAutoSized), this];
+    const invalidatedLayouts = [...this.__ancestorLayouts, this];
 
     // Write
     invalidatedLayouts.forEach((layout) => {
+      // Cancel any pending ResizeObserver rAF to prevent it from potentially
+      // overriding the layout state with stale measurements.
+      cancelAnimationFrame(layout.__resizeRaf);
+
       layout.__detailCachedSize = null;
 
       if (layout.__isDetailAutoSized) {
@@ -496,7 +524,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
    */
   async _setDetail(newDetail, skipTransition) {
     // Don't start a transition if detail didn't change
-    const oldDetail = this.querySelector('[slot="detail"]');
+    const oldDetail = this.__slottedDetail;
     if (oldDetail === (newDetail || null)) {
       return;
     }
@@ -522,7 +550,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
       return;
     }
 
-    const hasPlaceholder = !!this.querySelector('[slot="detail-placeholder"]');
+    const hasPlaceholder = !!this.__slottedDetailPlaceholder;
     if ((oldDetail && newDetail) || (hasPlaceholder && !this.hasAttribute('overlay'))) {
       await this._startTransition('replace', updateSlot);
     } else if (!oldDetail && newDetail) {
@@ -594,18 +622,27 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
 
   /** @private */
   async __replaceTransition(updateSlot) {
+    const oldDetail = this.__slottedDetail;
+    if (oldDetail) {
+      oldDetail.slot = 'detail-outgoing';
+    }
+
     try {
-      this.__snapshotOutgoing();
+      this.$.detailOutgoing.style.width = this.__detailCachedSize;
 
       await updateSlot();
 
       const progress = getCurrentAnimationProgress(this.$.detail);
       await Promise.all([
         animateIn(this.$.detail, ['fade', 'slide'], progress),
-        animateOut(this.$.outgoing, ['fade', 'slide'], progress),
+        animateOut(this.$.detailOutgoing, ['fade', 'slide'], progress),
       ]);
     } finally {
-      this.__clearOutgoing();
+      // Skip removal if the slot was reassigned during the transition.
+      // The React component does this to let React handle the removal.
+      if (oldDetail && oldDetail.slot === 'detail-outgoing') {
+        oldDetail.remove();
+      }
     }
   }
 
@@ -620,30 +657,19 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     await updateSlot();
   }
 
-  /**
-   * Moves the current detail content to the outgoing slot so it can
-   * slide out while the new content slides in. Keeps the element in
-   * light DOM so light DOM styles continue to apply.
-   * @private
-   */
-  __snapshotOutgoing() {
-    const currentDetail = this.querySelector('[slot="detail"]');
-    if (!currentDetail) {
-      return;
-    }
-    currentDetail.setAttribute('slot', 'detail-outgoing');
-    this.$.outgoing.style.width = this.__detailCachedSize;
-    this.__replacing = true;
+  /** @private */
+  get __slottedMaster() {
+    return this.querySelector(':scope > :is([slot=""], :not([slot]))');
   }
 
-  /**
-   * Clears the outgoing container after the replace transition completes.
-   * @private
-   */
-  __clearOutgoing() {
-    this.querySelectorAll('[slot="detail-outgoing"]').forEach((el) => el.remove());
-    this.$.outgoing.style.width = '';
-    this.__replacing = false;
+  /** @private */
+  get __slottedDetail() {
+    return this.querySelector(':scope > [slot="detail"]');
+  }
+
+  /** @private */
+  get __slottedDetailPlaceholder() {
+    return this.querySelector(':scope > [slot="detail-placeholder"]');
   }
 
   /**

package/web-types.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/master-detail-layout",
-  "version": "25.2.0-alpha6",
+  "version": "25.2.0-alpha8",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "vaadin-master-detail-layout",
-          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Slots\n\nThe component has two main content areas: the master area (default slot)\nand the detail area (`detail` slot). When the detail doesn't fit next to\nthe master, it is shown as an overlay on top of the master area:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail\">Detail content</div>\n</vaadin-master-detail-layout>\n```\n\nThe component also supports a `detail-placeholder` slot for content shown\nin the detail area when no detail is selected. Unlike the `detail` slot,\nthe placeholder is simply hidden when it doesn't fit next to the master area,\nrather than shown as an overlay:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail-placeholder\">Select an item</div>\n</vaadin-master-detail-layout>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name             | Description\n----------------------|----------------------\n`backdrop`            | Backdrop covering the master area in the overlay mode\n`master`              | The master area\n`detail`              | The detail area\n`detail-placeholder`  | The detail placeholder area\n\nThe following state attributes are available for styling:\n\nAttribute                 | Description\n--------------------------|----------------------\n`expand`                  | Set to `master`, `detail`, or `both`.\n`orientation`             | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`              | Set when the detail content is provided and visible.\n`has-detail-placeholder`  | Set when the detail placeholder content is provided.\n`overlay`                 | Set when columns don't fit and the detail is shown as an overlay.\n`overlay-containment`     | Set to `layout` or `viewport`.\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                  |\n:----------------------------------------------------|\n| `--vaadin-master-detail-layout-border-color`       |\n| `--vaadin-master-detail-layout-border-width`       |\n| `--vaadin-master-detail-layout-detail-background`  |\n| `--vaadin-master-detail-layout-detail-shadow`      |\n| `--vaadin-overlay-backdrop-background`             |\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Slots\n\nThe component has two main content areas: the master area (default slot)\nand the detail area (`detail` slot). When the detail doesn't fit next to\nthe master, it is shown as an overlay on top of the master area:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail\">Detail content</div>\n</vaadin-master-detail-layout>\n```\n\nThe component also supports a `detail-placeholder` slot for content shown\nin the detail area when no detail is selected. Unlike the `detail` slot,\nthe placeholder is simply hidden when it doesn't fit next to the master area,\nrather than shown as an overlay:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail-placeholder\">Select an item</div>\n</vaadin-master-detail-layout>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name             | Description\n----------------------|----------------------\n`backdrop`            | Backdrop covering the master area in the overlay mode\n`master`              | The master area\n`detail`              | The detail area\n`detail-placeholder`  | The detail placeholder area\n\nThe following state attributes are available for styling:\n\nAttribute                 | Description\n--------------------------|----------------------\n`expand-master`           | Set when the master area expands to fill available space.\n`expand-detail`           | Set when the detail area expands to fill available space.\n`orientation`             | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`              | Set when the detail content is provided and visible.\n`has-detail-placeholder`  | Set when the detail placeholder content is provided.\n`overlay`                 | Set when columns don't fit and the detail is shown as an overlay.\n`overlay-containment`     | Set to `layout` or `page`.\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                  |\n:----------------------------------------------------|\n| `--vaadin-master-detail-layout-border-color`       |\n| `--vaadin-master-detail-layout-border-width`       |\n| `--vaadin-master-detail-layout-detail-background`  |\n| `--vaadin-master-detail-layout-detail-shadow`      |\n| `--vaadin-overlay-backdrop-background`             |\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
           "attributes": [
             {
               "name": "detail-size",
@@ -22,11 +22,33 @@
               }
             },
             {
-              "name": "expand",
-              "description": "Controls which column(s) expand to fill available space.\nPossible values: `'master'`, `'detail'`, `'both'`.\nDefaults to `'master'`.",
+              "name": "expand-detail",
+              "description": "When true, the detail area grows to fill the available space.\nIf `expandMaster` is also true, both areas share the available\nspace equally.",
               "value": {
                 "type": [
-                  "string",
+                  "boolean",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "expand-master",
+              "description": "When true, the master area grows to fill the available space.\nIf `expandDetail` is also true, both areas share the available\nspace equally.",
+              "value": {
+                "type": [
+                  "boolean",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "force-overlay",
+              "description": "When true, the layout forces the detail area to be shown as an overlay,\neven if there is enough space for master and detail to be shown next to\neach other using the default (split) mode.",
+              "value": {
+                "type": [
+                  "boolean",
                   "null",
                   "undefined"
                 ]
@@ -67,7 +89,7 @@
             },
             {
               "name": "overlay-containment",
-              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `viewport`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
+              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `page`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
               "value": {
                 "type": [
                   "string",
@@ -113,11 +135,33 @@
                 }
               },
               {
-                "name": "expand",
-                "description": "Controls which column(s) expand to fill available space.\nPossible values: `'master'`, `'detail'`, `'both'`.\nDefaults to `'master'`.",
+                "name": "expandDetail",
+                "description": "When true, the detail area grows to fill the available space.\nIf `expandMaster` is also true, both areas share the available\nspace equally.",
                 "value": {
                   "type": [
-                    "string",
+                    "boolean",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "expandMaster",
+                "description": "When true, the master area grows to fill the available space.\nIf `expandDetail` is also true, both areas share the available\nspace equally.",
+                "value": {
+                  "type": [
+                    "boolean",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "forceOverlay",
+                "description": "When true, the layout forces the detail area to be shown as an overlay,\neven if there is enough space for master and detail to be shown next to\neach other using the default (split) mode.",
+                "value": {
+                  "type": [
+                    "boolean",
                     "null",
                     "undefined"
                   ]
@@ -158,7 +202,7 @@
               },
               {
                 "name": "overlayContainment",
-                "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `viewport`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
+                "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `page`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
                 "value": {
                   "type": [
                     "string",

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-alpha6",
+  "version": "25.2.0-alpha8",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -16,26 +16,40 @@
       "elements": [
         {
           "name": "vaadin-master-detail-layout",
-          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Slots\n\nThe component has two main content areas: the master area (default slot)\nand the detail area (`detail` slot). When the detail doesn't fit next to\nthe master, it is shown as an overlay on top of the master area:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail\">Detail content</div>\n</vaadin-master-detail-layout>\n```\n\nThe component also supports a `detail-placeholder` slot for content shown\nin the detail area when no detail is selected. Unlike the `detail` slot,\nthe placeholder is simply hidden when it doesn't fit next to the master area,\nrather than shown as an overlay:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail-placeholder\">Select an item</div>\n</vaadin-master-detail-layout>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name             | Description\n----------------------|----------------------\n`backdrop`            | Backdrop covering the master area in the overlay mode\n`master`              | The master area\n`detail`              | The detail area\n`detail-placeholder`  | The detail placeholder area\n\nThe following state attributes are available for styling:\n\nAttribute                 | Description\n--------------------------|----------------------\n`expand`                  | Set to `master`, `detail`, or `both`.\n`orientation`             | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`              | Set when the detail content is provided and visible.\n`has-detail-placeholder`  | Set when the detail placeholder content is provided.\n`overlay`                 | Set when columns don't fit and the detail is shown as an overlay.\n`overlay-containment`     | Set to `layout` or `viewport`.\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                  |\n:----------------------------------------------------|\n| `--vaadin-master-detail-layout-border-color`       |\n| `--vaadin-master-detail-layout-border-width`       |\n| `--vaadin-master-detail-layout-detail-background`  |\n| `--vaadin-master-detail-layout-detail-shadow`      |\n| `--vaadin-overlay-backdrop-background`             |\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.\n\n### Slots\n\nThe component has two main content areas: the master area (default slot)\nand the detail area (`detail` slot). When the detail doesn't fit next to\nthe master, it is shown as an overlay on top of the master area:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail\">Detail content</div>\n</vaadin-master-detail-layout>\n```\n\nThe component also supports a `detail-placeholder` slot for content shown\nin the detail area when no detail is selected. Unlike the `detail` slot,\nthe placeholder is simply hidden when it doesn't fit next to the master area,\nrather than shown as an overlay:\n\n```html\n<vaadin-master-detail-layout>\n  <div>Master content</div>\n  <div slot=\"detail-placeholder\">Select an item</div>\n</vaadin-master-detail-layout>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name             | Description\n----------------------|----------------------\n`backdrop`            | Backdrop covering the master area in the overlay mode\n`master`              | The master area\n`detail`              | The detail area\n`detail-placeholder`  | The detail placeholder area\n\nThe following state attributes are available for styling:\n\nAttribute                 | Description\n--------------------------|----------------------\n`expand-master`           | Set when the master area expands to fill available space.\n`expand-detail`           | Set when the detail area expands to fill available space.\n`orientation`             | Set to `horizontal` or `vertical` depending on the orientation.\n`has-detail`              | Set when the detail content is provided and visible.\n`has-detail-placeholder`  | Set when the detail placeholder content is provided.\n`overlay`                 | Set when columns don't fit and the detail is shown as an overlay.\n`overlay-containment`     | Set to `layout` or `page`.\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                  |\n:----------------------------------------------------|\n| `--vaadin-master-detail-layout-border-color`       |\n| `--vaadin-master-detail-layout-border-width`       |\n| `--vaadin-master-detail-layout-detail-background`  |\n| `--vaadin-master-detail-layout-detail-shadow`      |\n| `--vaadin-overlay-backdrop-background`             |\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
           "extension": true,
           "attributes": [
             {
-              "name": "?noAnimation",
-              "description": "When true, the layout does not use animated transitions for the detail area.",
+              "name": "?expandDetail",
+              "description": "When true, the detail area grows to fill the available space.\nIf `expandMaster` is also true, both areas share the available\nspace equally.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".detailSize",
-              "description": "Size (in CSS length units) to be set on the detail area in\nthe CSS grid layout. When there is not enough space to show\nmaster and detail areas next to each other, the detail area\nis shown as an overlay.\n<p>\nIf not specified, the size is determined automatically by measuring\nthe detail content in a `min-content` CSS grid column when it first\nbecomes visible, and then caching the resulting intrinsic size. To\nrecalculate the cached intrinsic size, use the `recalculateLayout`\nmethod.",
+              "name": "?expandMaster",
+              "description": "When true, the master area grows to fill the available space.\nIf `expandDetail` is also true, both areas share the available\nspace equally.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": "?forceOverlay",
+              "description": "When true, the layout forces the detail area to be shown as an overlay,\neven if there is enough space for master and detail to be shown next to\neach other using the default (split) mode.",
               "value": {
                 "kind": "expression"
               }
             },
             {
-              "name": ".expand",
-              "description": "Controls which column(s) expand to fill available space.\nPossible values: `'master'`, `'detail'`, `'both'`.\nDefaults to `'master'`.",
+              "name": "?noAnimation",
+              "description": "When true, the layout does not use animated transitions for the detail area.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".detailSize",
+              "description": "Size (in CSS length units) to be set on the detail area in\nthe CSS grid layout. When there is not enough space to show\nmaster and detail areas next to each other, the detail area\nis shown as an overlay.\n<p>\nIf not specified, the size is determined automatically by measuring\nthe detail content in a `min-content` CSS grid column when it first\nbecomes visible, and then caching the resulting intrinsic size. To\nrecalculate the cached intrinsic size, use the `recalculateLayout`\nmethod.",
               "value": {
                 "kind": "expression"
               }
@@ -56,7 +70,7 @@
             },
             {
               "name": ".overlayContainment",
-              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `viewport`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
+              "description": "Defines the containment of the detail area when the layout is in\noverlay mode. When set to `layout`, the overlay is confined to the\nlayout. When set to `page`, the overlay is confined to the\nbrowser's viewport. Defaults to `layout`.",
               "value": {
                 "kind": "expression"
               }