Skip to content

A platform for community discussion. Free, open, simple.

A11Y: improvements to the keyboard shortcuts modal for screenreaders (#40038)

Krisd71878163f0b
diff --git a/app/assets/stylesheets/common/components/keyboard_shortcuts.scss b/app/assets/stylesheets/common/components/keyboard_shortcuts.scss
index 47630ad8ec9..646a680167e 100644
--- a/app/assets/stylesheets/common/components/keyboard_shortcuts.scss
+++ b/app/assets/stylesheets/common/components/keyboard_shortcuts.scss
@@ -43,6 +43,7 @@
font-size: var(--font-0);
background-color: var(--primary-very-low);
padding: 0.5rem 1rem;
+ margin: 0;
}
}
@@ -78,19 +79,27 @@
}
}
- ul {
- list-style: none;
- margin: 0;
+ table {
+ border-collapse: collapse;
+ width: 100%;
+ }
- li {
- align-items: center;
- display: flex;
- flex-wrap: nowrap;
- flex-direction: row-reverse;
- justify-content: space-between;
- border-bottom: 1px solid var(--content-border-color);
- padding: 0.25rem 1rem;
- }
+ tbody tr {
+ border-bottom: 1px solid var(--content-border-color);
+ }
+
+ td {
+ padding: 0.25rem 1rem;
+ vertical-align: middle;
+ }
+
+ .shortcut-description {
+ width: 100%;
+ }
+
+ .shortcut-key {
+ text-align: right;
+ white-space: nowrap;
span {
border-radius: 3px;
@@ -111,10 +120,10 @@
display: revert;
text-align: right;
}
+ }
- kbd {
- font-family: var(--d-font-family--monospace);
- font-weight: bold;
- }
+ kbd {
+ font-family: var(--d-font-family--monospace);
+ font-weight: bold;
}
}
diff --git a/config/locales/client.en.yml b/config/locales/client.en.yml
index 429cb4f4b51..6d6240f91af 100644
--- a/config/locales/client.en.yml
+++ b/config/locales/client.en.yml
@@ -5431,110 +5431,119 @@ en:
title: "Keyboard Shortcuts"
short_title: "Shortcuts"
search_ctrl_f_tip: "To search across this entire forum, press <kbd>/</kbd>"
+ description_header: "Description"
+ key_header: "Key"
+ search_aliases:
+ shift: "shift"
+ alt: "alt option"
+ meta: "meta cmd command win windows super"
+ ctrl: "ctrl control"
+ enter: "enter return"
+ esc: "esc escape"
jump_to:
title: "Jump To"
- home: "%{shortcut} Home"
- latest: "%{shortcut} Latest"
- new: "%{shortcut} New"
- unread: "%{shortcut} Unread"
- unseen: "%{shortcut} Unseen"
- categories: "%{shortcut} Categories"
- top: "%{shortcut} Top"
- bookmarks: "%{shortcut} Bookmarks"
- profile: "%{shortcut} Profile"
- messages: "%{shortcut} Messages"
- drafts: "%{shortcut} Drafts"
- next: "%{shortcut} Next Topic"
- previous: "%{shortcut} Previous Topic"
+ home: "Home"
+ latest: "Latest"
+ new: "New"
+ unread: "Unread"
+ unseen: "Unseen"
+ categories: "Categories"
+ top: "Top"
+ bookmarks: "Bookmarks"
+ profile: "Profile"
+ messages: "Messages"
+ drafts: "Drafts"
+ next: "Next Topic"
+ previous: "Previous Topic"
navigation:
title: "Navigation"
- jump: "%{shortcut} Go to post #"
- back: "%{shortcut} Back"
- up_down: "%{shortcut} Move selection &uarr; &darr;"
- open: "%{shortcut} Open selected topic"
- open_new_window: "%{shortcut} Open selected topic in new tab/window"
- next_prev: "%{shortcut} Next/previous section"
- go_to_unread_post: "%{shortcut} Go to the first unread post"
+ jump: "Go to post #"
+ back: "Back"
+ up_down: "Move selection &uarr; &darr;"
+ open: "Open selected topic"
+ open_new_window: "Open selected topic in new tab/window"
+ next_prev: "Next/previous section"
+ go_to_unread_post: "Go to the first unread post"
application:
title: "Application"
- create: "%{shortcut} Create a new topic or personal message"
- notifications: "%{shortcut} Open notifications"
- hamburger_menu: "%{shortcut} Open navigation menu"
- user_profile_menu: "%{shortcut} Open user menu"
- show_incoming_updated_topics: "%{shortcut} Show updated topics"
- search: "%{shortcut} Search"
- filter_sidebar: "%{shortcut} Filter sidebar"
- help: "%{shortcut} Open keyboard help"
- toggle_bulk_select: "%{shortcut} Toggle bulk select"
- dismiss: "%{shortcut} Dismiss selected topics"
- x: "%{shortcut} Toggle selection (in bulk select mode)"
- log_out: "%{shortcut} Log Out"
+ create: "Create a new topic or personal message"
+ notifications: "Open notifications"
+ hamburger_menu: "Open navigation menu"
+ user_profile_menu: "Open user menu"
+ show_incoming_updated_topics: "Show updated topics"
+ search: "Search"
+ filter_sidebar: "Filter sidebar"
+ help: "Open keyboard help"
+ toggle_bulk_select: "Toggle bulk select"
+ dismiss: "Dismiss selected topics"
+ x: "Toggle selection (in bulk select mode)"
+ log_out: "Log Out"
composing:
title: "Composing"
- return: "%{shortcut} Return to composer"
- minimize: "%{shortcut} Minimize composer"
- create_or_reply: "%{shortcut} Create topic or post reply"
- fullscreen: "%{shortcut} Fullscreen composer"
- insert_current_time: "%{shortcut} Insert current time"
- bold: "%{shortcut} Bold"
- italic: "%{shortcut} Italic"
- link: "%{shortcut} Insert link"
- preformatted: "%{shortcut} Preformatted text"
- paragraph: "%{shortcut} Paragraph"
- heading_1: "%{shortcut} Heading 1"
- heading_2: "%{shortcut} Heading 2"
- heading_3: "%{shortcut} Heading 3"
- heading_4: "%{shortcut} Heading 4"
- toggle_direction: "%{shortcut} Toggle text direction"
- ordered_list: "%{shortcut} Ordered list"
- unordered_list: "%{shortcut} Unordered list"
- blockquote: "%{shortcut} Blockquote"
+ return: "Return to composer"
+ minimize: "Minimize composer"
+ create_or_reply: "Create topic or post reply"
+ fullscreen: "Fullscreen composer"
+ insert_current_time: "Insert current time"
+ bold: "Bold"
+ italic: "Italic"
+ link: "Insert link"
+ preformatted: "Preformatted text"
+ paragraph: "Paragraph"
+ heading_1: "Heading 1"
+ heading_2: "Heading 2"
+ heading_3: "Heading 3"
+ heading_4: "Heading 4"
+ toggle_direction: "Toggle text direction"
+ ordered_list: "Ordered list"
+ unordered_list: "Unordered list"
+ blockquote: "Blockquote"
bookmarks:
title: "Bookmarking"
- enter: "%{shortcut} Save and close"
- later_today: "%{shortcut} Later today"
- later_this_week: "%{shortcut} Later this week"
- tomorrow: "%{shortcut} Tomorrow"
- next_week: "%{shortcut} Next week"
- next_month: "%{shortcut} Next month"
- next_business_week: "%{shortcut} Start of next week"
- next_business_day: "%{shortcut} Next business day"
- custom: "%{shortcut} Custom date and time"
- none: "%{shortcut} No reminder"
- delete: "%{shortcut} Delete bookmark"
+ enter: "Save and close"
+ later_today: "Later today"
+ later_this_week: "Later this week"
+ tomorrow: "Tomorrow"
+ next_week: "Next week"
+ next_month: "Next month"
+ next_business_week: "Start of next week"
+ next_business_day: "Next business day"
+ custom: "Custom date and time"
+ none: "No reminder"
+ delete: "Delete bookmark"
actions:
title: "Actions"
- bookmark_topic: "%{shortcut} Toggle bookmark topic"
- pin_unpin_topic: "%{shortcut} Pin/Unpin topic"
- share_topic: "%{shortcut} Share topic"
- share_post: "%{shortcut} Share post"
- reply_as_new_topic: "%{shortcut} Reply as linked topic"
- reply_topic: "%{shortcut} Reply to topic"
- reply_post: "%{shortcut} Reply to post"
- quote_post: "%{shortcut} Quote post"
- like: "%{shortcut} Like post"
- flag: "%{shortcut} Flag post"
- bookmark: "%{shortcut} Bookmark post"
- edit: "%{shortcut} Edit post"
- delete: "%{shortcut} Delete post"
- mark_muted: "%{shortcut} Mute topic"
- mark_regular: "%{shortcut} Normal (default) topic"
- mark_tracking: "%{shortcut} Track topic"
- mark_watching: "%{shortcut} Watch topic"
- print: "%{shortcut} Print topic"
- defer: "%{shortcut} Mark topic as unread"
- topic_admin_actions: "%{shortcut} Open topic admin actions"
- archive_private_message: "%{shortcut} Toggle archive personal message"
+ bookmark_topic: "Toggle bookmark topic"
+ pin_unpin_topic: "Pin/Unpin topic"
+ share_topic: "Share topic"
+ share_post: "Share post"
+ reply_as_new_topic: "Reply as linked topic"
+ reply_topic: "Reply to topic"
+ reply_post: "Reply to post"
+ quote_post: "Quote post"
+ like: "Like post"
+ flag: "Flag post"
+ bookmark: "Bookmark post"
+ edit: "Edit post"
+ delete: "Delete post"
+ mark_muted: "Mute topic"
+ mark_regular: "Normal (default) topic"
+ mark_tracking: "Track topic"
+ mark_watching: "Watch topic"
+ print: "Print topic"
+ defer: "Mark topic as unread"
+ topic_admin_actions: "Open topic admin actions"
+ archive_private_message: "Toggle archive personal message"
search_menu:
title: "Search Menu"
- prev_next: "%{shortcut} Move selection up and down"
- insert_url: "%{shortcut} Insert selection into open composer"
- full_page_search: "%{shortcut} Launches full page search"
+ prev_next: "Move selection up and down"
+ insert_url: "Insert selection into open composer"
+ full_page_search: "Launches full page search"
admin:
title: "Admin"
- search_prev_next: "%{shortcut} Move selection up and down"
- search_open: "%{shortcut} Open search for the admin interface"
- search_full_page: "%{shortcut} Open full page admin search"
+ search_prev_next: "Move selection up and down"
+ search_open: "Open search for the admin interface"
+ search_full_page: "Open full page admin search"
badges:
earned_n_times:
diff --git a/frontend/discourse/app/components/modal/keyboard-shortcuts-help.gjs b/frontend/discourse/app/components/modal/keyboard-shortcuts-help.gjs
index c13fdda9aeb..050a5742c70 100644
--- a/frontend/discourse/app/components/modal/keyboard-shortcuts-help.gjs
+++ b/frontend/discourse/app/components/modal/keyboard-shortcuts-help.gjs
@@ -25,9 +25,25 @@ const translationForExtraShortcuts = {
meta: META,
ctrl: CTRL,
enter: ENTER,
+ esc: ESC,
comma: COMMA,
};
+const SEARCH_ALIASES = new Map();
+function addSearchAlias(key, aliasKey) {
+ // Some platforms render distinct keys (e.g. Meta and Ctrl) with the same
+ // string. Merge aliases so both semantic names remain searchable.
+ const alias = i18n(`${KEY}.search_aliases.${aliasKey}`);
+ const existing = SEARCH_ALIASES.get(key);
+ SEARCH_ALIASES.set(key, existing ? `${existing} ${alias}` : alias);
+}
+addSearchAlias(SHIFT, "shift");
+addSearchAlias(ALT, "alt");
+addSearchAlias(META, "meta");
+addSearchAlias(CTRL, "ctrl");
+addSearchAlias(ENTER, "enter");
+addSearchAlias(ESC, "esc");
+
function buildHTML(keys1, keys2, shortcutsDelimiter) {
const allKeys = [keys1, keys2]
.filter((keys) => keys.length !== 0)
@@ -74,14 +90,34 @@ function wrapInSpan(shortcut, delimiter) {
return `<span class="delimiter-${delimiter}" dir="ltr">${shortcut}</span>`;
}
+function buildSearchText(keys) {
+ return keys
+ .flatMap((k) => {
+ const alias = SEARCH_ALIASES.get(k);
+ return alias ? [k, alias] : [k];
+ })
+ .join(" ");
+}
+
function buildShortcut(
key,
{ keys1 = [], keys2 = [], shortcutsDelimiter = "or" }
) {
- const context = {
+ // "space"/"newline" mean keys1 then keys2 are pressed in sequence — one
+ // searchable combination. "or"/"slash" mean alternatives — each group
+ // searched independently so tokens can't span alternatives
+ // (e.g. "ctrl /" must not match a "/ or Ctrl+Alt+F" shortcut).
+ const isSequence =
+ shortcutsDelimiter === "space" || shortcutsDelimiter === "newline";
+ const shortcutTexts = isSequence
+ ? [buildSearchText([...keys1, ...keys2])]
+ : [keys1, keys2].filter((keys) => keys.length > 0).map(buildSearchText);
+
+ return {
shortcut: buildHTML(keys1, keys2, shortcutsDelimiter),
+ shortcutTexts,
+ description: i18n(`${KEY}.${key}`, { shortcut: "" }).trim(),
};
- return i18n(`${KEY}.${key}`, context);
}
export default class KeyboardShortcutsHelp extends Component {
@@ -336,20 +372,37 @@ export default class KeyboardShortcutsHelp extends Component {
@action
filterShortcuts(event) {
- this.searchTerm = event.target.value.toLowerCase().trim();
+ this.searchTerm = event.target.value.toLowerCase();
}
get filteredShortcuts() {
+ const searchTokens = this.searchTerm.trim().split(/\s+/).filter(Boolean);
return Object.entries(this.shortcuts).reduce(
(acc, [category, shortcutCategory]) => {
const filteredShortcuts = Object.entries(
shortcutCategory.shortcuts
).reduce((shortcutsAcc, [name, shortcut]) => {
- if (
- this.searchTerm === "" ||
- name.toLowerCase().includes(this.searchTerm) ||
- shortcut.toLowerCase().includes(this.searchTerm)
- ) {
+ const nameLower = name.toLowerCase();
+ const descriptionLower = shortcut.description.toLowerCase();
+
+ // For shortcuts with alternative key groups, all tokens must satisfy
+ // within a single group (plus name/description) so that tokens can't
+ // span alternatives.
+ const matches =
+ searchTokens.length === 0 ||
+ shortcut.shortcutTexts.some((text) => {
+ const lower = text.toLowerCase();
+ const compact = lower.replace(/\s+/g, "");
+ return searchTokens.every(
+ (token) =>
+ nameLower.includes(token) ||
+ descriptionLower.includes(token) ||
+ lower.includes(token) ||
+ compact.includes(token)
+ );
+ });
+
+ if (matches) {
shortcutsAcc[name] = shortcut;
}
return shortcutsAcc;
@@ -465,6 +518,7 @@ export default class KeyboardShortcutsHelp extends Component {
@filterAction={{this.filterShortcuts}}
@value={{this.searchTerm}}
placeholder={{i18n "keyboard_shortcuts_help.search_placeholder"}}
+ aria-label={{i18n "keyboard_shortcuts_help.search_placeholder"}}
/>
<div class="keyboard-shortcuts-help__container">
@@ -476,14 +530,33 @@ export default class KeyboardShortcutsHelp extends Component {
class="shortcut-category span-{{shortcutCategory.count}}
shortcut-category-{{category}}"
>
- <h2>{{i18n
+ <h2 id="shortcut-category-{{category}}-heading">{{i18n
(concat "keyboard_shortcuts_help." category ".title")
}}</h2>
- <ul>
- {{#each-in shortcutCategory.shortcuts as |name shortcut|}}
- <li>{{trustHTML shortcut}}</li>
- {{/each-in}}
- </ul>
+ <table aria-labelledby="shortcut-category-{{category}}-heading">
+ <thead class="sr-only">
+ <tr>
+ <th scope="col">{{i18n
+ "keyboard_shortcuts_help.description_header"
+ }}</th>
+ <th scope="col">{{i18n
+ "keyboard_shortcuts_help.key_header"
+ }}</th>
+ </tr>
+ </thead>
+ <tbody>
+ {{#each-in shortcutCategory.shortcuts as |name pair|}}
+ <tr>
+ <td class="shortcut-description">{{trustHTML
+ pair.description
+ }}</td>
+ <td class="shortcut-key">{{trustHTML
+ pair.shortcut
+ }}</td>
+ </tr>
+ {{/each-in}}
+ </tbody>
+ </table>
</section>
{{/each-in}}
</div>
diff --git a/frontend/discourse/tests/acceptance/keyboard-shortcuts-test.js b/frontend/discourse/tests/acceptance/keyboard-shortcuts-test.js
index d2e90ee91a0..b5a72941608 100644
--- a/frontend/discourse/tests/acceptance/keyboard-shortcuts-test.js
+++ b/frontend/discourse/tests/acceptance/keyboard-shortcuts-test.js
@@ -1,6 +1,13 @@
-import { click, currentURL, triggerKeyEvent, visit } from "@ember/test-helpers";
+import {
+ click,
+ currentURL,
+ fillIn,
+ triggerKeyEvent,
+ visit,
+} from "@ember/test-helpers";
import { module, test } from "qunit";
import { cloneJSON } from "discourse/lib/object";
+import { withPluginApi } from "discourse/lib/plugin-api";
import DiscoveryFixtures from "discourse/tests/fixtures/discovery-fixtures";
import { acceptance, chromeTest } from "discourse/tests/helpers/qunit-helpers";
import { i18n } from "discourse-i18n";
@@ -319,3 +326,100 @@ acceptance("Keyboard Shortcuts - Authenticated Users", function (needs) {
});
});
});
+
+acceptance("Keyboard Shortcuts Help Modal - Search", function () {
+ async function openHelpModal() {
+ await visit("/");
+ await triggerKeyEvent(document, "keypress", "?".charCodeAt(0));
+ }
+
+ function description(key) {
+ return i18n(`keyboard_shortcuts_help.${key}`, { shortcut: "" }).trim();
+ }
+
+ test("matches sequential keys without whitespace (gh → G H)", async function (assert) {
+ await openHelpModal();
+ await fillIn(".filter-input", "gh");
+
+ assert
+ .dom(".shortcut-category-jump_to tbody")
+ .includesText(description("jump_to.home"));
+ assert
+ .dom(".shortcut-category-jump_to tbody")
+ .doesNotIncludeText(description("jump_to.latest"));
+ });
+
+ test("requires every search token to match (command /)", async function (assert) {
+ await openHelpModal();
+ await fillIn(".filter-input", "command /");
+
+ assert
+ .dom(".shortcut-category-application tbody")
+ .includesText(description("application.filter_sidebar"));
+ assert
+ .dom(".shortcut-category-application tbody")
+ .doesNotIncludeText(description("application.help"));
+ });
+
+ test("modifier aliases match regardless of glyph (ctrl)", async function (assert) {
+ await openHelpModal();
+ await fillIn(".filter-input", "ctrl");
+
+ assert
+ .dom(".shortcut-category-application tbody")
+ .includesText(description("application.search"));
+ });
+
+ test("multi-word description match", async function (assert) {
+ await openHelpModal();
+ await fillIn(".filter-input", "open keyboard help");
+
+ assert
+ .dom(".shortcut-category-application tbody")
+ .includesText(description("application.help"));
+ assert
+ .dom(".shortcut-category-jump_to")
+ .doesNotExist("unrelated categories are filtered out");
+ });
+
+ test("alternative key groups don't merge for compact match", async function (assert) {
+ await openHelpModal();
+ await fillIn(".filter-input", "kj");
+
+ // navigation.up_down is K or J, not K then J. "kj" must not
+ // match it just because both letters appear across the alternative groups.
+ assert
+ .dom(".shortcut-category-navigation")
+ .doesNotExist(
+ "alternative key groups don't false-match the merged compact form"
+ );
+ });
+
+ test("alternative key groups don't satisfy tokens across alternatives", async function (assert) {
+ await openHelpModal();
+ await fillIn(".filter-input", "ctrl /");
+
+ // application.search has alternatives "/" or Ctrl+Alt+F. "ctrl /" must not
+ // match because "ctrl" lives in one alternative and "/" in the other.
+ assert
+ .dom(".shortcut-category-application tbody")
+ .doesNotIncludeText(description("application.search"));
+ });
+
+ test("plugin-registered shortcut with raw 'esc' key matches escape alias", async function (assert) {
+ withPluginApi((api) => {
+ api.addKeyboardShortcut("shift+esc", () => {}, {
+ help: {
+ category: "esc_test",
+ name: "esc_test.bail",
+ definition: { keys1: ["shift", "esc"] },
+ },
+ });
+ });
+
+ await openHelpModal();
+ await fillIn(".filter-input", "escape");
+
+ assert.dom(".shortcut-category-esc_test tbody tr").exists({ count: 1 });
+ });
+});
diff --git a/frontend/discourse/tests/acceptance/plugin-keyboard-shortcut-test.js b/frontend/discourse/tests/acceptance/plugin-keyboard-shortcut-test.js
index d03b1de89a5..bb04dffc273 100644
--- a/frontend/discourse/tests/acceptance/plugin-keyboard-shortcut-test.js
+++ b/frontend/discourse/tests/acceptance/plugin-keyboard-shortcut-test.js
@@ -63,14 +63,14 @@ acceptance("Plugin Keyboard Shortcuts - Anonymous", function () {
await triggerKeyEvent(document, "keypress", "?".charCodeAt(0));
assert.dom(".shortcut-category-new_category").exists();
- assert.dom(".shortcut-category-new_category li").exists({ count: 1 });
+ assert.dom(".shortcut-category-new_category tbody tr").exists({ count: 1 });
});
test("a plugin can add a shortcut to and existing category in the shortcut help modal", async function (assert) {
await visit("/");
await triggerKeyEvent(document, "keypress", "?".charCodeAt(0));
const countBefore = document.querySelectorAll(
- ".shortcut-category-application li"
+ ".shortcut-category-application tbody tr"
).length;
await click(".modal-close");
@@ -89,7 +89,7 @@ acceptance("Plugin Keyboard Shortcuts - Anonymous", function () {
await triggerKeyEvent(document, "keypress", "?".charCodeAt(0));
assert
- .dom(".shortcut-category-application li")
+ .dom(".shortcut-category-application tbody tr")
.exists({ count: countBefore + 1 });
});
});
diff --git a/plugins/discourse-templates/test/javascripts/acceptance/templates-test.js b/plugins/discourse-templates/test/javascripts/acceptance/templates-test.js
index 6a43c9e8caa..da033c9adcb 100644
--- a/plugins/discourse-templates/test/javascripts/acceptance/templates-test.js
+++ b/plugins/discourse-templates/test/javascripts/acceptance/templates-test.js
@@ -289,7 +289,7 @@ acceptance("keyboard shortcut", function (needs) {
await triggerKeyEvent(document, "keypress", "?".charCodeAt(0));
assert.dom(".shortcut-category-templates").exists();
- assert.dom(".shortcut-category-templates li").exists({ count: 1 });
+ assert.dom(".shortcut-category-templates tbody tr").exists({ count: 1 });
});
test("Composer | Title field focused | Template is inserted", async function (assert) {