Add an opt-in ariaNotify() transport for screen reader announcements

.changelog/5962-fix-aria-notify-transport.md

@@ -0,0 +1,3 @@
+### Added
+
+- 🧪 Added `styleOptions.assistiveTechnologyAnnouncementTransport` to announce via `ariaNotify()` instead of the live region, in PR [#5962](https://github.com/microsoft/BotFramework-WebChat/pull/5962), by [@OEvgeny](https://github.com/OEvgeny)

__tests__/html2/accessibility/ariaNotify/adaptiveCard.inputValue.html

@@ -0,0 +1,129 @@
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <link href="/assets/index.css" rel="stylesheet" type="text/css" />
+    <!-- Shows the live region, so the snapshot shows the copy the announcements are computed from. -->
+    <link href="/assets/accessibility.liveRegionAttachment.css" rel="stylesheet" type="text/css" />
+  </head>
+  <body>
+    <main id="webchat"></main>
+    <script type="importmap">
+      {
+        "imports": {
+          "@testduet/wait-for": "https://esm.sh/@testduet/wait-for",
+          "botframework-webchat": "/__dist__/packages/bundle/static/botframework-webchat.js",
+          "botframework-webchat/": "/__dist__/packages/bundle/static/botframework-webchat/",
+          "jest-mock": "https://esm.sh/jest-mock",
+          "react": "/__dist__/packages/bundle/static/react.js",
+          "react-dom": "/__dist__/packages/bundle/static/react-dom.js",
+          "react-dom/client": "/__dist__/packages/bundle/static/react-dom/client.js"
+        }
+      }
+    </script>
+    <script type="module">
+      import '/test-harness.mjs';
+      import '/test-page-object.mjs';
+
+      import { waitFor } from '@testduet/wait-for';
+      import { createStoreWithOptions, ReactWebChat } from 'botframework-webchat';
+      import { spyOn } from 'jest-mock';
+      import { createElement } from 'react';
+      import { createRoot } from 'react-dom/client';
+
+      // TODO: This is for `createDirectLineEmulator` only, should find ways to eliminate this line.
+      window.WebChat = { createStoreWithOptions };
+
+      run(async function () {
+        // GIVEN: The browser supports `ariaNotify()`, recorded instead of announced.
+        const ariaNotify = spyOn(Element.prototype, 'ariaNotify').mockImplementation(() => {});
+
+        const { directLine, store } = testHelpers.createDirectLineEmulator();
+
+        // GIVEN: Web Chat sends announcements via `ariaNotify()`.
+        createRoot(document.getElementById('webchat')).render(
+          createElement(ReactWebChat, {
+            directLine,
+            store,
+            styleOptions: {
+              assistiveTechnologyAnnouncementTransport: 'aria-notify',
+              hideSendBox: true,
+              internalLiveRegionFadeAfter: 60000 // Would keep live region entries for 60 seconds, does not apply to `ariaNotify()`.
+            }
+          })
+        );
+
+        await pageConditions.uiConnected();
+
+        // The connectivity notification is announced first, see `message.html`.
+        await waitFor(() => expect(ariaNotify).toHaveBeenCalledTimes(1));
+        ariaNotify.mockClear();
+
+        // WHEN: The bot sends an Adaptive Card form with named and pre-filled inputs, as in `liveRegion/attachment/adaptiveCard.inputValue.html`.
+        await directLine.emulateIncomingActivity({
+          attachments: [
+            {
+              content: {
+                $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
+                actions: [{ title: 'Place order', type: 'Action.Submit' }],
+                body: [
+                  { id: 'name', label: 'Your name', type: 'Input.Text', value: 'Ada' },
+                  { id: 'quantity', label: 'Quantity', type: 'Input.Number', value: 3 },
+                  { id: 'date', label: 'Delivery date', type: 'Input.Date', value: '2026-10-20' },
+                  { id: 'note', placeholder: 'Add a note', type: 'Input.Text' }, // No label: the card names it by its placeholder.
+                  {
+                    choices: [
+                      { title: 'Red', value: 'red' },
+                      { title: 'Blue', value: 'blue' }
+                    ],
+                    id: 'color',
+                    label: 'Color',
+                    type: 'Input.ChoiceSet',
+                    value: 'blue'
+                  },
+                  { id: 'gift', title: 'Gift wrap', type: 'Input.Toggle', value: 'true' } // Equals the default "valueOn": checked.
+                ],
+                type: 'AdaptiveCard',
+                version: '1.5'
+              },
+              contentType: 'application/vnd.microsoft.card.adaptive'
+            }
+          ],
+          from: { role: 'bot' },
+          type: 'message'
+        });
+
+        await pageConditions.numActivitiesShown(1);
+
+        // THEN: The card is announced once, with every input of its live region copy read by name and value, then the button, followed by the note of the live region.
+        await waitFor(() =>
+          expect(ariaNotify.mock.calls).toEqual([
+            [
+              [
+                'Bot said',
+                'A card',
+                'Your name Ada',
+                'Quantity 3',
+                'Delivery date 2026-10-20',
+                'Add a note', // Empty: read by name only.
+                'Color Blue', // The title of the selected choice.
+                'Gift wrap', // Checkboxes are read by their label; "checked" is not read, it would need a localized word.
+                'Place order'
+              ].join(' '),
+              { priority: 'normal' }
+            ],
+            [
+              'Message is interactive. Press shift tab key 2 to 3 times to switch to the chat history. Then click on the message to interact.',
+              { priority: 'normal' }
+            ]
+          ])
+        );
+
+        // THEN: The live region is emptied right after announcing, without waiting 60 seconds: its copy of the card is only rendered to compute the text.
+        await waitFor(() => expect(pageElements.liveRegion().childElementCount).toBe(0));
+
+        // THEN: The live region (top) is empty, there is nothing for screen readers to read from it; the transcript shows the form.
+        await host.snapshot('local');
+      });
+    </script>
+  </body>
+</html>

__tests__/html2/accessibility/ariaNotify/heroCard.html

@@ -0,0 +1,108 @@
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <link href="/assets/index.css" rel="stylesheet" type="text/css" />
+    <!-- Shows the live region, so the snapshot shows the copy the announcements are computed from. -->
+    <link href="/assets/accessibility.liveRegionAttachment.css" rel="stylesheet" type="text/css" />
+  </head>
+  <body>
+    <main id="webchat"></main>
+    <script type="importmap">
+      {
+        "imports": {
+          "@testduet/wait-for": "https://esm.sh/@testduet/wait-for",
+          "botframework-webchat": "/__dist__/packages/bundle/static/botframework-webchat.js",
+          "botframework-webchat/": "/__dist__/packages/bundle/static/botframework-webchat/",
+          "jest-mock": "https://esm.sh/jest-mock",
+          "react": "/__dist__/packages/bundle/static/react.js",
+          "react-dom": "/__dist__/packages/bundle/static/react-dom.js",
+          "react-dom/client": "/__dist__/packages/bundle/static/react-dom/client.js"
+        }
+      }
+    </script>
+    <script type="module">
+      import '/test-harness.mjs';
+      import '/test-page-object.mjs';
+
+      import { waitFor } from '@testduet/wait-for';
+      import { createStoreWithOptions, ReactWebChat } from 'botframework-webchat';
+      import { spyOn } from 'jest-mock';
+      import { createElement } from 'react';
+      import { createRoot } from 'react-dom/client';
+
+      // TODO: This is for `createDirectLineEmulator` only, should find ways to eliminate this line.
+      window.WebChat = { createStoreWithOptions };
+
+      run(async function () {
+        // GIVEN: The browser supports `ariaNotify()`, recorded instead of announced.
+        const ariaNotify = spyOn(Element.prototype, 'ariaNotify').mockImplementation(() => {});
+
+        const { directLine, store } = testHelpers.createDirectLineEmulator();
+
+        // GIVEN: Web Chat sends announcements via `ariaNotify()`.
+        createRoot(document.getElementById('webchat')).render(
+          createElement(ReactWebChat, {
+            directLine,
+            store,
+            styleOptions: {
+              assistiveTechnologyAnnouncementTransport: 'aria-notify',
+              hideSendBox: true,
+              internalLiveRegionFadeAfter: 60000 // Would keep live region entries for 60 seconds, does not apply to `ariaNotify()`.
+            }
+          })
+        );
+
+        await pageConditions.uiConnected();
+
+        // The connectivity notification is announced first, see `message.html`.
+        await waitFor(() => expect(ariaNotify).toHaveBeenCalledTimes(1));
+        ariaNotify.mockClear();
+
+        // WHEN: The bot sends a hero card with an image and two buttons.
+        await directLine.emulateIncomingActivity({
+          attachments: [
+            {
+              content: {
+                buttons: [
+                  { title: 'Tomorrow', type: 'imBack', value: 'Tomorrow' },
+                  { title: 'Next week', type: 'imBack', value: 'Next week' }
+                ],
+                images: [{ alt: 'Bot avatar', url: '/assets/bot-avatar.jpg' }],
+                subtitle: 'Seattle',
+                text: 'Sunny, no umbrella needed.',
+                title: 'Weather today'
+              },
+              contentType: 'application/vnd.microsoft.card.hero'
+            }
+          ],
+          from: { role: 'bot' },
+          type: 'message'
+        });
+
+        await pageConditions.numActivitiesShown(1);
+        await pageConditions.allImagesLoaded();
+
+        // THEN: The card is announced once, with the alt text of the image and the buttons as separate words ("Tomorrow Next week", not "TomorrowNext week"), then its note.
+        await waitFor(() =>
+          expect(ariaNotify.mock.calls).toEqual([
+            [
+              'Bot said A card Weather today Seattle Sunny, no umbrella needed. Bot avatar Tomorrow Next week',
+              { priority: 'normal' }
+            ],
+            // The buttons make the message interactive.
+            [
+              'Message is interactive. Press shift tab key 2 to 3 times to switch to the chat history. Then click on the message to interact.',
+              { priority: 'normal' }
+            ]
+          ])
+        );
+
+        // THEN: The live region is emptied right after announcing, without waiting 60 seconds: its copy of the card is only rendered to compute the text.
+        await waitFor(() => expect(pageElements.liveRegion().childElementCount).toBe(0));
+
+        // THEN: The live region (top) is empty, there is nothing for screen readers to read from it; the transcript shows the hero card.
+        await host.snapshot('local');
+      });
+    </script>
+  </body>
+</html>

__tests__/html2/accessibility/ariaNotify/hostHidesLiveRegion.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <link href="/assets/index.css" rel="stylesheet" type="text/css" />
+    <style>
+      /* The host page hides the live region of Web Chat from everyone, including screen readers. */
+      .webchat__live-region {
+        display: none !important;
+      }
+    </style>
+  </head>
+  <body>
+    <main id="webchat"></main>
+    <script type="importmap">
+      {
+        "imports": {
+          "@testduet/wait-for": "https://esm.sh/@testduet/wait-for",
+          "botframework-webchat": "/__dist__/packages/bundle/static/botframework-webchat.js",
+          "botframework-webchat/": "/__dist__/packages/bundle/static/botframework-webchat/",
+          "jest-mock": "https://esm.sh/jest-mock",
+          "react": "/__dist__/packages/bundle/static/react.js",
+          "react-dom": "/__dist__/packages/bundle/static/react-dom.js",
+          "react-dom/client": "/__dist__/packages/bundle/static/react-dom/client.js"
+        }
+      }
+    </script>
+    <script type="module">
+      import '/test-harness.mjs';
+      import '/test-page-object.mjs';
+
+      import { waitFor } from '@testduet/wait-for';
+      import { createStoreWithOptions, ReactWebChat } from 'botframework-webchat';
+      import { spyOn } from 'jest-mock';
+      import { createElement } from 'react';
+      import { createRoot } from 'react-dom/client';
+
+      // TODO: This is for `createDirectLineEmulator` only, should find ways to eliminate this line.
+      window.WebChat = { createStoreWithOptions };
+
+      run(async function () {
+        // GIVEN: The browser supports `ariaNotify()`, recorded instead of announced.
+        const ariaNotify = spyOn(Element.prototype, 'ariaNotify').mockImplementation(() => {});
+
+        const { directLine, store } = testHelpers.createDirectLineEmulator();
+
+        // GIVEN: Web Chat sends announcements via `ariaNotify()`.
+        createRoot(document.getElementById('webchat')).render(
+          createElement(ReactWebChat, {
+            directLine,
+            store,
+            styleOptions: { assistiveTechnologyAnnouncementTransport: 'aria-notify', hideSendBox: true }
+          })
+        );
+
+        await pageConditions.uiConnected();
+
+        // WHEN: The bot sends a message.
+        await directLine.emulateIncomingActivity({
+          from: { role: 'bot' },
+          text: 'Hello, **World**!',
+          type: 'message'
+        });
+
+        await pageConditions.numActivitiesShown(1);
+
+        // THEN: The message is still announced, on the root element of Web Chat, which the host page did not hide.
+        await waitFor(() =>
+          expect(ariaNotify.mock.calls).toEqual([
+            ['connected', { priority: 'normal' }], // The connectivity notification, see `message.html`.
+            ['Bot said Hello, World!', { priority: 'normal' }]
+          ])
+        );
+        expect(ariaNotify.mock.contexts).toEqual([
+          document.querySelector('.webchat'),
+          document.querySelector('.webchat')
+        ]);
+
+        // THEN: The live region is not shown (hidden by the host page); the transcript shows the message.
+        await host.snapshot('local');
+      });
+    </script>
+  </body>
+</html>