feat: add forceOverlay property to master-detail-layout (#8824)

web-padawan · web-flow · commit 603a86b1801b · 2025-03-20T10:08:34.000+02:00
diff --git a/dev/master-detail-layout.html b/dev/master-detail-layout.html
@@ -45,6 +45,7 @@
       <vaadin-checkbox id="vertical" label="Use vertical orientation"></vaadin-checkbox>
       <vaadin-checkbox id="maxWidth" label="Use max-width on the host"></vaadin-checkbox>
       <vaadin-checkbox id="maxHeight" label="Use max-height on the host"></vaadin-checkbox>
+      <vaadin-checkbox id="forceOverlay" label="Force overlay"></vaadin-checkbox>
     </p>
 
     <vaadin-master-detail-layout>
@@ -104,6 +105,10 @@
           layout.style.maxHeight = '';
         }
       });
+
+      document.querySelector('#forceOverlay').addEventListener('change', (e) => {
+        layout.forceOverlay = e.target.checked;
+      });
     </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
@@ -60,6 +60,15 @@ declare class MasterDetailLayout extends ResizeMixin(ThemableMixin(ElementMixin(
    * Defaults to horizontal.
    */
   orientation: 'horizontal' | 'vertical';
+
+  /**
+   * When specified, forces the layout to use overlay mode, 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;
 }
 
 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
@@ -214,6 +214,20 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
         observer: '__orientationChanged',
         sync: true,
       },
+
+      /**
+       * When specified, forces the layout to use overlay mode, 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,
+        observer: '__forceOverlayChanged',
+        sync: true,
+      },
     };
   }
 
@@ -274,6 +288,13 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
     }
   }
 
+  /** @private */
+  __forceOverlayChanged(forceOverlay, oldForceOverlay) {
+    if (forceOverlay || oldForceOverlay) {
+      this.__detectLayoutMode();
+    }
+  }
+
   /** @private */
   __updateStyleProperty(prop, size, oldSize) {
     if (size) {
@@ -292,6 +313,11 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
       return;
     }
 
+    if (this.forceOverlay) {
+      this.setAttribute('overlay', '');
+      return;
+    }
+
     if (this.orientation === 'vertical') {
       this.__detectVerticalMode();
     } else {
diff --git a/packages/master-detail-layout/test/master-detail-layout.test.js b/packages/master-detail-layout/test/master-detail-layout.test.js
@@ -290,6 +290,31 @@ describe('vaadin-master-detail-layout', () => {
 
         expect(layout.hasAttribute('overlay')).to.be.false;
       });
+
+      it('should enforce the overlay mode when forceOverlay is set to true', async () => {
+        layout.forceOverlay = true;
+        await nextRender();
+        expect(layout.hasAttribute('overlay')).to.be.true;
+
+        layout.forceOverlay = false;
+        await nextRender();
+        expect(layout.hasAttribute('overlay')).to.be.false;
+      });
+
+      it('should not set the overlay mode with forceOverlay after removing details', async () => {
+        layout.forceOverlay = true;
+        await nextRender();
+
+        detailContent.remove();
+        await nextRender();
+
+        expect(layout.hasAttribute('overlay')).to.be.false;
+
+        layout.appendChild(detailContent);
+        await nextRender();
+
+        expect(layout.hasAttribute('overlay')).to.be.true;
+      });
     });
 
     describe('vertical', () => {
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
@@ -16,3 +16,4 @@ assertType<string | null | undefined>(layout.detailMinSize);
 assertType<string | null | undefined>(layout.masterSize);
 assertType<string | null | undefined>(layout.masterMinSize);
 assertType<'horizontal' | 'vertical'>(layout.orientation);
+assertType<boolean>(layout.forceOverlay);
