Potentially swap arrow keys and tab in rustdoc keyboard shortcuts

[Manishearth]

Currently rustdoc's keyboard shortcuts use Tab to cycle between the tabs at the top of search results, and the arrow keys for moving through search results.

It's much more common for Tab and Shift + Tab to be used for navigating a list, and you can autosupport this by adding tabindexes, I think those autoskip display:none elements as well. It's pretty bad form to override Tab. Perhaps we should use tabIndex for this and use something else for switching the search result tabs?

[GuillaumeGomez]

I never navigated a list using tab. I didn't even know it was a thing. O.o

Also, up and down arrows seem more accurate to me and this has been integrated. As a little "bonus", docs.rs uses arrows as well to go through crates.

However, we can talk about adding tabindex if you want?

[Manishearth]

tabindex won't work if we override tab, that's the problem

this is a well-established pattern

[GuillaumeGomez]

Even with tabindex, we'll still have to bind 'enter' key I assume to change the current search tab, no? Also, we can't bind right and left arrows to do this so we're kinda limited to find replacements. The last option would be to add a setting to disable like you proposed in #65211 I guess? But we have other issues to answer on this other one.

[Manishearth]

No, if you're using tab navigation the enter key should automatically work to "click" the currently selected thing. The browser functionality around this is quite robust, let's not reinvent it.

…

On Thu, Oct 10, 2019, 7:02 AM Guillaume Gomez ***@***.***> wrote: Even with tabindex, we'll still have to bind 'enter' key I assume to change the current search tab, no? Also, we can't bind right and left arrows to do this so we're kinda limited to find replacements. The last option would be to add a setting to disable like you proposed in #65211 <#65211> I guess? But we have other issues to answer on this other one. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#65212?email_source=notifications&email_token=AAMK6SC2KC2VI45ASMRD5RLQN4YZDA5CNFSM4I6TJNAKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEA4ORGY#issuecomment-540600475>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAMK6SF2EQYCJ2LL4JCUBYLQN4YZDANCNFSM4I6TJNAA> .

[GuillaumeGomez]

TIL. One less thing to worry about. :)

[steveklabnik]

Triage: not aware of any work here

[GuillaumeGomez]

After coming back to this issue after such a long time, I think we should keep the current behavior.

[Manishearth]

I still disagree. I haven't had the time to prototype this, but this is very much not following the norms for keyboard navigation which has accessibility implications.

[GuillaumeGomez]

I don't see how accessibility can be impacted by this. I assume they don't go through text content the same way and that changing how the interactions are done will change anything for them. In addition to that, when included in docs.rs, adding more tabindex could be problematic depending on docs.rs evolutions (we added some tabindex there as well).

[Manishearth]

Firstly, keyboard accessibility is not only for the blind. People may prefer keyboards over mice for many accessibiltiy reasons. However, tab navigation is a huge part of accessibility for the blind in many cases.

In addition to that, when included in docs.rs, adding more tabindex could be problematic depending on docs.rs evolutions (we added some tabindex there as well).

No, that's the point, we don't actually need to add tabindex, currently we're overriding tab defaults via JS which is almost always really bad. The tab defaults for the page are quite good already, what would happen is that you would tab through focus on the top tabs, and then through all of the links and summary short strings. We may potentially want to exclude the summary short strings from tab navigation, but other than that we wouldn't be doing special tabindex stuff.

[Manishearth]

The largest problem here is that the moment you tab into the "tabs", your keyboard navigation is stuck there forever. Overriding browser tabbing with JS isn't always a problem but this is like one of the biggest reasons it usually is.

[jyn514]

Perhaps we should use tabIndex for this and use something else for switching the search result tabs?

Maybe we could use left/right arrows instead of tab for switching between 'In Names' and 'In Parameters'? I think that's more clear than tabs anyway.

[Manishearth]

