Code change:
Currently rustdoc's keyboard shortcuts use <kbd<kbdTab</kbd</kbdto 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 <kbd<kbdTab</kbd</kbdand <kbd<kbdShift</kbd+ <kbdTab</kbd</kbdto be used for navigating a list, and you can autosupport this by adding es, I think those autoskip elements as well. It's pretty bad form to override <kbd<kbdTab</kbd</kbd. Perhaps we should use for this and use something else for switching the search result tabs?
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", uses arrows as well to go through crates. However, we can talk about adding if you want?
tabindex won't work if we override tab, that's the problem this is a well-established pattern
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 I guess? But we have other issues to answer on this other one.
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.
TIL. One less thing to worry about. :)
Triage: not aware of any work here
After coming back to this issue after such a long time, I think we should keep the current behavior.
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.
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 , adding more tabindex could be problematic depending on evolutions (we some tabindex there as well).
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. 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.
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.
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.
My rough proposal is that we remove all JS that consumes <kbd<kbdTab</kbd</kbd, potentially use on the summary entries (and 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 ) 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 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.
But then how do you move in the search input? ;) 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 overload we in the JS, right? Then, with what would you replace it? Also, you can use and then use afterwards.
Nothing. The browser has acceptable default tab navigation behavior, though we can improve on it by applying some s if we want You only do this when focused on the search results area
Then I'm lost: how do you switch between the three tabs? 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. :-/
Tab navigate to a different "tab" and hit space. You will after hitting tab a few times. This is how keyboard navigation usually works.
That seems very counter-intuitive. Even more considering that switching between elements using isn't that common. Which is exactly why I don't think this is a good idea here. It's much more complicated than the current behavior.
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. 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.
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.
You can switch to the "default" behavior by simply pressing "esc". I don't see why it's a problem then.
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 :/
Some citations: From We are currently not coordinated with the structure of the webpage, and we do not follow the visual flow. From We violate this by tablocking From From Tab navigation, which is primarily how you change focus, is changing the context of the page here.
mentioned that she had been having trouble with this as well and was happy to see that it was reported.
What you're reporting isn't about accessibility but about personal preference: not using a mouse is a choice in most cases. Even though I think the current behavior is completely fine, I suggested to replace with another key. I don't want to lose the possibility to navigate the docs only with the keyboard, which is currently possible. Having to focus on tabs' title to switch between them is an absolute non-sense.
Even if this is true, what about the cases that are not the "most" case? That would be things like accessibility. Which does matter.
They can completely use rustdoc without a mouse, which was the whole point of those bindings. Accessibility does matter, I just don't agree with the arguments used here to support this.
This ... is an aspect of accessibility. Accessibility is about making your software accessible to the most number of people as possible; this includes people who are used to interacting with the web via keyboard. Even if it's a choice, it might introduce a barrier to entry to deliberately not use the choice (what if you don't even have a mouse attached to your computer and need to find one?) I do not think we should start a discussion about specific disabilities here, but there can be situations where someone has strong reasons for doing this where it's not "just a choice", as well. Furthermore tab-locking is absolutely a problem for blind users since the tab key is a key part of how blind users interact with the web and software in general. It feels roughly equivalent to locking Feel free to introduce a different keyboard shortcut for them that doesn't use tabs. My recommendation, to make this take the least amount of effort and least amount of change, was to use the default focus behavior and do nothing else. We don't have to force users to use the default focus behavior to navigate the page, I just want that to work. Alternatives would be good too; I'm having a hard time coming up with alternatives because most keys are used during typing. Note that with some tweaks we can make it so that literally the first tab-out of the search box will go to the tabs. So the workflow would be "tab, then hit tab more times to select your 'tab', and space" Also my personal feeling is that the tabs are not that used as much so I'm personally okay not having this. I'll point out that you are calling the default accessibility guidelines of the web as nonsense. This is stuff that has had a lot of work and research put into it, by people who are experts on this topic. The focus model of the web isn't perfect, but it's way better than what we'll be able to come up with. No, they cannot, because these are not clear at all, and there are norms about this so that people don't need to learn bespoke keyboard combinations for each website, because they won't. That's way too much overhead to just use a website. just didn't use search because of this. The tab-locking made it worse so she would refresh the page (not knowing that Esc works) to exit the search since the tab lock wouldn't let her otherwise, and over time stopped. She was typing URLs for documentation items directly instead of using search, which is an illustration of how bad this failure is. I'm sure she can talk more about her experience, but it is absolutely unacceptable for the answer to an accessibility issue to be "they can theoretically use it" when it is not designed for people to practically do it, since there's no obvious way to learn. Help text is not going to help here either, because, again, keyboard navigation on the web is largely a matter of norms, so people will not look for information on how to correctly keyboard navigate, they will simply dismiss the website as broken. That's a huge failure.
You can completely use rustdoc without a mouse (I don't have one for example), this isn't the issue here in my opinion. Well, we still need to keep that in mind in such discussions. I have to admit it's a bit hard to read this when I had to fight to keep rustdoc usable even without JS. But I'm glad that it's now an important parameter of rustdoc and that I'm not the only one to think about it. :) Yes, it's my whole point: I don't mind removing the current tab-locking (even less if it improves experience for people with no mouse!), but it needs to be replaced by something else. You're getting out of scope here, please not give me intentions I don't have. What I said is that the rustdoc search works without keyboard and that if we wanted to not tab-lock anymore, I'm okay with it but we needed to replace it with another key to be able to keep the same behavior overall. I'd rather simply switch fully out of the instead of doing such hacks if possible. We just need to agree on another key to have the same results. I agree with that part, but then it's a complete different issue. You're using one person to back all the reasoning here, which isn't great. I'm sorry if had a bad experience with rustdoc. But one person had issue with rustdoc doesn't mean it's a failure. Once again, it'd be nice to consider that people spent a lot of time on rustdoc and that if they knew about this, they'd be very happy about trying to improve the situation. However, I repeat myself once again: I agree that tab-locking isn't the best and I agree we should replace it and not remove it.
You theoretically can, practically it is hard to discover this keyboard setup and it does not follow norms, so people will not use it. 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. 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! 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. Thank you. I do not mind coming up with something better, but I do not want to block it on coming up with additional keyboard shortcuts, because I think this is hard. I want to remove this, and then consider coming up with something that can replace it, keeping in mind that tab-switching would be possible by default via the keyboard the same way it is on Google. I think tab-locking is very very bad and should be gotten rid of as soon as possible.
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.
Hi all, I was around when 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
a data point: i was wildly surprised to find that <kbdtab</kbdswitches 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: ! you might notice that the tab titles don't get annotations, because they're just s, so they're not keyboard-accessible.
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 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 . this means does a different thing for than it does by default on every browser: 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. 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.
Then that is a problem we should address! Well, you can't get this page if you don't have javascript enabled, so in that sense, it wouldn't improve anything. :laughing: 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). Because the page is much simpler and I think the comparison is a bit out of context here. For reference, I was commenting on this: 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. And I'm sorry about that. Which is why we're currently discussing about fixing it.
1. The whole point here is about prioritization. Until recently, I was mostly alone working on this. 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. Could you open a separate issue about this please?
will do. another point: in current versions of chrome, without vimium installed, pressing <kbdesc</kbddoes 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 <kbdtab</kbdonce you've done a search.
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 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. 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.
I meant no further custom JS. 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.
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?
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.
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.
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
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.
I think I can explain this, wants a way to go through search results without having to defocus the search field, so that you can keep typing
Not if you in a input field. And that problem will be solved when we'll stop tab-locking. ;) Good point, ctrl+arrows then! 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. Exactly! Great! I'll send the PR shortly then. We really need to improve the help popup.
ah, so pressing enter to (say) select an alternate tab would be out of the question since it would defocus? i can see that
Hello! Pardon the late response. As mentioned above, I would like to reiterate that 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 . 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 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.
I use vimium for navigation and browser use. I find the rust docs to be very amenable to use of a keyboard with vimium.
Could you and implement it? Since you seem more knowledgeable in this area.
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
Arf, another issue? :-/
While I appreciate the invitation to do so, I have very little familiarity with the internals of , 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.
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

Related discussion:
text: ["T", "Focus the theme picker menu"], ["↑", "Move up in search results"], ["↓", "Move down in search results"], <del> ["↹", "Switch tab"], </del> <ins> ["ctrl + ↑ / ↓", "Switch result tab"], </ins> ["&#9166;", "Go to active search result"], ["+", "Expand all sections"], ["-", "Collapse all sections"], <del> ].map(x => "<dt><kbd>" + x[0] + "</kbd></dt><dd>" + x[1] + "</dd>").join(""); </del> <ins> ].map(x => "<dt>" + x[0].split(" ") .map((y, index) => (index & 1) === 0 ? "<kbd>" + y + "</kbd>" : y) .join("") + "</dt><dd>" + x[1] + "</dd>").join(""); </ins> var div_shortcuts = document.createElement("div"); addClass(div_shortcuts, "shortcuts"); div_shortcuts.innerHTML = "<h2>Keyboard Shortcuts</h2><dl>" + shortcuts + "</dl></div>";