Provide a higher-level API for specifying PDOM structure.

[pixelzoom]

Related to phetsims/models-of-the-hydrogen-atom#67 and #901, and as noted in #899 ...

This issue is relevant for sun, scenery-phet, and any other common-code UI components that rely on HTML tags that provide structure (<h3>, <p>, etc.)

For some UI components, description currently involves hard-coding specific structure-related tags in common-code components and/or in sim-specific code. For example in greenhouse-effect, see inner class ConcentrationControlModeRadioButtonGroup in GreenhouseGasConcentrationPanel.ts:

// pdom
labelTagName: 'h4',
labelContent: GreenhouseEffectStrings.a11y.concentrationPanel.experimentModeStringProperty,
helpText: GreenhouseEffectStrings.a11y.concentrationPanel.experimentModeHelpTextStringProperty,

According to https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML#text_content:

One of the best accessibility aids a screen reader user can have is an excellent content structure with headings, paragraphs, lists, etc.

So structure is important for screen readers. But using low-level HTML tags to specify structure, like labelTagName: 'h4', in high-level application code is a brittle solution, and a concern for both maintenance and reuse. It depends on knowledge that the play area and control area are 'h2'. It depends on knowlege about what headings other code has (parents, siblings). And it depends on knowledge of where the instance of the component appears in the PDOM relative to the play area and control area. Perhaps less of a concern, it makes it difficult to use the scenery feature that allows the same Node to appear in more than one place in the scene graph.

Having to drop down into HTML also seems contraty to the spirit of Scenery -- which provides developers with a higher-level API so that we don't need to write HTML/CSS.

[pixelzoom]

More thoughts about this...

The visual parts of the Scenery provide an API for creating a scenery graph. Scenery is then responsible for implementing that scene graph as HTML, and the programmer never needs to deal with the DOM directly.

Could a similar level of abstraction be provided for the description parts of Scenery? For example, specify the structure of the Accessibility Tree via a high-level API. Then let Scenery take care of the details of how that is implemented as low-level HTML structure in the PDOM.

This would be more consistent with the philosopy of Scenery. The programmer works with an API that is at a higher level of abstraction than HTML, and the details of how to create the HTML are handled internally by Scenery.

[pixelzoom]

@jessegreenberg and I discussed this issue. It's more work than the other //TODO description comments that appear in the MOTHA codebase. And once it's addressed, description behavior and presentation in A11y View will be unchanged. So we're comfortable with saying that this does not block MOTHA publication. And structure options (like tagName: 'h3') can be addressed later, when they are addressed in other sims.

[marlitas]

Meeting 11/13

• Implement a11y api for adding PDOM headings scenery#855 is connected to this issue.
• We want to look into scenery/855 first and then proceed with this issue.