Add search-as-you-type (inline search results) feature (#2093)

Fixes #1977

---------

Co-authored-by: Kayce Basques <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/conf.py

@@ -217,6 +217,7 @@
         "version_match": version_match,
     },
     # "back_to_top_button": False,
+    "search_as_you_type": True,
 }
 
 html_sidebars = {

docs/user_guide/search.rst

@@ -63,3 +63,14 @@ following configuration to your ``conf.py`` file:
    html_theme_options = {
        "search_bar_text": "Your text here..."
    }
+
+Configure the inline search results (search-as-you-type) feature
+----------------------------------------------------------------
+
+Set the ``search_as_you_type`` HTML theme option to ``True``.
+
+.. code:: python
+
+   html_theme_options = {
+       "search_as_you_type": True
+   }

src/pydata_sphinx_theme/__init__.py

@@ -241,6 +241,12 @@ def update_and_remove_templates(
         """
         app.add_js_file(None, body=js)
 
+    # Specify whether search-as-you-type should be used or not.
+    search_as_you_type = str(context["theme_search_as_you_type"]).lower()
+    app.add_js_file(
+        None, body=f"DOCUMENTATION_OPTIONS.search_as_you_type = {search_as_you_type};"
+    )
+
     # Update version number for the "made with version..." component
     context["theme_version"] = __version__
 

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -261,6 +261,7 @@ var addEventListenerForSearchKeyboard = () => {
       // also allow Escape key to hide (but not show) the dynamic search field
       else if (document.activeElement === input && /Escape/i.test(event.key)) {
         toggleSearchField();
+        resetSearchAsYouTypeResults();
       }
     },
     true,
@@ -332,6 +333,170 @@ var setupSearchButtons = () => {
   searchDialog.addEventListener("click", closeDialogOnBackdropClick);
 };
 
+/*******************************************************************************
+ * Inline search results (search-as-you-type)
+ *
+ * Immediately displays search results under the search query textbox.
+ *
+ * The search is conducted by Sphinx's built-in search tools (searchtools.js).
+ * Usually searchtools.js is only available on /search.html but
+ * pydata-sphinx-theme (PST) has been modified to load searchtools.js on every
+ * page. After the user types something into PST's search query textbox,
+ * searchtools.js executes the search and populates the results into
+ * the #search-results container. searchtools.js expects the results container
+ * to have that exact ID.
+ */
+var setupSearchAsYouType = () => {
+  if (!DOCUMENTATION_OPTIONS.search_as_you_type) {
+    return;
+  }
+
+  // Don't interfere with the default search UX on /search.html.
+  if (window.location.pathname.endsWith("/search.html")) {
+    return;
+  }
+
+  // Bail if the Search class is not available. Search-as-you-type is
+  // impossible without that class. layout.html should ensure that
+  // searchtools.js loads.
+  //
+  // Search class is defined in upstream Sphinx:
+  // https://github.com/sphinx-doc/sphinx/blob/6678e357048ea1767daaad68e7e0569786f3b458/sphinx/themes/basic/static/searchtools.js#L181
+  if (!Search) {
+    return;
+  }
+
+  // Destroy the previous search container and create a new one.
+  resetSearchAsYouTypeResults();
+  let timeoutId = null;
+  let lastQuery = "";
+  const searchInput = document.querySelector(
+    "#pst-search-dialog input[name=q]",
+  );
+
+  // Initiate searches whenever the user types stuff in the search modal textbox.
+  searchInput.addEventListener("keyup", () => {
+    const query = searchInput.value;
+
+    // Don't search when there's nothing in the query textbox.
+    if (query === "") {
+      resetSearchAsYouTypeResults(); // Remove previous results.
+      return;
+    }
+
+    // Don't search if there is no detectable change between
+    // the last query and the current query. E.g. the user presses
+    // Tab to start navigating the search results.
+    if (query === lastQuery) {
+      return;
+    }
+
+    // The user has changed the search query. Delete the old results
+    // and start setting up the new container.
+    resetSearchAsYouTypeResults();
+
+    // Debounce so that the search only starts when the user stops typing.
+    const delay_ms = 300;
+    lastQuery = query;
+    if (timeoutId) {
+      window.clearTimeout(timeoutId);
+    }
+    timeoutId = window.setTimeout(() => {
+      Search.performSearch(query);
+      document.querySelector("#search-results").classList.remove("empty");
+      timeoutId = null;
+    }, delay_ms);
+  });
+};
+
+// Delete the old search results container (if it exists) and set up a new one.
+//
+// There is some complexity around ensuring that the search results links are
+// correct because we're extending searchtools.js past its assumed usage.
+// Sphinx assumes that searches are only executed from /search.html and
+// therefore it assumes that all search results links should be relative to
+// the root directory of the website. In our case the search can now execute
+// from any page of the website so we must fix the relative URLs that
+// searchtools.js generates.
+var resetSearchAsYouTypeResults = () => {
+  if (!DOCUMENTATION_OPTIONS.search_as_you_type) {
+    return;
+  }
+  // If a search-as-you-type results container was previously added,
+  // remove it now.
+  let results = document.querySelector("#search-results");
+  if (results) {
+    results.remove();
+  }
+
+  // Create a new search-as-you-type results container.
+  results = document.createElement("section");
+  results.classList.add("empty");
+  // Remove the container element from the tab order. Individual search
+  // results are still focusable.
+  results.tabIndex = -1;
+  // When focus is on a search result, make sure that pressing Escape closes
+  // the search modal.
+  results.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      event.stopPropagation();
+      toggleSearchField();
+      resetSearchAsYouTypeResults();
+    }
+  });
+  // IMPORTANT: The search results container MUST have this exact ID.
+  // searchtools.js is hardcoded to populate into the node with this ID.
+  results.id = "search-results";
+  let modal = document.querySelector("#pst-search-dialog");
+  modal.appendChild(results);
+
+  // Get the relative path back to the root of the website.
+  const root =
+    "URL_ROOT" in DOCUMENTATION_OPTIONS
+      ? DOCUMENTATION_OPTIONS.URL_ROOT // Sphinx v6 and earlier
+      : document.documentElement.dataset.content_root; // Sphinx v7 and later
+
+  // As Sphinx populates the search results, this observer makes sure that
+  // each URL is correct (i.e. doesn't 404).
+  const linkObserver = new MutationObserver(() => {
+    const links = Array.from(
+      document.querySelectorAll("#search-results .search a"),
+    );
+    // Check every link every time because the timing of when new results are
+    // added is unpredictable and it's not an expensive operation.
+    links.forEach((link) => {
+      link.tabIndex = 0; // Use natural tab order for search results.
+      // Don't use the link.href getter because the browser computes the href
+      // as a full URL. We need the relative URL that Sphinx generates.
+      const href = link.getAttribute("href");
+      if (href.startsWith(root)) {
+        // No work needed. The root has already been prepended to the href.
+        return;
+      }
+      link.href = `${root}${href}`;
+    });
+  });
+
+  // The node that linkObserver watches doesn't exist until the user types
+  // something into the search textbox. This second observer (resultsObserver)
+  // just waits for #search-results to exist and then registers
+  // linkObserver on it.
+  let isObserved = false;
+  const resultsObserver = new MutationObserver(() => {
+    if (isObserved) {
+      return;
+    }
+    const container = document.querySelector("#search-results .search");
+    if (!container) {
+      return;
+    }
+    linkObserver.observe(container, { childList: true });
+    isObserved = true;
+  });
+  resultsObserver.observe(results, { childList: true });
+};
+
 /*******************************************************************************
  * Version Switcher
  * Note that this depends on two variables existing that are defined in
@@ -857,6 +1022,7 @@ documentReady(addModeListener);
 documentReady(scrollToActive);
 documentReady(addTOCInteractivity);
 documentReady(setupSearchButtons);
+documentReady(setupSearchAsYouType);
 documentReady(setupMobileSidebarKeyboardHandlers);
 
 // Determining whether an element has scrollable content depends on stylesheets,

src/pydata_sphinx_theme/assets/styles/components/_search.scss

@@ -93,29 +93,50 @@
     z-index: $zindex-modal;
     top: 30%;
     left: 50%;
-    transform: translate(-50%, -50%);
+    transform: translate(-50%, -30%);
     right: 1rem;
+    margin-bottom: 0;
     margin-top: 0.5rem;
     width: 90%;
     max-width: 800px;
     background-color: transparent;
     padding: $focus-ring-width;
     border: none;
+    flex-direction: column;
+    height: 80vh;
 
     &::backdrop {
       background-color: black;
       opacity: 0.5;
     }
 
     form.bd-search {
-      flex-grow: 1;
+      flex-grow: 0;
 
       // Font and input text a bit bigger
       svg,
       input {
         font-size: var(--pst-font-size-icon);
       }
     }
+
+    /* In pydata-sphinx-theme.js this container is appended below
+     * the query input node after the user types their search query.
+     * Search results are populated into this container using Sphinx's
+     * built-in, JS-powered local search tools. */
+    #search-results {
+      overflow-y: scroll;
+      background-color: var(--pst-color-background);
+      padding: 1em;
+
+      a {
+        color: var(--pst-color-link);
+      }
+
+      &.empty {
+        display: none;
+      }
+    }
   }
 }
 

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -37,6 +37,15 @@
   {%- if last_updated %}
     <meta name="docbuild:last-update" content="{{ last_updated | e }}"/>
   {%- endif %}
+  {% if pagename == 'search' %}
+    {# Search tools are already loaded on search page. Don't load them twice. #}
+  {% else %}
+    {# Load Sphinx's built-in search tools so that our custom inline search
+       experience can work on any page. #}
+    <script src="{{ pathto('_static/searchtools.js', 1) | e }}"></script>
+    <script src="{{ pathto('_static/language_data.js', 1) | e }}"></script>
+    <script src="{{ pathto('searchindex.js', 1) | e }}"></script>
+  {% endif %}
 {%- endblock extrahead %}
 {% block body_tag %}
   {# set up with scrollspy to update the toc as we scroll #}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -36,6 +36,7 @@ logo =
 logo_link =
 surface_warnings = True
 back_to_top_button = True
+search_as_you_type = False
 
 # Template placement in theme layouts
 navbar_start = navbar-logo

tests/test_a11y.py

@@ -291,3 +291,34 @@ def test_breadcrumb_expansion(page: Page, url_base: str) -> None:
     expect(page.get_by_label("Breadcrumb").get_by_role("list")).to_contain_text(
         "Update Sphinx configuration during the build"
     )
+
+
+@pytest.mark.a11y
+def test_search_as_you_type(page: Page, url_base: str) -> None:
+    """Search-as-you-type feature should support keyboard navigation.
+
+    When the search-as-you-type (inline search results) feature is enabled,
+    pressing Tab after entering a search query should focus the first inline
+    search result.
+    """
+    page.set_viewport_size({"width": 1440, "height": 720})
+    page.goto(urljoin(url_base, "/examples/kitchen-sink/blocks.html"))
+    # Click the search textbox.
+    searchbox = page.locator("css=.navbar-header-items .search-button__default-text")
+    searchbox.click()
+    # Type a search query.
+    query_input = page.locator("css=#pst-search-dialog input[type=search]")
+    expect(query_input).to_be_visible()
+    query_input.type("test")
+    page.wait_for_timeout(301)  # Search execution is debounced for 300 ms.
+    search_results = page.locator("css=#search-results")
+    expect(search_results).to_be_visible()
+    # Navigate with the keyboard.
+    query_input.press("Tab")
+    # Make sure that the first inline search result is focused.
+    actual_focused_content = page.evaluate("document.activeElement.textContent")
+    first_result_selector = "#search-results .search li:first-child a"
+    expected_focused_content = page.evaluate(
+        f"document.querySelector('{first_result_selector}').textContent"
+    )
+    assert actual_focused_content == expected_focused_content