refactor: rename MDL overflow attribute to overlay (#11407)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: web-padawan

packages/aura/src/components/master-detail-layout.css

@@ -3,7 +3,7 @@ vaadin-master-detail-layout::part(detail) {
   background: var(--aura-surface-color) padding-box;
 }
 
-vaadin-master-detail-layout[overflow]::part(detail) {
+vaadin-master-detail-layout[overlay]::part(detail) {
   --aura-surface-opacity: var(--aura-overlay-surface-opacity);
   background: var(--aura-surface-color) padding-box;
   -webkit-backdrop-filter: var(--aura-overlay-backdrop-filter);
@@ -14,19 +14,19 @@ vaadin-master-detail-layout[overflow]::part(detail) {
     var(--aura-shadow-m);
 }
 
-vaadin-master-detail-layout[overflow][overlay-containment='viewport']::part(detail) {
+vaadin-master-detail-layout[overlay][overlay-containment='viewport']::part(detail) {
   box-shadow: var(--aura-overlay-shadow);
 }
 
 /* TODO could be a built-in variant */
-vaadin-master-detail-layout[theme~='inset-drawer'][overflow]::part(detail),
-vaadin-master-detail-layout[overflow][overlay-containment='viewport']::part(detail) {
+vaadin-master-detail-layout[theme~='inset-drawer'][overlay]::part(detail),
+vaadin-master-detail-layout[overlay][overlay-containment='viewport']::part(detail) {
   margin: calc(var(--aura-app-layout-inset) / 2);
   border-radius: var(--_app-layout-radius);
 }
 
 vaadin-master-detail-layout > vaadin-master-detail-layout,
-vaadin-master-detail-layout:not([overflow])::part(detail) {
+vaadin-master-detail-layout:not([overlay])::part(detail) {
   border-start-end-radius: var(--_app-layout-radius);
   border-end-end-radius: var(--_app-layout-radius);
 }

packages/master-detail-layout/ARCHITECTURE.md

@@ -54,7 +54,7 @@ The `>=` (not `>`) is intentional: when `keep-detail-column-offscreen` or `:not(
 Layout detection is split into two methods to avoid forced reflows:
 
 - **`__computeLayoutState()`** — pure reads: `checkVisibility()`, `getComputedStyle()`, `getFocusableElements()`. Called in the ResizeObserver callback where layout is already computed — no forced reflow.
-- **`__applyLayoutState(state)`** — pure writes: toggles `has-detail`, `overflow`, `keep-detail-column-offscreen`; calls `requestUpdate()` for ARIA; focuses detail. No DOM/style reads.
+- **`__applyLayoutState(state)`** — pure writes: toggles `has-detail`, `overlay`, `keep-detail-column-offscreen`; calls `requestUpdate()` for ARIA; focuses detail. No DOM/style reads.
 
 ### ResizeObserver
 
@@ -64,7 +64,7 @@ Layout detection is split into two methods to avoid forced reflows:
 
 ## Overlay Modes
 
-When `overflow` AND `has-detail` are both set, the detail becomes an overlay:
+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
@@ -85,7 +85,7 @@ Setting `overlaySize` to `100%` makes the detail cover the full layout (replaces
 
 Prevents the master from jumping when the detail overlay first appears.
 
-When no detail is present, master's extra track is set to `calc(100% - masterSize)`, pushing the detail column offscreen. This ensures that when a detail element appears, it starts offscreen and is then either moved into an overlay (if overflow, so no blink occurs and master area size is preserved) or revealed by removing the `calc()` override (if no overflow). The `keep-detail-column-offscreen` attribute keeps the same override active when detail first appears with overflow, until the overlay takes effect.
+When no detail is present, master's extra track is set to `calc(100% - masterSize)`, pushing the detail column offscreen. This ensures that when a detail element appears, it starts offscreen and is then either moved into an overlay (if `overlay` is set, so no blink occurs and master area size is preserved) or revealed by removing the `calc()` override (if no overlay). The `keep-detail-column-offscreen` attribute keeps the same override active when detail first appears with overlay, until the overlay takes effect.
 
 ```css
 :host(:not([has-detail])),
@@ -94,7 +94,7 @@ When no detail is present, master's extra track is set to `calc(100% - masterSiz
 }
 ```
 
-Set when detail first appears with overflow, cleared when detail is removed or overflow resolves.
+Set when detail first appears with overlay, cleared when detail is removed or overlay resolves.
 
 ## Detail Animations
 

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

@@ -88,12 +88,12 @@ export const masterDetailLayoutStyles = css`
     --_detail-column: var(--_detail-size) 1fr;
   }
 
-  :host([orientation='horizontal'][has-detail]:not([overflow])) #detail {
+  :host([orientation='horizontal'][has-detail]: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));
   }
 
-  :host([orientation='vertical'][has-detail]:not([overflow])) #detail {
+  :host([orientation='vertical'][has-detail]: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));
   }
