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

kaycebasques · 2025-01-07T01:42:26Z

Fixes #1977

choldgraf · 2025-01-07T03:01:31Z

This is super cool

12rambau · 2025-01-07T09:44:55Z

For me it's the most wanted feature, brilliant !

drammock

thank you a thousand times for including such clear and detailed code comments. So far I've only read the implementation, haven't played around with it on the PR build yet.

drammock · 2025-01-08T17:55:24Z

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

+  // Don't interfere with the default search UX on /search.html.
+  if (window.location.pathname.endsWith("/search.html")) {
+    return;
+  }


we should also account for dirhtml builds, which I think (?) will have a url like https://whatever.com/en/search/ or potentially https://whatever.com/en/search/index.html

dirhtml was not on my radar. Will need to look into what that does to figure out how it affects the impl.

I introduced a temporary change to tox.ini in this PR to make docs-dev build dirhtml instead of html. It all seems to work fine still

drammock · 2025-01-08T17:57:22Z

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

+  // searchtools.js loads.
+  //
+  // Search class is defined in upstream Sphinx:
+  // https://github.com/sphinx-doc/sphinx/blob/master/sphinx/themes/basic/static/searchtools.js#L181


link to .../blob/master/... may suffer from line number drift or otherwise go stale. Let's use a permalink to a specific repo state.

Fixed now, will let you resolve

drammock · 2025-01-08T18:02:28Z

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

+  }
+
+  // Create a new search-as-you-type results container.
+  results = document.createElement("section");


@gabalafou would appreciate your perspective on what is the best node type for an appearing/disappearing list of search results, and how this can/should/will interact with things like tab focus.

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

tests/test_a11y.py

github-actions · 2025-01-08T18:08:57Z

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
src/pydata_sphinx_theme
__init__.py
Project Total

_{This report was generated by python-coverage-comment-action}

kaycebasques · 2025-01-09T19:30:19Z

tox.ini

@@ -122,7 +122,7 @@ set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 extras = {[testenv:docs-no-checks]extras}
 package = editable
 commands =
-    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
+    sphinx-build -b dirhtml docs/ docs/_build/html -v -w warnings.txt {posargs}


This should be reverted before (hopefully eventually) merging

kaycebasques · 2025-01-09T19:34:41Z

@drammock all actionable feedback addressed

drammock · 2025-01-09T19:39:18Z

@drammock all actionable feedback addressed

time for more feedback then 😆 I was just playing around with the CI build, and 2 things didn't match expectations:

pressing tab first focuses the entire search results container, seems more useful if the container wasn't a tab stop and the first tab went straight to the first search result link.
pressing esc when tab-focus is on a search result doesn't exit the search modal/overlay.

kaycebasques · 2025-01-12T01:07:19Z

time for more feedback then 😆

BRING IT

Will add inline code comments addressing the two latest items

kaycebasques · 2025-01-12T01:09:47Z

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();


If the user types a query into the search box and then presses Esc to close the modal, then the last inline search results should be removed.

kaycebasques · 2025-01-12T01:12:13Z

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

+  results.classList.add("empty");
+  // Remove the container element from the tab order. Individual search
+  // results are still focusable.
+  results.tabIndex = -1;


Attempting to make the search results container non-focusable here

kaycebasques · 2025-01-12T01:12:22Z

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

+    // 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.


Attempting to make sure that inline search results links are focusable here

kaycebasques · 2025-01-12T01:18:34Z

tests/test_a11y.py

+
+
+@pytest.mark.a11y
+def test_search_as_you_type(page: Page, url_base: str) -> None:


@drammock re: the search results container itself receiving focus, it seems like this test should have failed? Does CI not run the a11y tests on different OS / browser permutations?

yeah, seems it should have 🤷🏻
CI only runs a11y tests in one job (ubuntu-latest, py3.12).

Added #2095 to track the issue. I assume we'll want to address that in a separate PR

