8350638: Make keyboard navigation more usable in API docs

Reviewed-by: liach, nbenalla

Author: hns

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java

@@ -35,6 +35,7 @@
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
 import jdk.javadoc.internal.html.Content;
 import jdk.javadoc.internal.html.ContentBuilder;
+import jdk.javadoc.internal.html.Entity;
 import jdk.javadoc.internal.html.HtmlId;
 import jdk.javadoc.internal.html.HtmlTree;
 import jdk.javadoc.internal.html.Text;
@@ -172,6 +173,27 @@ private Content getNavigationSection() {
                     .add(searchRefer);
             navSection.add(section);
         }
+
+        // Keyboard Navigation
+        section = newHelpSection(contents.getContent("doclet.help.keyboard_navigation.title"),
+                HtmlIds.HELP_KEYBOARD_NAVIGATION);
+        var  keyboardPara = HtmlTree.P(contents.getContent("doclet.help.keyboard_navigation.intro"));
+        var keyboardList = HtmlTree.UL();
+        if (options.createIndex()) {
+            keyboardList.add(HtmlTree.LI(contents.getContent("doclet.help.keyboard_navigation.index",
+                    HtmlTree.KBD(Text.of("/")))));
+        }
+        keyboardList.add(HtmlTree.LI(contents.getContent("doclet.help.keyboard_navigation.filter",
+                HtmlTree.KBD(Text.of(".")))));
+        keyboardList.add(HtmlTree.LI(contents.getContent("doclet.help.keyboard_navigation.escape",
+                HtmlTree.KBD(Text.of("Esc")))));
+        keyboardList.add(HtmlTree.LI(contents.getContent("doclet.help.keyboard_navigation.search",
+                HtmlTree.KBD(Text.of("Tab")), HtmlTree.KBD(Entity.of("downarrow")),
+                HtmlTree.KBD(Entity.of("uparrow")))));
+        keyboardList.add(HtmlTree.LI(contents.getContent("doclet.help.keyboard_navigation.tabs",
+                HtmlTree.KBD(Entity.of("leftarrow")), HtmlTree.KBD(Entity.of("rightarrow")))));
+        navSection.add(section.add(keyboardPara.add(keyboardList)));
+
         tableOfContents.popNestedList();
 
         return content;

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java

