feat: add min-size properties and overlay mode to master-detail-layout (#8789)

web-padawan · web-flow · commit 20802b446d96 · 2025-03-13T16:35:24.000+02:00
diff --git a/dev/master-detail-layout.html b/dev/master-detail-layout.html
@@ -14,11 +14,22 @@
       vaadin-master-detail-layout {
         border: solid 1px #ccc;
       }
+
+      vaadin-master-detail-layout[overlay]::part(master) {
+        background-color: var(--lumo-shade-20pct);
+      }
+
+      vaadin-master-detail-layout[overlay]::part(detail) {
+        background: #fff;
+        border-left: solid 1px #ccc;
+      }
     </style>
 
     <p>
       <vaadin-checkbox id="detailSize" label="Set detail size"></vaadin-checkbox>
+      <vaadin-checkbox id="detailMinSize" label="Set detail min-size"></vaadin-checkbox>
       <vaadin-checkbox id="masterSize" label="Set master size"></vaadin-checkbox>
+      <vaadin-checkbox id="masterMinSize" label="Set master min-size"></vaadin-checkbox>
     </p>
 
     <vaadin-master-detail-layout>
@@ -38,9 +49,17 @@
         layout.detailSize = e.target.checked ? '300px' : null;
       });
 
+      document.querySelector('#detailMinSize').addEventListener('change', (e) => {
+        layout.detailMinSize = e.target.checked ? '300px' : null;
+      });
+
       document.querySelector('#masterSize').addEventListener('change', (e) => {
         layout.masterSize = e.target.checked ? '300px' : null;
       });
+
+      document.querySelector('#masterMinSize').addEventListener('change', (e) => {
+        layout.masterMinSize = e.target.checked ? '300px' : null;
+      });
     </script>
   </body>
 </html>
diff --git a/packages/master-detail-layout/src/vaadin-master-detail-layout.d.ts b/packages/master-detail-layout/src/vaadin-master-detail-layout.d.ts
@@ -4,29 +4,56 @@
  * 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 { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
  * `<vaadin-master-detail-layout>` is a web component for building UIs with a master
  * (or primary) area and a detail (or secondary) area that is displayed next to, or
  * overlaid on top of, the master area, depending on configuration and viewport size.
  */
-declare class MasterDetailLayout extends ThemableMixin(ElementMixin(HTMLElement)) {
+declare class MasterDetailLayout extends ResizeMixin(ThemableMixin(ElementMixin(HTMLElement))) {
   /**
    * Fixed size (in CSS length units) to be set on the detail area.
-   * When specified, it prevents the detail area from growing.
+   * When specified, it prevents the detail area from growing or
+   * shrinking. If there is not enough space to show master and detail
+   * areas next to each other, the layout switches to the overlay mode.
    *
    * @attr {string} detail-size
    */
   detailSize: string | null | undefined;
 
+  /**
+   * Minimum size (in CSS length units) to be set on the detail area.
+   * When specified, it prevents the detail area from shrinking below
+   * this size. If there is not enough space to show master and detail
+   * areas next to each other, the layout switches to the overlay mode.
+   *
+   * @attr {string} detail-min-size
+   */
+  detailMinSize: string | null | undefined;
+
   /**
    * Fixed size (in CSS length units) to be set on the master area.
-   * When specified, it prevents the master area from growing.
+   * When specified, it prevents the master area from growing or
+   * shrinking. If there is not enough space to show master and detail
+   * areas next to each other, the layout switches to the overlay mode.
+   * Setting `100%` enforces the overlay mode to be used by default.
    *
    * @attr {string} master-size
    */
   masterSize: string | null | undefined;
+
+  /**
+   * Minimum size (in CSS length units) to be set on the master area.
+   * When specified, it prevents the master area from shrinking below
+   * this size. If there is not enough space to show master and detail
+   * areas next to each other, the layout switches to the overlay mode.
+   * Setting `100%` enforces the overlay mode to be used by default.
+   *
+   * @attr {string} master-min-size
+   */
+  masterMinSize: string | null | undefined;
 }
 
 declare global {
diff --git a/packages/master-detail-layout/src/vaadin-master-detail-layout.js b/packages/master-detail-layout/src/vaadin-master-detail-layout.js
@@ -7,6 +7,7 @@ import { css, html, LitElement } from 'lit';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
@@ -18,8 +19,9 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * @extends HTMLElement
  * @mixes ThemableMixin
  * @mixes ElementMixin
+ * @mixes ResizeMixin
  */
-class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
+class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)))) {
   static get is() {
     return 'vaadin-master-detail-layout';
   }
@@ -40,6 +42,23 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
         display: none;
       }
 
+      /* Overlay mode */
+      :host([overlay][has-detail]) {
+        position: relative;
+      }
+
+      :host([overlay]) [part='detail'] {
+        position: absolute;
+        inset-inline-end: 0;
+        height: 100%;
+        width: var(--_detail-min-size, min-content);
+        max-width: 100%;
+      }
+
+      :host([overlay]) [part='master'] {
+        max-width: 100%;
+      }
+
       /* No fixed size */
       :host(:not([has-master-size])) [part='master'],
       :host(:not([has-detail-size])) [part='detail'] {
@@ -67,14 +86,30 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
         flex-grow: 1;
         flex-basis: var(--_detail-size);
       }
