Some keyboard actions are unavailable on a mac

[julianna-langston]

When you're on a Mac, is you navigate to a C2M chart and press "H", you get the Help docs.

The Help docs say that you can press Home, End, Page Up, and Page Down to perform tasks (among others). These keys are no available on Macs.

These actions should be remapped to something available on Macs, and the help dialog should reflect that fact.

[spmealin]

To address the specific concern mentioned in this issue, on Macs that do not have physical home / end /page up / page down keys, using the function key in conjunction with left arrow / right arrow / up arrow / down arrow are the equivalents. For example, pressing function (marked as FN on most keyboards) and then also pressing the left arrow will appear to the operating system (OS) / applications as the home key.

More generally, we need to figure out if and how we adjust our help text for alternative keyboards. Consider the following: given that it is impossible to programmatically detect if someone has a physical button, and given that there are virtually unlimited manufacturers of computer hardware, and given that different manufacturers use different key combinations to emulate these keys, then we cannot statically cover all possible combinations, nor can we dynamically change the text to address a specific situation since we cannot detect what buttons exist. Basing dynamic text on the OS as reported by the user’s agent string or fingerprinting APIs is likewise not a solution since the OS is not typically aware if a key is physical or being emulated by hardware-specific firmware.

Since our primary audience are screen reader users, and our secondary audience are keyboard-only users, I think it is acceptable to assume that the user is familiar with their own hardware. Using the proper names of the keys and forgoing any hardware-specific suggestions on how to emulate those keys will be both the simplest solution to implement and most clearly communicate what the user needs to do. If the user is not familiar with how to emulate a key that is not physically present on their hardware, the knowledge is always a quick internet search away.

[ndrezn]

Just a question on this, why not add keybinding descriptions for the common cases of both MacOS and Windows? I empathize that it's difficult or impossible to automatically detect the keys available, or OS to show the buttons for, but showing the most common options for the most common operating systems feels reasonable, and would really improve the usability of the help menu.

As a Mac user I was 😵‍💫 trying to figure out how to translate the keybindings.

[spmealin]

@ndrezn, thanks for the perspective. My main concern is that on MacOS, Fn+arrow do not always map to home/end. For example, the full-size keyboard with numpad appears to have physical home / end keys. Additionally, from a quick 10-minute check, many of the most third-party recommended keyboards for Mac map other functions to those combinations of keys. For example, Logitech keeps on coming up, and they remap fn+arrows to adjusting the brightness of their keyboard backlight, according to their manuals. One keyboard even notably remapped the home and end keys to capsloc+F11 and Fn+F12, which is insane in my opinion.

You said that you didn’t know you could use the Fn+arrow keys to emulate the home / end keys, how did you eventually resolve the problem? Did you only find out from reading my comment, or did you find that information another way? As a native screen reader user, I did not think that this is a problem that needs to be explicitly addressed, but if it is a problem that you encountered, I could be assuming what I thought was general knowledge could be more specialized. I will take a quick, informal poll of some blind and sighted Mac users to help me collect some objective data.

[ndrezn]

I ran into the problem testing the integration with Plotly, and learning to interact with it -- I ended up chatting with members of our team who were using the tool heavily & working with @julianna-langston so basically learned the keybindings through word of mouth.

My understanding is most screen reader users are working with Windows, so prioritizing Windows makes sense for this project. In Plotly, we expect Chart2Music will be useful for not just screen reader users but also a general audience, as it can be easier to discern differences in tone than differences of a few pixels on a display. So generally we're excited about using this toolkit to reach a broader audience & want the help text to reflect that.

I'm not sure if this is already possible, but maybe this issue/feature request should be changed: Make it possible for developers using Chart2Music to edit the text in the help menu. This way, developers working with Chart2Music could modify the help text to cater to the specific needs of their project. If this exists -- fantastic -- Chart2Music default help text doesn't need to change but developers can override it (or build a fancy OS/hardware detection system themselves). If it doesn't, I think it'd be a valuable add without changing default behaviour of the Chart2Music UI.

(I'll also note, depending on the best strategy to resolve this in your opinion, the Plotly team is happy to contribute to help out with implementation.)

[gvwilson]

[full disclosure: also at Plotly, but have experience working with blind/VI users in other contexts] 👍 to enabling devs to change the text in the help page - this would help with internationalization as well (e.g., we'd like to be able to offer a French explanation of the key bindings).

[julianna-langston]

Current plan is to provide better functionality for developers to augment the keyboard dialog. Estimated timeline is the next few weeks.

[ndrezn]

@julianna-langston here at Plotly we're prepping major releases but the team has bandwidth in mid-Nov to contribute/test/review these changes!

[julianna-langston]

fyi #592

[julianna-langston]

This feature is now live in v1.18.0. You can add this to your options:

options: {
  modifyHelpDialogKeyboardListing: (lang, headers, shortcuts) => {
    console.log("Language:", lang); // "en", "fr", etc
    console.log("Headers:", headers); // ["Keyboard Shortcut", "Description", "Common Alternate Keyboard Shortcut"]
    console.log("Keyboard shortcuts:", shortcuts);

    return headers.concat(shortcuts)
}

This will get you started with the function. You can modify the contents, and whatever is returned in that array will be displayed in the Help dialog's table.

If you want to modify the front matter, you can follow the same steps with the option callback modifyHelpDialogText

I'll try to update the site with more comprehensive documentation in the next day.