Add invisible 'keyboard help' prototype to accessibility tree

[jessegreenberg]

From phetsims/scenery#450, @terracoda said:

@jessegreenberg, How's this for a draft version of Keyboard Help. Use H1 and H2's if you put it in a modal dialog. Use H2's and H3's if you put it directly in the p-dom content hierarchy and wrap it in a section.

<h1>Keyboard Help</h1>
<h2>Balloon Interactions</h2>
<ul>
    <li>Arrow Keys: Grabs &amp; moves balloon in any direction.</li>
    <li>Spacebar or Control plus Enter: Releases balloon.</li>
    <li>Shift plus Arrow Key: Grabs &amp; Moves balloon with bigger steps.</li> 
</ul>
<h2>Quick Move Hotkey Combinations</h2>
<ul>
    <li>J plus S: Jumps to edge of Sweater.</li> 
    <li>J plus W: Jumps to Wall.</li>
    <li>J plus N: Jumps to Near Wall.</li>
    <li>J plus M: Jumps to Middle of Play Area.</li>  
</ul>
<h2>Sim Navigation &amp; Help</h2>  
<ul>
    <li>Tab key: Goes to next focusable item.</li>
    <li>Question Mark: Opens keyboard help.</li>
</ul>

@jessegreenberg said:

This looks good @terracoda! I will add something like this to the accessibility tree for balloons-and-static-electricity.

[jessegreenberg]

Accessible modals are tricky! I have run into a few issues with the keyboard help menu.

1. Using question mark to bring up the dialog only works in forms mode. This means that the user can only pull up the keyboard help menu if the balloon or radio buttons are selected.

2. Moving the focus to the dialog means that the screen reader is already in forms mode, and cannot read through headings and lists.

I have been working off of this example:
https://accessibility.oit.ncsu.edu/training/aria/modal-window/version-3/

In that case, the modal is brought up with a single button. This takes away the challenge of pulling up the dialog when the user is not focusing on a form element.

It also looks like dialog's are only meant to be used for forms in a11y? The example above implies that content which is not explicitly tied to an input is invisible to AT.

[jessegreenberg]

Forcing documents mode with various roles proves ineffective.

[jessegreenberg]

I am not sure what the long term solution will be. In the mean time, we have a few options:

1. Create a discrete button on the screen that pulls up the keyboard help menu, much like a modal. This would allow us to remain in documents mode when the modal is up.

2. Inject the above HTML structure directly into the DOM, not hidden in any way. The information would be available to the user, and could be contained in the header for the ScreenView.

3. Wait to include this content until we determine a longer term solution.

4. ???

[jessegreenberg]

For now, I am a fan of option 2. option 1 would take some time and might even pop the AT into forms mode anyway.

[jessegreenberg]

Above commit is an initial implementation of the dialog. Here it is, rendered in the DOM:

<div id="dialog-14-498-496" role="dialog" tabindex="0" aria-labelledby="dialog-label-14-498-496">
    <h1 id="dialog-label-14-498-496">‪Keyboard Help‬</h1>
    <h2>‪Balloon Interactions‬</h2>
    <ul>
        <li>‪Arrow Keys: Grabs and moves balloon in any direction.‬</li>
        <li>‪Spacebar or Control plus Enter: Releases balloon.‬</li>
        <li>‪Shift plus Arrow Key: Grabs and Moves balloon with bigger steps.‬</li>
    </ul>
    <h2>‪Quick Move Hotkey Combinations‬</h2>
    <ul>
        <li>‪J plus S: Jumps to edge of Sweater.‬</li>
        <li>‪J plus W: Jumps to Wall.‬</li>
        <li>‪J plus N: Jumps to Near Wall.‬</li>
        <li>‪J plus M: Jumps to Middle of Play Area.‬</li>
    </ul>
    <h2>‪Sim Navigation and Help‬</h2>
    <ul>
        <li>‪Tab key: Goes to next focusable item.‬</li>
        <li>‪Question Mark: Opens keyboard help.‬</li>
    </ul>
</div>

[jessegreenberg]

Another temporary solution could be to place all of the content under the 'dialog' as the content for an aria description. Feels unconventional, but could work. Will be easy to try, I will take a stab at it.

