refactor: use aria-description for confirm dialog message (#9775)

Author: sissbruecker

packages/confirm-dialog/src/vaadin-confirm-dialog-mixin.d.ts

@@ -39,8 +39,8 @@ export declare class ConfirmDialogMixinClass {
   /**
    * Sets the `aria-describedby` attribute of the overlay element.
    *
-   * By default, all elements inside the message area are linked
-   * through the `aria-describedby` attribute. However, there are
+   * By default, the text contents of all elements inside the message area
+   * are combined into the `aria-description` attribute. However, there are
    * cases where this can confuse screen reader users (e.g. the dialog
    * may present a password confirmation form). For these cases,
    * it's better to associate only the elements that will help describe

packages/confirm-dialog/src/vaadin-confirm-dialog-mixin.js

@@ -6,7 +6,6 @@
 import { setAriaIDReference } from '@vaadin/a11y-base/src/aria-id-reference.js';
 import { OverlayClassMixin } from '@vaadin/component-base/src/overlay-class-mixin.js';
 import { SlotController } from '@vaadin/component-base/src/slot-controller.js';
-import { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
 import { DialogSizeMixin } from '@vaadin/dialog/src/vaadin-dialog-size-mixin.js';
 
 /**
@@ -21,8 +20,8 @@ export const ConfirmDialogMixin = (superClass) =>
         /**
          * Sets the `aria-describedby` attribute of the overlay element.
          *
-         * By default, all elements inside the message area are linked
-         * through the `aria-describedby` attribute. However, there are
+         * By default, the text contents of all elements inside the message area
+         * are combined into the `aria-description` attribute. However, there are
          * cases where this can confuse screen reader users (e.g. the dialog
          * may present a password confirmation form). For these cases,
          * it's better to associate only the elements that will help describe
@@ -263,13 +262,7 @@ export const ConfirmDialogMixin = (superClass) =>
         multiple: true,
         observe: false,
         initializer: (node) => {
-          const wrapper = document.createElement('div');
-          wrapper.style.display = 'contents';
-          const wrapperId = `confirm-dialog-message-${generateUniqueId()}`;
-          wrapper.id = wrapperId;
-          this.appendChild(wrapper);
-          wrapper.appendChild(node);
-          this._messageNodes = [...this._messageNodes, wrapper];
+          this._messageNodes = [...this._messageNodes, node];
         },
       });
       this.addController(this._messageController);
@@ -329,16 +322,17 @@ export const ConfirmDialogMixin = (superClass) =>
         return;
       }
 
-      if (accessibleDescriptionRef !== undefined) {
+      if (accessibleDescriptionRef) {
+        overlay.removeAttribute('aria-description');
         setAriaIDReference(overlay, 'aria-describedby', {
           newId: accessibleDescriptionRef,
           oldId: this.__oldAccessibleDescriptionRef,
           fromUser: true,
         });
       } else {
-        messageNodes.forEach((node) => {
-          setAriaIDReference(overlay, 'aria-describedby', { newId: node.id });
-        });
+        overlay.removeAttribute('aria-describedby');
+        const ariaDescription = messageNodes.map((node) => node.textContent.trim()).join(' ');
+        overlay.setAttribute('aria-description', ariaDescription);
       }
 
       this.__oldAccessibleDescriptionRef = accessibleDescriptionRef;
@@ -387,11 +381,9 @@ export const ConfirmDialogMixin = (superClass) =>
     /** @private */
     __updateMessageNodes(nodes, message) {
       if (nodes && nodes.length > 0) {
-        const defaultWrapperNode = nodes.find(
-          (node) => this._messageController.defaultNode && node === this._messageController.defaultNode.parentElement,
-        );
-        if (defaultWrapperNode) {
-          defaultWrapperNode.firstChild.textContent = message;
+        const defaultNode = nodes.find((node) => node === this._messageController.defaultNode);
+        if (defaultNode) {
+          defaultNode.textContent = message;
         }
       }
     }

packages/confirm-dialog/test/confirm-dialog.test.js

@@ -83,20 +83,25 @@ describe('vaadin-confirm-dialog', () => {
       expect(overlay.ariaLabel).to.equal('confirmation');
     });
 
+    it('should set aria-description on the overlay', () => {
+      expect(overlay.ariaDescription).to.equal('Confirmation message');
+    });
+
     it('should set `aria-describedby` on the overlay when `accessibleDescriptionRef` is defined', async () => {
       const customId = 'id-0';
       confirm.accessibleDescriptionRef = customId;
       await nextFrame();
       expect(overlay.getAttribute('aria-describedby')).to.equal(customId);
+      expect(overlay.hasAttribute('aria-description')).to.be.false;
     });
 
-    it('should restore `aria-describedby` on the overlay when `accessibleDescriptionRef` is removed', async () => {
-      const generatedDescribedByValue = overlay.getAttribute('aria-describedby');
+    it('should restore `aria-description` on the overlay when `accessibleDescriptionRef` is removed', async () => {
       confirm.accessibleDescriptionRef = 'id-0';
       await nextFrame();
       confirm.accessibleDescriptionRef = null;
       await nextFrame();
-      expect(overlay.getAttribute('aria-describedby')).to.equal(generatedDescribedByValue);
+      expect(overlay.hasAttribute('aria-describedby')).to.be.false;
+      expect(overlay.getAttribute('aria-description')).to.be.equal('Confirmation message');
     });
   });
 
@@ -197,10 +202,9 @@ describe('vaadin-confirm-dialog', () => {
       });
 
       describe('a11y', () => {
-        it('should associate message node with aria-describedby', () => {
+        it('should use message as aria-description', () => {
           const messageNode = messageSlot.assignedNodes()[0];
-          const overlayDescribedBy = overlay.getAttribute('aria-describedby');
-          expect(overlayDescribedBy).to.equal(messageNode.id);
+          expect(overlay.getAttribute('aria-description')).to.equal(messageNode.textContent);
         });
       });
     });
@@ -234,7 +238,7 @@ describe('vaadin-confirm-dialog', () => {
 
     describe('a11y', () => {
       const firstChild = 'Confirm message';
-      const secondChild = '<div>Additionale content</div>';
+      const secondChild = '<div>Additional content</div>';
 
       beforeEach(async () => {
         confirm = fixtureSync(`
@@ -248,31 +252,8 @@ describe('vaadin-confirm-dialog', () => {
         messageSlot = overlay.shadowRoot.querySelector('[part="message"] > slot');
       });
 
-      it('should wrap slotted children inside <div> elements', () => {
-        const nodes = messageSlot.assignedNodes();
-        expect(nodes[0].textContent.trim()).to.equal(firstChild);
-        expect(nodes[1].innerHTML.trim()).to.equal(secondChild);
-      });
-
-      it('should generate id for wrapper elements', () => {
-        const nodes = messageSlot.assignedNodes();
-        nodes.forEach((node) => expect(node.id).to.be.not.null);
-      });
-
-      it('should set "display: contents" on the wrapper elements', () => {
-        const nodes = messageSlot.assignedNodes();
-        nodes.forEach((node) => expect(node.style.display).to.equal('contents'));
-      });
-
-      it('should associate generated ids with aria-describedby in overlay', () => {
-        const nodes = messageSlot.assignedNodes();
-        const overlayDescribedBy = overlay.getAttribute('aria-describedby');
-        expect(overlayDescribedBy).to.be.not.null;
-
-        const overlayDescribedByItems = overlayDescribedBy.split(' ');
-        expect(overlayDescribedByItems).to.have.lengthOf(2);
-        const wrapperIds = nodes.map((node) => node.id);
-        expect(overlayDescribedByItems).to.have.members(wrapperIds);
+      it('should use combined message text as aria-description in overlay', () => {
+        expect(overlay.getAttribute('aria-description')).to.equal('Confirm message Additional content');
       });
     });
   });

packages/confirm-dialog/test/dom/__snapshots__/confirm-dialog.test.snap.js

@@ -3,7 +3,7 @@ export const snapshots = {};
 
 snapshots["vaadin-confirm-dialog overlay"] = 
 `<vaadin-confirm-dialog-overlay
-  aria-describedby="confirm-dialog-message-0"
+  aria-description="Do you want to save or discard the changes?"
   aria-label="Unsaved changes"
   focus-trap=""
   has-footer=""
@@ -17,9 +17,7 @@ snapshots["vaadin-confirm-dialog overlay"] =
   <h3 slot="header">
     Unsaved changes
   </h3>
-  <div id="confirm-dialog-message-0">
-    Do you want to save or discard the changes?
-  </div>
+  Do you want to save or discard the changes?
   <vaadin-button
     hidden=""
     role="button"
@@ -53,7 +51,7 @@ snapshots["vaadin-confirm-dialog overlay"] =
 
 snapshots["vaadin-confirm-dialog overlay theme"] = 
 `<vaadin-confirm-dialog-overlay
-  aria-describedby="confirm-dialog-message-1"
+  aria-description="Do you want to save or discard the changes?"
   aria-label="Unsaved changes"
   focus-trap=""
   has-footer=""
@@ -68,9 +66,7 @@ snapshots["vaadin-confirm-dialog overlay theme"] =
   <h3 slot="header">
     Unsaved changes
   </h3>
-  <div id="confirm-dialog-message-1">
-    Do you want to save or discard the changes?
-  </div>
+  Do you want to save or discard the changes?
   <vaadin-button
     hidden=""
     role="button"
@@ -104,7 +100,7 @@ snapshots["vaadin-confirm-dialog overlay theme"] =
 
 snapshots["vaadin-confirm-dialog overlay class"] = 
 `<vaadin-confirm-dialog-overlay
-  aria-describedby="confirm-dialog-message-2"
+  aria-description="Do you want to save or discard the changes?"
   aria-label="Unsaved changes"
   class="confirm-dialog-overlay custom"
   focus-trap=""
@@ -119,9 +115,7 @@ snapshots["vaadin-confirm-dialog overlay class"] =
   <h3 slot="header">
     Unsaved changes
   </h3>
-  <div id="confirm-dialog-message-2">
-    Do you want to save or discard the changes?
-  </div>
+  Do you want to save or discard the changes?
   <vaadin-button
     hidden=""
     role="button"

packages/crud/test/dom/__snapshots__/crud.test.snap.js

@@ -47,19 +47,19 @@ snapshots["vaadin-crud host default"] =
           theme="small"
         >
           <label
-            for="input-vaadin-text-field-8"
-            id="label-vaadin-text-field-2"
+            for="input-vaadin-text-field-6"
+            id="label-vaadin-text-field-0"
             slot="label"
           >
           </label>
           <div
             hidden=""
-            id="error-message-vaadin-text-field-4"
+            id="error-message-vaadin-text-field-2"
             slot="error-message"
           >
           </div>
           <input
-            id="input-vaadin-text-field-8"
+            id="input-vaadin-text-field-6"
             slot="input"
             type="text"
           >
@@ -78,19 +78,19 @@ snapshots["vaadin-crud host default"] =
           theme="small"
         >
           <label
-            for="input-vaadin-text-field-9"
-            id="label-vaadin-text-field-5"
+            for="input-vaadin-text-field-7"
+            id="label-vaadin-text-field-3"
             slot="label"
           >
           </label>
           <div
             hidden=""
-            id="error-message-vaadin-text-field-7"
+            id="error-message-vaadin-text-field-5"
             slot="error-message"
           >
           </div>
           <input
-            id="input-vaadin-text-field-9"
+            id="input-vaadin-text-field-7"
             slot="input"
             type="text"
           >
@@ -236,13 +236,8 @@ snapshots["vaadin-crud shadow default"] =
   <h3 slot="header">
     Discard changes
   </h3>
-  <div
-    id="confirm-dialog-message-0"
-    style="display: contents;"
-  >
-    <div>
-      There are unsaved changes to this item.
-    </div>
+  <div>
+    There are unsaved changes to this item.
   </div>
   <vaadin-button
     role="button"
@@ -279,13 +274,8 @@ snapshots["vaadin-crud shadow default"] =
   <h3 slot="header">
     Delete item
   </h3>
-  <div
-    id="confirm-dialog-message-1"
-    style="display: contents;"
-  >
-    <div>
-      Are you sure you want to delete this item? This action cannot be undone.
-    </div>
+  <div>
+    Are you sure you want to delete this item? This action cannot be undone.
   </div>
   <vaadin-button
     role="button"