feat: add role and ARIA attributes to master-detail-layout (#8850)

web-padawan · web-flow · commit 77fde54849f1 · 2025-03-25T12:26:13.000+02:00
diff --git a/packages/master-detail-layout/src/vaadin-master-detail-layout.js b/packages/master-detail-layout/src/vaadin-master-detail-layout.js
@@ -3,7 +3,7 @@
  * Copyright (c) 2025 - 2025 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { css, html, LitElement } from 'lit';
+import { css, html, LitElement, nothing } from 'lit';
 import { getFocusableElements } from '@vaadin/a11y-base/src/focus-utils.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
@@ -279,16 +279,45 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
         observer: '__stackThresholdChanged',
         sync: true,
       },
+
+      /**
+       * When true, the component uses the overlay mode. This property is read-only.
+       * In order to enforce the overlay mode, use `forceOverlay` property.
+       * @protected
+       */
+      _overlay: {
+        type: Boolean,
+        attribute: 'overlay',
+        reflectToAttribute: true,
+        sync: true,
+      },
+
+      /**
+       * When true, the component uses the stack mode. This property is read-only.
+       * In order to enforce the stack mode, use `stackThreshold` property.
+       * @protected
+       */
+      _stack: {
+        type: Boolean,
+        attribute: 'stack',
+        reflectToAttribute: true,
+        sync: true,
+      },
     };
   }
 
   /** @protected */
   render() {
     return html`
-      <div id="master" part="master">
+      <div id="master" part="master" ?inert="${this._overlay && this.containment === 'layout'}">
         <slot></slot>
       </div>
-      <div id="detail" part="detail">
+      <div
+        id="detail"
+        part="detail"
+        role="${this._overlay || this._stack ? 'dialog' : nothing}"
+        aria-modal="${this._overlay && this.containment === 'viewport' ? 'true' : nothing}"
+      >
         <slot name="detail" @slotchange="${this.__onDetailSlotChange}"></slot>
       </div>
     `;
@@ -383,19 +412,19 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
 
   /** @private */
   __detectLayoutMode() {
-    this.removeAttribute('overlay');
-    this.removeAttribute('stack');
+    this._overlay = false;
+    this._stack = false;
 
     if (this.forceOverlay) {
-      this.setAttribute('overlay', '');
+      this._overlay = true;
       return;
     }
 
     if (this.stackThreshold != null) {
       const threshold = this.__getStackThresholdInPixels();
       const size = this.orientation === 'vertical' ? this.offsetHeight : this.offsetWidth;
       if (size <= threshold) {
-        this.setAttribute('stack', '');
+        this._stack = true;
         return;
       }
     }
@@ -425,34 +454,29 @@ class MasterDetailLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolylitM
 
     // 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');
-    }
+    this._overlay = this.offsetWidth < masterWidth + detailWidth;
 
     // 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', '');
+      this._overlay = true;
     }
   }
 
   /** @private */
   __detectVerticalMode() {
     // Remove overlay attribute temporarily to detect if there is enough space
     // for both areas so that layout could switch back to the split mode.
-    if (this.hasAttribute('overlay')) {
-      this.removeAttribute('overlay');
-    }
+    this._overlay = false;
+
     const masterHeight = this.$.master.clientHeight;
 
     // If the combined minimum size of both the master and the detail content
     // exceeds the available height, the layout changes to the overlay mode.
     if (this.offsetHeight < masterHeight + this.$.detail.clientHeight) {
-      this.setAttribute('overlay', '');
+      this._overlay = true;
     }
   }
 
diff --git a/packages/master-detail-layout/test/aria.test.js b/packages/master-detail-layout/test/aria.test.js
@@ -0,0 +1,60 @@
+import { expect } from '@vaadin/chai-plugins';
+import { fixtureSync, nextRender, nextResize } from '@vaadin/testing-helpers';
+import '../vaadin-master-detail-layout.js';
+import './helpers/master-content.js';
+import './helpers/detail-content.js';
+
+describe('ARIA', () => {
+  let layout, master, detail;
+
+  beforeEach(async () => {
+    layout = fixtureSync(`
+      <vaadin-master-detail-layout>
+        <master-content></master-content>
+        <detail-content slot="detail"></detail-content>
+      </vaadin-master-detail-layout>
+    `);
+    await nextRender();
+    master = layout.shadowRoot.querySelector('[part="master"]');
+    detail = layout.shadowRoot.querySelector('[part="detail"]');
+  });
+
+  it('should set role to dialog on the detail part in the overlay mode', () => {
+    layout.forceOverlay = true;
+    expect(detail.getAttribute('role')).to.equal('dialog');
+
+    layout.forceOverlay = false;
+    expect(detail.hasAttribute('role')).to.be.false;
+  });
+
+  it('should set role to dialog on the detail part in the stack mode', async () => {
+    layout.stackThreshold = '500px';
+    layout.style.width = '500px';
+    await nextResize(layout);
+
+    expect(detail.getAttribute('role')).to.equal('dialog');
+
+    layout.style.width = '600px';
+    await nextResize(layout);
+
+    expect(detail.hasAttribute('role')).to.be.false;
+  });
+
+  it('should set aria-model on the detail part with the viewport containment', () => {
+    layout.forceOverlay = true;
+    layout.containment = 'viewport';
+    expect(detail.getAttribute('aria-modal')).to.equal('true');
+
+    layout.containment = 'layout';
+    expect(detail.hasAttribute('aria-modal')).to.be.false;
+  });
+
+  it('should set inert on the master part with the layout containment', () => {
+    layout.forceOverlay = true;
+    layout.containment = 'layout';
+    expect(master.hasAttribute('inert')).to.be.true;
+
+    layout.containment = 'viewport';
+    expect(master.hasAttribute('inert')).to.be.false;
+  });
+});