My rough proposal is that we remove all JS that consumes Tab, potentially use tabindex=-1 on the summary entries (and tabindex=0 on the links, if necessary, but i don't think it will be).

(Negative tab index = "do not tab-focus this". Zero tab index = "please tab focus this in document order", this does not interfere with any explicitly defined positive tab indices in docs.rs)

We could also add arrow key navigation, but people also use arrow keys for editing typed search phrases so that's more complex. At the very least we need to get rid of the custom JS IMO.

[jyn514]

We could also add arrow key navigation, but people also use arrow keys for editing typed search phrases so that's more complex. At the very least we need to get rid of the custom JS IMO.

Hmm, personally I think I'd prefer for left/right to switch the search tabs and have to use s explicitly to bring the search bar into focus. I don't think we should get rid of keyboard shortcuts for tabbing without having some replacement, even if it's a few more keystrokes.

[Manishearth]

Hmm, personally I think I'd prefer for left/right to switch the search tabs and have to use s explicitly to bring the search bar into focus. I don't think we should get rid of keyboard shortcuts for tabbing without having some replacement, even if it's a few more keystrokes.

Oh sure, I meant that we should not be capturing left/right whilst focused on the search box. We can add that event listener to the search results area, that should be fine.

[GuillaumeGomez]

Perhaps we should use tabIndex for this and use something else for switching the search result tabs?

Maybe we could use left/right arrows instead of tab for switching between 'In Names' and 'In Parameters'? I think that's more clear than tabs anyway.

But then how do you move in the search input? ;)

Firstly, keyboard accessibility is not only for the blind. People may prefer keyboards over mice for many accessibiltiy reasons. However, tab navigation is a huge part of accessibility for the blind in many cases.

@Manishearth I don't see how the current behavior blocks that? You can still move through answers using up and down arrows. But I think I'm starting to understand your issue: it's the tab overload we added in the JS, right? Then, with what would you replace it? Also, you can use esc and then use tab afterwards.

[Manishearth]

Then, with what would you replace it?

Nothing. The browser has acceptable default tab navigation behavior, though we can improve on it by applying some tabindex=-1s if we want

But then how do you move in the search input? ;)

You only do this when focused on the search results area

[GuillaumeGomez]

Nothing. The browser has acceptable default tab navigation behavior, though we can improve on it by applying some tabindex=-1s if we want

Then I'm lost: how do you switch between the three tabs?

You only do this when focused on the search results area

But then you need to focus on the search results area, which is almost never the case as far as can I can tell. That doesn't sound like a great idea. :-/

[Manishearth]

Then I'm lost: how do you switch between the three tabs?

Tab navigate to a different "tab" and hit space.

But then you need to focus on the search results area, which is almost never the case as far as can I can tell. That doesn't sound like a great idea. :-/

You will after hitting tab a few times. This is how keyboard navigation usually works.

[GuillaumeGomez]

Tab navigate to a different "tab" and hit space.

That seems very counter-intuitive. Even more considering that switching between elements using tag isn't that common.

You will after hitting tab a few times. This is how keyboard navigation usually works.

Which is exactly why I don't think this is a good idea here. It's much more complicated than the current behavior.

[Manishearth]

That seems very counter-intuitive. Even more considering that switching between elements using tag isn't that common.

This is literally how keyboard navigation typically works on the web. There are norms for how to do this, many people use this to a fair amount, some people rely strongly on it.

Which is exactly why I don't think this is a good idea here. It's much more complicated than the current behavior.

The current behavior tab-locks you which is a huge accessibility hazard. Furthermore, it's nonintuitive, it does not follow the typical model of tab-navigation on the web.

[antoyo]

I'm only using keyboard on my computer and I never use tab to switch between elements and I also find current shortcuts good enough.

[GuillaumeGomez]

You can switch to the "default" behavior by simply pressing "esc". I don't see why it's a problem then.

[Manishearth]

Firstly, no, the escape key exits the search pane altogether.

Secondly, keyboard users will not know to expect such a thing.

No matter what, it is a problem that our webpages tablock by default. I can't believe that we're having a hard time coming to agreement on that, I would have expected accessibility to be valued here :/

[Manishearth]

Some citations:

From https://www.csun.edu/universal-design-center/web-accessibility-criteria-tab-order

Tab order is important for proper navigation through a keyboard interface. The keyboard tab order must be coordinated with the structure of the webpage. The default keyboard navigation order must be logical and intuitive. The tab order should follow the visual flow of the page: left to right, top to bottom – header first, then main navigation, then page navigation (if present), and finally the footer.

We are currently not coordinated with the structure of the webpage, and we do not follow the visual flow.

From https://www.w3.org/WAI/WCAG21/quickref/#no-keyboard-trap:

If keyboard focus can be moved to a component of the page using a keyboard interface, then focus can be moved away from that component using only a keyboard interface, and, if it requires more than unmodified arrow or tab keys or other standard exit methods, the user is advised of the method for moving focus away.