kaycebasques · 2025-01-13T18:56:25Z

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

+  // When focus is on a search result, make sure that pressing Escape closes
+  // the search modal.
+  results.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") {


Escape should work as expected now

Kayce Basques added 14 commits January 3, 2025 16:54

Add a function to set up search-as-you-type

45b6447

Update the layout to load search-related scripts

1a1112b

Don't interfere with search page and bail if Search class isn't found

aee0d92

Add more search-as-you-type logic (not working yet)

ead8b4e

Start search-as-you-type styles (not working yet)

37143ed

Get basic search-as-you-type UX working

bdf3385

Hide the search results container until it has content

e531e70

Remove search results when query is empty

c9b5daa

Fix top position of search dialog

1f522ed

Make the feature configurable

1db1290

Add a11y test

710b383

Update comments

66c93ca

Add docs

00bb0af

Add comments to a11y test

5b06319

kaycebasques mentioned this pull request Jan 7, 2025

Search-as-you-type UX built on top of built-in Sphinx search tools #1977

Open

pre-commit-ci bot and others added 3 commits January 7, 2025 01:43

[pre-commit.ci] Automatic linting and formatting fixes

c203489

Add docstring

8f3de69

Fix docstring length

f40c6ff

kaycebasques mentioned this pull request Jan 7, 2025

test_pygments_fallbacks is failing #2094

Closed

12rambau mentioned this pull request Jan 7, 2025

Support third-party serarch like Algolia, minisearch, and lyrajs #795

Open

Merge branch 'pydata:main' into search

5132816

drammock reviewed Jan 8, 2025

View reviewed changes

Kayce Basques and others added 4 commits January 9, 2025 11:15

Make the a11y test more robust

19bab1c

[pre-commit.ci] Automatic linting and formatting fixes

4388a76

Make the link to Search class more robust

07d4b62

Temporary to change to verify dirhtml

49025fa

kaycebasques commented Jan 9, 2025

View reviewed changes

Kayce Basques and others added 3 commits January 11, 2025 16:52

Fix keyboard navigation stuff

78abe78

Revert docs-dev script back to its original state

23d2db2

[pre-commit.ci] Automatic linting and formatting fixes

be4ea8d

kaycebasques commented Jan 12, 2025

View reviewed changes

kaycebasques commented Jan 13, 2025

View reviewed changes

kaycebasques mentioned this pull request Jan 13, 2025

Update CI to run a11y tests on more browser / OS combos #2095

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

kaycebasques commented Jan 7, 2025

choldgraf commented Jan 7, 2025

12rambau commented Jan 7, 2025

drammock left a comment

drammock Jan 8, 2025

kaycebasques Jan 8, 2025

kaycebasques Jan 9, 2025

drammock Jan 8, 2025

kaycebasques Jan 8, 2025

kaycebasques Jan 9, 2025

drammock Jan 8, 2025

github-actions bot commented Jan 8, 2025

kaycebasques Jan 9, 2025

kaycebasques commented Jan 9, 2025

drammock commented Jan 9, 2025

kaycebasques commented Jan 12, 2025

kaycebasques Jan 12, 2025

kaycebasques Jan 12, 2025

kaycebasques Jan 12, 2025

kaycebasques Jan 12, 2025

drammock Jan 13, 2025

kaycebasques Jan 13, 2025

kaycebasques Jan 13, 2025



		@pytest.mark.a11y
		def test_search_as_you_type(page: Page, url_base: str) -> None:

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

Are you sure you want to change the base?

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

Conversation

kaycebasques commented Jan 7, 2025

choldgraf commented Jan 7, 2025

12rambau commented Jan 7, 2025

drammock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jan 8, 2025

Coverage report

Choose a reason for hiding this comment

kaycebasques commented Jan 9, 2025

drammock commented Jan 9, 2025

kaycebasques commented Jan 12, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment