Announcer: Part 1 #2362

marcysutton · 2024-11-15T22:45:50Z

The initial implementation for a live region component! I'm getting this draft PR up so I can test with the remote URL.

Jira Issue: https://khanacademy.atlassian.net/browse/WB-1768

Outstanding questions/work areas:

Testing in more ATs, particularly in webapp and on mobile devices.
More integration with React: usage for JSX, debouncing with custom duration in continuously re-rendering components like the Video Player with Clarifications, etc.

changeset-bot · 2024-11-15T22:45:53Z

🦋 Changeset detected

Latest commit: 50f263b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@khanacademy/wonder-blocks-announcer	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2024-11-15T22:47:52Z

Size Change: +1.99 kB (+2.04%)

Total Size: 99.3 kB

Filename	Size	Change
`packages/wonder-blocks-announcer/dist/es/index.js`	1.99 kB	+1.99 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size
`packages/wonder-blocks-accordion/dist/es/index.js`	3.78 kB
`packages/wonder-blocks-banner/dist/es/index.js`	1.53 kB
`packages/wonder-blocks-birthday-picker/dist/es/index.js`	1.77 kB
`packages/wonder-blocks-breadcrumbs/dist/es/index.js`	887 B
`packages/wonder-blocks-button/dist/es/index.js`	4.04 kB
`packages/wonder-blocks-cell/dist/es/index.js`	2.01 kB
`packages/wonder-blocks-clickable/dist/es/index.js`	3.06 kB
`packages/wonder-blocks-core/dist/es/index.js`	3.48 kB
`packages/wonder-blocks-data/dist/es/index.js`	6.24 kB
`packages/wonder-blocks-dropdown/dist/es/index.js`	19.2 kB
`packages/wonder-blocks-form/dist/es/index.js`	6.28 kB
`packages/wonder-blocks-grid/dist/es/index.js`	1.36 kB
`packages/wonder-blocks-icon-button/dist/es/index.js`	2.95 kB
`packages/wonder-blocks-icon/dist/es/index.js`	871 B
`packages/wonder-blocks-labeled-field/dist/es/index.js`	72 B
`packages/wonder-blocks-layout/dist/es/index.js`	1.82 kB
`packages/wonder-blocks-link/dist/es/index.js`	2.28 kB
`packages/wonder-blocks-modal/dist/es/index.js`	5.43 kB
`packages/wonder-blocks-pill/dist/es/index.js`	1.65 kB
`packages/wonder-blocks-popover/dist/es/index.js`	4.87 kB
`packages/wonder-blocks-progress-spinner/dist/es/index.js`	1.52 kB
`packages/wonder-blocks-search-field/dist/es/index.js`	1.38 kB
`packages/wonder-blocks-switch/dist/es/index.js`	1.94 kB
`packages/wonder-blocks-testing-core/dist/es/index.js`	3.74 kB
`packages/wonder-blocks-testing/dist/es/index.js`	1.07 kB
`packages/wonder-blocks-theming/dist/es/index.js`	693 B
`packages/wonder-blocks-timing/dist/es/index.js`	1.8 kB
`packages/wonder-blocks-tokens/dist/es/index.js`	2.36 kB
`packages/wonder-blocks-toolbar/dist/es/index.js`	905 B
`packages/wonder-blocks-tooltip/dist/es/index.js`	7.08 kB
`packages/wonder-blocks-typography/dist/es/index.js`	1.23 kB

_{compressed-size-action}

github-actions · 2024-11-15T22:48:32Z

A new build was pushed to Chromatic! 🚀

https://5e1bf4b385e3fb0020b7073c-nlcjdakqus.chromatic.com/

Chromatic results:

Metric	Total
Captured snapshots	378
Tests with visual changes	1
Total stories	514
Inherited (not captured) snapshots [TurboSnap]	0
Tests on the build	378

khan-actions-bot · 2024-11-20T21:28:58Z

Gerald

Required Reviewers