[jessegreenberg]

From https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_dialog_role:

Dialogs always need to have at least one focusable control.
When the dialog appears on the screen, keyboard focus (whose control depends upon the dialogs purpose) should be moved to the default focusable control inside the dialog. For dialogs that only provide a basic message it could be an "OK" button. For dialogs containing a form it could be the first field in the form.

This makes a lot of sense. A combination of the above and #105 (comment) should work nicely.

[jessegreenberg]

In phetsims/scenery#450, @terracoda said:

<div role="dialog" aria-labelledby="dialog1Title" aria-describedby="dialog1Desc">
<h1 id="dialog1Title">Keyboard Help</h1>
    <section id="dialog1Desc">
        <h2>Balloon Interactions </h2>
        <ul>
            <li>Arrow Keys: Grabs &amp; moves balloon in any direction.</li>
            <li>Spacebar or Control plus Enter: Releases balloon.</li>
            <li>Shift plus Arrow Key: Grabs &amp; Moves balloon with bigger steps.</li> 
        </ul>
        <h2>Quick Move Hotkey Combinations</h2>
        <ul>
            <li>J plus S: Jumps to edge of Sweater.</li> 
            <li>J plus W: Jumps to Wall.</li>
            <li>J plus N: Jumps to Near Wall.</li>
            <li>J plus M: Jumps to Middle of Play Area.</li>  
        </ul>
        <h2>Sim Navigation &amp; Help</h2>  
        <ul>
            <li>Tab key: Goes to next focusable item.</li>
            <li>Question Mark: Opens keyboard help.</li>
        </ul>
    </section>
  <button>Close</button> 
</div>

@jessegreenberg said

This is just what I had in mind, see #105 (comment)

[jessegreenberg]

Made the change to sim code to produce the above structure. Here it is, rendered by scenery:

<div id="dialog-14-498-496" role="dialog" tabindex="0" aria-labelledby="dialog-label-14-498-496" aria-describedby="dialog-section-14-498-496">
    <h1 id="dialog-label-14-498-496">‪Keyboard Help‬</h1>
    <section id="dialog-section-14-498-496">
        <h2>‪Balloon Interactions‬</h2>
        <ul>
            <li>‪Arrow Keys: Grabs and moves balloon in any direction.‬</li>
            <li>‪Spacebar or Control plus Enter: Releases balloon.‬</li>
            <li>‪Shift plus Arrow Key: Grabs and Moves balloon with bigger steps.‬</li>
        </ul>
        <h2>‪Quick Move Hotkey Combinations‬</h2>
        <ul>
            <li>‪J plus S: Jumps to edge of Sweater.‬</li>
            <li>‪J plus W: Jumps to Wall.‬</li>
            <li>‪J plus N: Jumps to Near Wall.‬</li>
            <li>‪J plus M: Jumps to Middle of Play Area.‬</li>
        </ul><h2>‪Sim Navigation and Help‬</h2>
        <ul>
            <li>‪Tab key: Goes to next focusable item.‬</li>
            <li>‪Question Mark: Opens keyboard help.‬</li>
        </ul>
    </section>
</div>

Next step will be to test with a screen reader. Will do this soon.

[jessegreenberg]

The above seems to work well for Windows 7 Chrome and Firefox with NVDA. Two issues are still present.

1. The AT is still in 'forms' mode. The screen reader will read through the dialog HTML, but the user cannot go through it line by line unless they toggle back to document mode.

2. The dialog can still only be brought up if the AT is already in 'forms' mode.

[terracoda]

@jessegreenberg Here's new content for the Keyboard commands and help:

