[WB-1891]: Integrating Announcer into SingleSelect and MultiSelect

.changeset/clean-peas-prove.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-announcer": major
+---
+
+Introducing WB Announcer API for ARIA Live Regions

.changeset/plenty-crews-search.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-dropdown": minor
+---
+
+Integrates Announcer for value announcements in SingleSelect and MultiSelect

__docs__/wonder-blocks-announcer/announcer.stories.tsx

@@ -114,14 +114,4 @@ const styles = StyleSheet.create({
         alignItems: "center",
         justifyContent: "center",
     },
-    container: {
-        width: "100%",
-    },
-    narrowBanner: {
-        maxWidth: 400,
-    },
-    rightToLeft: {
-        width: "100%",
-        direction: "rtl",
-    },
 });

__docs__/wonder-blocks-dropdown/multi-select.accessibility.mdx

@@ -44,3 +44,18 @@ receives focus. This can be useful when the options contain icons or other infor
 that would need to be omitted from the visible label.
 
 <Canvas of={MultiSelectAccessibilityStories.UsingOpenerAriaLabel} />
+
+## Automatic screen reader announcements in `MultiSelect`
+
+`MultiSelect` uses the [Wonder Blocks Announcer](/?path=/docs/packages-announcer--docs)
+under the hood for content updates in screen readers, such as the number of items
+and the selected value.
+
+To observe the affect of the Announcer, you have a few options:
+
+1. Turn on a screen reader such as VoiceOver or NVDA while using the `MultiSelect`
+2. Inspect the DOM in the browser and look at the `#wbAnnounce` DIV element
+3. Look at the `With visible Announcer` story to see messages appended
+visually to the DOM
+
+<Canvas of={MultiSelectAccessibilityStories.WithVisibleAnnouncer} />

__docs__/wonder-blocks-dropdown/multi-select.accessibility.stories.tsx

@@ -1,9 +1,11 @@
 import * as React from "react";
 import magnifyingGlassIcon from "@phosphor-icons/core/regular/magnifying-glass.svg";
 import {OptionItem, MultiSelect} from "@khanacademy/wonder-blocks-dropdown";
+// import {initAnnouncer} from "@khanacademy/wonder-blocks-announcer";
 import {LabeledField} from "@khanacademy/wonder-blocks-labeled-field";
 import {View} from "@khanacademy/wonder-blocks-core";
 import {PhosphorIcon} from "@khanacademy/wonder-blocks-icon";
