From 44d9f4e95bf9590d1f933f769c75798486372ad7 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Sun, 11 May 2025 08:59:58 +0000 Subject: [PATCH 1/4] Use `/` (or `s`) to open search box We allow for using `s` to open the search box, but it's more common to use `/` (forward slash) for this. E.g., MDN's documentation uses `/` for search. Rustdoc and GitHub accept either. Let's allow either key to be used, and let's switch to "advertising" `/` rather than `s` in the hover text for the search button. In making that switch, let's also simplify that hover text a bit. Previously it had said "Search. (Shortkey: s)". This was the only top button on which we had included a period in the hover text. Let's remove that, and let's remove the "shortkey" bit of jargon. It's enough to just put `/` in a parenthetical, i.e. "Search (`/`)". People will gleam from that what we mean. We've also updated the guide accordingly. --- guide/src/guide/reading.md | 2 +- src/front-end/searcher/searcher.js | 4 ++-- src/front-end/templates/index.hbs | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/src/guide/reading.md b/guide/src/guide/reading.md index cab3a86538..704f4bcc68 100644 --- a/guide/src/guide/reading.md +++ b/guide/src/guide/reading.md @@ -42,7 +42,7 @@ Tapping the menu bar will scroll the page to the top. ## Search Each book has a built-in search system. -Pressing the search icon () in the menu bar, or pressing the `S` key on the keyboard will open an input box for entering search terms. +Pressing the search icon () in the menu bar, or pressing the `/` or `S` key on the keyboard will open an input box for entering search terms. Typing some terms will show matching chapters and sections in real time. Clicking any of the results will jump to that section. diff --git a/src/front-end/searcher/searcher.js b/src/front-end/searcher/searcher.js index 2ecba880d2..a29883c0d0 100644 --- a/src/front-end/searcher/searcher.js +++ b/src/front-end/searcher/searcher.js @@ -35,7 +35,7 @@ window.search = window.search || {}; URL_SEARCH_PARAM = 'search', URL_MARK_PARAM = 'highlight', - SEARCH_HOTKEY_KEYCODE = 83, + SEARCH_HOTKEY_KEYCODES = [83, 191], // `s` or `/`. ESCAPE_KEYCODE = 27, DOWN_KEYCODE = 40, UP_KEYCODE = 38, @@ -362,7 +362,7 @@ window.search = window.search || {}; } showSearch(false); marker.unmark(); - } else if (!hasFocus() && e.keyCode === SEARCH_HOTKEY_KEYCODE) { + } else if (!hasFocus() && SEARCH_HOTKEY_KEYCODES.includes(e.keyCode)) { e.preventDefault(); showSearch(true); window.scrollTo(0, 0); diff --git a/src/front-end/templates/index.hbs b/src/front-end/templates/index.hbs index 98f3b886c9..ca3c73fba4 100644 --- a/src/front-end/templates/index.hbs +++ b/src/front-end/templates/index.hbs @@ -142,7 +142,7 @@
    • {{#if search_enabled}} - {{/if}} From 84a5ba97079027f9da188ba6d63e024c027e6a7c Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Sun, 11 May 2025 09:23:41 +0000 Subject: [PATCH 2/4] Handle `DOWN_KEYCODE` with no results If, when searching, one pressed the down arrow key when there were no results, this caused an uncaught exception and defocused the search box. Let's prevent this and keep the search box focused when pressing down in this state by checking first whether there is a result for us to focus instead. --- src/front-end/searcher/searcher.js | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/front-end/searcher/searcher.js b/src/front-end/searcher/searcher.js index a29883c0d0..d7f9f580e1 100644 --- a/src/front-end/searcher/searcher.js +++ b/src/front-end/searcher/searcher.js @@ -369,8 +369,11 @@ window.search = window.search || {}; searchbar.select(); } else if (hasFocus() && e.keyCode === DOWN_KEYCODE) { e.preventDefault(); - unfocusSearchbar(); - searchresults.firstElementChild.classList.add('focus'); + const first = searchresults.firstElementChild; + if (first !== null) { + unfocusSearchbar(); + first.classList.add('focus'); + } } else if (!hasFocus() && (e.keyCode === DOWN_KEYCODE || e.keyCode === UP_KEYCODE || e.keyCode === SELECT_KEYCODE)) { From 3e871d1971479cf38b12047d07204608c5b07076 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Sun, 11 May 2025 09:33:01 +0000 Subject: [PATCH 3/4] Navigate to first search result on `enter` It's common for search boxes like ours to automatically navigate to the first search result when the `enter` / `select` key is pressed, as that can allow for rapid navigation. E.g., the MDN documentation does this. Let's similarly navigate to the first result when, in the search box, the user presses the `enter` key and there is a first result to which to navigate. --- src/front-end/searcher/searcher.js | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/front-end/searcher/searcher.js b/src/front-end/searcher/searcher.js index d7f9f580e1..476c17e4cc 100644 --- a/src/front-end/searcher/searcher.js +++ b/src/front-end/searcher/searcher.js @@ -367,12 +367,16 @@ window.search = window.search || {}; showSearch(true); window.scrollTo(0, 0); searchbar.select(); - } else if (hasFocus() && e.keyCode === DOWN_KEYCODE) { + } else if (hasFocus() && (e.keyCode === DOWN_KEYCODE + || e.keyCode === SELECT_KEYCODE)) { e.preventDefault(); const first = searchresults.firstElementChild; if (first !== null) { unfocusSearchbar(); first.classList.add('focus'); + if (e.keyCode === SELECT_KEYCODE) { + window.location.assign(first.querySelector('a')); + } } } else if (!hasFocus() && (e.keyCode === DOWN_KEYCODE || e.keyCode === UP_KEYCODE From 52e406bf95a6df82513fdb656815afced2658514 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Tue, 13 May 2025 20:45:36 +0000 Subject: [PATCH 4/4] Use `` tag to describe keyboard shortcuts When describing, in the guide, the keyboard shortcuts that we accept, let's use the `` element. This causes the key to render in a box that people will recognize as conventional. The way that this is displayed helps to make it clear that, though we present the key in uppercase, we actually mean for the lowercase letter to be entered. Therefore, we present the key in uppercase since 1) that's how it appears on most keyboards and 2) for some characters such as `l`, presenting the character in lowercase might be ambiguous. We'll spell out "Escape" rather than saying "Esc" (even though many keyboards spell it that way) since the `KeyboardEvent.keycode`[^1] is called "Escape", and that's how it would appear in an `aria-keyshortcuts` attribute[^2]. [^1]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode [^2]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts --- guide/src/guide/reading.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/src/guide/reading.md b/guide/src/guide/reading.md index 704f4bcc68..fd8183690f 100644 --- a/guide/src/guide/reading.md +++ b/guide/src/guide/reading.md @@ -42,14 +42,14 @@ Tapping the menu bar will scroll the page to the top. ## Search Each book has a built-in search system. -Pressing the search icon () in the menu bar, or pressing the `/` or `S` key on the keyboard will open an input box for entering search terms. +Pressing the search icon () in the menu bar, or pressing the / or S key on the keyboard will open an input box for entering search terms. Typing some terms will show matching chapters and sections in real time. Clicking any of the results will jump to that section. The up and down arrow keys can be used to navigate the results, and enter will open the highlighted section. After loading a search result, the matching search terms will be highlighted in the text. -Clicking a highlighted word or pressing the `Esc` key will remove the highlighting. +Clicking a highlighted word or pressing the Escape key will remove the highlighting. ## Code blocks