Search bar shortcut behavior

[gabalafou]

TL;DR- Proposal

I propose two changes to the search keyboard shortcut (Ctrl + K):

1. It always opens, never closes, the search bar, and
2. It always opens the search bar in the modal (aka pop-over) dialog; it does not take you to a search input field that may already be on the page (e.g., in the sidebar or at the top of a search results page).

Background

While working on #1932, I noticed that the JavaScript that handles toggling the search bar on and off is more complex than I would have expected.

Prior to #807, if I'm reading the previous code correctly, the behavior of the keyboard shortcut was to show and focus the pop-over search bar. But #807 changed the keyboard shortcut so that if there is a persistent search input field on the page, it takes precedence over the pop-over search bar. I'm not entirely sure why this was done. (@drammock, any insight here?)

However, the current behavior (introduced in #807) is problematic for at least a few reasons:

1. It breaks the search button. On mobile, a persistent search bar in the sidebar is hidden behind the mobile hamburger menu. This means that when you click the search button in the nav bar, nothing happens.
2. It (probably) violates WCAG SC 3.2.4: Consistent Identification (Level AA). The idea behind this 3.2.4 is that it's bad for accessibility for functionality to be inconsistent across web pages. If some pages (such as the search result page) have a persistent search bar, but others do not, that means that the behavior when you press the keyboard shortcut is not always consistent across pages on the site. In some pages it pops up an input field, in others it puts you into an input field already on the page.
3. It's not very consistent. It would be more consistent and symmetric if Ctrl + K always opens the search bar modal, while Escape always closes it.

Benefits

1. Simpler JavaScript
2. Simpler docs
3. More consistent behavior / compliance with WCAG 3.2.4

[drammock]

if there is a persistent search input field on the page, it takes precedence over the pop-over search bar. I'm not entirely sure why this was done. (@drammock, any insight here?)

We strongly recommend (but do not enforce) that users enable only one or the other of the search button / search field. So we assume that if the field is present, the modal is not

[gabalafou]

Yes but why is that?

The search docs page says:

If a page includes both the search button and an always-visible search field, the keyboard shortcuts will focus on the always-visible field and the hidden search field overlay will not display.

But it doesn't explain why we decided on that behavior, and I can't seem to piece together an explanation from old GitHub issues and comments.

But I have some hypotheses...

But first, to make sure we're on the same page, I want to get clear on terms. As far as I understand it, there are three named search components:

1. search-field - a component that contains an input field where the user can type a search term. Important: the search-field component is always included in two places on PST-powered sites: the search results page and the overlay/modal; as far as I can tell, there is no way to turn that off explicitly. The component can also be included elsewhere on the site, such as in the sidebar or the nav bar, depending on how theme adopters configure their site.
2. search-button - a magnifying glass icon that when clicked takes you to a search-field
3. search-button-field - a button that looks like a rounded search field but otherwise behaves just like search-button

Do we consider it bad UI for a docs site to put a search-button-field and a non-hidden search-field on the same page? Is that the reason behind the warning on the search docs page?

Or did we have some sites asking to turn off the on-demand search overlay?

If the latter, then I would prefer to make that an explicit configuration option, rather than a side-effect of including a persistent search-field on all pages.

If, on the other hand, we think it's bad UI to put both a non-modal search-field and a search-button-field on the same page, then I think all we need to do is say so in the docs (and provide sensible defaults).

Now that leaves us with the case of a site that has no search-button-field but does have a persistent search-field - for example, cashocs. I suppose it could be a bit confusing for the persistent search-field on the site to say Ctrl + K, but then the shortcut opens up the search overlay/modal instead. So I propose removing the shortcut hint from any search-field that is outside the overlay/modal. I think this is also a good idea because if theme adopters persist the search-field in the sidebar or the nav bar, it won't have much width, so it would be better to free up the width that the hint takes. To take it a bit further, on the search modal, I would prefer moving the shortcut hint to a new line with our smallest font and change it to say: "Escape to close. Ctrl + K to open."

So to slightly rephrase my original proposal, unless users have asked us for a way to turn off the search overlay, then either of the following actions should always result in opening the overlay:

• clicking a search-button or search-button-field
• pressing Ctrl + K

[drammock]

Do we consider it bad UI for a docs site to put a search-button-field and a non-hidden search-field on the same page? Is that the reason behind the warning on the search docs page?

yes.

Or did we have some sites asking to turn off the on-demand search overlay?

I don't recall that ever happening. The intent was that it's linked to the search-button(-field) components so it can be disabled in conf.py on any user site. In other words, the overlay modal was meant to only happen if the search-button or search-button-field are present. if the (persistent-)search-field is present, ctrl+k is meant to focus that field and not overlay a new one. This has problems on mobile (focused field hidden in the offscreen sidebar drawer), as you've noted, but that was the intent.

for example, cashocs. I suppose it could be a bit confusing for the persistent search-field on the site to say Ctrl + K, but then the shortcut opens up the search overlay/modal instead.

I agree that would be bad UX.

unless users have asked us for a way to turn off the search overlay, then either of the following actions should always result in opening the overlay...

I'm a bit hesitant here. If we're going to let folks place a persistent search field in their sites, it feels a bit mean to not give it a keyboard shortcut and not use it unless they click on it with their mouse / tap it with their finger.