We violate this by tablocking

From https://www.w3.org/WAI/WCAG21/quickref/#focus-order:

If a Web page can be navigated sequentially and the navigation sequences affect meaning or operation, focusable components receive focus in an order that preserves meaning and operability.

From https://www.w3.org/WAI/WCAG21/quickref/#on-focus:

When any user interface component receives focus, it does not initiate a change of context.

Tab navigation, which is primarily how you change focus, is changing the context of the page here.

[Manishearth]

@katie-martin-fastly mentioned that she had been having trouble with this as well and was happy to see that it was reported.

[Manishearth]

Honestly, the fact that Google works this way should be a strong signal that we should follow suit, since most people using keyboard navigation will be used to doing it the same way there.

[dns2utf8]

Hi all,

I was around when @GuillaumeGomez implemented the feature and I have grown quite fond of how it works because it is very intuitive for me.
What would you do with the tab key when it is not bound to tabbing trough the results?
After pressing escape, the tab is free anyways.

Just because Google does something, feels like an ad-hominem argument. Unless you would like rustdoc to collect the most common searches and report them (for a subscription?) to the crate authors too?

Can you elaborate on the No-JS idea? Because this is hard for me to imagine since the filtering is very powerful at the moment and I love the reverse search which I need in like 30% of my queries.

Cheers,
Stefan

[sersorrel]

a data point: i was wildly surprised to find that tab switches between tabs, and it took me a while to work out that it only happens when the textfield has focus.

i usually use vimium to navigate the search results, which works because the results are just (pairs of) links:

...though you might notice that the tab titles don't get annotations, because they're just <div>s, so they're not keyboard-accessible.

[iximeow]

You're using one person to back all the reasoning here, which isn't great. I'm sorry if @katie-martin-fastly had a bad experience with rustdoc. But one person had issue with rustdoc doesn't mean it's a failure

how many people are necessary?

even if the accessibility point is not compelling for some reason, the current tab mechanic has a very surprising behavior: if you begin a search, then empty the box (backspace, or ctrl+a and then backspace), the docs page reverts to the crate documentation as if no search had been done, but focus is still locked to the search bar. the page is visually identical to having not done a search, where tab could cycle between elements.

before seeing this issue, i had encountered this and assumed that docs.rs simply had some flaky javascript, did not make time to investigate, and moved on. i thought it was a bug.

to return to a mode where the tab key is useful again, you have to know to press esc. this means esc does a different thing for docs.rs than it does by default on every browser: esc is a shortcut for "stop", which stops all connections. the escape key has an expected behavior. it will not occur to someone who primarily navigates the internet by keyboard to press the escape key.

What would you do with the tab key when it is not bound to tabbing trough the results?

i would have the tab key to cycle through through tabs and continue to the "in names" content, from top to bottom. cycling from "In Return Types" to "In Names" is an extremely narrow repurposing of tab (and shift+tab, to go backwards in tab order) command.

[GuillaumeGomez]

You theoretically can, practically it is hard to discover this keyboard setup and it does not follow norms, so people will not use it.

Then that is a problem we should address!

This isn't a hack! This is how focus works on the web by default! We would not even have to write code to support this, our page is laid out in a way that works well without any javascript!

Well, you can't get this page if you don't have javascript enabled, so in that sense, it wouldn't improve anything. 😆

And it's exactly what I suggest by replacing instead of removing. The default web behavior exists but requires multiple actions. We can do better than that (like we currently do for example).

It is! The default focus behavior of the web! Which is what is used everywhere, including on Google Search, which also has search results and tabs.

Because the page is much simpler and I think the comparison is a bit out of context here.

This isn't a hack! This is how focus works on the web by default! We would not even have to write code to support this, our page is laid out in a way that works well without any javascript!

For reference, I was commenting on this: So the workflow would be "tab, then hit tab more times to select your 'tab', and space and I misunderstood what you meant. But that still makes more interactions than the current behavior (one), which is why I want a replacement and not a removal.

And again, without javascript, you can't have the search results page.

No, I also had the same problem here, I just am more comfortable with switching to a mouse for this. I'm highlighting Katie's experience because she hit the worst failure mode -- she stopped using search entirely.

And I'm sorry about that. Which is why we're currently discussing about fixing it.

