RFR: 8350638: Make keyboard navigation more usable in API docs [v9]

[Chen Liang]

On Fri, 7 Mar 2025 08:44:08 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
>> 
>>  - <kbd>/</kbd> to switch focus to the search input
>>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
>> 
>> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
>> 
>> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
>> 
>> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
>> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
>> 
>> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
>> 
>> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.
>
> Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Wording

Marked as reviewed by liach (Reviewer).

-------------

PR Review: https://git.openjdk.org/jdk/pull/23777#pullrequestreview-2668319702