ParallelDOM: New high level API for descriptive text

[kathy-phet]

When an accordian box contains a complex node that isn't available in the pdom, we should be able to put a descriptive paragraph there in the pdom - similar to the way alt-text is used for images.

[kathy-phet]

Example of where this would be used, if available, is in MOTHA electron levels:

phetsims/models-of-the-hydrogen-atom#85

[jessegreenberg]

I don't think we should add options to AccordionBox (and other content containers) for this. I think that the "alt-text" content should be implemented on the content Node of the AccordionBox.

With the low level API, that looks something like

energyLevelDiagram.tagName = 'p';
energyLevelDiagram.innerContent = 'This is a description of the energy level diagram...';

More broadly, we should think about the high level API for this for any Node. We could keep using accessibleName

energyLevelDiagram.accessibleName = 'This is a description of the energy level diagram...';

Or maybe we will create something new

energyLevelDiagram.altText = 'This is a description of the energy level diagram...';

I don't see a scenery issue for deciding on the high level API for non-interactive content. I would like to create that in scenery and close this issue. @kathy-phet is that OK with you?

[kathy-phet]

Making an issue in scenery for the high level API that can serve this type of function sounds good, thanks! accessiblename doesn’t match the goal of providing a longer description (could be multiple sentences) of what is visible in the node. I like the api name you suggested. Discussion can continue over in the scenery issue.

…

________________________________ From: Jesse Greenberg ***@***.***> Sent: Thursday, November 14, 2024 1:27:21 PM To: phetsims/sun ***@***.***> Cc: Kathy Perkins ***@***.***>; Assign ***@***.***> Subject: Re: [phetsims/sun] Accordian Box: Add API for passing descriptive paragraph (Issue phetsims/scenery#1673) [External email - use caution] Assigned phetsims/scenery#1673<#1673> to @kathy-phet<https://github.com/kathy-phet>. — Reply to this email directly, view it on GitHub<#1673>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ABG4KZEOMGZ4P5K3LTFEIHT2AUBSTAVCNFSM6AAAAABRZQZ7XKVHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJVGMYDIMBTGYZTINY>. You are receiving this because you were assigned.Message ID: ***@***.***>

[kathy-phet]

Maybe you could just transfer this issue and re-title it.

[jessegreenberg]

Sounds great. The issue has been transferred and I updated the title to reflect this idea.

[terracoda]

I think we need to approach how we refer to this kind of description (essentially a Static State description) differently, and understand that the description may need more structure than just a paragraph. See Molecules and Light's Light Spectrum Diagram as a good example. This diagram is implemented in an non-modal dialog, but it could exist in an accordion box, or in a modal dialog.

I think we could be general and just call it a "description" or an "accessibleDescription", and the API needs to offer document structures in addition to a paragraph.

Could "accessibleDescription" be the higher-level API, defaulting to a paragraph, but offering devs an easy way to add document structures for all sorts of descriptions. It would be the responsibility of the description designer to indicate what structures are needed for a complex description like in the case of the Energy Spectrum Diagram.

[terracoda]

I think this Buoyancy commit is related to making additional information and/or RichText accessible. Important sim content that is outside of names and help text.

https://github.com/phetsims/density-buoyancy-common/blob/6ba45b6a5fdbece5cba9590f520571a529697b35/js/buoyancy/view/ReadoutListAccordionBox.ts#L127-L130

[kathy-phet]

Yes, seems useful for @jessegreenberg to look at. Perhaps this provides ideas about an higher level optional API piece for RichText in general?

[terracoda]

This same kind of text (technically dynamic state descriptions) is also in the Values accordion box in Trig Tour

We want it to be straightforward to make screen text accessible. For the Voicing feature, this non-interactive but still dynamic on-screen text would need to be made into reading blocks in order to be voiced.

[jessegreenberg]

I think this Buoyancy commit is related to making additional information and/or RichText accessible. Important sim content that is outside of names and help text.

That is an example of the low level API, using tagName and innerContent. I thought we wanted something that was more high level than that - like a single option we could use for all Nodes for "descriptive text", that is neither "accessible name" or "help text".