refactor!: rename overlayContainment from "viewport" to "page" (#11520)

web-padawan · claude · web-flow · commit 62a23068473b · 2026-04-20T13:50:03.000+03:00
Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/dev/aura/grid-mdl-view.js b/dev/aura/grid-mdl-view.js
@@ -226,7 +226,7 @@ customElements.define(
             <vaadin-master-detail-layout
               class="aura-surface-solid"
               detail-size="25rem"
-              overlay-containment="viewport"
+              overlay-containment="page"
               expand="master"
             >
               <div class="aura-view">
diff --git a/dev/master-detail-layout.html b/dev/master-detail-layout.html
@@ -233,7 +233,7 @@ <h3>View ${window.mdlCount}</h3>
                   value="layout"
                 >
                   <vaadin-radio-button value="layout" label="Layout"></vaadin-radio-button>
-                  <vaadin-radio-button value="viewport" label="Viewport"></vaadin-radio-button>
+                  <vaadin-radio-button value="page" label="Page"></vaadin-radio-button>
                 </vaadin-radio-group>
                 <vaadin-radio-group
                   @change=${this._configChange}
diff --git a/packages/aura/src/components/master-detail-layout.css b/packages/aura/src/components/master-detail-layout.css
@@ -15,13 +15,13 @@ vaadin-master-detail-layout[has-detail][overlay]::part(detail) {
   );
 }
 
-vaadin-master-detail-layout[has-detail][overlay][overlay-containment='viewport']::part(detail) {
+vaadin-master-detail-layout[has-detail][overlay][overlay-containment='page']::part(detail) {
   box-shadow: var(--vaadin-master-detail-layout-detail-shadow, var(--aura-overlay-shadow));
 }
 
 /* TODO could be a built-in variant */
 vaadin-master-detail-layout[theme~='inset-drawer'][has-detail][overlay]::part(detail),
-vaadin-master-detail-layout[has-detail][overlay][overlay-containment='viewport']::part(detail) {
+vaadin-master-detail-layout[has-detail][overlay][overlay-containment='page']::part(detail) {
   margin: calc(var(--aura-app-layout-inset) / 2);
   border-radius: var(--_app-layout-radius);
 }
diff --git a/packages/master-detail-layout/ARCHITECTURE.md b/packages/master-detail-layout/ARCHITECTURE.md
@@ -89,15 +89,15 @@ When `overlay` AND `has-detail` are both set, the detail becomes an overlay:
 - `position: absolute; grid-column: none` removes detail from grid flow
 - Backdrop becomes visible (`opacity: 1`, `pointer-events: auto`)
 - `overlaySize` (CSS custom property `--_overlay-size`) controls overlay dimensions; falls back to `--_detail-size`
-- `overlayContainment` (`layout`/`viewport`) controls positioning: `absolute` vs `fixed`
-- ARIA: `role="dialog"` on detail, `inert` on master (layout containment), `aria-modal` (viewport containment)
+- `overlayContainment` (`layout`/`page`) controls positioning: `absolute` vs `fixed`
+- ARIA: `role="dialog"` on detail, `inert` on master (layout containment), `aria-modal` (page containment)
 
 ### Overlay positioning
 
-| Orientation | Default                                              | `overlayContainment='viewport'` |
-| ----------- | ---------------------------------------------------- | ------------------------------- |
-| Horizontal  | `width: overlaySize/detailSize; inset-inline-end: 0` | `position: fixed`               |
-| Vertical    | `height: overlaySize/detailSize; inset-block-end: 0` | `position: fixed`               |
+| Orientation | Default                                              | `overlayContainment='page'` |
+| ----------- | ---------------------------------------------------- | --------------------------- |
+| Horizontal  | `width: overlaySize/detailSize; inset-inline-end: 0` | `position: fixed`           |
+| Vertical    | `height: overlaySize/detailSize; inset-block-end: 0` | `position: fixed`           |
 
 Setting `overlaySize` to `100%` makes the detail cover the full layout (replaces old "full" mode).
 
diff --git a/packages/master-detail-layout/src/styles/vaadin-master-detail-layout-base-styles.js b/packages/master-detail-layout/src/styles/vaadin-master-detail-layout-base-styles.js
@@ -238,7 +238,7 @@ export const masterDetailLayoutStyles = css`
     max-height: 100%;
   }
 
-  :host([has-detail][overlay][overlay-containment='viewport']) :is(#detail, #detailOutgoing, #backdrop) {
+  :host([has-detail][overlay][overlay-containment='page']) :is(#detail, #detailOutgoing, #backdrop) {
     position: fixed;
   }
 
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
@@ -64,7 +64,7 @@ export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterD
  * `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,12 +128,12 @@ 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.
diff --git a/packages/master-detail-layout/src/vaadin-master-detail-layout.js b/packages/master-detail-layout/src/vaadin-master-detail-layout.js
@@ -70,7 +70,7 @@ import {
  * `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:
  *
@@ -167,7 +167,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
       /**
        * 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
@@ -218,8 +218,8 @@ 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>
@@ -233,7 +233,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
         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>
diff --git a/packages/master-detail-layout/test/aria.test.js b/packages/master-detail-layout/test/aria.test.js
@@ -35,8 +35,8 @@ describe('ARIA', () => {
     expect(detail.hasAttribute('role')).to.be.false;
   });
 
-  it('should set aria-modal on detail with viewport containment', async () => {
-    layout.overlayContainment = 'viewport';
+  it('should set aria-modal on detail with page containment', async () => {
+    layout.overlayContainment = 'page';
     await onceResized(layout);
     expect(detail.getAttribute('aria-modal')).to.equal('true');
   });
@@ -49,8 +49,8 @@ describe('ARIA', () => {
     expect(master.hasAttribute('inert')).to.be.true;
   });
 
-  it('should not set inert on master with viewport containment', async () => {
-    layout.overlayContainment = 'viewport';
+  it('should not set inert on master with page containment', async () => {
+    layout.overlayContainment = 'page';
     await onceResized(layout);
     expect(master.hasAttribute('inert')).to.be.false;
   });
diff --git a/packages/master-detail-layout/test/overlay.test.js b/packages/master-detail-layout/test/overlay.test.js
@@ -193,7 +193,7 @@ describe('overlay', () => {
     });
   });
 
-  describe('overlayContainment viewport', () => {
+  describe('overlayContainment page', () => {
     ['horizontal', 'vertical'].forEach((orientation) => {
       describe(orientation, () => {
         let layout, detail, backdrop;
@@ -207,7 +207,7 @@ describe('overlay', () => {
               ${orientationAttr}
               master-size="300px"
               detail-size="300px"
-              overlay-containment="viewport"
+              overlay-containment="page"
               style="${sizeStyle}"
             >
               <div>Master</div>
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
@@ -14,7 +14,7 @@ assertType<ThemableMixinClass>(layout);
 assertType<string | null | undefined>(layout.detailSize);
 assertType<string | null | undefined>(layout.masterSize);
 assertType<string | null | undefined>(layout.overlaySize);
-assertType<'layout' | 'viewport'>(layout.overlayContainment);
+assertType<'layout' | 'page'>(layout.overlayContainment);
 assertType<'master' | 'detail' | 'both'>(layout.expand);
 assertType<'horizontal' | 'vertical'>(layout.orientation);
 assertType<boolean>(layout.noAnimation);
diff --git a/packages/master-detail-layout/test/visual/aura/master-detail-layout.test.js b/packages/master-detail-layout/test/visual/aura/master-detail-layout.test.js
@@ -44,10 +44,10 @@ describe('master-detail-layout', () => {
       await visualDiff(element, 'drawer-default');
     });
 
-    it('viewport', async () => {
-      mdl.overlayContainment = 'viewport';
+    it('page', async () => {
+      mdl.overlayContainment = 'page';
       await onceResized(mdl);
-      await visualDiff(document.body, 'drawer-viewport');
+      await visualDiff(document.body, 'drawer-page');
     });
 
     it('inset-drawer', async () => {
diff --git a/packages/master-detail-layout/test/visual/aura/screenshots/dark/master-detail-layout/baseline/drawer-page.png b/packages/master-detail-layout/test/visual/aura/screenshots/dark/master-detail-layout/baseline/drawer-page.png
diff --git a/packages/master-detail-layout/test/visual/aura/screenshots/default/master-detail-layout/baseline/drawer-page.png b/packages/master-detail-layout/test/visual/aura/screenshots/default/master-detail-layout/baseline/drawer-page.png
diff --git a/packages/master-detail-layout/test/visual/base/master-detail-layout.test.js b/packages/master-detail-layout/test/visual/base/master-detail-layout.test.js
@@ -88,10 +88,10 @@ describe('master-detail-layout', () => {
             await visualDiff(div, `${dir}-overlay-default`);
           });
 
-          it('viewport', async () => {
-            mdl.overlayContainment = 'viewport';
+          it('page', async () => {
+            mdl.overlayContainment = 'page';
             await onceResized(mdl);
-            await visualDiff(document.body, `${dir}-overlay-viewport`);
+            await visualDiff(document.body, `${dir}-overlay-page`);
           });
 
           it('overlay size', async () => {
diff --git a/packages/master-detail-layout/test/visual/base/screenshots/master-detail-layout/baseline/ltr-overlay-page.png b/packages/master-detail-layout/test/visual/base/screenshots/master-detail-layout/baseline/ltr-overlay-page.png
diff --git a/packages/master-detail-layout/test/visual/base/screenshots/master-detail-layout/baseline/rtl-overlay-page.png b/packages/master-detail-layout/test/visual/base/screenshots/master-detail-layout/baseline/rtl-overlay-page.png
diff --git a/packages/master-detail-layout/test/visual/lumo/master-detail-layout.test.js b/packages/master-detail-layout/test/visual/lumo/master-detail-layout.test.js
@@ -44,10 +44,10 @@ describe('master-detail-layout', () => {
           await visualDiff(element, `${dir}-overlay-default`);
         });
 
-        it('viewport', async () => {
-          element.overlayContainment = 'viewport';
+        it('page', async () => {
+          element.overlayContainment = 'page';
           await onceResized(element);
-          await visualDiff(document.body, `${dir}-overlay-viewport`);
+          await visualDiff(document.body, `${dir}-overlay-page`);
         });
 
         it('no detail', async () => {
diff --git a/packages/master-detail-layout/test/visual/lumo/screenshots/master-detail-layout/baseline/ltr-overlay-page.png b/packages/master-detail-layout/test/visual/lumo/screenshots/master-detail-layout/baseline/ltr-overlay-page.png
diff --git a/packages/master-detail-layout/test/visual/lumo/screenshots/master-detail-layout/baseline/rtl-overlay-page.png b/packages/master-detail-layout/test/visual/lumo/screenshots/master-detail-layout/baseline/rtl-overlay-page.png

Original file line number	Diff line number	Diff line change
`@@ -226,7 +226,7 @@ customElements.define(`
`226`	`226`	`<vaadin-master-detail-layout`
`227`	`227`	`class="aura-surface-solid"`
`228`	`228`	`detail-size="25rem"`
`229`		`- overlay-containment="viewport"`
	`229`	`+ overlay-containment="page"`
`230`	`230`	`expand="master"`
`231`	`231`	`>`
`232`	`232`	`<div class="aura-view">`
Original file line number	Diff line number	Diff line change
`@@ -233,7 +233,7 @@ <h3>View ${window.mdlCount}</h3>`
`233`	`233`	`value="layout"`
`234`	`234`	`>`
`235`	`235`	`<vaadin-radio-button value="layout" label="Layout"></vaadin-radio-button>`
`236`		`- <vaadin-radio-button value="viewport" label="Viewport"></vaadin-radio-button>`
	`236`	`+ <vaadin-radio-button value="page" label="Page"></vaadin-radio-button>`
`237`	`237`	`</vaadin-radio-group>`
`238`	`238`	`<vaadin-radio-group`
`239`	`239`	`@change=${this._configChange}`
Original file line number	Diff line number	Diff line change
`@@ -15,13 +15,13 @@ vaadin-master-detail-layout[has-detail][overlay]::part(detail) {`
`15`	`15`	`);`
`16`	`16`	`}`
`17`	`17`
`18`		`-vaadin-master-detail-layout[has-detail][overlay][overlay-containment='viewport']::part(detail) {`
	`18`	`+vaadin-master-detail-layout[has-detail][overlay][overlay-containment='page']::part(detail) {`
`19`	`19`	`box-shadow: var(--vaadin-master-detail-layout-detail-shadow, var(--aura-overlay-shadow));`
`20`	`20`	`}`
`21`	`21`
`22`	`22`	`/* TODO could be a built-in variant */`
`23`	`23`	`vaadin-master-detail-layout[theme~='inset-drawer'][has-detail][overlay]::part(detail),`
`24`		`-vaadin-master-detail-layout[has-detail][overlay][overlay-containment='viewport']::part(detail) {`
	`24`	`+vaadin-master-detail-layout[has-detail][overlay][overlay-containment='page']::part(detail) {`
`25`	`25`	`margin: calc(var(--aura-app-layout-inset) / 2);`
`26`	`26`	`border-radius: var(--_app-layout-radius);`
`27`	`27`	`}`
Original file line number	Diff line number	Diff line change
@@ -238,7 +238,7 @@ export const masterDetailLayoutStyles = css`
`238`	`238`	`max-height: 100%;`
`239`	`239`	`}`
`240`	`240`
`241`		`- :host([has-detail][overlay][overlay-containment='viewport']) :is(#detail, #detailOutgoing, #backdrop) {`
	`241`	`+ :host([has-detail][overlay][overlay-containment='page']) :is(#detail, #detailOutgoing, #backdrop) {`
`242`	`242`	`position: fixed;`
`243`	`243`	`}`
`244`	`244`