<div id="dialog-14-498-496" role="dialog" tabindex="0" aria-labelledby="dialog-label-14-498-496" aria-describedby="dialog-section-14-498-496">
    <h1 id="dialog-label-14-498-496">‪Keyboard Commands and Help‬</h1>
    <section id="dialog-section-14-498-496">
        <h2>‪Balloon Interactions‬</h2>
        <h3>Grab and Drag Balloon</h3>
        <p>Use the WASD keys to grab and drag the balloon in four directions. Add the Shift key to the letter to make bigger steps.</p>
        <ul>
            <li>W key drags up. Shift plus W drags up a lot.</li>
            <li>A key drags left.</li>
            <li>S key drags down.</li>
            <li>D key drags right.</li>
       </ul>
       <h3>Release Balloon</h3>
       <ul>
            <li>‪Spacebar: Releases balloon.‬</li>
           <li>‪Control plus Enter: Releases balloon.‬</li>
           <li>‪Tabbing away from the balloon releases it.‬</li>
        </ul>
        <h3>‪Quick Move Hotkeys‬</h3>
       <p>Use these key combinations to jump to a location in the Play Area.</p>
        <ul>
            <li>‪J plus S jumps to edge of sweater.‬</li>
            <li>‪J plus W jumps to wall.‬</li>
            <li>‪J plus N jumps to near wall.‬</li>
            <li>‪J plus M jumps to middle of Play Area.‬</li>
        </ul>

  <h2>‪Sim Navigation and Help‬</h2>
        <ul>
            <li>‪Press Tab to go to next item.‬</li>
            <li>‪Shift plus Tab to go to previous item.‬</li>
            <li>‪Press Question Mark to opens keyboard commands and help.‬</li>
        </ul>
    </section>
</div>

[jessegreenberg]

Thanks @terracoda, adding this now.

[jessegreenberg]

‪Control plus Enter (Windows-only): Releases balloon.

@terracoda, this still does not work for iOS?

[terracoda]

@jessegreenberg Just re-checked this and it works fine in Firefox 43 on Yosemite. I thought it was windows-only by design :-) We should remove that from the keyboard help :-)

[jessegreenberg]

Great! Do you mind if I remove "(Windows-only)" from the description then?

[jessegreenberg]

Here is the dialog now in the parallel DOM

<div id="dialog-14-499-497" role="dialog" tabindex="0">
    <section>
        <h2>‪Balloon Interactions‬</h2>
        <h3>‪Grab and Drag Balloon‬</h3>
        <p>‪Use the WASD keys to grab and drag the balloon in four directions. Add the Shift key to the letter to make bigger steps.‬</p>
        <ul>
            <li>‪W key drags up. Shift plus W drags up a lot.‬</li>
            <li>‪A key drags left.‬</li>
            <li>‪S key drags down.‬</li>
            <li>‪D key drags right.‬</li>
        </ul>
        <h3>‪Release Balloon‬</h3>
        <ul>
            <li>‪‪Spacebar: Releases balloon.‬</li>
            <li>‪‪Control plus Enter (Windows-only): Releases balloon.‬</li>
            <li>‪‪Tabbing away from the balloon will release it.‬</li>
        </ul>
        <h3>‪‪Quick Move Hotkeys‬</h3>
        <p>‪Use these key combinations to jump to a location in the Play Area.‬</p>
        <ul>
            <li>‪J plus S jumps to edge of sweater.‬‬</li>
            <li>‪‪J plus W jumps to wall.‬‬</li>
            <li>‪‪J plus N jumps to near wall.‬‬</li>
            <li>‪‪J plus M jumps to middle of Play Area.‬</li>
        </ul>
        <h2>‪‪Sim Navigation and Help‬‬</h2>
        <ul>
            <li>‪‪Press Tab to go to next item.‬</li>
            <li>‪‪Shift plus Tab to go to previous item.‬</li>
            <li>‪‪‪Press Question Mark to opens keyboard commands and help.‬</li>
        </ul>
    </section>
</div>

[terracoda]

@jessegreenberg of course not, and, I did so in my comment above right after my test, sorry, I didn't mention it.

[terracoda]

@jessegreenberg I think we can also remove the colons...

           <li>‪‪Spacebar releases balloon.‬</li>
            <li>‪‪Control plus Enter releases balloon.‬</li>

Screen reader output may sound better.

[jessegreenberg]

Sounds good, I removed the colons.

[jessegreenberg]

Please see #123 for changes involving the keyboard help dialog. Most notably, there is some new visual content to go along with the dialog, and a new structure that should support 'documents' mode with the virtual cursor.

Since the keyboard help dialog was added, closing this issue. New issues can be created for any additional changes.