+import {allCountries} from "./option-item-examples";
 
 export default {
     title: "Packages / Dropdown / MultiSelect / Accessibility",
@@ -48,7 +50,7 @@ const MultiSelectAriaLabel = () => (
     <View>
         <MultiSelect
             aria-label="Class options"
-            id="unique-single-select"
+            id="unique-multi-select"
             selectedValues={["one"]}
             onChange={() => {}}
         >
@@ -129,3 +131,42 @@ export const UsingCustomOpenerAriaLabel = {
     render: MultiSelectCustomOpenerLabel.bind({}),
     name: "Using aria-label on custom opener",
 };
+
+const optionItems = allCountries.map(([code, translatedName]) => (
+    <OptionItem key={code} value={code} label={translatedName} />
+));
+
+const MultiSelectWithVisibleAnnouncer = () => {
+    // React.useEffect(() => {
+    //     // Inject Announcer into the Storybook iframe instead of body
+    //     const storybookRoot = document.getElementById("storybook-docs");
+    //     if (storybookRoot) {
+    //         console.log("announcer init");
+    //         // initAnnouncer({targetNode: storybookRoot});
+    //     }
+    // }, []);
+    const [selectedValues, setSelectedValues] = React.useState<Array<string>>(
+        [],
+    );
+    return (
+        <View>
+            <MultiSelect
+                aria-label="Country"
+                onChange={setSelectedValues}
+                isFilterable={true}
+                selectedValues={selectedValues}
+            >
+                {optionItems}
+            </MultiSelect>
+        </View>
+    );
+};
+
+export const WithVisibleAnnouncer = {
+    render: MultiSelectWithVisibleAnnouncer.bind({}),
+    name: "With visible Announcer",
+    parameters: {
+        addBodyClass: "showAnnouncer",
+        chromatic: {disableSnapshot: true},
+    },
+};

__docs__/wonder-blocks-dropdown/single-select.accessibility.mdx

@@ -49,3 +49,18 @@ receives focus. This can be useful when the options contain icons or other infor
 that would need to be omitted from the visible label.
 
 <Canvas of={SingleSelectAccessibilityStories.UsingOpenerAriaLabel} />
+
+## Automatic screen reader announcements in `SingleSelect`
+
+`SingleSelect` uses the [Wonder Blocks Announcer](/?path=/docs/packages-announcer--docs)
+under the hood for content updates in screen readers, such as the number of items
+and the selected value.
+
+To observe the affect of the Announcer, you have a few options:
+
+1. Turn on a screen reader such as VoiceOver or NVDA while using the `SingleSelect`
+2. Inspect the DOM in the browser and look at the `wbAnnounce` DIV element
+3. Look at the `With visible Announcer` story to see messages appended
+visually to the DOM
+
+<Canvas of={SingleSelectAccessibilityStories.WithVisibleAnnouncer} />

__docs__/wonder-blocks-dropdown/single-select.accessibility.stories.tsx

@@ -1,9 +1,11 @@
 import * as React from "react";
 import caretDown from "@phosphor-icons/core/regular/caret-down.svg";
 import {OptionItem, SingleSelect} from "@khanacademy/wonder-blocks-dropdown";
+// import {initAnnouncer} from "@khanacademy/wonder-blocks-announcer";
 import {View} from "@khanacademy/wonder-blocks-core";
 import {LabeledField} from "@khanacademy/wonder-blocks-labeled-field";
 import {PhosphorIcon} from "@khanacademy/wonder-blocks-icon";
+import {allCountries} from "./option-item-examples";
 
 export default {
     title: "Packages / Dropdown / SingleSelect / Accessibility",
@@ -130,6 +132,44 @@ export const UsingCustomOpenerAriaLabel = {
     name: "Using aria-label on custom opener",
 };
 
+const optionItems = allCountries.map(([code, translatedName]) => (
+    <OptionItem key={code} value={code} label={translatedName} />
+));
+
+const SingleSelectWithVisibleAnnouncer = () => {
+    // React.useEffect(() => {
+    //     // Inject Announcer into the Storybook iframe instead of body
+    //     const storybookRoot = document.getElementById("storybook-docs");
+    //     if (storybookRoot) {
+    //         console.log("announcer init");
+    //         initAnnouncer({targetNode: storybookRoot});
+    //     }
+    // }, []);
+    const [selectedValue, setSelectedValue] = React.useState("");
+    return (
+        <View>
+            <SingleSelect
+                aria-label="Country"
+                onChange={setSelectedValue}
+                isFilterable={true}
+                placeholder="Select a country"
+                selectedValue={selectedValue}
+            >
+                {optionItems}
+            </SingleSelect>
+        </View>
+    );
+};
+
+export const WithVisibleAnnouncer = {
+    render: SingleSelectWithVisibleAnnouncer.bind({}),
+    name: "With visible Announcer",
+    parameters: {
+        addBodyClass: "showAnnouncer",
+        chromatic: {disableSnapshot: true},
+    },
+};
+
 // This story exists for debugging automated unit tests.
 const SingleSelectKeyboardSelection = () => {
     const [selectedValue, setSelectedValue] = React.useState("");

packages/wonder-blocks-announcer/package.json

@@ -23,5 +23,6 @@
     "react": "18.2.0"
   },
   "devDependencies": {
+    "@khanacademy/wb-dev-build-settings": "workspace:*"
   }
 }

packages/wonder-blocks-announcer/src/__tests__/announce-message.test.tsx

@@ -19,15 +19,15 @@ describe("Announcer.announceMessage", () => {
         const message1 = "One Fish Two Fish";
 
         // ACT
-        const announcement1Id = await announceMessage({
+        const announcement1Id = announceMessage({
             message: message1,
             initialTimeout: 0,
             debounceThreshold: 0,
         });
         jest.advanceTimersByTime(500);
 
         // ASSERT
-        expect(announcement1Id).toBe("wbARegion-polite1");
+        await expect(announcement1Id).resolves.toBe("wbARegion-polite1");
     });
 
     test("creates the live region elements when called", () => {
@@ -144,7 +144,7 @@ describe("Announcer.announceMessage", () => {
     test("removes messages after a length of time", async () => {
         const message1 = "A Thing";
 
-        // default timeout is 5000ms + 250ms (removalDelay + debounceThreshold)
+        // default debounced content timeout is 5000ms + 250ms (removalDelay + debounceThreshold)
         render(
             <AnnounceMessageButton message={message1} debounceThreshold={1} />,
         );
@@ -158,8 +158,10 @@ describe("Announcer.announceMessage", () => {
         jest.advanceTimersByTime(500);
         expect(message1Region).toHaveTextContent(message1);
 
+        // This functional setTimeout (2) for the debounce comes after an initialTimeout
+        // for Safari/VO in the announceMessage function (1).
         expect(setTimeout).toHaveBeenNthCalledWith(
-            1,
+            2,
             expect.any(Function),
             5250,
         );

packages/wonder-blocks-announcer/src/__tests__/announcer.test.ts

@@ -161,6 +161,7 @@ describe("Announcer class", () => {
             const waitThreshold = 1000;
 
             // Act
+            // The second call will win out in the trailing edge implementation
             announcer.announce("a thing", "polite", waitThreshold);
             announcer.announce("two things", "polite", waitThreshold);
 
@@ -173,7 +174,7 @@ describe("Announcer class", () => {
                 announcer.dictionary.get(`wbARegion-polite0`)?.element;
 
             // ASSERT
-            await expect(targetElement?.textContent).toBe("a thing");
+            await expect(targetElement?.textContent).toBe("two things");
             await expect(targetElement2?.textContent).toBe("");
         });
     });
@@ -206,16 +207,12 @@ describe("Announcer class", () => {
             // Act
             announcer.announce("One Fish", "polite", 0);
             jest.advanceTimersByTime(5);
-            announcer.announce("Loud Fish", "assertive", 0);
-
             expect(screen.getByText("One Fish")).toBeInTheDocument();
-            expect(screen.getByText("Loud Fish")).toBeInTheDocument();
 
             announcer.clear();
 
             // Assert
             expect(screen.queryByText("One Fish")).not.toBeInTheDocument();
-            expect(screen.queryByText("Loud Fish")).not.toBeInTheDocument();
         });
 
         test("handling calls when nothing has been announced", () => {

packages/wonder-blocks-announcer/src/__tests__/clear-messages.test.tsx

@@ -2,39 +2,46 @@ import {screen, waitFor} from "@testing-library/react";
 import {announceMessage} from "../announce-message";
 import {clearMessages} from "../clear-messages";
 
-jest.useFakeTimers();
-
 describe("Announcer.clearMessages", () => {
+    beforeAll(() => {
+        jest.useFakeTimers();
+    });
+    afterAll(() => {
+        jest.useRealTimers();
+    });
     test("empties a targeted live region element by IDREF", async () => {
         // ARRANGE
         const message1 = "Shine a million stars";
         const message2 = "Dull no stars";
 
         // ACT
-        const announcement1Id = await announceMessage({
+        const announcement1IdPromise = announceMessage({
             message: message1,
             initialTimeout: 0,
             debounceThreshold: 0,
         });
+        jest.advanceTimersByTime(0);
+        await Promise.resolve();
 
         const region1 = screen.getByTestId("wbARegion-polite1");
 
-        jest.advanceTimersByTime(250);
+        const announcement1Id = await announcement1IdPromise;
 
-        await waitFor(() => {
-            expect(region1).toHaveTextContent(message1);
-        });
+        jest.advanceTimersByTime(0);
+        await Promise.resolve();
 
-        await announceMessage({
+        expect(region1).toHaveTextContent(message1);
+        clearMessages(announcement1Id);
+
+        announceMessage({
             message: message2,
             initialTimeout: 0,
             debounceThreshold: 0,
         });
 
         const region2 = screen.getByTestId("wbARegion-polite0");
 
-        jest.advanceTimersByTime(250);
-        clearMessages(announcement1Id);
+        jest.advanceTimersByTime(0);
 
         // ASSERT
         await waitFor(() => {
@@ -49,7 +56,7 @@ describe("Announcer.clearMessages", () => {
         const message2 = "Red fish blue fish";
 
         // ACT
-        await announceMessage({
+        announceMessage({
             message: message1,
             initialTimeout: 0,
             debounceThreshold: 0,
@@ -60,7 +67,7 @@ describe("Announcer.clearMessages", () => {
         const region1 = screen.queryByTestId("wbARegion-polite1");
         expect(region1).toHaveTextContent(message1);
 
-        await announceMessage({
+        announceMessage({
             message: message2,
             initialTimeout: 0,
             debounceThreshold: 0,
@@ -69,7 +76,7 @@ describe("Announcer.clearMessages", () => {
         const region2 = screen.getByTestId("wbARegion-polite0");
         expect(region2).toHaveTextContent(message2);
 
-        await announceMessage({
+        announceMessage({
             message: message1,
             level: "assertive",
             initialTimeout: 0,

packages/wonder-blocks-announcer/src/__tests__/init-announcer.test.tsx

@@ -0,0 +1,30 @@
+import {screen} from "@testing-library/react";
+import Announcer from "../announcer";
+import {initAnnouncer} from "../init-announcer";
+import {announceMessage} from "../announce-message";
+
+describe("Announcer.initAnnouncer", () => {
+    let announcer: Announcer;
+    afterEach(() => {
+        announcer.reset();
+    });
+
+    it("injects the Announcer when called", () => {
+        // Arrange
+        announcer = initAnnouncer();
+        // Act
+        const regionWrapper = screen.getByTestId("wbAnnounce");
+        // Assert
+        expect(regionWrapper).toBeInTheDocument();
+    });
+
+    it("only injects one Announcer", () => {
+        // Arrange
+        announcer = initAnnouncer();
+        announceMessage({message: "A thing"});
+        // Act
+        const regionWrapper = screen.getAllByTestId("wbAnnounce");
+        // Assert
+        expect(regionWrapper.length).toEqual(1);
+    });
+});

packages/wonder-blocks-announcer/src/__tests__/util/dom.test.ts

@@ -5,7 +5,7 @@ import {
     createRegion,
     removeMessage,
 } from "../../util/dom";
-import {PolitenessLevel} from "../../../types/announcer.types";
+import {type PolitenessLevel} from "../../util/announcer.types";
 
 jest.useFakeTimers();
 jest.spyOn(global, "setTimeout");

packages/wonder-blocks-announcer/src/__tests__/util/test-utilities.ts

@@ -1,4 +1,4 @@
-import type {RegionDef, PolitenessLevel} from "../../../types/announcer.types";
+import type {RegionDef, PolitenessLevel} from "../../util/announcer.types";
 
 export function createTestRegionList(
     level: PolitenessLevel,