Build out support for high-level ParallelDOM APIs in common-code UI components.

[pixelzoom]

Related to https://github.com/phetsims/special-ops/issues/269 ...

This issue is relevant for sun, scenery-phet, and any other common-code UI components.

I discussed with @jessegreenberg, and ParallelDOM has two categories of API: low-level and high-level. From ParallelDOM.ts (where they are for some reason called "functions" when they are in fact options):

  /*
   * Higher Level API Functions
   */
  accessibleName?: PDOMValueType | null; // Sets the name of this node, read when this node receives focus and inserted appropriately based on accessibleNameBehavior
  accessibleNameBehavior?: PDOMBehaviorFunction; // Sets the way in which accessibleName will be set for the Node, see DEFAULT_ACCESSIBLE_NAME_BEHAVIOR for example
  helpText?: PDOMValueType | null; // Sets the descriptive content for this node, read by the virtual cursor, inserted into DOM appropriately based on helpTextBehavior
  helpTextBehavior?: PDOMBehaviorFunction; // Sets the way in which help text will be set for the Node, see DEFAULT_HELP_TEXT_BEHAVIOR for example
  pdomHeading?: PDOMValueType | null; // Sets content for the heading whose level will be automatically generated if specified
  pdomHeadingBehavior?: PDOMBehaviorFunction; // Set to modify default behavior for inserting pdomHeading string

  /*
   * Lower Level API Functions
   */
  containerTagName?: string | null; // Sets the tag name for an [optional] element that contains this Node's siblings
  containerAriaRole?: string | null; // Sets the ARIA role for the container parent DOM element

  innerContent?: PDOMValueType | null; // Sets the inner text or HTML for a node's primary sibling element
  inputType?: string | null; // Sets the input type for the primary sibling DOM element, only relevant if tagName is 'input'
  inputValue?: PDOMValueType | null | number; // Sets the input value for the primary sibling DOM element, only relevant if tagName is 'input'
  pdomChecked?: boolean; // Sets the 'checked' state for inputs of type 'radio' and 'checkbox'
  pdomNamespace?: string | null; // Sets the namespace for the primary element
  ariaLabel?: PDOMValueType | null; // Sets the value of the 'aria-label' attribute on the primary sibling of this Node
  ariaRole?: string | null; // Sets the ARIA role for the primary sibling of this Node
  ariaValueText?: PDOMValueType | null; // sets the aria-valuetext attribute of the primary sibling
  (...and many more low-level API options)

The intention/goal is that sim-specific code should be using the high-level API, while common-code UI components should provide the high-level API and convert that to the low-level API. But in practice:

• Support for the high-level APIs is spotty across PhET UI components.
• Low-level APIs have been used in sim-specific code to work around the lack of high-level API support.
• The distinction between low-level and high-level is not universally understood by PhET developers, probably because of the lack of documentation, pattern descriptions, exemplars, etc.

Towards the goal of making accessible names and help text part of the standard feature set, PhET will likely want to start by building out support for accessibleName and helpText. (Other description-related options should be kept in mind, but may be prioritized differently.) Related work includes:

• [ ] Build out support for the accessibleName and helpText options in common-code UI components.
• [ ] Identify and remove sim-specific workarounds that use low-level APIs.
• [ ] Where appropriate, exclude low-level options from the API of common-code UI components, to prevent use of those options and encourage use of the high-level APIs. For example, innerContent should not be settable by sublcasses of ButtonNode, because it is responsible for propagating accessibleName to the appropriate low-level options.
• [ ] Where appropriate, provide defaults for accessibleName and helpText. For example, instead of every sim adding accessibleName: 'Erase' to EraseButton, that should be the default, which can be overridden if needed.
• [ ] Revise or create binder documentation specific UI components in binder files, e.g. ComboBox.md. The documentation should be clear about the low-level internals of the component and the high-level API intended to be used in sim-specific code. (The current binder docs are not clear about this, and mostly focus on the internals.). Provide programming examples of how to use in sim-specific code.
• [ ] Create a quick-start guide for accessible names and help text, similar to the quick-start guide for alt input.

I will create GitHub issues for specific examples that were encountered while adding accessible name and help text to MOTHA for https://github.com/phetsims/models-of-the-hydrogen-atom/issues/67. Those issues will be linked to this issue, but should not be considered a complete list of what needs to be built out.

[pixelzoom]

Also for consideration...

Until support is implemented, exclude accessibleName and helpText options -- via the TypeScript Options types and/or via assertions.

All common-code components that have ParallelDOM as an ancestor currently include accessibleName and helpText as part of their API. This includes all scenery Nodes, and all common-code UI components. A small subset of these actually do anything with accessibleName and helpText, and the reset siliently ignore them. This makes it difficult to identify where accessibleName and helpText are actually supported, and where it still needs to be built out.

[terracoda]

Just adding a comment that it would be wonderful to have any default descriptions percolate to our live demos of sim components. I was talking to @jessegreenberg about this.