@@ -119,47 +119,47 @@ export const masterDetailLayoutStyles = css`
     z-index: 1;
   }
 
-  :host([overflow]) {
+  :host([overlay]) {
     --_detail-offscreen: calc((100% + 30px) * var(--_rtl-multiplier));
   }
 
-  :host([overflow][orientation='vertical']) {
+  :host([overlay][orientation='vertical']) {
     --_detail-offscreen: 0 calc(100% + 30px);
   }
 
-  :host([overflow]) :is(#detail, #outgoing) {
+  :host([overlay]) :is(#detail, #outgoing) {
     position: absolute;
     z-index: 2;
     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));
     grid-column: none;
   }
 
-  :host([overflow]) [part~='backdrop'] {
+  :host([overlay]) [part~='backdrop'] {
     display: block;
   }
 
-  :host([overflow]:not([orientation='vertical'])) :is(#detail, #outgoing) {
+  :host([overlay]:not([orientation='vertical'])) :is(#detail, #outgoing) {
     inset-block: 0;
     width: var(--_overlay-size, var(--_detail-size, min-content));
     inset-inline-end: 0;
   }
 
-  :host([overflow][orientation='vertical']) :is(#detail, #outgoing) {
+  :host([overlay][orientation='vertical']) :is(#detail, #outgoing) {
     grid-column: auto;
     grid-row: none;
     inset-inline: 0;
     height: var(--_overlay-size, var(--_detail-size, min-content));
     inset-block-end: 0;
   }
 
-  :host([overflow][overlay-containment='viewport']) :is(#detail, #outgoing),
-  :host([overflow][overlay-containment='viewport']) [part~='backdrop'] {
+  :host([overlay][overlay-containment='viewport']) :is(#detail, #outgoing),
+  :host([overlay][overlay-containment='viewport']) [part~='backdrop'] {
     position: fixed;
   }
 
   @media (forced-colors: active) {
-    :host([overflow]) :is(#detail, #outgoing) {
+    :host([overlay]) :is(#detail, #outgoing) {
       outline: 3px solid !important;
     }
 
@@ -174,7 +174,7 @@ export const masterDetailLayoutStyles = css`
       --_transition-duration: 200ms;
     }
 
-    :host([overflow]:not([no-animation])) {
+    :host([overlay]:not([no-animation])) {
       --_transition-duration: 300ms;
     }
   }

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

@@ -36,7 +36,7 @@ export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterD
  * `expand`              | Set to `master`, `detail`, or `both`.
  * `orientation`         | Set to `horizontal` or `vertical` depending on the orientation.
  * `has-detail`          | Set when the detail content is provided and visible.
- * `overflow`            | Set when columns don't fit and the detail is shown as an overlay.
+ * `overlay`             | Set when columns don't fit and the detail is shown as an overlay.
  * `overlay-containment` | Set to `layout` or `viewport`.
  *
  * The following custom CSS properties are available for styling:

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

