Allow users to customize keyboard shortcuts

[afercia]

Edit: Discussed during today's (March 1st 2018) bug scrub and agreed to consider a generic mechanism to allow users to customize keyboard shortcuts. Chances of conflicts are very high for any shortcut and many users would be unable to use the related features.

----- Original description:

Follow up to #3084

Keyboard navigation through the editor regions is currently implemented with the shortcuts ctrl+backtick and ctrl+shift+backtick, inspired by what Slack does.

However, not all the keyboard layouts have a physical key for the backtick. See for example the Italian keyboard layout. See the relevant discussion on https://github.com/WordPress/gutenberg/pull/3084

until we find a single keyboard shortcut that's actually a standard, the closest is what we have here with ⌘+` that Slack uses. It seems worth trying this. We could then supplement it, or replace it, with a simpler shortcut that doesn't change between keyboards, if we can find a good idea for what that should be.

Worth noting Slack has preferences for the language and the keyboard layout, though at the moment that's limited to just 4 languages.

A few options to consider:

• find a shortcut that works universally across all keyboard layouts (I doubt there's one)
• use a single key shortcut, as mentioned on #3084
• make the shortcut configurable on a per user basis

[afercia]

Gmail for example, does use Cmd/Ctrl + Shift shortcuts but uses also single key shortcuts or combinations of character keys:

As mentioned in #3084 single key shortcuts work, when not inside an editable field. Screen readers use single key shortcuts but they already have their own mechanisms to jump through landmark regions.

[aardrian]

Drive-by commenting here, but are we primarily concerned with only Latin or Western languages?

If so, then finding a shared key may be possible (if awkward). If not, then prior i18n experience suggests different languages / sets of languages will need to have different key mappings and we'll still need to allow users to customize anyway.

[afercia]

Quoting ATAG A.3.1.5 https://www.w3.org/TR/2015/REC-ATAG20-20150924/#sc_a315

Customize Keyboard Access: If the authoring tool includes keyboard commands, then those keyboard commands can be customized.

The intent of this success criterion is to ensure that authors using a keyboard interface on platforms that support keyboard commands have the ability to remap the authoring tool's default keyboard shortcuts in order to avoid keystroke conflicts, use familiar keystroke combinations and optimize keyboard layout (e.g. for one-handed use).

[afercia]

Investigating on #5847 / #6144 I've read some Mousetrap (the tool used by Gutenberg to implement keyboard shortcuts) documentation. Reference: https://craig.is/killing/mice https://github.com/ccampbell/mousetrap

Worth noting that also sequences of keystrokes work, see https://craig.is/killing/mice#api.bind.sequence and also shortcuts that include sequences and combinations. For example, pressing Command (or Ctrl) twice would work. This opens up new possibilities, and maybe it's something easier to implement than customizable shortcuts. Any thoughts more than welcome. /cc @aardrian @rianrietveld @joedolson @samikeijonen etc.

[aardrian]

I do not know where else to put this, but please be cautious when applying keyboard shortcuts, particularly when using Slack as an example. Slack has made its accessibility worse for screen reader users who rely on keyboard navigation. This Twitter exchange between a skilled SR user and the Slack guy in charge of accessibility demonstrates that disconnect: https://twitter.com/LeonieWatson/status/974615133044359168

Further, many screen reader users and many keyboard-only users have motor impairments that make many complex (or even simple) combos possible. Shortcuts may be a nice add-on for many users, but they are not a guaranteed accessibility fix (so it is ok to have them, but don't make those the only means of interaction for a feature).

[aardrian]

@afercia

Investigating on #5847 / #6144 I've read some Mousetrap (the tool used by Gutenberg to implement keyboard shortcuts) documentation. Reference: https://craig.is/killing/mice https://github.com/ccampbell/mousetrap

Fired it up with NVDA. The first example on the page is to hit the 4 key to highlight the first line of code. Without NVDA it works fine. With NVDA, since NVDA (rightly) captures keystrokes, it jumps me to the first <h4> on the page.

In order to pass the key through to the OS, bypassing NVDA, I need to use NVDA Key + F2 and then I can hit 4. (note that NVDA Key will be either Caps Lock or Insert depending on the user's configuration).

In my experience, few screen reader users know what their passthrough key combo is, let alone know when or how to use it.

That being said, in a very quick glance at the library, I saw no statements about how to implement it and account for screen readers. The answer from the developer may be "Meh", which should be documented if that is the approach.

[afercia]

@aardrian thanks. Yep I'm aware the passthrough key is not so used, and I'd say it's not acceptable to ask users to use it. I haven't looked at the Mousetrap examples, however the good part is that Mousetrap is "agnostic" and allows to really use any shortcut. It's up to the implementation to make them work with AT for example making SR enter forms mode or application mode where appropriate.

Shortcuts are probably more useful for pro-keyboard users (non screen reader users). Worth nothing the Ctrl + backtick shortcut mentioned here basically matches the ARIA landmarks so screen reader users can just use their screen reader to jump through landmarks.

[aardrian]

Ah, I get it. The things you want to designate as targets for Ctrl + backtick correspond to named regions / landmarks. I like that.

[afercia]

Yep, it's an attempt to emulate landmarks for non-screen reader users 😆

[afercia]

Just to confirm the "Ctrl + backtick" shortcut doesn't work on various non-English layout keyboards and thus the ability to jump through the main editor sections is not available to all users (see also #1182):

• not available on an Italian keyboard layout (@afercia)
• not available on a Dutch keyboard layout (@rianrietveld)
• not available on a Finnish keyboard layout (@samikeijonen)
• not available on a French keyboard layout (@audrasjb)
• likely way more

[fuzzbomb]

Yep, it's an attempt to emulate landmarks for non-screen reader users

Facebook has an interesting approach to landmark navigation. A landmarks menu as an early tab-stop on the page, where you'd often find a skip-to-main link. I think it's notable, because I presume a lot of keyboard users have found it already. I'm not a Facebook user myself, but it's used on the sign-up screen too, so I played with it there.

Description here: https://a11ywins.tumblr.com/post/170270963528/facebook-ax-navbar

[samikeijonen]

That's interesting approach. I actually logged in to Facebook the test it out, worked as described.

[afercia]

@fuzzbomb interesting. I see they use Alt + / to invoke the menu, so the keyboard shortcut issue still stands. On my Italian keyboard for example I'd need to press Shift+7 to get a slash /. Not sure about other keyboard layouts but it would probably still need some kind of customization mechanism. (@samikeijonen where's the slash / on your Finnish keyboard?)

However, you made me think at a core Trac ticket that asked to make the existing Skip link accessible to developers (see https://core.trac.wordpress.org/ticket/36644). While the proposal there is not exactly the same thing, I'm now wondering: what if we try to make the existing Skip link extensible, i.e. more skip links can be added there via a filter or something?

Then, it should be changed to an ARIA menu with arrows navigation and it would be great to have a customizable shortcut to invoke it.

[samikeijonen]

@afercia Same here with /, I could not access with Alt + /. But at least it was the first Tab stop.

[afercia]

@samikeijonen thanks. That's the point, we need a tool users can access when focus is in the Gutenberg UI 🙂

[jasmussen]

we need a tool users can access when focus is in the Gutenberg UI 🙂

For the sake of argument and pretending it would be the easiest thing in the world: what if we were to add regions to all of the WordPress UI, not just Gutenberg — would this be an a11y benefit?

[fuzzbomb]

Sure, the Facebook landmark navigation can be accessed via a keyboard shortcut, but you can also get there quickly by tabbing after loading a page. The ALT+slash would be just another customizable shortcut.

The thing that interests me about Facebook's approach, is it includes links to their accessibility help pages too, but keeps the whole region to a single tab-stop. The region isn't just a fancy skip-link alternative, it's a region for a11y tools in general.

Now, you could potentially add other things there too, like a headings navigation drop-down, or... links to customize accessibility settings per user. So that's where a mechanism to customize keyboard shortcuts could live - in an a11y-tools region, just one TAB key (and a couple of arrows) away from the start of the page. If ALT+/ doesn't suit you, a keyboard-only user could still find a way into customizing that without much effort.

An always-visible button to reveal the "accessibility tools" region could live on the main toolbar, quite unobtrusively. So the a11y tools region is easily reached by a single TAB after loading the page, or lots of Shift-TABs form somewhere in the middle of the page, or a mouse click, Dragon, or whatever keyboard shortcut it has.

I don't know how many shortcuts are being proposed, but I think something on the scale of Gmail is too much. One way to avoid excess would be a system where lots of actions can have a keyboard shortcut, but most of them are unassigned by default (an empty setting). KDE Plasma desktop and GNOME desktop do it this way.

(For what it's worth, Ctrl+backtick is used by Ubuntu Unity desktop for "cycling through windows in the current application", while KDE Plasma uses Alt+backtick, and GNOME uses Win+backtick, and macOS uses Splat+backtick for the same task. So it goes.)

Going even further, keyboard shortcuts could be completely turned off by default - users would have to opt-in, but there'd much less risk of frustrating assistive tech users with key conflicts. For users who want them, I'd trust the handbook, and all those "10 things to do after installing WordPress" articles to get the word out. Imagine if everyone was told to check out the accessibility settings link....

P.S. I'm a Drupal a11y maintainer, rather than a WordPress contributor. I found this issue because I follow WP-a11y news. We don't have any keyboard shortcuts yet, we've preferred basic sequential keyboard controls. I expect it's a matter of time before we need to look at this issue in Drupal's authoring tools initiative too.

[fuzzbomb]

we need a tool users can access when focus is in the Gutenberg UI slightly_smiling_face

For the sake of argument and pretending it would be the easiest thing in the world: what if we were to add regions to all of the WordPress UI, not just Gutenberg — would this be an a11y benefit?

Hang on, is the intention to constrain focus inside an editing form? It seems the top toolbar (and/or dashboard sidebar) should be an available region at least. I'm not clear about WP terminology, btw.

It's totally do-able to have landmark regions in all areas of the UI. The hard part is deciding how many.

[fuzzbomb]

I'm now wondering: what if we try to make the existing Skip link extensible, i.e. more skip links can be added there via a filter or something?

Yeah, some API for adding skip-links would be doable. I think the Facebook one presents landmark regions, not sure whether it discovers them dynamically in the browser, or managed server-side. There's a JS landmark discovery implementation at matatk/landmarks.

[afercia]

To recap: Gutenberg already uses 3 ARIA landmark regions.They're the ones marked with role="region":

• the top bar
• the main editor area
• the sidebar

Assistive technology users already have tools to use ARIA landmarks: screen readers provide specific tools to navigate through them.

Instead, keyboard users who don't use a screen reader can't take advantage of ARIA landmarks (yes there are some browsers extensions that enable them). So the Ctrl+backtick shortcut was implemented to allow users to jump through the main 3 editor areas that match the ARIA landmarks.

The point is, keyboard users need to be able to jump from a block to the top bar or the sidebar at any moment.

Sure, the Facebook landmark navigation can be accessed via a keyboard shortcut, but you can also get there quickly by tabbing after loading a page. The ALT+slash would be just another customizable shortcut.

We can't ask users to tab through the whole interface to make, for example, a drop-cap in a paragraph. I'd say the most important thing in this issue is how to correctly implement shortcuts that work for all users, so we need customization. Then, we can discuss an additional tool like an "a11y menu".

(For what it's worth, Ctrl+backtick is used by Ubuntu Unity desktop for "cycling through windows in the current application", while KDE Plasma uses Alt+backtick, and GNOME uses Win+backtick, and macOS uses Splat+backtick for the same task. So it goes.)

Interesting, but I guess that changes depending on the keyboard layout set in the OS 🙂 WordPress is a global project, we shouldn't code for English keyboard layout only.

[fuzzbomb]

So the top bar landmark region is the thing with "+new" and "view post", and a keyboard-only user can still reach it the long way with shift-tab, in case they haven't discovered the landmarks keyboard shortcut? My point is keyboard-only users are sometimes very happy to use basic sequential nav, because learning shortcuts is a chore.

[afercia]

It is. We also need a way to "jump" from teh selected block to the sidebar to solve an interesting problem: when a block has focus, Gutenberg considers that block "selected" and the sidebar is contextual. So for example you're in a block and want to apply a drop cap or change colors or font size: you need to go to the sidebar. When using only the keyboard: as soon as you press Tab and start your journey in the hope to reach the sidebar, you may land in another block (if there are many blocks). At that point, the newly focused block is the "selected" one. Keep tabbing and the last block will be the "selected" one. Finally, you're in the sidebar but now anything you do in the sidebar applies to the last block (the "selected" one) 😬

Basically, when using the keyboard and tabbing through the interface, the "selected" block will always be the last one. Or the first one if tabbing backwards.

At this point, the shortcut to jump to the sidebar is essential. I'd also suggest to consider any other alternative that could make life easier for keyboard users, for example a "jump to the sidebar" link placed inside the blocks. /Cc @jasmussen

[jasmussen]

At this point, the shortcut to jump to the sidebar is essential. I'd also suggest to consider any other alternative that could make life easier for keyboard users, for example a "jump to the sidebar" link placed inside the blocks.

Can this benefit from the navigation mode PR that Riad is working on?

[samikeijonen]

for example a "jump to the sidebar" link placed inside the blocks

With Graham we talked about this in London. There definitely needs to be "jump to the sidebar" link. Could it be the first element in Block settings menu / More options?

[jasmussen]

With Graham we talked about this in London. There definitely needs to be "jump to the sidebar" link. Could it be the first element in Block settings menu / More options?

Wasn't this why we created the "Show Block Settings" link? Can that work as a skip link?

[samikeijonen]

Wasn't this why we created the "Show Block Settings" link? Can that work as a skip link?

Where is that? I'm on the latest master branch.

Edit: Sorry there it is. But it only toggles Show/Hide block settings. It doesn't move the focus in block settings.

[jasmussen]

it only toggles Show/Hide block settings. It doesn't move the focus in block settings.

Right, but couldn't it both show/hide block settings, and move focus there?

[samikeijonen]

It could, then the wording might need to change.

Edit: Or maybe it's not a good idea to have it in the same link.

1. Let's say block settings are open. User clicks Hide block settings, focus should not move anywhere.
2. Let's say block settings are close. User clicks Show block settings, I'm not sure would I want my focus shift anywhere.

Edit block setting or something would make more sense to me.

[afercia]

Well a "jump to" link (actually not a link) doesn't necessaarily need to be visible in the UI. It does need to be revealed on focus. See for example when tabbing at the end of the block settings sidebar #5856

[samikeijonen]

You're right, it doesn't have to be visible. Both are fine by me. In this case I feel that it should be visible. There are already lot's of things going on/off.

[jasmussen]

But since we already have that option in the menu — do we need another, visible or otherwise? Can the one in the menu not double as both?

[samikeijonen]

Then Show block settings should be re-named Show and move to block settings or something. But like I said, it might be weird that I'm forced to move my focus in there if I really just want to open the block settings panel.

[afercia]

Right, but couldn't it both show/hide block settings, and move focus there?

Hm I feel that would be an assumption. The two things should be separated. As a user, I may want to open the block settings just to have a look at them, not necessarily to jump there. A second, specific control to jump there would make things clearer and respect users intent.

[jasmussen]

Fair enough. Seems like the next step could be a PR to test how the solution we believe the most in feels.

[rianrietveld]

Any devs in the house who have time to take this up and write a PR?

[afercia]

For inspiration, Slack uses also F6 to navigate through the landmarks (I guess they've added F6 since a while). Note: F6 is one of the standard keyboard shortcuts on Windows and it's well known by keyboard users. What it does is:

Cycle through screen elements in a window or on the desktop

That means:

• when there's an application open in a window, cycles through elements defined by the application within the window and ignores the operating system UI
• when focus in on the Desktop, cycles through the main operating system UI sections

Since the main application in a window is the browser, that means on Windows, in (most of the?) browsers F6 will cycle through the browser's address bar and the document. In fact, Slack uses F6 on the mac and Ctrl+F6 on Windows:

On the mac:

On Windows:

Seems to me this is better than backtick, as F6 should be available on all keyboard layout? (unless I'm missing something)

[jasmussen]

I dig it. The key, at least to me personally and I'm not the expert on this, is that _if we can reuse a shortcut that is used in other apps, let's defer to that. In this case there's a clear precedence in Slack that's worth mimicking.

Worth noting that the above Slack shortcut works in addition to the ctrl + (key below escape) button. I would love if we could keep that other shortcut as well, even if it's not listed in any of the help files.

One thing that's curious — Macs default to using some custom commands on the F keys, like brightness and volume. While you can change this default, I suspect no-one does, which means normally you need to hold the Fn key to invoke the true F6 action. However in Slack it's working for me, with and without holding Fn. I don't know if that's because F6 is not mapped to a system function (neither is F5), or if Slack is doing something special here to intercept both the F6 command and the Fn+F6 command. Worth testing.

[samikeijonen]

Really quick test but I need Fn+F6 in Slack. But +1 since every (most) keyboard should have those keys.

[afercia]

OK so I've tried F6 but unfortunately doesn't work well across browsers and platforms.

• macOS chrome and safari: F6 works
• macOS firefox: F6 doesn't work, ctrl+F6 doesn't work
• windows chrome: ctrl+F6 works
• windows firefox and IE 11: ctrl+F6 doesn't work

So, on Windows I've tried alt+F6 and seems to work in Chrome and Firefox. Doesn't work in IE 11 :( Weird but the only way to make it work in IE 11 is to focus the browser's address bar first and then ir works. Of course, tabbing from there will lose focus...

Unsure what to do. Any better idea?? :)

[jasmussen]

That's a bummer. I think we need @iseulde advice, she's a keyboard shortcut wizard.

Just to recap, and re-reading this, the reason we want an alternative to Ctrl + [key below escape] is because it's too hard for us to figure out which key that is on international keyboards, correct? Would this key combo be okay if we were able to solicit some help to figure this out? We'd want an array that listed both what the keycode was, as well as what character to show in the shortcut sheet.

Here are some other options.

• Google Chrome when navigated on Android using Talkback and external keyboard uses Alt+D for next region, Alt+Shift+D for previous region.
• This rando browser extension uses Alt + Shift + N and Alt + Shift + P.
• NVDA uses D and Shift D. Is it okay to create a shortcut that only works when you're not editing text?
• j/k is often the keyboard shortcuts for next and previous. Should we use Ctrl + j and Ctrl + k for next and previous region?

[ellatrix]

Lacking some context here, sorry if it's already discussed.

What prevents us from using some modifier + arrows/tab to cycle through regions? They're all used already? Something like alt+tab is maybe still available.

What if the blocks act like a list where you go through them with arrow keys, not unlike a normal editor, and it act like one field when tabbing through?

[ellatrix]

I'm not a fan of using letters for navigation. Also the F# keys are a but hard to discover and remember. Ideally we'd have something the way moving the caret works. Arrow = move by one, option + arrow = move by word, etc. Would be cool if tab = move by one tubbable element and option + tab = move by region.

[jasmussen]

Something like alt+tab is maybe still available.

This switches between open windows in Windows right?

What if the blocks act like a list where you go through them with arrow keys, not unlike a normal editor, and it act like one field when tabbing through?

Sorry I should've clarified. This is for navigating between regions. When you press ctrl + [the key below Escape], you navigate through regions like this:

This already works, but we're looking at an alternative keyboard shortcut because we're not sure this one works on all keyboards and aren't sure how to find out if it does.

However your point is good regarding navigating the block list, and we've discussed something in that vein here: https://github.com/WordPress/gutenberg/pull/5709#issuecomment-393791220

[jasmussen]

option + tab = move by region.

I agree, tab feels like a superior key to use for navigating regions here, since tab is inherently about picking elements on the page. However it's also a challenge as most modifier combinations of tab are used:

• Ctrl + Tab and Ctrl + Shift + Tab switches tabs in browsers
• Alt + Tab on Mac doesn't seem to do anything, but on Windows it switches between windows, which also locks us out of ⌘+Tab on mac.
• Ctrl + Alt + Tab for tabbing forwards and Ctrl + Shift + Alt + Tab might work, but it's a bit fiddly, and Ctrl + Alt are mapped to the magnifier on Macs if you have that enabled.

In other words, as much as I want to use tab here, not sure we can :(

[samikeijonen]

Also the F# keys are a but hard to discover and remember.

Pretty much every combination is hard to remember. Needs good documentation anyway.

This already works, but we're looking at an alternative keyboard shortcut because we're not sure this one works on all keyboards.

It doesn't, we are sure :)

OK so I've tried F6 but unfortunately doesn't work well across browsers and platforms.

@afercia Was there a PR already for testing?

[afercia]

As commented in part above:

• backtick is not available on at least 4 keyboard layouts, likely more. See https://github.com/WordPress/gutenberg/issues/3218#issuecomment-381651232
• screen readers Alt+D or D work just with a screen reader running, we need a shortcut that works for keyboard users who don't use a screen reader. For example, Ald+D on Windows conflicts with the native shortcut to focus the browser address bar.
• alt+tab is taken on Windows
• arrows won't work from within the writing-flow? and I guess they won't work either from within an input field (or, we don't want them to work from within an input field, to preserve native interaction); we need a "global" shortcut that works from anywhere, at any moment

@samikeijonen no there's no PR I've just added the shortcuts in components/higher-order/navigate-regions/index.js it's very easy to try.

So after the great illusion 😬that F6 was an option, I guess we're again at the initial issue.

[samikeijonen]

In accessibility meeting we decided to test either of these key combinations:

Next landmark: Alt+Shift+N Previous landmark: Alt+Shift+P

Or

Next landmark: Ctrl+Alt+N Previous landmark: Ctrl+Alt+P

We concluded that there needs to be three keys combination anyways even if it's hard to remember. Once again documentation is the key here.

[samikeijonen]

Also noting that there is Landmarks extension which uses these keyboard shortcuts.

[afercia]

There's now a pending PR https://github.com/WordPress/gutenberg/pull/8005 to test the shortcuts:

Next landmark: Alt+Shift+N Previous landmark: Alt+Shift+P

/Cc @samikeijonen @rianrietveld @audrasjb (pinging you as lucky users of keyboard layouts with no backtick key)

[jasmussen]

keyboard layouts with no backtick key

Those seem like good keyboard shortcuts!

I do not mean to object at all, this is an area where I defer to the experts. However I wanted to clarify that I also do not have a backtick key:

But the keyboard shortcut still works. That is, I press Ctrl + [the key below escape], and it navigates between regions just fine. This was the suggestion I was referring to earlier — that we use that same area of the keyboard for all regions, even if the actual key varies from region to region — it may be backtick in the US and $ on danish keyboards. Is this an option in addition to the other shortcuts?