1772771 - [a11y] Figure out appropriate semantic, non-table-based DOM for new "query" mechanism results

Status: NEW

(Webtools :: Searchfox, task)

Description

[Andrew Sutherland [:asuth] (he/him)]

In bug 1772720 I'm adding new templating logic for the experimental "query" mechanism which ideally will provide searchfox with a variety of new super-powers. Currently, the "search" results are fundamentally built on a big table. In bug 1558691 and bug 1511279 we added explicit header tags or aria-roles to mark "qual kind" groups/sections as h2 and file paths as h3. We seem to have missed marking "path kinds" (normal/third-party/tests/generated) as h1, presumably because we currently explicitly never actually say "Normal", it's just implied.

I'm currently trying my hand at having us not structure everything inside a giant table. There are a few reasons for this:

• It's not clear we need a table for the primary hierarchical display of search-style results. And having the table providing the primary structure does create some implementation awkwardness, like we manually handle toggling a single layer of expandos by creating a CSS class from a hash and then manually querySelectorAll-ing on that class and toggling element.style.display between "none" and "".
• I am envisioning potentially having 2 columns for results on the query page with support for heterogeneous and contextual results like documentation links and class hierarchies and the like. The rigidity of the table structure certainly wouldn't help with this, especially if we want to experiment using floats or something like that. Although CSS grid is probably more likely.
• The a11y tree in devtools looks bad since the table dominates. Maybe a11y tools like NVDA are able to ignore this, but it seems like having the built DOM reflect the semantics and thereby the a11y tree as well, that would be nice.
• The "query" results will actually include our fully semantically rendered and marked-up HTML output as long as I can make the performance work, and that will still do our table-like presentation stuff, and it's always nice to avoid tables within tables.

cc'ing :Jamie as a heads-up and for any initial thoughts. I'll make sure to provide links once I start to make progress. Note that this "query" UI is a medium-term effort that will take a while and is not going to replace the existing "search" mechanism anytime soon. But it is the focus of (my) enhancement efforts so the existing "search" is not going to see much in the way of enhancements as "query" strictly provides an opt-in super-set of the functionality "search" provides.

Comment 1

[Andrew Sutherland [:asuth] (he/him)]

While looking at MDN's page for summary I encounted a warning box for an example that says:

Warning: Because the <summary> element has a default role of button (which strips all roles from child elements), this example will not work for users of assistive technologies such as screen readers. The <h4> will have its role removed and thus will not be treated as a heading for these users.

I'm a little confused if that warning is still relevant, as the accessibility tree for "role: name" ends up looking like the following tree (manually translated) and it seems maybe fine:

• details: ""
  • summary: "▾ Definitions (DoubleSubOne::doublePure)"
    • staticText: "▾ "
    • heading: "Definitions (DoubleSubOne::doublePure)"
      • text leaf: "Definitions (DoubleSubOne::doublePure)"

And that's for HTML that looks like:

<details open="">
    <summary><h2>Definitions (DoubleSubOne::doublePure)</h2></summary>
    ....
</details>

The one notable styling thing I've done is added a CSS rule for details > summary > h2 to make the display value be "inline-block" and to drop the margins to 0. I have not tested anything using an a11y tool like NVDA yet as I'm still muddling through addressing other fundamental layout and result quality issues.

Comment 2

[James Teh [:Jamie]]

(In reply to Andrew Sutherland [:asuth] (he/him) from comment #0)

We seem to have missed marking "path kinds" (normal/third-party/tests/generated) as h1, presumably because we currently explicitly never actually say "Normal", it's just implied.

Yeah, having h1s for those would be nice, but i never got around to filing a bug for it.

• It's not clear we need a table for the primary hierarchical display of search-style results.

Semantically speaking, what would happen to the line numbers without the table?

• I am envisioning potentially having 2 columns for results on the query page with support for heterogeneous and contextual results like documentation links and class hierarchies and the like.

Would the "columns" have semantic meaning (the alignment between cells in the two columns means something) or would they just be in columns to make best use of the visual space?

• The a11y tree in devtools looks bad since the table dominates.

I don't really understand this. It would be the same if some other kind of container were used.

• The "query" results will actually include our fully semantically rendered and marked-up HTML output as long as I can make the performance work, and that will still do our table-like presentation stuff,

Does that mean each and every result will end up being its own table? I guess that makes some semantic sense, but it's going to be pretty verbose for screen reader users, as they'll get a table announcement for every result they read.