Add a basic keyboard shortcuts overview dialog

[lb-]

Is your proposal related to a problem?

There is a longer term desire to add a fully fledged keyboard shortcuts dialog, with the ability to be customised and potentially support 'quick type' actions throughout the admin. See #3949

However, we have discussed with some other core team and agreed we should start with something simple first.

This issue is to set up a very basic keyboard shortcuts overview dialog that's accessible within the Wagtail admin menu's help section.

Describe the solution you'd like

There should be a simple clickable button in the help section of the admin menu that allows the user to access a new dialog. It should have the label 'Shortcuts' and use the regex icon for now, we can enhance this later.

Inside the dialog, it should have a basic set of shortcut groups as per the schedule below.

Section	Label	Windows	MacOS (if different)
Actions	Save	Ctrl + s	⌘ + s
Actions	Preview	Ctrl + p	⌘ + p
Common actions	Copy	Ctrl + c	⌘ + c
Common actions	Cut	Ctrl + c	⌘ + c
Common actions	Paste	Ctrl + c	⌘ + c
Common actions	Paste without formatting	Ctrl + c	⌘ + c
Common actions	Undo	Ctrl + z	⌘ + z
Common actions	Redo	Ctrl + shift + c	⌘ + shift + c
Text formatting	Bold	Ctrl + b	⌘ + b
Text formatting	Italic	Ctrl + i	⌘ + i
Text formatting	Underline	Ctrl + u	⌘ + u
Text formatting	Monospace (code)	Ctrl + j	⌘ + j
Text formatting	Strike-through	Ctrl + shift + x	⌘ + shift + x
Text formatting	Superscript	Ctrl + .	⌘ + .
Text formatting	Subscript	Ctrl + ,	⌘ + ,
Text content	Insert or edit a link	Ctrl + k	⌘ + k
Text content	Insert horizontal line	---

(Also add other text content; blockquote, code block apply heading style, numbered list, bullet list)

Mockup

Beyond that we want to keep things simple, we may need to review the keyboard shortcuts on the PR and whoever picks this up should manually test them also.

Finally, we will want a way to show the meta key differently on MacOS-like devices or Windows-like.

Proposed implementation

1. Add a new menu item, something like this should be a good starting point.

wagtail/admin/wagtail_hooks.py

@hooks.register("register_help_menu_item")
def register_keyboard_shortcuts_menu_item():
    return MenuItem(
        _("Shortcuts"),
        icon_name="regex",
        order=1200,
        attrs={
            "role": "button",
            "data-a11y-dialog-show": "keyboard-shortcuts-dialog",
            "data-action": "w-action#noop:prevent:stop",
            "data-controller": "w-action",
        },
        name="keyboard-shortcuts-trigger",
        url="#",
    )

# add before @hooks.register("register_admin_menu_item")

2. Add a new template tag to link to a new shared template include

Something like below, I have not fully tested but this should be an OK starting point to pass the meta key contextually to the template.

Feel free to approach this differently.

wagtail/admin/templatetags/wagtailadmin_tags.py

@register.inclusion_tag("wagtailadmin/shared/keyboard_shortcuts_dialog.html", takes_context=True)
def keyboard_shortcuts_dialog(context):
    user_agent = context["request"].headers.get("User-Agent", "")
    is_mac = re.search(r"Mac|iPod|iPhone|iPad", user_agent)
    return {
        "meta": "⌘" if is_mac else "Ctrl",
    }

# add before @register.inclusion_tag("wagtailadmin/shared/human_readable_date.html")

3. Add the new template tag to the admin template

wagtail/admin/templates/wagtailadmin/base.html

{% extends "wagtailadmin/admin_base.html" %}
{% load wagtailadmin_tags wagtailcore_tags i18n %}

{% block furniture %}
    <template data-wagtail-sidebar-branding-logo>{% block branding_logo %}{% endblock %}</template>
    {% sidebar_props %}
    <aside id="wagtail-sidebar" class="sidebar-loading" data-wagtail-sidebar aria-label="{% trans 'Sidebar' %}"></aside>
    {% keyboard_shortcuts_dialog %}
# ...

4. The detail part, build out the initial keyboard shortcuts template content

Below is a basic starting point but it has no styles and we may want to be smarter about generating the content. It's OK if the PR for this issue has lots of repeated HTML, we want to start simple and then refine the content as we build more features.

We can probably use the tailwind classes to build out most of the styling but feel fre to add a standalone stylesheet within client/scss/components if needed.

wagtail/admin/templates/wagtailadmin/shared/keyboard_shortcuts_dialog.html