@@ -42,7 +42,7 @@ function parseTrackSizes(gridTemplate) {
  * `expand`              | Set to `master`, `detail`, or `both`.
  * `orientation`         | Set to `horizontal` or `vertical` depending on the orientation.
  * `has-detail`          | Set when the detail content is provided and visible.
- * `overflow`            | Set when columns don't fit and the detail is shown as an overlay.
+ * `overlay`             | Set when columns don't fit and the detail is shown as an overlay.
  * `overlay-containment` | Set to `layout` or `viewport`.
  *
  * The following custom CSS properties are available for styling:
@@ -182,7 +182,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
 
   /** @protected */
   render() {
-    const isOverlay = this.hasAttribute('has-detail') && this.hasAttribute('overflow');
+    const isOverlay = this.hasAttribute('has-detail') && this.hasAttribute('overlay');
     const isViewport = isOverlay && this.overlayContainment === 'viewport';
     const isLayoutContained = isOverlay && !isViewport;
 
@@ -290,7 +290,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
    * @private
    */
   __applyLayoutState({ hadDetail, hasDetail, hasOverflow, focusTarget }) {
-    // Set keep-detail-column-offscreen when detail first appears with overflow
+    // Set keep-detail-column-offscreen when detail first appears with overlay
     // to prevent master width from jumping.
     if (!hadDetail && hasDetail && hasOverflow) {
       this.setAttribute('keep-detail-column-offscreen', '');
@@ -299,10 +299,10 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
     }
 
     this.toggleAttribute('has-detail', hasDetail);
-    this.toggleAttribute('overflow', hasOverflow);
+    this.toggleAttribute('overlay', hasOverflow);
 
     // Re-render to update ARIA attributes (role, aria-modal, inert)
-    // which depend on has-detail and overflow state.
+    // which depend on has-detail and overlay state.
     this.requestUpdate();
 
     if (focusTarget) {
@@ -434,7 +434,7 @@ class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElem
 
     const opts = this.__getAnimationParams();
     opts.interrupted = interrupted;
-    opts.overlay = this.hasAttribute('overflow');
+    opts.overlay = this.hasAttribute('overlay');
 
     return this.__animateTransition(transitionType, opts, updateCallback);
   }

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

@@ -25,7 +25,7 @@ describe('ARIA', () => {
   });
 
   it('should set role="dialog" on detail in overlay mode', () => {
-    expect(layout.hasAttribute('overflow')).to.be.true;
+    expect(layout.hasAttribute('overlay')).to.be.true;
     expect(detail.getAttribute('role')).to.equal('dialog');
   });
 

…ster-detail-layout/test/overflow.test.js …il-layout/test/overlay-detection.test.jspackages/master-detail-layout/test/overflow.test.js renamed to packages/master-detail-layout/test/overlay-detection.test.js packages/master-detail-layout/test/overflow.test.js renamed to packages/master-detail-layout/test/overlay-detection.test.js

@@ -7,7 +7,7 @@ window.Vaadin ||= {};
 window.Vaadin.featureFlags ||= {};
 window.Vaadin.featureFlags.masterDetailLayoutComponent = true;
 
-describe('overflow detection', () => {
+describe('overlay detection', () => {
   describe('horizontal', () => {
     let layout;
 
@@ -22,65 +22,65 @@ describe('overflow detection', () => {
     });
 
     describe('layout resize', () => {
-      it('should not set overflow when columns fit within the layout', () => {
-        expect(layout.hasAttribute('overflow')).to.be.false;
+      it('should not set overlay when columns fit within the layout', () => {
+        expect(layout.hasAttribute('overlay')).to.be.false;
       });
 
-      it('should set overflow when layout size is decreased below column minimums', async () => {
+      it('should set overlay when layout size is decreased below column minimums', async () => {
         layout.style.width = '400px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.true;
+        expect(layout.hasAttribute('overlay')).to.be.true;
       });
 
-      it('should remove overflow when layout size is increased to fit columns', async () => {
+      it('should remove overlay when layout size is increased to fit columns', async () => {
         layout.style.width = '400px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.true;
+        expect(layout.hasAttribute('overlay')).to.be.true;
 
         layout.style.width = '800px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.false;
+        expect(layout.hasAttribute('overlay')).to.be.false;
       });
     });
 
     describe('property changes', () => {
-      it('should set overflow when masterSize increases beyond available space', async () => {
+      it('should set overlay when masterSize increases beyond available space', async () => {
         layout.masterSize = '600px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.true;
+        expect(layout.hasAttribute('overlay')).to.be.true;
       });
 
-      it('should remove overflow when masterSize decreases to fit', async () => {
+      it('should remove overlay when masterSize decreases to fit', async () => {
         layout.style.width = '400px';
         await onceResized(layout);
 
         layout.masterSize = '100px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.false;
+        expect(layout.hasAttribute('overlay')).to.be.false;
       });
 
-      it('should remove overflow when masterSize decreases to fit while keep-detail-column-offscreen is set', async () => {
+      it('should remove overlay when masterSize decreases to fit while keep-detail-column-offscreen is set', async () => {
         layout.style.width = '400px';
         await onceResized(layout);
 
         layout.masterSize = '50px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.false;
+        expect(layout.hasAttribute('overlay')).to.be.false;
       });
 
-      it('should set overflow when masterSize is set to 100%', async () => {
+      it('should set overlay when masterSize is set to 100%', async () => {
         layout.masterSize = '100%';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.true;
+        expect(layout.hasAttribute('overlay')).to.be.true;
       });
 
-      it('should not set overflow when detail is removed', async () => {
+      it('should not set overlay when detail is removed', async () => {
         layout.style.width = '400px';
         await onceResized(layout);
 
         layout.querySelector('[slot="detail"]').remove();
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.false;
+        expect(layout.hasAttribute('overlay')).to.be.false;
       });
     });
   });
@@ -103,23 +103,23 @@ describe('overflow detection', () => {
       await onceResized(layout);
     });
 
-    it('should not set overflow when rows fit within the layout', () => {
-      expect(layout.hasAttribute('overflow')).to.be.false;
+    it('should not set overlay when rows fit within the layout', () => {
+      expect(layout.hasAttribute('overlay')).to.be.false;
     });
 
-    it('should set overflow when layout height is decreased below row minimums', async () => {
+    it('should set overlay when layout height is decreased below row minimums', async () => {
       layout.style.height = '400px';
       await onceResized(layout);
-      expect(layout.hasAttribute('overflow')).to.be.true;
+      expect(layout.hasAttribute('overlay')).to.be.true;
     });
 
-    it('should remove overflow when layout height is increased to fit rows', async () => {
+    it('should remove overlay when layout height is increased to fit rows', async () => {
       layout.style.height = '400px';
       await onceResized(layout);
 
       layout.style.height = '800px';
       await onceResized(layout);
-      expect(layout.hasAttribute('overflow')).to.be.false;
+      expect(layout.hasAttribute('overlay')).to.be.false;
     });
   });
 
@@ -150,14 +150,14 @@ describe('overflow detection', () => {
       // round to integers, which can mask overflow when the fractional host size is
       // slightly less than the track sum (e.g. 599.6px rounds up to 600px, matching
       // the 300+300 track sum).
-      it(`should not report false overflow due to sub-pixel rounding`, async () => {
+      it(`should not report false overlay due to sub-pixel rounding`, async () => {
         layout.style[sizeProp] = '600.4px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.false;
+        expect(layout.hasAttribute('overlay')).to.be.false;
 
         layout.style[sizeProp] = '599.6px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.true;
+        expect(layout.hasAttribute('overlay')).to.be.true;
       });
     });
   });

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

@@ -44,11 +44,11 @@ describe('overlay', () => {
         const detailContent = layout.querySelector('[slot="detail"]');
         detailContent.remove();
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.false;
+        expect(layout.hasAttribute('overlay')).to.be.false;
 
         layout.appendChild(detailContent);
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.true;
+        expect(layout.hasAttribute('overlay')).to.be.true;
         expect(getComputedStyle(detail).position).to.equal('absolute');
       });
     });
@@ -117,7 +117,7 @@ describe('overlay', () => {
       it('should switch back to split mode when layout grows', async () => {
         layout.style.width = '800px';
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.false;
+        expect(layout.hasAttribute('overlay')).to.be.false;
       });
 
       it('should switch to overlay when detail is added to a narrow layout', async () => {
@@ -127,7 +127,7 @@ describe('overlay', () => {
 
         layout.appendChild(detailContent);
         await onceResized(layout);
-        expect(layout.hasAttribute('overflow')).to.be.true;
+        expect(layout.hasAttribute('overlay')).to.be.true;
         expect(detail.offsetWidth).to.equal(layout.offsetWidth);
       });
     });

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

@@ -288,8 +288,8 @@ describe('Transitions', () => {
       const midValue = parseFloat(midTranslate);
       expect(midValue).to.be.greaterThan(0);
 
-      // Set overflow so replace uses slide (not cross-fade)
-      layout.setAttribute('overflow', '');
+      // Set overlay so replace uses slide (not cross-fade)
+      layout.setAttribute('overlay', '');
 
       // Interrupt with replace — outgoing should start from captured position
       const replaceCallback = sinon.spy();