@Khan/wonder-blocks for changes to .changeset/thirty-ducks-type.md, .storybook/preview.tsx, __docs__/wonder-blocks-announcer/announcer.stories.tsx, packages/wonder-blocks-announcer/package.json, packages/wonder-blocks-announcer/tsconfig-build.json, static/sb-styles/preview.css, packages/wonder-blocks-announcer/src/announce-message.ts, packages/wonder-blocks-announcer/src/announcer.ts, packages/wonder-blocks-announcer/src/clear-messages.ts, packages/wonder-blocks-announcer/src/index.ts, packages/wonder-blocks-announcer/types/announcer.types.ts, packages/wonder-blocks-announcer/src/__tests__/announce-message.test.tsx, packages/wonder-blocks-announcer/src/__tests__/announcer.test.ts, packages/wonder-blocks-announcer/src/__tests__/clear-messages.test.tsx, packages/wonder-blocks-announcer/src/util/dom.ts, packages/wonder-blocks-announcer/src/util/util.ts, packages/wonder-blocks-announcer/src/__tests__/components/announce-message-button.tsx, packages/wonder-blocks-announcer/src/__tests__/util/dom.test.ts, packages/wonder-blocks-announcer/src/__tests__/util/test-utilities.ts, packages/wonder-blocks-announcer/src/__tests__/util/util.test.ts

Don't want to be involved in this pull request? Comment #removeme and we won't notify you of further changes.

github-actions · 2024-11-20T21:29:39Z

npm Snapshot: Published

🎉 Good news!! We've packaged up the latest commit from this PR (ce3ccdd) and published all packages with changesets to npm.

You can install the packages in webapp by running:

./services/static/dev/tools/deploy_wonder_blocks.js --tag="PR2362"

Packages can also be installed manually by running:

yarn add @khanacademy/wonder-blocks-<package-name>@PR2362

jandrade

This is looking really good! Giving my initial review with some suggestions on how to structure the files to be more consistent with the rest of the repo and asking some questions to get a bit more context on certain parts. This is great progress 👏

packages/wonder-blocks-announcer/CHANGELOG.md

packages/wonder-blocks-announcer/src/components/send-message-button.tsx

packages/wonder-blocks-announcer/src/index.ts

jandrade · 2024-11-21T16:09:15Z

packages/wonder-blocks-announcer/src/index.ts

+        setTimeout(() => {
+            return announcer?.announce(message, level, removalDelay);
+        }, 100);


question: Is there a specific reason why we need to use this timeout? I wonder if there's another way to handle this case, but I don't think I have full context on that.

It was for Safari and VoiceOver, but I can play around with it again to see if we really need it.

Yes, this does seem important for Safari in particular! I made it configurable so it can be manipulated at runtime if necessary (especially for tests).

I ended up removing this with the move to async! It wasn't needed in my testing for Safari/Voiceover.

An initial timeout might still be needed to get reliable announcements! The async code does seem to be messing with Voiceover in both Chrome and Safari, especially on the first couple of messages. When I test in Storybook, polite messages are getting dropped almost entirely and only some assertive messages are making it through. So I'll figure out how to work it back in..probably in the announce method of the Announcer class. I hate to say it, but it might make sense to get rid of the double announcer element approach and simplify things.

I did some more testing and added the initial timeout back in for Safari. I also included an option to set the length to 0 so that tests can skip it and work properly. I kept the double announcer stuff in as there wasn't a compelling reason to remove when I tested it.

packages/wonder-blocks-announcer/src/index.ts

beaesguerra

Great work so far Marcy! Left some feedback and questions 😄

beaesguerra · 2024-11-22T17:13:20Z

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

