Gutenberg: 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?

[samikeijonen]

But the keyboard shortcut still works. That is, I press Ctrl + [the key below escape]

Well I'll be damned, this works also for me! Even if the key looks different in my keyboard. I guess we can have both.

[afercia]

But the keyboard shortcut still works. That is, I press Ctrl + [the key below escape],

No, it doesn't 🙂Just to clarify again, on my Windows laptop switching between languages and keyboard layouts:

• English with US keyboard: works
• Italian with US keyboard: works
• Italian with Italian keyboard: doesn't work

[jasmussen]

I'm sorry it doesn't help that I'm not being clear. What I've been trying to say, and clearly failing at, is that it seems like it should be possible to use _the key geographically located below the escape key_ worldwide. This is a good _geographical_ location because it's close to tab which is often used for related navigation, and it's a convenient location for such a powerful feature.

It happens to work in the US, and in Denmark, and perhaps in Finland as well? We would need an array of key combinations for each language. Based on this image (correct me if I'm wrong), we'd want to support Ctrl+~ for it to work on Italian keyboards.

I know this is extra work to make this work across locales, and indeed it may not be worth it. But I wanted to make sure my point was understood.

[afercia]

When I switch to the Italian keyboard layout, that key becomes the backslash key \. https://it.wikipedia.org/wiki/File:Italian_Keyboard_layout.svg

My personal opinion is that given the multitude of keyboard layouts and also the fact sometimes vendors implement non-standard layouts, this is going to be a can of worms 🙂

You can check how that key differs in the various QWERTY layouts here: https://en.wikipedia.org/wiki/QWERTY
There's a great variety. Also, Spanish is different from Latin American Spanish, Portuguese is different from Brazilian, etc. French and Belgian layouts are different, not to mention languages with non-latin alphabets.

[afercia]

Additional keyboard shortcuts for the "navigate regions" component have been added in #8005. This solves the immediate problem with the backtick key not present on all the keyboard layouts. Introducing a mechanism to customize shortcuts is still a nice idea for the future tough. Moving to the ideas project.

[afercia]

Quick update: just noticed the Ctrl + backtick shortcut can't work on Opera (mac) because it's used by the browser:

One more proof that shortcuts conflicts are very likely to happen and there's no reliable way to have "conflict-free" shortcuts.

[afercia]

Related: https://wordpress.org/support/topic/modifying-shortcuts-in-gutenberg/

[Betinadts]

I am going through the whole topic, but I have already checked and:

• Ctrl+backtick doesn't work for Bulgarian/English language;
• Alt+Shift+1/2/3/4 also doesn't work for Bulgarian/English language;

I definitely need to find some way for using Alt+Shift+number combination, because using the mouse for choosing every single heading is a disaster.
Chrome @ Windows
Wordpress 5.1.1.

[Betinadts]

I really do not understand where exactly did my comment go.
I will upload a screenshot of the issue that I want to address. I just need to have the option to use shortcut for headings again, not clicking the mouse for every single heading in every blog post or etc.

I have already tried using Ctrl+backtick for Bulgarian language - it doesn't work.
The same for Alt+Shift+any number.
Chrome @ Windows

[mtias]

We should start discussing some ideas for what UI to use for customizing the shortcuts — should it be within the editor? Separately? Should it be extensible? (I could imagine a plugin or a configuration set people could pull from the repo for, say, a good set of shortcuts for a Spanish keyboard layout on Mac, and so on.)

[mariohamann]

I think it's a great idea to make it possible to change keyboard shortcuts. (Using a German Keyboard I often encounter problems as well...).

I would like to raise the question, how users can sync their personal settings between different WordPress instances? JSON export and import? Sync them additionally to Local Storage? (But can Local Storage be accessed from different domains? I don't think so.)

(Of course on WordPress.com/with Jetpack it could be stored in WordPress.com account.
<vision_mode>Maybe a neutral and GPDR-compliant "Gutenberg-Cloud-Account" could help, which saves settings like Keyboard settings, fullscreen mode, sidebar-settings etc. as well and could even be used on Drupal etc. :) After opening Gutenberg in a WP instance for the first time, it could directly ask for the account. But that's definitely out of scope of this issue...</vision_mode>)

[afercia]

Saving user settings in Local Storage isn't ideal and shows more and more its limits. I think there's a project somewhere to ditch this pattern and save user settings in the database instead, as it should had been since the beginning. Not sure about the progress there but I think it should be prioritized.

[enriquesanchez]

Here's a prototype of a flow that looks to address customizing keyboard shortcuts on its most basic form.

I'm purposely using the most recent design iterations @karmatosed has been working on for #24965 as the frame for this new feature, as I think the new Options or Preferences modal will be a good place for the keyboard shortcuts UI to live. That said, please don't pay too much attention to the menu on the left, for now let's just focus on keyboard shortcuts.

The flow goes over a few basic actions:

1. Display all keyboard shortcuts
2. Edit/customize a keyboard shortcut
3. Disable a keyboard shortcut
4. Restore defaults

I'm also considering that this will be an important feature for keyboard and assistive technology users, so I want to make sure that we keep it simple and obvious.

I'd love to hear your feedback:

• Is this flow intuitive?
• Am I missing an action or feature?
• From an a11y perspective, are we making it easy for keyboard and assistive technology users to customize their keyboard shortcuts?

---

In addition to the flow above, I also explored a different layout for displaying the list of keyboard shortcuts:

| Labels on left, shortcuts on right | Shortcuts on left, labels on right |
|------------|--------------|
| | |

I lean towards labels on left, shortcuts on right, since this is a common a well-established pattern but would also like to hear your thoughts. Which one do you find easier to read and scan?

[alexstine]

@enriquesanchez

I lean towards labels on left, shortcuts on right, since this is a common a well-established pattern but would also like to hear your thoughts. Which one do you find easier to read and scan?

Perfect layout. Question is, how will the shortcuts be displayed? E.g. on the right where you select a shortcut, will that be a checkbox, radio, or select field?

Thanks.

[enriquesanchez]

Thank you, @alexstine!

Question is, how will the shortcuts be displayed?

I'm proposing to have the keyboard shortcuts displayed very similar to how they currently appear in the 'Options' menu of the block editor, but I have a few additional elements on the prototype.

There is a heading on top that reads "Keyboard shortcuts" followed by a short description text. This text reads: "You can edit shortcuts and customize them to your needs, or leave them empty to disable."

Following that there's a text button that reads "Restore defaults". The intention for this option is that if you make some changes to your keyboard shortcuts and need or want to restore them back to the initial state, you can just click this button and all shortcuts will restore to the default value.

Then the shortcuts appear as a list, with the label/description on the left, followed by the shortcut key combination to the right, in the same row. My proposal also adds a pencil icon button to the right next to the shortcut keys. Clicking on the pencil icon button displays a text input field that comes pre-filled with the shortcut combination. The shortcut combination is also pre-selected so you can easily start typing and replace it.

As you type the new desired shortcut keys combination, the characters appear in the input field. Next to the input field, there is a 'Save' text button and a 'Cancel' icon button. If you select 'Save', then the new shortcut key combination will be recorded and appear in place of the previous one.

I'm also proposing that in addition to changing the shortcut key combination, you can also leave the field empty and select 'Save' in order to have a shortcut key disabled. If you do this, the shortcut key combination that we display is replaced by a text label that reads 'Disabled'.

How does this flow feel to you? Is it intuitive enough? Are there any options or features missing from this flow?

[alexstine]

@enriquesanchez I think that flow is perfect. Thanks for explaining it.

I like the most how you are able to focus on one shortcut at a time instead of having a big list of shortcuts with text fields. You intentionally need to click on Edit button first per shortcut.

How might conflicts be handled? E.g. setting shortcut 1 to X and shortcut 2 to X. Will there be some type of alert?

Thanks.

[afercia]

Thanks so much for the proposal and to help this issue finally move on.

Very first observations:

• Besides the global "Restore defaults" button I think there's the need for a button for each single shortcut. As a user, I might want to reset a single, specific, keyboard shortcut to its defaults and not lose all the other custom shortcuts I previously set. Intead, the current UI allows only to reset them all or none.
• We should avoid icon-only buttons and use buttons with visible text instead. Icon-only controls are an accessibility anti-pattern and we shouldn't use it, at least here since this is a user interface mainly targeted to users with accessibility needs. The "edit" icon for example should be replaced with plain, visible, text: "Edit".
• Regarding "As you type the new desired shortcut keys combination, the characters appear in the input field" we need to consider that on Windows the modifier keys don't use single characters. They're plain text for "Ctrl", "Shift", "Alt"... so this would need a different technical mechanism but also the design should account for that. Screenshot of the current keyboard shortcuts list on Windows:

I have some reservations on the following things:

• The input field to enter a custom shortcut appears _and replaces_ part of the UI: the accessibility team already pointed out this isn't a good pattern (see for example the discussion on the toolbars). It would be worth considering a disclosure pattern instead: click the Edit button, an input field is revealed after the Edit button _in addition_ to the other UI elements.
• The "Save" and "Cancel" buttons displayed inside the input field look weird to me and are potentially confusing for users. Besides details on technical implementation, I don't see the need to display them this way and I'd encourage a more standard, expected, placement of these buttons.
• The "Cancel" button is another icon-only button which uses a "X". Besides the fact that the "X" suggests the idea of "closing" instead of "cancelling", also this button should use plain text instead of an icon.

Re: @alexstine's concern on conflicts: yes there should be a mechanism to detect conflicts and warn users that a keyboard shortcut is already in use. I think this is technically doable but yep, it's about implementation details while we're still on the initial design phase 🙂

[enriquesanchez]

Thank you for the feedback, @alexstine and @afercia! Here's an iteration on the design that addressed some of the points you made.

Since we'd want to have the options to Edit, Disable and Restore for each individual keyboard shortcut, I'm looking at having these options surfaced in a popover menu instead:

_The image above shows a list of keyboard shortcuts. For each item, there's a label/description on the left followed by the shortcut keys to the right in the same row. Next to that, there's an ellipsis menu button, similar to what's found in the editor and block toolbars. On one of these keyoard shortcuts, the ellipsis menu button is activated and a popover with three menu items appears below it: 'Edit shortcut, 'Disable shortcut', and 'Restore to default'. That last one, 'Restore to default' should only appear when/if the keyboard shortcut has been customized._

If I were to click on 'Edit shortcut', a dialog would appear in place. I agree with you @afercia, that this dialog should not replace any content. What I'm proposing is that the dialog sits on top and aligned with the keybord shortcut row for clarity and proximity. What I like about this solution is that the shortcut label/description is kept visible, so it's easier to correlate the two.

_The image above shows a UI dialog that contains an input field with the keyboard shortcut combination, and a Save and Cancel buttons to the right of it._

As for conflicts, I think we need to show an error message in place, near the input field. Here's what I'm proposing:

_The image above shows the previous UI dialog that appears when editing a shortcut. The input field has a red border around it to indicate an error state, and below it there's an error message that reads "This shortcut is already being used.". The 'Save' button is in a disabled state because the action cannot be performed._

---

What do you think about this iteration? I believe it addressed the feedback your brought up.

[alexstine]

@enriquesanchez Sorry, now I am gonna be difficult.

Since we'd want to have the options to Edit, Disable and Restore for each individual keyboard shortcut, I'm looking at having these options surfaced in a popover menu instead:

From my point of view, I think a menu inside a dialog is not a good idea. It adds another required selection to get in to the menu and then find edit, delete, or restore. Anyway to just not put those in a menu?

I can see both sides... It will probably not fit well on smaller screens, but just something to think about.

Thanks.

[enriquesanchez]

Sorry, now I am gonna be difficult.

Not at all @alexstine, I really appreciate your feedback and understand your point.

My reasoning for having these three options inside a menu was that having them exposed and repeating in every row, in a list of dozens of shortcuts, will add a lot of clutter and visual noise. That can make this UI hard to parse for some folks.

I'll definitively look at alternatives. One idea I had initially but haven't fully explored is to have these options exposed once you click on the 'Edit' button for the shortcut. We'll need a bigger dialog to fit everything, but I think it's worth a try.

[kellychoffman]

Latest iteration feels close. Couple details to consider, but aren't blockers:

• Popovers/modals usually have the CTA button (Save) to the far right.
• Inline error message might be a bit awkward interaction in that the container has to resize for it to show. Might be worth exploring some other options here. A couple ideas that come to mind: have helper/instructional text in its place that gets replaced with the error msg, have the error show as a banner error on Save attempt, or something else.

[mariohamann]

• Popovers/modals usually have the CTA button (Save) to the far right.

@kellychoffman To focus on the keyboard settings in this issue, I wrote a more general answer over here: https://github.com/WordPress/gutenberg/issues/24965#issuecomment-706520051

In short: I think Save-Buttons could be used contextually in relation to the preference category. Maybe keyboard settings could profit from one general Save button. What is better accessible? One single Save button or a save button for every shortcut? (Maybe that relates to the question when and where conflict errors should show up.)

[enriquesanchez]

@mariohamann This is great feedback Mario. Thank you!

Maybe keyboard settings could profit from one general Save button. What is better accessible?

I think it depends. If I'm only going to change one keyboard shortcut, then having the confirm button right there next to the shortcut field is definitively easier for most folks. I wouldn't have to navigate to find the Save button somewhere else below the list.

If I were to be changing a lot of these shortcuts, then maybe having only one Save button will be easier. That said, I suspect the latter will be the least common case here, and we should optimize for single-edit actions.

[enriquesanchez]

• Popovers/modals usually have the CTA button (Save) to the far right.
• Inline error message might be a bit awkward interaction in that the container has to resize for it to show. Might be worth exploring some other options here

Thank you! Here are some iterations that address your feedback, @kellychoffman

I like the direction of using the default notices banner we use elsewhere. The notice is prominent and because it appears inside the modal, it's near where the error happens. There's also the benefit that these notices get properly communicated to assistive technologies with wp.a11y.speak().

---

I also explored alternatives on how to access the editing options (Customize, Disable, and Restore). In the previous exploration I looked at having a dropdown menu next to each shortcut with the three options:

_The image above shows a list of keyboard shortcuts. For each item, there's a label/description on the left followed by the shortcut keys to the right in the same row. Next to that, there's an ellipsis menu button, similar to what's found in the editor and block toolbars. On one of these keyoard shortcuts, the ellipsis menu button is activated and a popover with three menu items appears below it: 'Edit shortcut, 'Disable shortcut', and 'Restore to default'._

This time I looked at how we could condense all three actions into a single dialog:

_The image above shows a list of keyboard shortcuts. For each item, there's a label/description on the left followed by the shortcut keys to the right in the same row. Next to that, there's an Edit menu button. On one of these keyboard shortcuts, the Edit button is activated and a dialog sits right under it. The dialog has a text field with the shortcut key. This is where the user will be able to customize the shortcut. Below this text field, there's a toggle control with the label 'Disable shortcut'. This is the control users will activate if they want to diable the keyboard shortcut. Below follows a row of three buttons. The first one is 'Restore to default', which should only appear if the shortcut has been customized. Then follows 'Cancel' and 'Save'._

I'm torn between these two. On the one hand, I like the clarity of choices on the previous version and how it keeps the edit dialog minimal. But on the other, I like how this last exploration simplifies the flow by just offering one choice to make up front.

I'd love to hear your feedback or suggestions.

[mariohamann]

Really like those explorations. I would like to add some thoughts about the visuals, I hope that's fine:

• Notices banner: Personally I have the feeling the notice could deserve a bit more margin especially to the top. It feels a bit "urged". Maybe using the same margin as for the title (like "Keyboard shortcuts") would be fine, so it visually "replaces" the title?
• Really love the last one. I would prefer the dialog field appearing ABOVE the edit button if there is enough space. As the shortcut is definetely changed with keyboard, the next possible interaction with the mouse would be clicking the "Save" button. Therefore, if the dialog appears above, the way with the mouse to the "Save" button is much shorter.
• Another thing I'm asking myself: Would it support the process, if the shortcut being edited at the moment would be more emphasized (or the others being more reduced?). I think the current "blue" may be too decent to indicate the current state – especially in terms of a11y. Next image shows two ideas: The first one making the other non-selected items more transparent, the second one inverting the clicked button. The latter feels better for me. You can give it a try over here on Figma: https://www.figma.com/proto/WwbLC4uG5BGW38ZlCRh9uz/Preferences?node-id=8%3A66&viewport=-1374%2C108%2C0.36925479769706726&scaling=scale-down

Mockup of all three suggestions below.

[enriquesanchez]

Here's one last update from me on this issue.

I've made some minor updates to the flow:

• Reduced the amount of UI: I’m no longer using a popover inside the modal (thanks @alexstine for the feedback on this!)
• Simplified a few actions such as restoring and disabling shortcuts: removed the buttons and toggles I was previously using. Added some clarification to the section's description on these: _"These are the keyboard shortcuts available in the block editor. You can customize them to your needs or leave the field empty to disable them."_
• I’m now using the current shortcuts modal in the block editor to have a clearer picture of where these will live.

Here's a GIF of the updated prototype:

And some static mockups for a more detailed overview:

_Description: The image above shows the keyboard shortcuts modal open in the block editor. The modal contains a list of all the shortcuts available and next to each an edit button (a pencil icon)._

---

_Description: Clicking the edit button for any of the shortcuts will display inline a text field with the currently assigned shortcut. Users can enter a different shortcut if needed. There is a save button next to the field._

---

_Description: If the user enters a shortcut that is already being used, we display an error message "Shortcut already in use." below the field and highlight the field in red. This error message needs to also be communicated to Assistive technologies._

---

_Description: If a field is left empty, the shortcut is disabled and a label "None" appears in place of the shortcut. Once a shortcut has been edited/modified, we display a little dot indicating that the shortcut has been customized. This should help uses keep track of which shortcuts they've modified. The dot should include a tooltip for clarity and this state change should also be communicated to assistive technologies._

If we find that the dot does not work here, we can also opt for an asterisk instead:

---

_Description: A shortcut that has already been modified will show an additional "Restore" button when editing it. This restore button will appear next to the Save button. Clicking on restore returns the shortcut to the default value and closes the edit field._

---

I think the above is in a good place to try for a v1 of this feature. I did not spend much time on this, but for a follow up effort it'll be great to consider @mtias suggestion:

Should it be extensible? (I could imagine a plugin or a configuration set people could pull from the repo for, say, a good set of shortcuts for a Spanish keyboard layout on Mac, and so on.)

This could be as simple as adding an option to import a key bindings configuration:

_Description: The image above shows the same keyboard shortcuts modal from this proposal with an additional button that says "Import configuration" just below the modal's description._

If we give this option to users, we should also offer a way for users to restore and go back to defaults.

---

And lastly, I also mocked up what the keyboard flow for this feaure will look like. Considering that this will be a feature that will greatly benefit keyboard users and users of assistive technologies, I thought it'll be important to consider how the flow will work in that scenario:

_Description: the gif above shows the keyboard focus flow of the same shortucts modal described above. It's a step by step flow of each focus stop needed to customize one shortcut field.

[mariohamann]

Really like those explorations!
At one point of your
last GIF I was a bit irritated: After having "written" a new shortcut, I would have expected to use return key to save it. In your GIF you are using tab to get to save button instead. I think you needed this to make it possible to reach the button to revert a setting? Otherwise I definitely would expect to press "return" to save shortcut and to press "escape" to forget new shortcut.

[mariohamann]

What do you think about directly using an "Undo" icon to indicate changes and make it reversable? (Raised the space between "Undo" and "Edit" icon a bit in the following screenshot.)

That would even make the "Edit" flow cleaner, as the "Undo" there wouldn't be needed anymore. (In my opinion clicking outside of the edit area or pressing esc would revert the _current_ changes as well.