Identify reusable code for speech-synthesis feature.

[pixelzoom]

number-pairs is currently not reusing anything from number-suite-common. And we probably need to keep it that way for now, due to PhET-iO support issues. But there is a lot of existing code related to the speech-synthesis feature that we should inspect, especially since the design is the same for number-pairs. Some code we might consider generalizing, adding PhET-iO support, and moving to common code. Other code we might be able to copy and improve.

Here's the existing code that's related to the speech synthesis feature. (This might not be a complete list.)

number-suite-common:

• LanguageAndVoiceControl - 2 carousels that replace the standard UI in Preferences > Localization
• SecondLanguageControl - ABSwitch and 1 carousel that appears in Preferences > Simulation
• AutoHearControl - ABSwitch that appears in Preferences > Audio
• NumberSuiteCommonSpeechSynthesisAnnouncer (extends utterance-queue.SpeechSynthesisAnnouncer)
• NumberSuiteCommonUtteranceQueue (abstract, extends utterance-queue.UtteranceQueue)
• NumberSuiteCommonPreferences
• SpeechSynthesisButton
• NoVoiceWarningButton
• NoVoiceWarningDialog

number-play:

• LocaleSwitch - ABSwitch between primary and secondary locale
• numberPlaySpeechSynthesisAnnouncer (instance of NumberSuiteCommonSpeechSynthesisAnnouncer, singleton)
• numberPlayUtteranceQueue (extends NumberSuiteCommonUtteranceQueue, singleton)
• numberPlayPreferences (singleton)

number-compare:

• numberCompareSpeechSynthesisAnnouncer (instance of NumberSuiteCommonSpeechSynthesisAnnouncer, singleton)
• numberCompareUtteranceQueue (extends NumberSuiteCommonUtteranceQueue, singleton)
• numberComparePreferences (singleton)

[pixelzoom]

LanguageAndVoiceControl and SecondLanguageControl were components that I thought would be good candiates to move to joist. But looking at their current implementations, they are tightly coupled to UtteranceQueue in general, and the NumberSuiteCommonUtteranceQueue subclass of UtteranceQueue in particular. So the first order of business will be to see if they can be decoupled.

[pixelzoom]

@marlitas and I will meet about this feature on Tue 12/3 @ 10:30 MT.

[pixelzoom]

Utterance queue is described at https://github.com/phetsims/phet-info/blob/main/doc/interactive-description-technical-guide.md#utterancequeue. For more about aria-live, see https://www.youtube.com/watch?v=BLlJRVyS2UM.

[pixelzoom]

@marlitas and I met, reviewed the state of code in number-suite-common, number-play, number-compare.

We discussed various options for implementing these features. Contrary to a previous decision, we decided that rather than copy code from number-suite-common, we will add it as a dependency and use the code directly.

Next steps:

@pixelzoom:

• Add number-suite-common (and its dependency counting-common) as dependencies in package.json and tsconfig.json.
• Create NumberPairsPreferences, ala GeomtricOpticsPreferences.
• Create singleton numberPairsSpeechSynthesisAnnouncer subclass of NumberSuiteCommonSpeechSynthesisAnnouncer.
• Create singleton numberPairsUtteranceQueue of NumberSuiteCommonUtteranceQueue.
• Figure out what allURL is in NumberSuiteCommonPreferences.
• Remove dependency on NumberSuiteCommonPreferences in SecondLanguageControl.
• Reuse LanguageAndVoiceControl.
• Reuse SecondLanguageControl.
• Reuse AutoHearControl.

@marlitas

• Switch over to NumberSuiteCommonStrings where possible.
• Reuse/copy SpeechSynthesisButton, NoVoiceWarningButton, and NoVoiceWarningDialog, and wire them up.
• Wire up the current "phrase" to the "Automatically Hear Phrase" control in Preferences > Audio.
• Check on how speech synthesis is expected to work with screen reader. (It looks like speech is addToBack of UtteranceQueue, so should occur after button is read.)

After the above, we can evaluate how to improve the implementation, whether to contribute back to the suite, etc.

[pixelzoom]

@marlitas and I reviewed my work on 12/10/24.

I'll look at adding PhET-iO instrumentation to NumberPairsPreferencesNode, AutoHearControl, SecondLanguageControl, and LanguageAndVoiceControl.

[pixelzoom]

In the above commits, I added basic PhET-iO instrumentation for the Preferences controls related to speech synthesis. The controls in number-suite-common default to tandem: Tandem.OPT_OUT, and number-pairs provides valid tandems.

[marlitas]

Implemented above. I'll send over to @pixelzoom for review, but other than that I think this is good to go.

I created and issue for Check on how speech synthesis is expected to work with screen reader.
#50

p.s. no rush on the review. I'm still parsing through the others.

[pixelzoom]

@marlitas reminder that in #22 (comment), we said:

After the above, we can evaluate how to improve the implementation, whether to contribute back to the suite, etc.

[marlitas]

Mmmm. thanks for that reminder. Okay. Well then let's maybe both review and create a list of suggestions. I do think this issue is nearing the end of it's original intention though.

[pixelzoom]

... I do think this issue is nearing the end of it's original intention though.

Agreed. And I'm OK if we decide that "improve the implementation" and/or "contribute back to the suite" is out of scope. I feel like I made some good improvements (eliminating dependencies) in the commits above.

[pixelzoom]

After the above, we can evaluate how to improve the implementation, whether to contribute back to the suite, etc.

@marlitas and I discussed. I spent 3+ hours this morning on #53, and I don't feel like I have more time to spend on improving number-suite-common. So we're it as is, maybe make a few improvements as we run into problems. We're not going to do anything proactively.

Closing.

[marlitas]

@pixelzoom and I discussed, and we believe this is now ready to close. We will address any improvements as bugs come up or as we interact with the code.