Clean up displayed and accessible text for ComboBoxKeyboardHelpSection

[terracoda]

We noticed in Gas Properties that the default language for the ComboBox Keyboard Help dialog content is a little wordy and inconsistent, so we want to clean it up.

[terracoda]

Pop Up Menu / Options Menu??

1. Open options menu [Space] or [Enter] OR just Open options menu [Space] or [Enter]
2. Move through options [Up][Down]
3. Choose option [Enter]
4. Close without changing [Esc]

How's this @arouinfar?

1. What do you think of "Options Menu" rather than "Pop Up Menu" since these comboboxes often "drop down" as well as "pop up"?
2. What do you think is best for the first step? Include or exclude "menu"?

We also kicked around the idea of a brief Basic Actions one-liner for crowded dialogs. I am not sure how it would look in the dialog, but here is one line of brief content.

• Open options, then move through and choose [Space] or [Enter], [Up][Down], [Enter]

Here's our original customized combobox example from Molarity:

Could be changed to: Change Solute

1. Open solutes [Space] or [Enter] OR "Open solutes options"
2. Move through solutes [Up][Down]
3. Choose solute [Enter]
4. Close without changing [Esc]

[terracoda]

Assigning to @arouinfar for feedback, and tagging @jessegreenberg and @pixelzoom since we just discussed this for Gas Properties.

[terracoda]

@arouinfar, if you think this is good, please assign to @jessegreenberg for implementation.

[pixelzoom]

Open solutes [Space] or [Enter] OR "Open solutes options"

How about "Show solute choices" ?

[terracoda]

Oh, I like that. I like avoiding techy words like "options".

[terracoda]

Possible new default ComboBoxKeyboardHelpSection

Pop Up Menu / or customize like Change X??

1. Show choices [Space] or [Enter] OR just Open options menu [Space] or [Enter]
2. Move through choices [Up][Down]
3. Change choice [Enter]
4. Close without changing [Esc]

@pixelzoom, what do you think of this for default ComboBox language?

Then Molarity could read like this: Change Solute

1. Show solute choices [Space] or [Enter] OR "Show solutes"
2. Move through solutes [Up][Down]
3. Change solute [Enter]
4. Close without changing [Esc]

[pixelzoom]

I like the default you've suggested for ComboBox.

I even think the default is good enough that customizing only the title may work. For example:

Change Solute

1. Show choices [Space] or [Enter] OR "Show solutes"
2. Move through choices [Up][Down]
3. Change choice [Enter]
4. Close without changing [Esc]

This would put less burden on developers and translators. The current API for customing requires specifying a title ("Change Solute"), singular form ("solute"), and plural form ("solutes"). It would be nice if we didn't need to incur that cost.

[terracoda]

@pixelzoom, I agree that using a customized title combined with the word "choices" in the list is quite generalizable. I agree that the following could work for Molarity

Change Solute

1. Show choices [Space] or [Enter]
2. Move through choices [Up][Down]
3. Change choice [Enter]
4. Close without changing [Esc]

[arouinfar]

Thanks for iterating on this @terracoda @pixelzoom. I really like the generalized "choice(s)" text and suggested defaults. Customizing the title will provide the necessary context on a sim-by-sim basis.

I think we're ready to update the implementation, so over to @jessegreenberg.

[terracoda]

I just need to add the accessible content. It should be easy.

[terracoda]

Change Solute

1. Show choices with Space or Enter keys.
2. Move through choices with Up and Down arrow keys.
3. Change choice with Enter key.
4. Close without changing with Escape key.

So, except for the heading, the generic version is the same.

Change X or Show Choices

1. Show choices with Space or Enter keys.
2. Move through choices with Up and Down arrow keys.
3. Change choice with Enter key.
4. Close without changing with Escape key.

I am not sure what the default/generic heading should be. I think "Show Choices" is better than "Pop Open Menu".

[jessegreenberg]

I changed the strings in the above commit. Since these are translatable, I had to choose how to make the change. I asked for help on the developer channel:

``` Jesse Greenberg I need to change a couple of common code strings. For example, these: "keyboardHelpDialog.comboBox.options": { "value": "options" }, "keyboardHelpDialog.comboBox.option": { "value": "option" }, need to change from 'options'/'option' to 'choices'/'choice'. Should I just change the English value? Or should I add new keys? (edited) Marla Schulz :spiral_calendar_pad: 2 hours ago If we want to keep translations I know changing the keys can be a bit complex and tedious… not sure how devs feel about keys not matching values though… for common code strings it seems more important for them to match. This is the doc @jbphet created on how to change string keys and preserve translations. https://github.com/phetsims/rosetta/blob/main/doc/how-to-change-a-string-key.md Jesse Greenberg I see, thanks. Based on that document it sounds like I should either change the string value or leave the existing keys/values unchanged and add new ones. (edited) Michael Kauzmann It is definitely best to never change common code string keys that exist in published sims. ```

And decided to update the values in the strings file without changing the keys (requires significant work) or creating new key value pairs (means we would have unused key value pairs in the strings file.

@terracoda said:

I am not sure what the default/generic heading should be. I think "Show Choices" is better than "Pop Open Menu".

I made it so that the visual string and PDOM heading share the same string. @terracoda can you please review?

[terracoda]

Sorry, for my confusion @jessegreenberg. This is a long issue now.

I didn't have a final confirmation of the title text from @arouinfar , but I think the following options for a default capture the spirit - note the I changed "Show Choices" to "Change Choice" in the heading.

The idea is that designers can substitute "X" or "Choice" with a word relevant to the sim. Also, a learner is selecting one thing from a list of choices, so the word in the title is singular.

When there is more than one combobox present on a screen or in a sim, the heading can be generalized to something more generic, "Change Choice" or something else.

Here's the visual and A11y versions for implementation:

Change X or Change Choice

1. Show choices [[Space]] or [[Enter]]
2. Move through choices [[Up]] and [[Down]]
3. Change choice [[Enter]]

4. Close without changing [[Escape]]

   Change X or Change Choice

5. Show choices with Space or Enter keys.
6. Move through choices with Up and Down arrow keys.
7. Change choice with Enter key.
8. Close without changing with Escape key.

[jessegreenberg]

Great, thanks @terracoda! Here is what the visual and PDOM content looks like now, matching the above comment. Closing.