Keyboard shortcut documentation for editor in the Wagtail UI

[tmsndrs]

Is your proposal related to a problem?

As part of the ATAG guidelines.

(Guideline A.3.1) (For the authoring tool user interface) Provide keyboard access to authoring features.

We want to work towards a fully compliant, customisable and flexible keyboard shortcut system within Wagtail.

At this time, there are some undocumented keyboard shortcuts, some browser 'default' shortcuts and lots of available shortcuts in Draftail.

These, however, are hard to discover and we would like to improve this.

Describe the solution you'd like

As per the comments below, here are some mockups for how a shortcuts panel could work.

Access from the Help menu (help users to learn the command to toggle the panel to negate the need to access it from this menu):

Panel:

• Scrollable
• Considered making it searchable, but decided to keep things simple for now
• Link out to the full documentation
• Prioritise Wagtail specific commands (currently only 2, bit would be great to add more here eg: Duplicate block, Move block up/down, Add block (outside of richtext), Collapse/Expand block/field, Collapse/Expand all, Toggle comments panel, Toggle status panel, Toggle Minimap ...
• Prototype here (use ⌘ + /) to open the panel in Figma

Tasks

• Adopt a Stimulus controller approach to add keyboard shortcuts to specific elements - 🎛️ Replace MouseTrap usage with built in Stimulus keyboard support #10167
• Enhance the Stimulus controller to allow for a tooltip on hover to show the relevant keyboard shortcut on elements that have it.
• Ensure that there is a way to allow a keyboard shortcut to trigger globally, even in text input, via a Stimulus attribute. Add ability to make a keyboard shortcut global with the Stimulus KeyboardController/w-kbd #11844
• Migrate any other existing (non-Draftail) keyboard shortcuts to the Stimulus approach, or some other mechanism so a central registry on the client can be used if needed in the future.
• Add a keyboard shortcut for the sidebar opening/closing (likely [/])
• Add a keyboard shortcut for the minimap, when available, opening/closing + some other side panel keyboard shortcuts, global open/closing of panels. More in the solution above.
• Add a very basic, starting point, keyboard shortcut overview dialog Add a basic keyboard shortcuts overview dialog #11711
• Enhance the keyboard shortcuts dialog with a more suitable 'keyboard' icon Update keyboard shortcuts menu button & dialog icon to a new 'keyboard' icon #11767
• Add a way to trigger the keyboard shortcut dialog with a keyboard shortcut (either cmd + / or shift + / or both) & include on the dialog itself
• Once the editor's guide has the keyboard shortcuts documented on a page, link to that page in the dialog - see Rich Text Keyboard Shortcuts  guide#368 & New content: Page-level keyboard shortcuts guide#346
• Develop a way to ensure that the keyboard shortcut (groups?) only show on admin pages where they are relevant (needs discussion on implementation, could be a simple template block approach or a more complex hooks or JS approach), once built, we should ensure that the existing admin code adopts this and also document.
• Make the content within the keyboard shortcut dialog searchable with a simple text field and filtering/highlighting, this can be done with an existing Stimulus controller or something new if needed.
• Long term: Add support for 'activating' the action that the keyboard shortcut has. E.g. you could activate the minimap by opening the keyboard shortcuts dialog and clicking the minimap action. At this point we may want to raise a new issue as this is more of a 'slash commands' for global actions feature and will need more thought.

Describe alternatives you've considered

• This seems to be a long term direction and we would like to see this in place, in some form, in a future release in Wagtail.

Additional context

• Many fixes to keyboard shortcuts within the rich text editor update were fixed (issues documented Rich text areas swallowing keyboard shortcut events #2191 ).
• Very early mockup from the original issue below.

Working on this

• For now, we will split out smaller issues for others to pick up either within the core team or other contributors.

[tmsndrs]

Note: I haven't thought about how this modal would be launched yet because I'm unclear if we'll have one set of shortcuts (preferable from a UX perspective I think) or different shortcuts within different parts of the UI.

[lb-]

Just adding some basic research into what other popular web applications do in regards activation of keyboard shortcuts modal (via a keyboard shortcut).

It seems that Medium's modal is the only one that can actually be activated within a text box that the user has focus on.

Medium

• Open Shortcuts Modal ⌘ + ? / Ctrl + ?
• Close Shortcuts Modal ⌘ + ? / Ctrl + ? not Escape
• Works if you are in the middle of writing text or not.
• Note: Great interface, simple and lets you slide to more advanced shortcuts and small animations on how to do basic things like format text.
• https://help.medium.com/hc/en-us/articles/214672207-Keyboard-shortcuts

Inbox by Google, Google Drive, Gmail

• Open Shortcuts Modal Shift + ?
• Close Shortcuts Modal Esc
• Disabled when inside a text box.
• https://support.google.com/mail/answer/6594?hl=en-GB

Trello

• Open Shortcuts Modal Shift + ?
• Close Shortcuts Modal Esc
• Disabled when writing inside a text box.
• http://help.trello.com/article/798-using-keyboard-shortcuts-in-trello

Github

• Open Shortcuts Modal Shift + ?
• Close Shortcuts Modal Esc
• Disabled when writing inside a text box.
• https://help.github.com/articles/using-keyboard-shortcuts/

[thibaudcolas]

Here is the list of keyboard shortcuts supported by Draftail, heavily inspired by Google Docs: https://github.com/springload/draftail/tree/master/docs#keyboard-shortcuts.

I foresee problems integrating this with the rich text editor because the shortcuts would need to change depending on:

• Which editor is used on the current page
• Which rich text features are enabled on the current editor(s)

I imagine we could easily circumvent this though by having some way for rich text editors to hook into the "show keyboard shortcuts" modal, and insert the relevant shortcuts when people are triggering this from a given rich text editor.

[thibaudcolas]

It's easier to see how this could work with the improvements done over the last few months:

• The shortcut modal opens with a keyboard shortcut like in examples above
• By default it display's "Wagtail's" shortcuts like in the original screenshot

For rich text shortcuts,

• The shortcut screen hooks into the new "rich text features" API.
• Editors implementing a given rich text feature can define the corresponding shortcut.
• When the shortcut modal opens, if there are rich text features active on the page it grabs these and displays them in a separate section for each active editor.

---

I think we could start with only the "default Wagtail shortcuts" modal, then expand to rich text shortcuts later on. If someone is interested in implementing this with React, I'm more than happy to give plenty of guidance.

[SalahAdDin]

@thibaudcolas More documentation for Wagtail 2.0

[thibaudcolas]

@SalahAdDin there's now a list of all Draftail keyboard shortcuts over at https://www.draftail.org/docs/keyboard-shortcuts (which is referenced in the official Wagtail docs).

[phildexter]

@thibaudcolas

Could we have this on hover?

Miro does this nicely. When you hover over an icon it shows you the shortcut.

Airtable also do this nicely

I think we could do a similar thing in Wagtail. When you hover over the Save or Preview buttons we show the shortcut then? This would help with discoverability of these shortcuts too and could be rolled out elsewhere if we brought more in.

[thibaudcolas]

I like the idea! Especially considering it’s what Draftail already does, at least for shortcuts that are associated with buttons.

Do you think it needs further design or would we just replicate the pattern from Draftail elsewhere?

[phildexter]

Lovely, thanks @thibaudcolas !

@benenright what do you think? Are you happy with this approach? If so shall I get some designs done that we can pass by you, or maybe you could do the designs?

[allcaps]

This is the way Slack presents keyboard shortcuts. I like it.

Slack has some nice details:

• Main heading in combination with the toggle shortcut. Press Cmd/ to toggle this panel.
• Shortcuts grouped per section. Basics, Navigation, et cetera
• The description is sometimes a link to perform the same action.
• There is an ? icon for additional information.

Some keyboard shortcuts do not have a visible element:

• Scroll up/down
• Move focus to next/previous section
• Undo/redo
• ...

Wagtail can have those as well. They can only be communicated by a 'cheat sheet' as there is no element to hover.

I think a cheat sheet is the best solution because:

• An overview of all shortcuts is the only way to learn all shortcuts
• A centralised place to display all shortcuts is the best way to hook in custom or third party shortcuts.
• Supports shortcuts that do not have a visible element.

I'd like to help and make the cheat sheet happen. Especially the part where integrators and third parties can hook their own shortcuts to the cheat sheet.

[phildexter]

That's great feedback @allcaps. Especially the part about allowing third parties to be able to hook in too. I think a cheat sheet would be useful, but perhaps we could even do both (show some in context where it's useful, but all in the cheat sheet).

The more interesting issue for me is the inconsistency with which the existing shortcuts work for save and print. Cmd+P often opens the print dialogue, and Cmd+S tries to save the page. I realise now that this is because of where I'm focusing - if I click on the top of the page near the title and use the shortcuts it is fine. If I am editing a field and then try then it doesn't work.

This isn't great, as the majority of the time you'll want to save or preview once you've just made an edit. I think we shouldn't promote these shortcuts until we figure out a way to make this more consistent, otherwise we risk detracting from Wagtail overall (Kano model theory).

[allcaps]

Before I forget, shortcuts may be different per operating system.

[thibaudcolas]

Interesting approach from Facebook, which has the same problem of "shortcuts are different depending on where you are in the app": https://engineering.fb.com/web/facebook-com-accessibility/

[Stormheg]

We discussed having keyboard shortcuts in our accessibility team meeting today. There is definitely interest in having this, first step would probably be to create a cheat sheet panel like in Tom's mockup and some way to register them.

There is also the issue that many areas of Wagtail are not currently useable with a keyboard. This is an accessibility issue that we are working on 😅

[lb-]

Updated discussion happening in UI chat on slack.

• What if we added a global keyboard shortcut to expand/collapse sidebar - [ Trello uses this (and uses ] for the right settings side panel). Update: so does Jira.
• Good feedback on this idea and again general push towards more keyboard shortcuts would be good.
• PR up to do a bit of house cleaning for our current minimal shortcuts approach (note: this is for non-draftail shortcuts) Rework existing page editor shortcuts behaviour to be easier to build on #8900
• @tomdyson feedback - I increasingly like the ‘command key’ style of keyboard shortcuts, e.g. mod-k for Github and Slack or mod-shift-p in VS Code, where you have one shortcut for bringing up a context-aware modal with type-ahead search on other actions.
• @Stormheg feedback - Would be nice to have some kind of ‘quickly jump to’ functionality like that in Wagtail.

[lb-]

Good article on deciding on keyboard shortcuts
https://stackoverflow.com/questions/4173707/best-practices-for-designing-keyboard-shortcuts

Also

https://www.commandbar.com/blog/selecting-keyboard-shortcuts-for-your-app

[lb-]

Good reference for common web application keyboard shortcuts https://usethekeyboard.com/

[lb-]

See also. https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey

Note. It's not recommended to use this but it's a good reference for naming things if we did our own data attributes approach.

E.g. data-controller="w-accesskey"

[laymonage]

A suggestion came up in our Wagtail+Next.js workshop:

...in the admin editor I love that CTRL+S saves the page. Anyone know the keyboard shortcut for 'Publish' - CTRL+P is the preview

The fact that we don't document the shortcuts (yet people find them anyway) suggests that there's some expectation for this to be useful, so I think this will definitely be a great addition 👍

[benenright]

Here are some mockups for how a shortcuts panel could work.

Access from the Help menu (help users to learn the command to toggle the panel to negate the need to access it from this menu):

Panel:

• Scrollable
• Considered making it searchable, but decided to keep things simple for now
• Link out to the full documentation
• Prioritise Wagtail specific commands (currently only 2, bit would be great to add more here eg: Duplicate block, Move block up/down, Add block (outside of richtext), Collapse/Expand block/field, Collapse/Expand all, Toggle comments panel, Toggle status panel, Toggle Minimap ...
• Prototype here (use ⌘ + /) to open the panel in Figma

[lb-]

As I know we will want to tackle the keyboard shortcuts stuff better in the coming release or so I have updated the Stimulus adoption issue to be both simpler to use in our DOM and avoids waiting on a Stimulus PR to be merged.

#10167 (comment)

The HTML data attributes to use a keyboard shortcut on any button would be something like; data-controller="w-kbd" data-w-kbd-key="mod+/".

Once that issue has a PR and is merged we can look at a way to collate these controlled elements and their keyboard shortcuts into data and present these in a keyboard shortcut modal. This data would need to incorporate the RichText shortcuts but that should not be too complex.

Still a while off but I feel there is a path forward.

[thibaudcolas]

We’ve discussed this with @lb- and @laymonage today, just noting we’re keen to proceed with the above designs with hard-coded content if anyone wants to contribute to this but feels daunted by the scope of having to register shortcuts.

[lb-]

Great, I might raise a new issue that covers this smaller scope with a bit of direction, hopefully with enough detail for a new-ish contributor to work with.

[lb-]

#11711 has been raised for a very basic initial version of the keyboard shortcuts dialog.

I have also updated this issue's description with a bit of an action plan and links to other issues that have already been created.

I am happy to help anyone that wants to contribute to this with some direction on what to work on or where to help.

[lb-]

@benenright - any chance you could add a comment with the keyboard icon svg?

[lb-]

We may also want to consider some guidelines in our documentation for how to create accessible keyboard shortcuts.

See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts

Also, the guidelines on that MDN page advise against overriding common browser shortcuts such as ctrl+p (for print). Which we do today for the preview tab.

We probably should be careful to document keyboard shortcuts that may not be good practice.

Thoughts @thibaudcolas ?

[lb-]

Also adding this comment from @zerolab

I stumbled upon https://github.com/ai/keyux the other day and thought of this issue (source)

It's a nice looking library that also has some great documentation on how to make accessible keyboard shortcuts.

[lb-]

#11740 has been merged & #10167 has been closed.

The next steps can be started if anyone is keen, specifically adding a new set of keyboard shortcuts for the sidebar, Minimap and the keyboard shortcuts dialog.

Post here if you want to pick something up and I can create an issue with some clear steps.

[NXPY123]

I'm interested in working on this. Adding shortcuts for the Minimap and keyboard shortcuts dialog sounds interesting.

[lb-]

One new issue created @NXPY123 - slightly different thing but it's something that would be helpful for the usage of these keyboard shortcuts.

#11844

FYI @zerolab and @allcaps (I know you Coen raised this concern in one of your other reviews).