[GuillaumeGomez]

how many people are necessary?

@iximeow 1. The whole point here is about prioritization. Until recently, I was mostly alone working on this. @dns2utf8 suggested this new feature, I thought it was nice and would improve everyone's life. Now I realize it didn't, I'm sorry about it but I still want to be able to switch tabs without losing focus on the search bar. We just need to agree on a key to do so and then it's done.

Please all remember that it's mostly about priority. I don't voluntarily want to make people rustdoc's experience bad. If something doesn't feel right to you, well, it's simply because I ignored it could be used this way.

@sersorrel Could you open a separate issue about this please?

[sersorrel]

@GuillaumeGomez will do.

another point: in current versions of chrome, without vimium installed, pressing esc does not release focus from the text field, it cancels the search altogether. so as far as i can see, if you don't use vimium, there's no way to recover the usual behaviour of tab once you've done a search.

[Manishearth]

What would you do with the tab key when it is not bound to tabbing trough the results?

Browsers by default use the tab key for focus, which is an important accessibility property. It would just use the default behavior, which lets you switch through "tabs" and the search results

Just because Google does something, feels like an ad-hominem argument. Unless you would like rustdoc to collect the most common searches and report them (for a subscription?) to the crate authors too?

This was an argument about norms: When people interact with the web, there are norms as to how things work. You can expect to find a search box at the top or top right of the page. You can expect to find a contact us at the bottom. Nobody is going to learn a billion minute things about how to use a particular website, a lot of this is based on norms. If you follow norms, you do not need to educate your users on how to use your website, which is exactly the problem we have here. Furthermore, the fact that Google -- an organization large enough to have accessibility teams to actually do the research on this -- picked the default behavior on their main website, is a pretty large signal.

But okay, Bing has similar behavior, except focus starts on the first search entry, and you can shift-tab to get back to the "tabs". This is also easy behavior to replicate with a little javascript. Wikipedia doesn't have "tabs" but it has options at the top of the search and it works the same way.

Can you elaborate on the No-JS idea? Because this is hard for me to imagine since the filtering is very powerful at the moment and I love the reverse search which I need in like 30% of my queries.

Oh no i'm not saying we remove all the JS here, I'm just saying that if we remove the JS around the tab key the default behavior is actually quite okay.

[Manishearth]

Well, you can't get this page if you don't have javascript enabled, so in that sense, it wouldn't improve anything. 😆

I meant no further custom JS.

For reference, I was commenting on this: So the workflow would be "tab, then hit tab more times to select your 'tab', and space and I misunderstood what you meant. But that still makes more interactions than the current behavior (one), which is why I want a replacement and not a removal.

I understood what you meant. That is more interactions, but what i'm saying is that -- we are not losing the ability to do this, it's just harder (but following web norms, so nobody has to learn them!!), and given that we are currently violating many accessibility guidelines I would like to remove this behavior as soon as possible (there was less urgency for me when I filed this because I had not noticed the tablocking), and perhaps introduce new behavior later if possible. I'm having trouble imagining a good option for new behavior. The best I can think of is using the up/down arrow keys for this, which isn't super intuitive.

[GuillaumeGomez]

I understood what you meant. That is more interactions, but what i'm saying is that -- we are not losing the ability to do this, it's just harder (but following web norms, so nobody has to learn them!!), and given that we are currently violating many accessibility guidelines I would like to remove this behavior as soon as possible (there was less urgency for me when I filed this because I had not noticed the tablocking), and perhaps introduce new behavior later if possible. I'm having trouble imagining a good option for new behavior. The best I can think of is using the up/down arrow keys for this, which isn't super intuitive.

up/down is already used to go through items in the current tab, so we'll need another one haha. tab was very convenient for that... Well anyway, let's just pick a key, whichever the one we take and I'll open a PR so we can move on.

[GuillaumeGomez]

Just got an idea for the key:

• ctrl (or shift) + up/down would go through tabs
• up/down alone go through items in the list

How does that sound?

[GuillaumeGomez]

@sersorrel It's voluntary (just realized it). The search page results is supposed to be switched into/out quickly by using escape or focusing on the search bar. We should really add all the rustdoc interactions into the help... I'll do that once we've settled down here.

[spearman]

My expectation is that arrow keys are for scrolling and tab is for selecting. It took me some time to get used to rustdoc doing things differently.

[iximeow]

