Problem with description for Electron Energy Level accordion box.

[pixelzoom]

From #67 (comment):

@pixelzoom , I hear "Electron Energy Levels, empty region," after the help text. Is that intentional or because the component not yet complete? I hear it even when the accordion is collapsed. Maybe need a new issue?

[pixelzoom]

It's not because the component is incomplete, because the design did not specify any description related to the content. And I have no idea what is saying "Electron Energy Levels, empty region".

@terracoda what did you expect to hear?

If you're not familiar with what will be displayed in this accordion box, please run the Java version at https://phet.colorado.edu/en/simulations/hydrogen-atom. Select any of the 3 quantum models (Bohr, de Broglie, Schrodinger), then check the "Show electron energy level" checkbox. Note that what's shown in the accordion box varies because the representation of "energy level" is specific to the selected model.

[pixelzoom]

I reviewed AccordionBox.md for clues, but I don't see anything relevant.

[terracoda]

I don't expect to hear "Empty region." I think that might mean there is an empty region element in the PDOM. I would expect to just hear, "Electron Energy Level, collapsed" or "Electron Energy Level, expanded"

[pixelzoom]

@jessegreenberg Since you recently made description improvements for AccordionBox (phetsims/sun#902), do you have thoughts on what might be going on here?

[kathy-phet]

@jessegreenberg @terracoda - Note, I do not hear "empty region" on NVDA / Windows. Description sounds OK. Says expanded and collapsed.

[pixelzoom]

11/7/24 design meeting: @DianaTavares @arouinfar @kathy-phet @terracoda @LindaStegemann @ariel-phet @KatieWoe @pixelzoom

@jessegreenberg will investigate. @terracoda is on macOS 14.5 + VoiceOver.

[Nancy-Salpepi]

I also don't hear "empty region" with macOS 15.0.1 + safari 18.0.1 + VO.

EDIT:
These were my original steps:

1. With VO on --tab to the Electron Energy Level accordion panel:

2. Use VO keys + right arrow to hear help text (down arrow doesn't do anything for me)

3. Press tab to get to next control

I can get "empty region" if I press VO keys + right arrow a second time (after step 2). This happens if the panel is expanded or not expanded, but I don't see why I would press those keys a second time.

[terracoda]

I am using Safari on MacOS 14.5

I have to press the down arrow and read with the virtual cursor to hear "empty region."
I only hear it if the panel is collapsed or if there is no accessible content or interactions present in the expanded panel, this is the case for MotHA.

In Ratio and Proportion, I hear "My Challenge, collapsed, button", on focus.

Then I hear, "My Challenge, empty, region" when I hit the down arrow and the state is collapsed.

I don't hear "empty, region" if it expanded, but I do hear when I leave the region when it is expanded.

This all makes sense. The panel is recognized as a region by VoiceOver. I am not sure if it has an explicit role of region, or if the role is implicit and dependent on the screen reader.

Regardless, to solve the issue, which I found surprising for the Electron Energy Level accordion box is to provide some content in the accordion panel when the accordion is expanded. Currently, the sims says "under construction" which is why I asked if the component was incomplete.

I don't know what will be in the panel, but a brief static description of what will be in the panel will resolve this issue.

@pixelzoom already said in design meeting that there is nothing there because nothing was provided.

@DianaTavares, @Nancy-Salpepi and @arouinfar likely know what is planned for this panel and can make a stab at a static description for it.

[terracoda]

I am changing the label to design. I do not think this is a dev issue.

[terracoda]

Assigning to @DianaTavares and tagging @Nancy-Salpepi and @arouinfar.

[DianaTavares]

@DianaTavares, @Nancy-Salpepi and @arouinfar likely know what is planned for this panel and can make a stab at a static description for it.

Well, we wrote a description of the content of this panel in the help text. Can that be used as the description and leave this component without help text? because the information here is not interactive, just displays data. I just think that if we leave the help text and also ad a static description, the information is going to be very similar.

The help text said:
Observe changes in the electron's state as shown in an energy level diagram

I will discuss this with @arouinfar and @Nancy-Salpepi in the standup meeting.

[pixelzoom]

I don't know what will be in the panel, but a brief static description of what will be in the panel will resolve this issue.

As @DianaTavares noted, the Panel already has helpText that describes the content. Is it also required to add description (accessibleName? helpText?) to a Panel's content? Is that a desirable requirement for the Panel API? (My instinct is "no".) If so, why would we also add helpText to the Panel?

[kathy-phet]

@pixelzoom @jessegreenberg - I think we do want to have an API for these "panel" dialogs that enable adding a paragraph description within the dialog when the dialog is complex or is an image. Think of it as "alt-text" for what is in the panel. The screen reader user will look for what is there and finding "empty" is problematic.

@jessegreenberg can you work on a nice API for optionally providing this kind of "alt-text" to a panel when the panel content itself isn't accessible like its an image or otherwise too complex for direct screen reader access?

[pixelzoom]

@terracoda said:

I don't know what will be in the panel, but a brief static description of what will be in the panel will resolve this issue.

Again, I'd encourage you to familiarize yourself with the sim. I'm not sure how effective description design can be done without being familar with the sim. From #75 (comment):

If you're not familiar with what will be displayed in this accordion box, please run the Java version at https://phet.colorado.edu/en/simulations/hydrogen-atom. Select any of the 3 quantum models (Bohr, de Broglie, Schrodinger), then check the "Show electron energy level" checkbox. Note that what's shown in the accordion box varies because the representation of "energy level" is specific to the selected model.

In case you're having trouble running the Java version, here are screenshots. The electron (blue sphere) moves to the position that describes its state. State is described by integer n for Bohr and de Broglie, and by (n,l,m) (the "quantum numbers") for Schrodinger. Larger n == higher energy.

Bohr and deBroglie models:

Schrodinger model:

[kathy-phet]

@pixelzoom - Taliesin and I took a look at this earlier this morning, and chatted through the panel alt-text approach for this component. For now, let's just see what suggestions @jessegreenberg can develop for adding an API for optionally inserting a paragraph description.

[pixelzoom]

@kathy-phet I'm not following what you're proposing.

How is what you've described different from the helpText that can already be added to Panel? Or are you looking for something that can be multi-paragraph, similar to the screen summary API?

Why would this be different for Panel vs Accordion box vs Dialog? They are all containers that have a "content" Node. And that content Node can be any type of scenery Node -- possibly with its own accessibleName, helpText, etc.

[pixelzoom]

@jessegreenberg and I discussed. To summarize… His opinion is that another option (like alt-text) is unnecessary, and that the desired behavior can be accomplished by changing where the AccordionBox’s helpText appears in the PDOM. And that what we do for AccordionBox should apply to other “container” UI components, like Dialog, Panel, etc.

@jessegreenberg please correct me if any of that is incorrect.

[pixelzoom]

Assigning to @jessegreenberg to investigate what he described to me in #75 (comment). Let me know if you'd like me to review.

[jessegreenberg]

That's right - helpText is the API we should keep using and I would rather not make the API more complicated by adding something new.

The problem comes from the implementation of the helpText in AccordionBox. Because it is outside of the "region" element, the screen reader describe it as "empty", even when this content is provided. We can fix this just by moving the helpText slightly in the PDOM.

[jessegreenberg]

This was changed in the above commit. It sounds correct to me in NVDA.

@terracoda can you please see if this is improved in VoiceOver?

[jessegreenberg]

@terracoda and I discussed this together. I am going to revert this change.

The helpText should not be in the region. It will be next to the button that expands/collapses the AccordionBox. We are going to change AccordionBox so that the entire region (not just its content) is hidden from the screen reader when collapsed. This will stop the screen reader from describing the region altogether when it is collapsed.

The screen reader will still describe the region as "empty" when it is open, and that is expected and correct. This can be resolved by adding accessible content to the contentNode of the AccordionBox. That is outside of the scope of "Accessible names and help text". Whether or not that is in scope for "Tier 1" description features remains to be determined.

[jessegreenberg]

Done in the above commits. @terracoda can you please confirm this is correct?

[terracoda]

It sounds correct in VoiceOver.

I hear the accordion box's name, collapsed state, and role, on focus: Energy Level Diagram, collapsed, button,
If I get to the accordion box with the virtual cursor, I also hear that it is an h3.

I hear the help text when I move ahead with the virtual cursor, and NO empty region and no mention of region when it is collapsed.

I only hear "Empty Region" when expanded and I read what is after the help text.

This is all good.

"Empty region" will go away of we describe the content that is to appear in the region. This would be what @kathy-phet meant by "alt text." If the dynamic energy level diagrams can be described in a static way that is meaningful that would be great. Perhaps just describing the essential idea of the layout differences between the model representations?

That would be part of a new issue.
Closing this one, since the accordion works as expected.