Review Combobox.md file

[terracoda]

When there is time it would be good to review https://github.com/phetsims/sun/blob/master/doc/ComboBox.md in case it is useful to update any roles in light of updates the combobox design pattern outlined in ARIA 1.2

Our accessible combobox, which might actually be comboboxListBox, is not broken.

Reference: https://www.linkedin.com/pulse/aria-combobox-update-differences-between-11-12-design-bryan-garaventa/

I think our design pattern is already pretty close to the one in ARIA 1.2. It would just be good to double check.

[pixelzoom]

To clarify...

PhET's combo box is implemented in ComboBox.ts. It is composed of 2 subcomponents: ComboBoxButton.ts (tagName: 'button') and ComboBoxListBox.ts (ariaRole: 'listbox'). Pressing the button opens the listbox.

In general... The desired HTML ARIA tags are specified by providing options to PhET UI components in the TypeScript/JavaScript code, see ParallelDOMOptions in ParallelDOM.ts. When a PhET UI component is created in the code, its corresponding HTML is added to the PDOM.

[terracoda]

I've updated the Combox.md file. What would be helpful for me @pixelzoom, if you review the document and let me know if this is a hepful resource for devs.

For example,

• Is it helpful to have the standards information as part of our documentation?
• Is it helpful to have links to the standards documentation?
• Is it important to have HTML examples?
• I think the HTML is helpful for both devs and designers, but I am not actually sure.

[terracoda]

@pixelzoom, assigning you, but feel free to unassign and comment when you have time.

[pixelzoom]

I read through ComboBox.md and it looks reasonable to me. Very nice that it mentions the classes that make up the implementations.

That said... I'm not really up to speed on the intended purpose/scope of these .md files. They originated with the A11y team and have never really been used by those of us not on the A11y team. So perhaps you should also have one of the A11y developers review, and decide whether it meets the goals of the A11y team, and the needs of the PhET team as a whole.

[terracoda]

@pixelzoom, thanks for the review.

These documents were created in collaboration withe a few broader team members (not just the inclusive design team) to share the details of inclusive design interaction patterns for both developers and designers in one place.

They are used to populate the binder project, which if ever completed will/could serve as valuable public-facing design and development documentation.

I agree that adding the type script classes is helpful. I think that makes a nice clear connection that was missing.

Closing.

Please re-open if you have comments about the general nature of this documentation.