{% load wagtailadmin_tags %}
{% dialog icon_name='regex' id='keyboard-shortcuts-dialog' title=_("Keyboard shortcuts") %}
    <table class="w-w-full w-text-left">
        <caption class="w-sr-only">
            All keyboard shortcuts
        </caption>
        <thead class="w-sr-only">
            <tr>
                <th scope="col">Section</th>
                <th scope="col">Keyboard shortcut</th>
                <th scope="col">Keyboard shortcut</th>
            </tr>
        </thead>
        <tbody>
            <tr colspan="2">
                <th class="w-text-left" scope="rowgroup">Actions</th>
            </tr>
            <tr>
              <th class="w-text-left" scope="row">Save</th>
              <td><kbd>{{ meta }} + s</kbd></td>
            </tr>
            <tr>
              <th class="w-text-left"  scope="row">Preview</th>
              <td><kbd>{{ meta }} + p</kbd></td>
            </tr>
        </tbody>
        <tbody>
            <tr colspan="2">
                <th class="w-text-left" scope="rowgroup">Common actions</th>
            </tr>
            <tr>
              <th class="w-text-left" scope="row">Copy</th>
              <td><kbd>{{ meta }} + c</kbd></td>
            </tr>
            <tr>
              <th class="w-text-left" scope="row">Cut</th>
              <td><kbd>{{ meta }} + x</kbd></td>
            </tr>
            <tr>
                <th class="w-text-left" scope="row">Paste</th>
                <td><kbd>{{ meta }} + v</kbd></td>
              </tr>
        </tbody>
    </table>
{% enddialog %}

5. Unit tests

It's important there is a basic unit test for the dialog content showing in the admin template and the trigger in the menu.

Mainly to ensure that the ids of the dialog and the data attributes on the menu trigger match and both are being rendered.

Testing the menu content is a bit tricky as it's all JSON (to render the React sidebar), but there should be some tests for the dismissable 'what's new in Wagtail' attributes and we can just do something similar in new tests.

Describe alternatives you've considered

• We could do nothing, but this kind of feature has been a long requested one and it's also incredibly useful for ATAG compliance (an accessible content management system).
• We could try to solve all the desired features in one PR such as a new keyboard shortcut to trigger the modal and a standalone page but for now let's start small.

Additional context

• The keyboard shortcuts suggested above and in the Figma need to be validated, it's OK that some of those shortcuts will not work everywhere (e.g. Cmd + p is for previewing). We may look at future enhancements where context specific shortcuts can be shown but that can come later.
• Be sure to review the Figma designs for the long term goal here https://www.figma.com/proto/h67EsVXdWsfu38WGGxWfpi/Wagtail-CMS?type=design&node-id=14420-153315&viewport=6289%2C-12853%2C1&t=Sk9k7iALDZCA1bu7-0&scaling=scale-down-width&starting-point-node-id=14420%3A153315 (note that we will not be able to do that with the current base dialog but for now it's best to keep the PR simple).
• 🎛️ Replace MouseTrap usage with built in Stimulus keyboard support #10167 - This is a related issue where we want to make it easier to add keyboard shortcuts within Wagtail's admin with Stimulus. Once that issue is resolved, we can look at adding more keyboard shortcuts and then documenting them in this dialog.

Working on this

• Anyone can contribute to this.
• The aim of this issue is to be a really simple starting point, anyone with basic knowledge of the Django template system and a willingness to do a bit of manual HTML writing and checking of keyboard shortcuts should be able to do.
• Once this issue is covered, there will be much more to build on in future PRs as we work towards the final goal laid out (mostly) in Keyboard shortcut documentation for editor in the Wagtail UI #3949
• View our contributing guidelines, add a comment to the issue once you’re ready to start.

[lb-]

I will not label this a good first issue but this is a great second or third issue for someone to pick up. We have a clear goal with an implementation proposal and small scope. This involves mostly usage of Django templates and Wagtail's own hooks system.

@thibaudcolas @laymonage - feel free to edit, we want to keep the scope as small as possible though. We can build on this, as discussed, with more enhancements such as a better icon, activation of this dialog with a separate keyboard shortcuts and maybe review how this content can be customised per view but let's keep future enhancements listed on #3949

[kituuu]

@lb- Can I work on this?

[lb-]

Go for it, I think you messaged on Slack right (checking your the same person :) ) @kituuu

[kituuu]

Go for it, I think you messaged on Slack right (checking your the same person :) ) @kituuu

Thanks, I'm the same person 🙃

[kituuu]

Hey @lb-

Basic implementation is done so anyone can work on this in the future. Should I add all the shortcuts you mentioned above?

Edit: Also can you tell me more about the unit tests. What exactly do we have to check in unit tests?

[lb-]

@kituuu yes please, try to add the sections/keyboard shortcuts described in the issue.

However, I have not manually tested all these in Wagtail (specifically the text editor shortcuts). For example, I think the ctrl/CMD+K may not work yet.

The generic browser/os shortcuts like cut and paste should be good to go.

It would be great to also ensure there is some styling included. To align with the designs for the content within the dialog. Such as the table row heights, section title text, border under rows.

[lb-]

Resolved via #11717