+
+      /* Min size */
+      :host([has-master-min-size]:not([overlay])) [part='master'] {
+        min-width: var(--_master-min-size);
+      }
+
+      :host([has-detail-min-size]:not([overlay])) [part='detail'] {
+        min-width: var(--_detail-min-size);
+      }
+
+      :host([has-master-min-size]) [part='master'],
+      :host([has-detail-min-size]) [part='detail'] {
+        flex-shrink: 0;
+      }
     `;
   }
 
   static get properties() {
     return {
       /**
        * Fixed size (in CSS length units) to be set on the detail area.
-       * When specified, it prevents the detail area from growing.
+       * When specified, it prevents the detail area from growing or
+       * shrinking. If there is not enough space to show master and detail
+       * areas next to each other, the layout switches to the overlay mode.
        *
        * @attr {string} detail-size
        */
@@ -84,9 +119,26 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
         observer: '__detailSizeChanged',
       },
 
+      /**
+       * Minimum size (in CSS length units) to be set on the detail area.
+       * When specified, it prevents the detail area from shrinking below
+       * this size. If there is not enough space to show master and detail
+       * areas next to each other, the layout switches to the overlay mode.
+       *
+       * @attr {string} detail-min-size
+       */
+      detailMinSize: {
+        type: String,
+        sync: true,
+        observer: '__detailMinSizeChanged',
+      },
+
       /**
        * Fixed size (in CSS length units) to be set on the master area.
-       * When specified, it prevents the master area from growing.
+       * When specified, it prevents the master area from growing or
+       * shrinking. If there is not enough space to show master and detail
+       * areas next to each other, the layout switches to the overlay mode.
+       * Setting `100%` enforces the overlay mode to be used by default.
        *
        * @attr {string} master-size
        */
@@ -95,16 +147,31 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
         sync: true,
         observer: '__masterSizeChanged',
       },
+
+      /**
+       * Minimum size (in CSS length units) to be set on the master area.
+       * When specified, it prevents the master area from shrinking below
+       * this size. If there is not enough space to show master and detail
+       * areas next to each other, the layout switches to the overlay mode.
+       * Setting `100%` enforces the overlay mode to be used by default.
+       *
+       * @attr {string} master-min-size
+       */
+      masterMinSize: {
+        type: String,
+        sync: true,
+        observer: '__masterMinSizeChanged',
+      },
     };
   }
 
   /** @protected */
   render() {
     return html`
-      <div part="master">
+      <div id="master" part="master">
         <slot></slot>
       </div>
-      <div part="detail">
+      <div id="detail" part="detail">
         <slot name="detail" @slotchange="${this.__onDetailSlotChange}"></slot>
       </div>
     `;
@@ -115,16 +182,36 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     this.toggleAttribute('has-detail', e.target.assignedNodes().length > 0);
   }
 
+  /**
+   * @protected
+   * @override
+   */
+  _onResize() {
+    this.__detectLayoutMode();
+  }
+
   /** @private */
   __detailSizeChanged(size, oldSize) {
-    this.toggleAttribute('has-detail-size', !!size);
     this.__updateStyleProperty('detail-size', size, oldSize);
+    this.__detectLayoutMode();
+  }
+
+  /** @private */
+  __detailMinSizeChanged(size, oldSize) {
+    this.__updateStyleProperty('detail-min-size', size, oldSize);
+    this.__detectLayoutMode();
   }
 
   /** @private */
   __masterSizeChanged(size, oldSize) {
-    this.toggleAttribute('has-master-size', !!size);
     this.__updateStyleProperty('master-size', size, oldSize);
+    this.__detectLayoutMode();
+  }
+
+  /** @private */
+  __masterMinSizeChanged(size, oldSize) {
+    this.__updateStyleProperty('master-min-size', size, oldSize);
+    this.__detectLayoutMode();
   }
 
   /** @private */
@@ -134,6 +221,37 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     } else if (oldSize) {
       this.style.removeProperty(`--_${prop}`);
     }
+
+    this.toggleAttribute(`has-${prop}`, !!size);
+  }
+
+  /** @private */
+  __detectLayoutMode() {
+    const detailWidth = this.$.detail.offsetWidth;
+
+    // Detect minimum width needed by master content. Use max-width to ensure
+    // the layout can switch back to split mode once there is enough space.
+    // If there is master  size or min-size set, use that instead to force the
+    // overlay mode by setting `masterSize` / `masterMinSize` to 100%/
+    this.$.master.style.maxWidth = this.masterSize || this.masterMinSize || 'min-content';
+    const masterWidth = this.$.master.offsetWidth;
+    this.$.master.style.maxWidth = '';
+
+    // If the combined minimum size of both the master and the detail content
+    // exceeds the size of the layout, the layout changes to the overlay mode.
+    if (this.offsetWidth < masterWidth + detailWidth) {
+      this.setAttribute('overlay', '');
+    } else {
+      this.removeAttribute('overlay');
+    }
+
+    // Toggling the overlay resizes master content, which can cause document
+    // scroll bar to appear or disappear, and trigger another resize of the
+    // layout which can affect previous measurements and end up in horizontal
+    // scroll. Check if that is the case and if so, preserve the overlay mode.
+    if (this.offsetWidth < this.scrollWidth) {
+      this.setAttribute('overlay', '');
+    }
   }
 }
 
diff --git a/packages/master-detail-layout/test/dom/__snapshots__/master-detail-layout.test.snap.js b/packages/master-detail-layout/test/dom/__snapshots__/master-detail-layout.test.snap.js
@@ -2,11 +2,17 @@
 export const snapshots = {};
 
 snapshots["vaadin-master-detail-layout shadow default"] = 
-`<div part="master">
+`<div
+  id="master"
+  part="master"
+>
   <slot>
   </slot>
 </div>
-<div part="detail">
+<div
+  id="detail"
+  part="detail"
+>
   <slot name="detail">
   </slot>
 </div>
diff --git a/packages/master-detail-layout/test/master-detail-layout.test.js b/packages/master-detail-layout/test/master-detail-layout.test.js
diff --git a/packages/master-detail-layout/test/typings/master-detail-layout.types.ts b/packages/master-detail-layout/test/typings/master-detail-layout.types.ts
