Skip to content

Rustdoc search box fails accessability guidelines #31060

@steveklabnik

Description

@steveklabnik
Member

Background links: https://www.w3.org/TR/WCAG20-TECHS/H32.html for a11y, http://doc.rust-lang.org/std/ for rustdoc search. Before typing anything:

2016-01-20-141055_981x72_scrot

After typing a query:

2016-01-20-141108_968x198_scrot

Basically, we currently implement the searchbox by using JS to hook into the submission: https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/static/main.js#L737-L741

So we're not providing a 'submit' button. But we're supposed to.

I'm not sure of the best way to resolve this, exactly. I think the plan would be:

  1. create an <input type="submit">
  2. hide it with CSS
  3. have it trigger that JS instead

Does that make sense? I am bad at front-end :(

Activity

added
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
on Jan 20, 2016
nagisa

nagisa commented on Jan 20, 2016

@nagisa
Member

I believe we already handle the submit events properly (I made it to do so) and pressing the Enter delivers such an event. I’m not sure how adding a hidden button would change anything here, but if that makes some a11y testing suite happier, sure?

marcysutton

marcysutton commented on Jan 20, 2016

@marcysutton

A few tweaky things you could do, to start:

  1. Add a label to the input field, either using a paired label element or an aria-label attribute directly on the input.
  2. Mark up the results table so the columns relate to each other. OR change the markup into a list of links using CSS to style them instead.

For the results experience, you have a few options. Without a submit button it acts like an autocomplete, which can be a complex ARIA pattern to master. Essentially, you'd use an ARIA live region to announce there are results on the screen, and bind the arrow keys to navigate the results nearby. But I think if you added a submit button you could get away with skipping the autocomplete functionality, since the user will expect results. To make things slick you could use focus management to send focus into the results after submitting.

Hope that helps!

added
T-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.
and removed on May 18, 2017
onelson

onelson commented on Nov 25, 2017

@onelson

I spent a little while looking at the markup and js in play here, and while it would be trivial to add a submit input which is hidden, it also feels a bit like following the letter of the law while neglecting the spirit.

I am not up to speed on ARIA mechanics, but skimming through https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions made me feel like @marcysutton is right on the money. The flow described here looks to line up very well with how search results behave.

In order to decide if it would be worth the extra effort I got a screen reader and enabled while searching the docs. The results were illuminating!

With an added submit input, it appears we earn nothing over what we already have. The content of the search box is read aloud as the search terms are typed, but there's no indication that results have been loaded after the fact.

I looked at a few examples of how live regions are meant to work, and made the following changes as a test:

diff --git a/src/librustdoc/html/layout.rs b/src/librustdoc/html/layout.rs
index 8c14d1bbe8..51e88c5bb0 100644
--- a/src/librustdoc/html/layout.rs
+++ b/src/librustdoc/html/layout.rs
@@ -72,7 +72,7 @@ r##"<!DOCTYPE html>
     <nav class="sub">
         <form class="search-form js-only">
             <div class="search-container">
-                <input class="search-input" name="search"
+                <input class="search-input" name="search" aria-controls="search"
                        autocomplete="off"
                        placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
                        type="search">
@@ -81,7 +81,7 @@ r##"<!DOCTYPE html>
     </nav>
 
     <section id='main' class="content">{content}</section>
-    <section id='search' class="content hidden"></section>
+    <section id='search' class="content hidden" role="alert" aria-live="polite"></section>
 
     <section class="footer"></section>

With the search input listed as something that controls the live region the results are rendered in, my typing was read aloud as I entered my terms, then as the results loaded in the reader announced:

  • the number of results for my search term
  • the number per column (types/modules, parameters, return values)
  • each of the visible results

This is just the visible text inside the search node in the DOM, but it felt like an immediate improvement.
When I resumed typing, the process started again from the top once I gave it a beat to interrupt.

This seems more useful, but examining some other examples of autocompletion widgets, I think we can do better.

One implementation I saw used a hidden span as the live region and updated its content with status and instructional text. In that case, the span would announce the number of results and instructions to use up/down to select an item from the list.

For us, I can imagine using a hidden span to report the number of results, total and for each column, what the active column is, then instruct the user to use up/down and also note that tab would switch columns. As the user navigates the list, the span could be updated with the text content of the result. This is exactly what Marcy was pitching, if I understand correctly.

This offers a couple wins over the initial test I did in that it's more instructional, it helps the user keep track of what state the page is in, and it saves the user from a rambling recital of all the visible results - instead the results are read at a pace controlled by the user themselves.

As an aside, using tab to switch the active column felt a little weird to me. I wonder if we couldn't listen to a different key press for switching the active result type. Maybe h/l for the vim crowd, or left/right (which seems better to me). For this to work, we'd have to pull focus from the search input while navigating the results, which would be a change from how it currently works. This could really offend folks used to the old behavior.

I'm no accessibility expert. I'm coming to this fresh. Still, if this sounds like a good plan to others, I'm happy to dig in and try to make it happen.

nrabulinski

nrabulinski commented on May 1, 2020

@nrabulinski
Contributor

@rustbot claim

self-assigned this
on May 1, 2020
Alexendoo

Alexendoo commented on Aug 5, 2020

@Alexendoo
Member

Hi, are you still working on this issue @nrabulinski?

Alexendoo

Alexendoo commented on Aug 26, 2020

@Alexendoo
Member

@rustbot release-assignment

removed their assignment
on Aug 26, 2020
jsha

jsha commented on Jun 3, 2021

@jsha
Contributor

using tab to switch the active column felt a little weird to me. I wonder if we couldn't listen to a different key press for switching the active result type. Maybe h/l for the vim crowd, or left/right (which seems better to me). For this to work, we'd have to pull focus from the search input while navigating the results, which would be a change from how it currently works. This could really offend folks used to the old behavior.

FYI, in #84462 we recently did this. After searching, you can use the down arrow to focus the results area, and then you can use left/right to focus different result tabs.

removed
T-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.
on Jan 18, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-a11yArea: Anything to do with accessibilityC-bugCategory: This is a bug.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @steveklabnik@ehuss@jsha@onelson@nagisa

        Issue actions

          Rustdoc search box fails accessability guidelines · Issue #31060 · rust-lang/rust