@@ -92,6 +92,7 @@ public class HtmlIds {
     static final HtmlId FIELD_SUMMARY = HtmlId.of("field-summary");
     static final HtmlId FOR_REMOVAL = HtmlId.of("for-removal");
     static final HtmlId HELP_NAVIGATION = HtmlId.of("help-navigation");
+    static final HtmlId HELP_KEYBOARD_NAVIGATION = HtmlId.of("help-keyboard-navigation");
     static final HtmlId HELP_PAGES = HtmlId.of("help-pages");
     static final HtmlId HELP_RELEASES = HtmlId.of("help-releases");
     static final HtmlId METHOD_DETAIL = HtmlId.of("method-detail");

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java

@@ -498,7 +498,8 @@ private void addSearch(Content target) {
         var inputText = HtmlTree.INPUT(HtmlAttr.InputType.TEXT, HtmlIds.SEARCH_INPUT)
                 .put(HtmlAttr.PLACEHOLDER, resources.getText("doclet.search_placeholder"))
                 .put(HtmlAttr.ARIA_LABEL, resources.getText("doclet.search_in_documentation"))
-                .put(HtmlAttr.AUTOCOMPLETE, "off");
+                .put(HtmlAttr.AUTOCOMPLETE, "off")
+                .put(HtmlAttr.SPELLCHECK, "false");
         var inputReset = HtmlTree.INPUT(HtmlAttr.InputType.RESET, HtmlIds.RESET_SEARCH)
                 .put(HtmlAttr.VALUE, resources.getText("doclet.search_reset"));
         var searchDiv = HtmlTree.DIV(HtmlStyles.navListSearch)

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SearchWriter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -32,6 +32,7 @@
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
 import jdk.javadoc.internal.html.Content;
 import jdk.javadoc.internal.html.ContentBuilder;
+import jdk.javadoc.internal.html.Entity;
 import jdk.javadoc.internal.html.HtmlAttr;
 import jdk.javadoc.internal.html.HtmlId;
 import jdk.javadoc.internal.html.HtmlTag;
@@ -85,15 +86,19 @@ protected void addSearchFileContents(Content contentTree) {
                 .add(HtmlTree.DIV(HtmlTree.INPUT(HtmlAttr.InputType.TEXT, HtmlId.of("page-search-input"))
                                 .put(HtmlAttr.PLACEHOLDER, resources.getText("doclet.search_placeholder"))
                                 .put(HtmlAttr.ARIA_LABEL, resources.getText("doclet.search_in_documentation"))
-                                .put(HtmlAttr.AUTOCOMPLETE, "off"))
+                                .put(HtmlAttr.AUTOCOMPLETE, "off")
+                                .put(HtmlAttr.SPELLCHECK, "false"))
                         .add(HtmlTree.INPUT(HtmlAttr.InputType.RESET, HtmlId.of("page-search-reset"))
                                 .put(HtmlAttr.VALUE, resources.getText("doclet.search_reset"))
                                 .put(HtmlAttr.STYLE, "margin: 6px;"))
                         .add(HtmlTree.DETAILS(HtmlStyles.pageSearchDetails)
                                 .add(HtmlTree.SUMMARY(contents.getContent("doclet.search.show_more"))
                                         .setId(HtmlId.of("page-search-expand")))))
                 .add(HtmlTree.DIV(HtmlStyles.pageSearchInfo, helpSection)
-                        .add(HtmlTree.P(contents.getContent("doclet.search.keyboard_info")))
+                        .add(HtmlTree.P(contents.getContent("doclet.search.keyboard_info",
+                                HtmlTree.KBD(Text.of("Ctrl")), HtmlTree.KBD(Text.of("Cmd")),
+                                new ContentBuilder(HtmlTree.KBD(Entity.of("leftarrow")), Text.of("/"),
+                                        HtmlTree.KBD(Entity.of("rightarrow"))))))
                         .add(HtmlTree.P(contents.getContent("doclet.search.browser_info")))
                         .add(HtmlTree.SPAN(Text.of("link"))
                                 .setId(HtmlId.of("page-search-link")))

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TableOfContents.java

@@ -47,7 +47,8 @@ public class TableOfContents {
      */
     public TableOfContents(HtmlDocletWriter writer) {
         this.writer = writer;
-        listBuilder = new ListBuilder(HtmlTree.OL(HtmlStyles.tocList));
+        listBuilder = new ListBuilder(HtmlTree.OL(HtmlStyles.tocList)
+                .put(HtmlAttr.TABINDEX, "-1"));
     }
 
     /**
@@ -96,18 +97,21 @@ protected Content toContent(boolean hasFilterInput) {
                     .add(HtmlTree.INPUT(HtmlAttr.InputType.TEXT, HtmlStyles.filterInput)
                             .put(HtmlAttr.PLACEHOLDER, writer.resources.getText("doclet.filter_label"))
                             .put(HtmlAttr.ARIA_LABEL, writer.resources.getText("doclet.filter_table_of_contents"))
-                            .put(HtmlAttr.AUTOCOMPLETE, "off"))
+                            .put(HtmlAttr.AUTOCOMPLETE, "off")
+                            .put(HtmlAttr.SPELLCHECK, "false"))
                     .add(HtmlTree.INPUT(HtmlAttr.InputType.RESET, HtmlStyles.resetFilter)
+                            .put(HtmlAttr.TABINDEX, "-1")
                             .put(HtmlAttr.VALUE, writer.resources.getText("doclet.filter_reset")));
         }
         content.add(header);
+        content.add(listBuilder);
         content.add(HtmlTree.BUTTON(HtmlStyles.hideSidebar)
                 .add(HtmlTree.SPAN(writer.contents.hideSidebar).add(Entity.NO_BREAK_SPACE))
                 .add(Entity.LEFT_POINTING_ANGLE));
         content.add(HtmlTree.BUTTON(HtmlStyles.showSidebar)
                 .add(Entity.RIGHT_POINTING_ANGLE)
                 .add(HtmlTree.SPAN(Entity.NO_BREAK_SPACE).add(writer.contents.showSidebar)));
-        return content.add(listBuilder);
+        return content;
     }
 
 }