+        timeoutDelay: {
+            control: "number",
+            type: "number",
+            description: "(milliseconds)",


I'm wondering if there's a way for us to use the function docs for the storybook docs! Normally we're able to get the prop docs automatically from setting component in this block, though this is different since these docs are for functions rather than components!

cc: @jandrade in case you have come across similar things before!

If there isn't a way to do this, it would be helpful to add a description for the different options so it shows up in the docs! This can help developers know when to use what level or when to use debounceThreshold. Same for documenting the clear-messages utility!

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

packages/wonder-blocks-announcer/src/send-message.ts

packages/wonder-blocks-announcer/types/Announcer.types.ts

packages/wonder-blocks-announcer/src/Announcer.ts

marcysutton · 2024-11-27T20:02:38Z

@jandrade @beaesguerra this is ready for another review! I added quite a few more tests. Yay!

In testing the debounce logic more thoroughly, I realized the first iteration was going to be unpredictable and hard to use. So I refactored it a bit. I'm currently debugging in ATs and working with Storybook though, as this might have broken things. 😬

Some code highlights:

I added a debounceThreshold parameter to allow callers to specify how long to wait before announcing another message. This is intended for repeatedly-rendering components like the ClarificationNotifications component for the video player which are re-rendered every 1/2 second. This seemed like a reasonable way to handle it without having to compare strings. (We might still need to do that so it's not annoying to screen reader users, but I want to try this approach first.)
The debounce function now returns the first message rather than the last, so it will be announced immediately (other implementations use the last callback rather than the first).
I got rid of the removalDelay parameter as it wasn't that useful to begin with, and it made the entire thing super confusing. Elements are still removed after a period time, I just changed it to not be configurable rather than trying to maintain removalDelay and debounceThreshold which both use setTimeouts.

The removalDelay is internally set to 5000 ms + the default debounce wait time of 250ms. If a custom debounceThreshold is passed in (say 2000ms), the internal removalDelay would updated to a longer duration for removal to avoid a race condition (2000ms + 5000ms).

My next steps are to test this more in webapp and see if it works as I expected!

packages/wonder-blocks-announcer/src/Announcer.ts

jandrade

Thanks for this new iteration. I'm adding some extra suggestions around the code (specially around tests). I'll keep digging into it and will integrate with the Combobox component. Thanks for all this progress!!

packages/wonder-blocks-announcer/src/Announcer.ts

jandrade · 2024-12-09T20:51:27Z

packages/wonder-blocks-announcer/src/Announcer.ts

+} from "./util/dom";
+import {alternateIndex, debounce} from "./util/util";
+
+const REMOVAL_TIMEOUT_DELAY = 5000;


question: Is there a specific reason why we have to wait for 5 seconds? do you think this would need to be configured by the consumer at some point?

It's admittedly a bit of a magic number... long enough to let the platform accessibility API read out a message of unknown length before it's removed, and also longer than the default initial timeout. Initially I made this configurable by the user but I removed the option due to added complexity to maintain.

idea: What if we determined the delay dynamically based on the number of words in the announcement multiplied by something like 500ms? That way long messages are accounted for! This might also account for translations that might be longer, though we would be assuming approximately how long each word is read!

It's an interesting thought. I'm hesitant to go that route as screen reader speech rates are configurable, so it's a moving target. Perhaps we could mark that down for a future improvement if it comes up in production?

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

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

packages/wonder-blocks-announcer/types/Announcer.types.ts

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

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

jandrade · 2024-12-10T20:32:11Z

packages/wonder-blocks-announcer/src/Announcer.ts

+        createDuplicateRegions(
+            aWrapper,
+            "assertive",
+            this.regionFactory.count,
+            this.dictionary,
+        );


thought: One thing that I noticed while playing with Storybook is that if I change the text in the Story and click the "submit" button, sometimes the announcement is not read by Voice Over. I'm not sure where to put this, but saw that sometimes was announced in one of the duplicate regions.

Hmm, that is odd. I noticed initial announcements aren't read if I change the politeness level to Assertive, but not for changing the text. The default Storybook frame also seems to impact reliability of messages, so I tend to test it in a standalone window. I think I'll opt for integration testing to observe these kinds of issues since I've spent so long on it already and the behavior is so inconsistent!

beaesguerra

Great progress Marcy! Left some questions and comments 😄

beaesguerra · 2024-12-11T21:49:44Z

packages/wonder-blocks-announcer/src/util/util.ts

+ * @param {number} wait Length of time to wait before calling callback again
+ * @returns {string} idRef of targeted live region element
+ */
+export function debounce(callback: (...args: any[]) => string, wait: number) {


I noticed we also have another debounce utility for dropdowns! The return type is a bit different though. No changes needed now but thought I'd mention it in case we want to consolidate utility functions across WB later on :)

Good call out! This one needs to return a promise with a string and a utility method for updating the wait time so it's pretty specific internally.

packages/wonder-blocks-announcer/src/clear-messages.ts

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

marcysutton · 2024-12-12T20:40:35Z

Alright, the debounce refactor is in! (it wasn't actually working when I tested it) I had to change it to allow a configurable debounce wait parameter with the simple announceMessage API. This means you can just call it with options without having to configure anything separately (helpful when it's being called in multiple places, so configurations don't interfere with each other).

@jandrade I also fixed that styling issue in Storybook that you were seeing with the Combobox. I added an addBodyClass decorator that can be used for anything...kind of a nice general improvement!

We don't need this yet!

1. Keeps announce from being called too frequently. We can play with the timeout duration. 2. Makes the returned IDREF more reliable in a browser.

D'oh!

1. Return first result and debounce subsequent calls within the debounceThreshold 2. Remove removalDelay parameter to simplify API 3. Put debounce utility into a separate file and add tests

Debounce wasn't actually limiting execution in the wait period. Now it does, and the debounce duration is still configurable when calling announceMessage!

I was trying to avoid having to import the Announcer in this test to keep things isolated, but it's so specific to the Announcer that I decided it didn't matter that much. Specifying the Announcer instance for the scope instead of generic thisArg logic simplified things quite a bit as well.

beaesguerra

This is looking great, I tested the story out with VoiceOver + Safari, NVDA + Chrome/Firefox and the message is announced as I expected! Thanks for your hard work on this!

I had a few suggestions around stories for other scenarios and documentation (non-blocking). I'm looking forward to seeing the announcer get used in context!

(Will let Juan be the final approver though since he may have feedback/insights on how it was integrating it with combobox!)

beaesguerra · 2024-12-19T23:17:29Z

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

+        timeoutDelay: {
+            control: "number",
+            type: "number",
+            description: "(milliseconds)",


If there isn't a way to do this, it would be helpful to add a description for the different options so it shows up in the docs! This can help developers know when to use what level or when to use debounceThreshold. Same for documenting the clear-messages utility!

beaesguerra · 2024-12-19T23:24:51Z

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

+    debounceThreshold,
+}: AnnounceMessageProps) => {
+    return (
+        <Button


(suggestion, no changes necessary) - I was curious about other scenarios that we could add to the story (or another story) so we can test different cases easily:

A button that triggers an announcement and another button that clears the specific announcement and/or all announcements

1 button that triggers a polite message, another button that triggers an assertive message to see the behaviour for different announcement levels

buttons with different debounceThreshold values to show how that option changes the behaviour

beaesguerra · 2024-12-20T00:11:34Z

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

+        message: "Here is some example text.",
+        level: "polite",
+    },
+};


We can disable this story for chromatic since we don't need visual regression tests for it! https://www.chromatic.com/docs/disable-snapshots/#with-storybook

jandrade · 2024-12-20T23:28:47Z

@marcysutton I've been testing the latest changes in Combobox and I'm still having some trouble announcing messages correctly when the dismiss/clear button is pressed.

The issue is that the button is pressed, the message is queued to be announced, but because the input[combobox] is focused again, then it causes the listbox to open and prioritizes the announcement for that (e.g. Expanded, completion selected). I'm attaching a screenshot here to illustrate this case:

Screen.Recording.2024-12-20.at.6.12.57.PM.mov

I'll try to put a new PR with my current progress.

marcysutton marked this pull request as ready for review November 20, 2024 21:28

khan-actions-bot requested a review from a team November 20, 2024 21:28

jandrade reviewed Nov 21, 2024

View reviewed changes

khan-actions-bot requested a review from a team November 22, 2024 17:28

beaesguerra reviewed Nov 22, 2024

View reviewed changes

khan-actions-bot requested a review from a team November 22, 2024 21:56

nishasy reviewed Dec 5, 2024

View reviewed changes

packages/wonder-blocks-announcer/src/Announcer.ts Outdated Show resolved Hide resolved

jandrade reviewed Dec 10, 2024

View reviewed changes

khan-actions-bot requested a review from a team December 10, 2024 22:36

beaesguerra reviewed Dec 11, 2024

View reviewed changes

khan-actions-bot requested a review from a team December 12, 2024 19:56

marcysutton added 12 commits December 12, 2024 14:09

Initial commit of Announcer

0d9daf9

WIP: append messages

737fdc5

Leverage React for tests

78f1208

Refactor to use dictionary

b3a31d4

Cleanup, move types, add comments

74ad711

Fix outdated param in story

0eb7de3

Put testing styles in Storybook preview.css

093c1c5

Remove console.log

4563523

Add working test for auto-removal of messages

d21b853

Added changeset

a613e12

Remove manually created changelog file

bcb7762

We don't need this yet!

Restructure files based on PR feedback

954feb5

marcysutton added 23 commits December 12, 2024 14:09

Expand tests

05018de

Make document check more consistent

925e1b7

Add comments, types, and a few more tests

4729428

Implement debounce / async logic

37ac932

1. Keeps announce from being called too frequently. We can play with the timeout duration. 2. Makes the returned IDREF more reliable in a browser.

Implement debounce / async logic

9927464

1. Keeps announce from being called too frequently. We can play with the timeout duration. 2. Makes the returned IDREF more reliable in a browser.

Get async tests working

cba83f9

Add missing test utility file

8526915

D'oh!

Update docs in Storybook for latest API changes

ea2d136

Firm up debounce logic

4b244e5

1. Return first result and debounce subsequent calls within the debounceThreshold 2. Remove removalDelay parameter to simplify API 3. Put debounce utility into a separate file and add tests

Clean up stray log and setTimeout testing approach

4702093

Add test file I somehow missed

0527a99

Suppress story artifacts from announcements

2db4a42

Add initial timeout back to help Safari/VO

8289cae

Fix typo in reattachment selector

91a9a19

Rename Announcer filenames to lowercase

9eac9b2

Remove console.log

76c06ff

Remove commented-out test code

c0e3d06

Update tests from review feedback

55f3ce3

Clean up WIP wonder-blocks-style code

fa29ada

Refactor debounce logic and tests

080ee31

Debounce wasn't actually limiting execution in the wait period. Now it does, and the debounce duration is still configurable when calling announceMessage!

Clean up storybook styling with custom body class

c44e59a

Update jsdoc comments for debounce utility

7e1912f

marcysutton force-pushed the announcer-pt1 branch from 4957581 to 7eacfef Compare December 12, 2024 22:09

marcysutton added 2 commits December 12, 2024 14:19

Allow node access for vanilla JS testing

b961200

Update dependencies for React 18

50f263b

marcysutton changed the base branch from announcer to main December 12, 2024 22:44

beaesguerra reviewed Dec 20, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Announcer: Part 1 #2362

Announcer: Part 1 #2362

marcysutton commented Nov 15, 2024 •

edited

Loading

changeset-bot bot commented Nov 15, 2024 •

edited

Loading

github-actions bot commented Nov 15, 2024 •

edited

Loading

github-actions bot commented Nov 15, 2024 •

edited

Loading

khan-actions-bot commented Nov 20, 2024 •

edited

Loading

github-actions bot commented Nov 20, 2024 •

edited

Loading

jandrade left a comment

jandrade Nov 21, 2024

marcysutton Nov 21, 2024

marcysutton Nov 22, 2024

marcysutton Nov 26, 2024

marcysutton Nov 27, 2024 •

edited

Loading

marcysutton Dec 12, 2024 •

edited

Loading

beaesguerra left a comment

beaesguerra Nov 22, 2024

beaesguerra Dec 19, 2024

marcysutton commented Nov 27, 2024 •

edited

Loading

jandrade left a comment

jandrade Dec 9, 2024

marcysutton Dec 10, 2024 •

edited

Loading

beaesguerra Dec 11, 2024

marcysutton Dec 12, 2024

jandrade Dec 10, 2024

marcysutton Dec 10, 2024 •

edited

Loading

beaesguerra left a comment

beaesguerra Dec 11, 2024

marcysutton Dec 12, 2024 •

edited

Loading

marcysutton commented Dec 12, 2024

beaesguerra left a comment

beaesguerra Dec 19, 2024

beaesguerra Dec 19, 2024

beaesguerra Dec 20, 2024

jandrade commented Dec 20, 2024

Announcer: Part 1 #2362

Are you sure you want to change the base?

Announcer: Part 1 #2362

Conversation

marcysutton commented Nov 15, 2024 • edited Loading

changeset-bot bot commented Nov 15, 2024 • edited Loading

🦋 Changeset detected

github-actions bot commented Nov 15, 2024 • edited Loading

github-actions bot commented Nov 15, 2024 • edited Loading

A new build was pushed to Chromatic! 🚀

Chromatic results:

khan-actions-bot commented Nov 20, 2024 • edited Loading

Gerald

github-actions bot commented Nov 20, 2024 • edited Loading

npm Snapshot: Published

jandrade left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton Nov 27, 2024 • edited Loading

Choose a reason for hiding this comment

marcysutton Dec 12, 2024 • edited Loading

Choose a reason for hiding this comment

beaesguerra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton commented Nov 27, 2024 • edited Loading

jandrade left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

beaesguerra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton Dec 12, 2024 • edited Loading

Choose a reason for hiding this comment

marcysutton commented Dec 12, 2024

beaesguerra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jandrade commented Dec 20, 2024

marcysutton commented Nov 15, 2024 •

edited

Loading

changeset-bot bot commented Nov 15, 2024 •

edited

Loading

github-actions bot commented Nov 15, 2024 •

edited

Loading

github-actions bot commented Nov 15, 2024 •

edited

Loading

khan-actions-bot commented Nov 20, 2024 •

edited

Loading

github-actions bot commented Nov 20, 2024 •

edited

Loading

marcysutton Nov 27, 2024 •

edited

Loading

marcysutton Dec 12, 2024 •

edited

Loading

marcysutton commented Nov 27, 2024 •

edited

Loading

marcysutton Dec 10, 2024 •

edited

Loading

marcysutton Dec 10, 2024 •

edited

Loading

marcysutton Dec 12, 2024 •

edited

Loading