Add keyboard help dialog

[jbphet]

In #174 we are adding alternative input to this sim, which will include keyboard navigation. As part of this effort we will need to add a "Keyboard Help" dialog too. Generally these dialogs include sim-specific language, so we will need a design for this sim that we can work from for the implementation.

Assigning to @terracoda, since that's who @jessegreenberg said it should go to. She can reassign as needed. Once we have a design, please assign this issue back to me for implementation.

[terracoda]

@jbphet, I copied a design doc template into the appropriate FL folder. I will get to this as soon as I can. I am assuming you will need special instructions for picking up (grabbing) and moving the magnet - possibly similar to Friction and BASE. And possibly some special modes for different moving at different speeds (prototyped originally with John Hung from IDRC).

I'll play with the sim and mock-up things in the design doc...here https://docs.google.com/document/d/1rkjdVe7-FJh17oBIFzWv16RZG9invMrirHdh5vJWafU/edit#heading=h.nnkdju7p2tyn

For a helpful reference, here's a screen shot of both the visual and accessible versions of Friction's KB dialog:

Please let me know of any deadlines.

[terracoda]

If there are custom commands for speeds, we'll need more instructions. If not, it should be pretty straightforward.

[terracoda]

@jbphet, I posted the content for a basic dialog in the design doc. I'll need to know more about any special speeds to do anything else.

Do you have enough to go on? I only used "bar magnet" in the initial Grab & Release instruction sand reduced to "magnet" in the Move instructions. You can use "bar magnet in all places" if it is important for the sim.

[terracoda]

OOPs, I just did the basics. Let me know about deadlines if you need more.

[jbphet]

@terracoda - I've published a dev version that includes what I believe is the desired keyboard navigation. I've also added the hints that go with it. There are custom keys for moving the magnet across the screen. The "1" key moves it slowly, "2" medium, and "3" is fast. Please play around with this and update the keyboard help dialog based on this.

dev link: https://phet-dev.colorado.edu/html/faradays-law/1.4.0-dev.62/phet/faradays-law_en_phet.html

[terracoda]

Moved to https://github.com/phetsims/faradays-law/issues/174#issuecomment-706293729

[terracoda]

Moved to https://github.com/phetsims/faradays-law/issues/174#issuecomment-706293729

[terracoda]

I just added above to design doc :-)

[terracoda]

Sorry, @jbphet, I forgot to re-assign to you.

[terracoda]

Moved to https://github.com/phetsims/faradays-law/issues/174#issuecomment-706293729

[terracoda]

The drafted content for the Keyboard Shortcuts dialog from the Design Doc is copied here for convenience:

Visual Keyboard Shortcuts Dialog (visual shorthand [[means key icon]])

Keyboard Shortcuts

[[Tab]] to get started.

Grab or Release Bar Magnet

Grab or release bar magnet [[Space]] or [[Enter]]

Move Bar Magnet

Move grabbed magnet [[up]] [[left]] [[down]] [[right]] or [[W]] [[A]] [[S]] [[D]] Move magnet slower [[Shift]] + [[up]] [[left]] [[down]] [[right]] or [[Shift]] + [[W]] [[A]] [[S]] [[D]] Press and hold Arrow key or letter key for continuous movement.

Auto-Slide Bar Magnet

Auto-Slide grabbed bar magnet left or right at 3 different speeds [[1]] [[2]] [[3]] Number keys start auto-slide or toggle sliding direction.

Basic Actions

Move to next item or group [[Tab]] Move to previous item or group [[Shift]] + [[Tab]] Move between items in a group [[Left]] [[Right]] or [[Up]] [[Down]] Toggle checkboxes [[Space]] Press buttons [[Space]] Exit a dialog [[Esc]]

Accessible Text for Keyboard Shortcuts Dialog (HTML PSUEDO CODE) H1: Keyboard Shortcuts P: Tab to get started.

H2: Grab or Release Bar Magnet P: Grab or release bar magnet with Space or Enter keys.

