feat: add containment mode to master-detail-layout (#8826)

Author: sissbruecker

dev/master-detail-layout.html

@@ -42,6 +42,7 @@
       <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>
+      <vaadin-checkbox id="containmentViewport" label="Use viewport containment"></vaadin-checkbox>
       <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>
@@ -86,6 +87,10 @@
         layout.masterMinSize = e.target.checked ? '300px' : null;
       });
 
+      document.querySelector('#containmentViewport').addEventListener('change', (e) => {
+        layout.containment = e.target.checked ? 'viewport' : 'layout';
+      });
+
       document.querySelector('#vertical').addEventListener('change', (e) => {
         layout.orientation = e.target.checked ? 'vertical' : 'horizontal';
       });

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

@@ -69,6 +69,14 @@ declare class MasterDetailLayout extends ResizeMixin(ThemableMixin(ElementMixin(
    * @attr {boolean} force-overlay
    */
   forceOverlay: boolean;
+
+  /**
+   * 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
+   * browser's viewport. Defaults to `layout`.
+   */
+  containment: 'layout' | 'viewport';
 }
 
 declare global {

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

@@ -47,17 +47,25 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
         position: relative;
       }
 
-      :host([overlay]) [part='detail'] {
+      :host([overlay][containment='layout']) [part='detail'] {
         position: absolute;
       }
 
+      :host([overlay][containment='viewport']) [part='detail'] {
+        position: fixed;
+      }
+
       :host([overlay][orientation='horizontal']) [part='detail'] {
         inset-inline-end: 0;
         height: 100%;
         width: var(--_detail-min-size, min-content);
         max-width: 100%;
       }
 
+      :host([overlay][orientation='horizontal'][containment='viewport']) [part='detail'] {
+        inset-block-start: 0;
+      }
+
       :host([overlay][orientation='horizontal']) [part='master'] {
         max-width: 100%;
       }
@@ -122,6 +130,10 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
         height: var(--_detail-min-size, min-content);
       }
 
+      :host([overlay][orientation='vertical'][containment='viewport']) [part='detail'] {
+        inset-inline-start: 0;
+      }
+
       /* Fixed size */
       :host([has-master-size][orientation='vertical']) [part='master'] {
         height: var(--_master-size);
@@ -228,6 +240,19 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
         observer: '__forceOverlayChanged',
         sync: true,
       },
+
+      /**
+       * 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
+       * browser's viewport. Defaults to `layout`.
+       */
+      containment: {
+        type: String,
+        value: 'layout',
+        reflectToAttribute: true,
+        sync: true,
+      },
     };
   }
 

packages/master-detail-layout/test/master-detail-layout.test.js

@@ -437,5 +437,86 @@ describe('vaadin-master-detail-layout', () => {
         expect(layout.hasAttribute('overlay')).to.be.false;
       });
     });
+
+    describe('containment', () => {
+      before(() => {
+        // Apply padding to body to test viewport containment.
+        document.body.style.padding = '20px';
+      });
+
+      after(() => {
+        document.body.style.padding = '';
+      });
+
+      describe('horizontal orientation', () => {
+        beforeEach(async () => {
+          // Use the threshold at which the overlay mode is on by default.
+          await setViewport({ width: 350, height });
+          await nextResize(layout);
+
+          expect(layout.hasAttribute('overlay')).to.be.true;
+        });
+
+        it('should contain overlay to layout by default', () => {
+          const layoutBounds = layout.getBoundingClientRect();
+          const detailBounds = detail.getBoundingClientRect();
+
+          expect(getComputedStyle(detail).position).to.equal('absolute');
+          expect(detailBounds.top).to.equal(layoutBounds.top);
+          expect(detailBounds.bottom).to.equal(layoutBounds.bottom);
+          expect(detailBounds.right).to.equal(layoutBounds.right);
+        });
+
+        it('should contain overlay to viewport when configured', async () => {
+          layout.containment = 'viewport';
+          await nextRender();
+
+          const detailBounds = detail.getBoundingClientRect();
+          const windowBounds = document.documentElement.getBoundingClientRect();
+
+          expect(getComputedStyle(detail).position).to.equal('fixed');
+          expect(detailBounds.top).to.equal(windowBounds.top);
+          expect(detailBounds.bottom).to.equal(windowBounds.bottom);
+          expect(detailBounds.right).to.equal(windowBounds.right);
+        });
+      });
+
+      describe('vertical orientation', () => {
+        beforeEach(async () => {
+          layout.orientation = 'vertical';
+          layout.style.maxHeight = '500px';
+          layout.parentElement.style.height = '100%';
+
+          // Use the threshold at which the overlay mode is on by default.
+          await setViewport({ width: 500, height: 400 });
+          await nextResize(layout);
+
+          expect(layout.hasAttribute('overlay')).to.be.true;
+        });
+
+        it('should contain overlay to layout by default', () => {
+          const layoutBounds = layout.getBoundingClientRect();
+          const detailBounds = detail.getBoundingClientRect();
+
+          expect(getComputedStyle(detail).position).to.equal('absolute');
+          expect(detailBounds.left).to.equal(layoutBounds.left);
+          expect(detailBounds.right).to.equal(layoutBounds.right);
+          expect(detailBounds.bottom).to.equal(layoutBounds.bottom);
+        });
+
+        it('should contain overlay to viewport when configured', async () => {
+          layout.containment = 'viewport';
+          await nextRender();
+
+          const detailBounds = detail.getBoundingClientRect();
+          const windowBounds = document.documentElement.getBoundingClientRect();
+
+          expect(getComputedStyle(detail).position).to.equal('fixed');
+          expect(detailBounds.left).to.equal(windowBounds.left);
+          expect(detailBounds.right).to.equal(windowBounds.right);
+          expect(detailBounds.bottom).to.equal(windowBounds.bottom);
+        });
+      });
+    });
   });
 });