review and update ComboBox.md

[pixelzoom]

There have been many changes to ComboBox.js - #430, #314, #445,....

ComboBox.md needs to reviewed and possibility updated, especially the a11y sections.

[terracoda]

@zepumph, please assign to me if you need me to help with any changes to ComboBox.md.

I'm not sure our a11y markdown docks have a place in the document yet that would describe that the widget (e.g. ComboBox) is made up of several different things. I think we will need a place in the document that lists out what makes up a ComboBox (e.g., perhaps list out the things that are included in this comment #445 (comment))

By the way, nice work everyone, in particular @pixelzoom and @zepumph for making a robust ComboBox.

[pixelzoom]

@terracoda said:

I think we will need a place in the document that lists out what makes up a ComboBox ...

And it sounds like "what makes up a ComboBox" may be different for JavaScript vs PDOM. For example, ComboBox's JavaScript implementation is a container that manages a button and a list box that contains items. In the PDOM (currently), the button (not a "combo box") is the top-level thing, and the button has a list box.

To make things easier to understand, maintain,..., I think it's advantageous to keep the 2 representations as similar as possible. But as @zepumph explained to me, sometimes there will be superior representations that differ, and we want to have the flexibility to accommodate. And differences should be documented in the associated .md file.

In the case of ComboBox... I wasn't involved in the a11y design for ComboBox, so I don't know if different representations are warranted in this case. But we are using different representations, and it does take a little bit of work to understand the differences. Those differences (what they are, why,...) should be documented in ComboBox.md.

[terracoda]

@pixelzoom, I actually do explain in the ComboBox.md file why we created and used the HTML structure that we use. You can find a brief explanation in the Accessibility section and just above the HTML code.

What kind of guidance or explanation do you think developers need to better understand how to implement the design pattern?

In terms of user experience, the differences between a combobox and a button+listbox are quite subtle. The main differences will be for screen reader users due to how their AT reads out HTML structure. The actual keyboard interactions are almost identical if not identical to a combobox widget.

[pixelzoom]

Yep, I read the explanation in the Accessibility section. But unless you're familiar with the prototypical combo box, it's a bit of a leap to identify how PhET's JavaScript and PDOM differ from the prototype, and from each other.

It might be worth noting that the prototypical combo box includes a text box, which we have replaced with a display on the button. We omit the text box because PhET sims do not support text input. https://en.wikipedia.org/wiki/Combo_box has a good overview of the prototypical combo box.

The optional label to the left of the combo box is also a PhET addition (a "decorartion") to the prototypical combo box.

A few other things that need to be reviewed/revised in ComboBox.md:

• The rounded corners of the list should match the rounded corners of the button

... and the rounded corners on the pointer highlights for items in the listbox.

• Generally used with limited space and/or a long list of choices

But if the list of choices is too long, then ComboBox is an inappropriate choice. Different style guides have different recommendations on the max number of items. Java for example recommends <= 20.

• Can include an indicator image (to the left of the list item)

PhET's combo box doesn't include such an indicator. We highlight items in the list on pointer enter/exit.

• Generally, the list panel is often the same width as the button

Not the case in PhET's variation. The button has 2 areas, item area and arrow area, separated by a vertical separator. The listbox is the same width as the button's item area. For example:

Home & End keys

These are both indicated as being "Optional" and are currently not supported.

[terracoda]

@zepumph, have Home and End shortcut keys been implemented as an option for the accessible combobox?

While the documentation says they are optional, the documentation also says that these shortcuts are highly recommended for lists with more than 5 items.

Molarity's combobox list has 9 items. I am not sure if there was a decision to not support these shortcuts at all or if this it would be worked on at a later date.

I'll mark this as a meeting item.

[terracoda]

@zepumph, the combobox implementation in Molarity is working really well. If you think we should handle the Home and End keys in a new issue, just say so.

[terracoda]

@zepumph, I discussed with @emily-phet, and we would like to have Home and End shortcuts in the long term. And we will see how we can loop this in for Molarity depending on time needed for this feature.

[zepumph]

@zepumph, the combobox implementation in Molarity is working really well. If you think we should handle the Home and End keys in a new issue, just say so.

Sorry this issue was totally lost, this was implemented in #534. @terracoda is there anything else for this issue? I believe we can close.

[pixelzoom]

@terracoda could you please weigh in on whether there's anything else to do here? ComboBox has been done for quite awhile, and this GitHub issue is a "loose end" that needs to be tied up.

[terracoda]

Last I checked, the combobox was working fine in Molarity.
We just might revisit later if we want to make it behave differently on mobile. I think there is a different issue for that.

[terracoda]

And I will add, the combobox works nicely on mobile, but the popped up list stays open if nothing is selected and the user moves their cursor. This is not a barrier...just something to work out in a different issue.

I think this one can be closed if the review is all done.