H2: Move Bar Magnet UL LI: Move grabbed magnet up, left, down, or right with Arrow keys, or with letter keys W, A, S, or D. LI: Move magnet slower with Shift plus Arrow keys, or Shift plus letter keys W, A, S, or D. LI: Press and hold Arrow key or letter key for continuous movement.

H2: Auto-Slide Bar Magnet UL LI: Auto-slide grabbed magnet left or right at 3 different speeds with number keys 1, 2 and 3. LI: Number keys start auto-slide or toggle sliding direction.

H2: Basic Actions UL: LI: Move to next item or group with Tab key. LI: Move to previous item or group with Shift plus Tab key. LI: Move between items in a group with Left and Right arrow keys or Up and Down Arrow keys. LI: Toggle checkboxes with Space key. LI: Press buttons with Space key. LI: Exit a dialog with Escape key.

[jbphet]

I've created the first cut of this keyboard dialog, and there are a couple of issues that I could use help with:

@jessegreenberg - @terracoda has designed something for which there doesn't seem to be a precedent or support in the code, which is a line that exists by itself in a row without any icons. I've left it out of the initial implementation, and am wondering what you would suggest. Should we add support for that, consider an alternative design, or figure out some alterative way to implement it? If you want to see the design element, search for "Press and hold" in this issue".

@terracoda - The phrase for auto-sliding is pretty long, so I split it up onto four lines and it still is being scaled down in the dialog. How would you suggest handling this?

There is what the current version looks like, and you can run it from master too if you like:

[terracoda]

@jbphet thanks for laying this out!

We may need to put the Auto-Slide directions on the top of the right-hand column to make things less cramped.

But here are some edits for the second round that might help create more space & consistency:

• [x] add "Grabbed" to the Move and Auto-Slide headings
• [x] remove "bar" from the small content and just use "magnet" in the small content
• [x] make sure to use "grabbed magnet" under move and auto-slide instructions
• [x] try this shortened version of content for auto-slide instructions:
  • "Auto-slide grabbed magnet horizontally and toggle slide direction [[1]] [[2]] [[3]]"

I have it all updated (changes marked in red) in the design document here.

I have an even shorter versions of the auto-slide instructions, but I am hoping the ones above with fit better.

For example, other possibilities that I sketched are:

• "Slide grabbed magnet horizontally and toggle slide direction [[1]] [[2]] [[3]]"
• "Start horizontal auto-slide and toggle slide direction [[1]] [[2]] [[3]]"
• "Start horizontal auto-slide (3 speeds), and toggle slide direction [[1]] [[2]] [[3]"

[terracoda]

@jbphet, the A11y content for the dialog is also updated in the design document.

[terracoda]

@jbphet, also @zepumph is working on some common code updates. Not sure if this will effect Faraday's Law, but just a heads up on that work.

[jessegreenberg]

a line that exists by itself in a row without any icons

True, there currently isn't support for this. We could add support for this in KeyboardHelpSection.js.

LI: Press and hold Arrow key or letter key for continuous movement.

Is this specific to Faraday's Law or does it need to be added to BASE/friction/coulombs-law/others? I am wondering if this should be in a reusable help section for draggable things like we have for sliders and the general content.

[terracoda]

Good catch @jessegreenberg, I updated the design doc, and decided to remove that line. It wasn't actually implemented, so I didn't mention it directly in the updates.

I removed it because it is quite intuitive, so learners just might do it on their own. I originally put it in because continuous movement is important for this sim.

By "reusable help section" do you mean Basic Actions or something else?

[jessegreenberg]

OK, sounds good. By reusable, I mean a component in common code that makes it easy to create sections like the "Move Bar Magnet" section. If all sims with a draggable component required that line, I would have recommended creating something like that. But since the line has been removed I don't think it is as important. I reviewed the existing "Move {{object}}" sections and they all have (intentionally) different titles/contents, so I don't think we should make it.

[terracoda]

Thanks @jessegreenberg, I get it. I think removing the line is best. We haven't needed it before now, and we usually want to keep the KB Shortcuts content as brief as possible.

