feat: add message-list announceMessages API (#9252) (#9270)

vaadin-bot · tomivirkki · web-flow · commit 6a490a221449 · 2025-05-23T10:24:10.000+03:00
Co-authored-by: Tomi Virkki &lt;tomivirkki@users.noreply.github.com&gt;
diff --git a/dev/messages.html b/dev/messages.html
@@ -27,11 +27,25 @@
           userColorIndex: 2,
         },
       ];
+
+      const input = document.querySelector('vaadin-message-input');
+      input.addEventListener('submit', (e) => {
+        const message = e.detail.value;
+        list.items = [
+          ...list.items,
+          {
+            text: message,
+            time: 'now',
+            userName: 'You',
+            userColorIndex: 0,
+          },
+        ];
+      });
     </script>
   </head>
 
   <body>
-    <vaadin-message-list></vaadin-message-list>
+    <vaadin-message-list announce-messages></vaadin-message-list>
     <vaadin-message-input>
       <vaadin-tooltip slot="tooltip" text="Press Enter to send"></vaadin-tooltip>
     </vaadin-message-input>
diff --git a/packages/message-list/src/vaadin-message-list-mixin.d.ts b/packages/message-list/src/vaadin-message-list-mixin.d.ts
@@ -48,4 +48,10 @@ export declare class MessageListMixinClass {
    * When set to `true`, the message text is parsed as Markdown.
    */
   markdown: boolean | undefined;
+
+  /**
+   * When set to `true`, new messages are announced to assistive technologies using ARIA live regions.
+   * @attr {boolean} announce-messages
+   */
+  announceMessages: boolean | undefined;
 }
diff --git a/packages/message-list/src/vaadin-message-list-mixin.js b/packages/message-list/src/vaadin-message-list-mixin.js
@@ -49,6 +49,18 @@ export const MessageListMixin = (superClass) =>
           observer: '__markdownChanged',
           reflectToAttribute: true,
         },
+
+        /**
+         * When set to `true`, new messages are announced to assistive technologies using ARIA live regions.
+         * @attr {boolean} announce-messages
+         * @type {boolean}
+         */
+        announceMessages: {
+          type: Boolean,
+          value: false,
+          observer: '__announceChanged',
+          sync: true,
+        },
       };
     }
 
@@ -63,7 +75,7 @@ export const MessageListMixin = (superClass) =>
 
       // Make screen readers announce new messages
       this.setAttribute('aria-relevant', 'additions');
-      this.setAttribute('role', 'log');
+      this.setAttribute('role', 'region');
     }
 
     /** @protected */
@@ -193,4 +205,9 @@ export const MessageListMixin = (superClass) =>
       const index = this._messages.findIndex((e) => e.tabIndex === 0);
       return index !== -1 ? index : 0;
     }
+
+    /** @private */
+    __announceChanged(announceMessages) {
+      this.ariaLive = announceMessages ? 'polite' : null;
+    }
   };
diff --git a/packages/message-list/test/dom/__snapshots__/message-list.test.snap.js b/packages/message-list/test/dom/__snapshots__/message-list.test.snap.js
@@ -4,7 +4,7 @@ export const snapshots = {};
 snapshots["vaadin-message-list default"] = 
 `<vaadin-message-list
   aria-relevant="additions"
-  role="log"
+  role="region"
 >
 </vaadin-message-list>
 `;
@@ -13,7 +13,7 @@ snapshots["vaadin-message-list default"] =
 snapshots["vaadin-message-list items"] = 
 `<vaadin-message-list
   aria-relevant="additions"
-  role="log"
+  role="region"
 >
   <vaadin-message
     role="listitem"
@@ -54,7 +54,7 @@ snapshots["vaadin-message-list items"] =
 snapshots["vaadin-message-list theme"] = 
 `<vaadin-message-list
   aria-relevant="additions"
-  role="log"
+  role="region"
 >
   <vaadin-message
     role="listitem"
@@ -80,7 +80,7 @@ snapshots["vaadin-message-list theme"] =
 snapshots["vaadin-message-list className"] = 
 `<vaadin-message-list
   aria-relevant="additions"
-  role="log"
+  role="region"
 >
   <vaadin-message
     class="pinned"
diff --git a/packages/message-list/test/message-list.test.js b/packages/message-list/test/message-list.test.js
@@ -409,4 +409,14 @@ describe('message-list', () => {
       expect(messageElements[1].hasAttribute('focused')).to.be.true;
     });
   });
+
+  describe('a11y', () => {
+    it('should toggle aria live', () => {
+      expect(messageList.getAttribute('aria-live')).to.be.null;
+      messageList.announceMessages = true;
+      expect(messageList.getAttribute('aria-live')).to.equal('polite');
+      messageList.announceMessages = false;
+      expect(messageList.getAttribute('aria-live')).to.be.null;
+    });
+  });
 });
diff --git a/packages/message-list/test/typings/message-list.types.ts b/packages/message-list/test/typings/message-list.types.ts
@@ -13,6 +13,7 @@ const list = document.createElement('vaadin-message-list');
 // Properties
 assertType<MessageListItem[] | null | undefined>(list.items);
 assertType<boolean | undefined>(list.markdown);
+assertType<boolean | undefined>(list.announceMessages);
 
 // Item properties
 const item: MessageListItem = list.items ? list.items[0] : {};