ctrl (or shift) + up/down would go through tabs

shift + up/down should be a non-option: shift+up will select the text being searched for.

why must the list of tabs be cyclic? is going from the third tab to first tab in one keystroke a common task?

i do not understand why tab cannot move focus from the third tab to the first item in the selected tab of results

[Manishearth]

@GuillaumeGomez that seems great! It seems a little unintuitive to me but that is fine, I don't think tab-switching is a particularly common operation. If you're okay with people learning the key combos I'm all for it.

[Manishearth]

i do not understand why tab cannot move focus from the third tab to the first item in the selected tab of results

I think I can explain this, @GuillaumeGomez wants a way to go through search results without having to defocus the search field, so that you can keep typing

[GuillaumeGomez]

My expectation is that arrow keys are for scrolling and tab is for selecting. It took me some time to get used to rustdoc doing things differently.

Not if you in a input field. And that problem will be solved when we'll stop tab-locking. ;)

shift + up/down should be a non-option: shift+up will select the text being searched for.

Good point, ctrl+arrows then!

why must the list of tabs be cyclic? is going from the third tab to first tab in one keystroke a common task?

i do not understand why tab cannot move focus from the third tab to the first item in the selected tab of results

That's a completely different behavior. But since we won't have tab-lock anymore, it'll now be possible so I guess it's all good? You'll have the choice between using rustdoc events through the search input or you can simply use the normal events by unfocusing the search input.

I think I can explain this, @GuillaumeGomez wants a way to go through search results without having to defocus the search field, so that you can keep typing

Exactly!

@GuillaumeGomez that seems great! It seems a little unintuitive to me but that is fine, I don't think tab-switching is a particularly common operation. If you're okay with people learning the key combos I'm all for it.

Great! I'll send the PR shortly then. We really need to improve the help popup.

[iximeow]

go through search results without having to defocus the search field

ah, so pressing enter to (say) select an alternate tab would be out of the question since it would defocus? i can see that

[cratelyn]

Hello! Pardon the late response. As mentioned above, I would like to reiterate that Tab is not only a conventional choice for navigating through lists such as this, but also a specified best practice for web accessibility. The W3C Working Groups's Authoring Practices says the following.

All focusable elements contained in a table are included in the page tab sequence.

I will try not to rehash the accessibility discussion above, but I will say that I do not own a mouse. Regardless of whether or not that is "by choice" due to a disability, this means that the tablocking behavior makes the generated documentation difficult for me to use. In many situations, rather than using the search feature, I often opt to manually type the URL's myself to navigate to a given type.

While today I am a Rust engineer by trade, until very recently I worked as a front-end engineer, often focusing on improving the accessibility features of existing websites. The behavior that @Manishearth is requesting is not a matter of preference, it is considered an industry-wide best practice. I do not believe that citing other websites' conformance to this is an ad-hominem argument, it is reasonable supporting evidence of this position.

[rbalicki2]

I use vimium for navigation and browser use. I find the rust docs to be very amenable to use of a keyboard with vimium.

[dns2utf8]

Could you @Manishearth and @katie-martin-fastly implement it? Since you seem more knowledgeable in this area.

[Manishearth]

@dns2utf8 I mean, we were suggesting switching to the default behavior of the browser, so there's nothing new to implement, just code to use. I'm happy to do this or implement Guillaume's proposed keyboard shortcuts but it seems like he's already working on it? If not, happy to do this myself.

There's a follow-up I'd like to experiment with which I'll implement, but I'll do that once we resolve this

[GuillaumeGomez]

There's a follow-up I'd like to experiment with which I'll implement, but I'll do that once we resolve this

Arf, another issue? :-/

[cratelyn]

Could you @Manishearth and @katie-martin-fastly implement it? Since you seem more knowledgeable in this area.

While I appreciate the invitation to do so, I have very little familiarity with the internals of rustdoc, and unfortunately very little bandwidth to contribute as of late. I do want to make a note of appreciation for all of the work that goes into maintaining this project, but I should disclaim that I was offering a comment describing my experience from the perspective of (a) a user of the Rust documentation impacted by keyboard accessibility, and (b) an engineer that has some previous experience with web accessibility guidelines and standards.

[Manishearth]

Arf, another issue? :-/

Nothing pressing, I just have ideas for how we can be even better here and want to experiment. I'll open PRs if I find something that works well