Also, for FL, we have the special 123 keys as an alternative which is indeed explained in detail.

[terracoda]

Un-assigning myself, over to you @jbphet.

[zepumph]

I made some changes to this sim's help dialog as part of https://github.com/phetsims/scenery-phet/issues/630. Most notably, I added checkbox content, as I noticed the inconsistency there. I also removed the usage of labelMaxWidth being passed to the general help section. This is because it was too short to prevent the scaling down of some of the newly longer texts in the general help section. I think in general (no pun intended), the general content shouldn't be constrained, since its max width is set for its content. Traditionally it has been alright for different help sections to have different widths, as long as each row in a single section is inline with one another.

Commits effecting this dialog:

https://github.com/phetsims/faradays-law/commit/fbc8bafde1e21eb3a28c40a4e75682863dc5a450 https://github.com/phetsims/faradays-law/commit/2c214372ba5dc1db4e0da41975c82ac54df8122b

[jbphet]

@terracoda - I've implemented it as currently specified and published a dev version (link below), please review and let me know what you would like for the next steps. Overall, it looks pretty good to me, but I had to put additional line breaks in a couple of the phrases to make them fit without getting their fonts reduced, and we might want to consider making these shorter.

Please assign back to me when it's ready for another round of revisions.

Dev link: https://phet-dev.colorado.edu/html/faradays-law/1.4.0-dev.63/phet/faradays-law_en_phet.html

[terracoda]

@jbphet, the visuals are looking really nice in the above Dev Link.

There are a couple of string issues in the accessible content:

1. The heading: "Auto-Slide Grabbed Bar Magnet." has a period at the end of it. Remove the period
2. The description for the auto-sliding needs to be updated:
   • From: Automatically slide the magnet from one slide to the other using the 1, 2, or 3 keys.
   • To: Auto-slide grabbed magnet horizontally and toggle slide direction with number keys 1, 2, or 3.

[jbphet]

@terracoda - the latest updates are now available in https://phet-dev.colorado.edu/html/faradays-law/1.4.0-dev.64/phet/faradays-law_en_phet.html. Please review and assign back to me with any comments.

[emily-phet]

I wasn't assigned - but took a look. Looks great to me!

[terracoda]

@jbphet, the content is good in both the visual dialog and the pdom dialog.

I do see that the size of the auto-slide text is still a little smaller than the rest of the text. That might be intentional given the space limitations. If it not possible (i.e., no time left) to make the entire dialog a little taller to accommodate making the auto-slide text the same size as the rest, that's ok.

We have the pan and zoom feature, so learners can make the text bigger if they need to.

Back to you to make the call on the text. @emily-phet said it was good as is.

Screenshots for the record.

[KatieWoe]

This is implemented in dev 65. I will note that the description for the 1, 2, and 3 keys did confuse me a bit and the controls took some experimenting.

[jbphet]

I do see that the size of the auto-slide text is still a little smaller than the rest of the text.

I adjusted the positions of the line breaks to improve the situation, and I think it's about as good as it's going to get without changing the text (including adding another line break). @terracoda - please look at it on master and let me know if we're good to go with this.

[terracoda]

Looks good @jbphet.

@KatieWoe, do you have a suggestions on how to make it clearer without making it longer?

Basically, this is a very custom interaction. You grab the magnet and then

• press 1 to move slowly and 1 again to toggle direction of the slide
• press 2 to move at medium speed and 2 to toggle direction
• press 3 to move fast and 3 to toggle direction

This interaction allows for experimenting at different speeds even if you are using a keyboard, or if you have any dexterity issues.

[terracoda]

@KatieWoe, I'll rephrase my question.

Did you figure it out? If so, I think it's ok.

Please close the issue or assign back to me if you have a great idea about wording :-)

[KatieWoe]

One of the things that tripped me up for awhile was when did the magnet switch directions. Everything else I figured out experimenting. Since the changes made in https://github.com/phetsims/faradays-law/issues/196, it makes more sense so I think its ok.

[terracoda]

Gotcha @KatieWoe. Thanks for your comment.