Skip to content

Make every dialog, table, picker, tab list, ordering and the cross-compare matrix work from the keyboard - #335

Open
r0ny123 wants to merge 23 commits into
ref/integrate-all-20261025from
fix/web-keyboard-access
Open

r0ny123 wants to merge 23 commits into
ref/integrate-all-20261025from
fix/web-keyboard-access

Conversation

@r0ny123

@r0ny123 r0ny123 commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator

Based on ref/integrate-all-20261025, the build of all open PRs (#316's comment has the order), so the diff here is this change alone. One of a set of PRs from a review of the front end against the modern-web-guidance accessibility and interaction guides; the others are #328 and #330 to #334, plus the semantics and layout PRs. Checked in Chromium.

Dialogs

  • aed8c40. The edit, rename, API-usage and "Compare with function…" triggers were <a role="button"> with no href, so the keyboard could not reach them. They are <button>s now, and the disabled rename keeps aria-disabled.
  • aa328f0. Bootstrap 5.0.2 ignores autofocus in a modal and drops focus to <body> on close. New code at the end of static/post_action.js (every page; it was static/keyboard.js until 222fe08) fixes both:
    • it moves focus into a dialog's [autofocus] field when it opens;
    • it returns focus to the opener when it closes, or to the opener's menu toggle when the opener was in a menu.

Links, buttons and disabled controls (011c419, 005f615, fa991dc)

  • 15 links lost a role="button" that hid the fact they navigate.
  • The navbar and jobs menu toggles are <button>s, so Space opens them.
  • Controls that only looked disabled now are disabled:
    • a pending account's menus;
    • the pager's First, Prev, Next and Last at the ends, which lose their href;
    • the cursor pager's Last page, a named disabled link;
    • empty jobs categories, with aria-disabled and tabindex="-1", keeping the href testMaintenanceJobs relies on;
    • the YARA tab.

Tables

  • 00de1f1. A sortable header was <th role="button">, which replaced the column-header role, and no header carried aria-sort.
    • Headers are plain th with aria-sort, and sort through a link. A sort loads a new URL, as the pager next to it does (AGENTS.md: "an ordinary link click"), so middle-click works too.
    • The unique-blocks statistics sort in the page, so its headers hold a <button>.
    • page_loading.js watches a.table-sort.
  • f550859. Rows were the only way into a sample, family, function or job, and only a mouse click worked.
    • Each listing row's id is now a real link, through the existing format_*_id macros, and a job number links to its job page.
    • The rows' click handlers stay for the mouse.
    • Picker rows keep a plain id, since a click there picks.
    • These id links get the existing 24px minimum width (WCAG 2.5.8).
  • c41732e. "Rows per page" reloaded the page on a single arrow key. A key change now waits for Enter or for focus to leave; pointer and touch still load at once. search.html now includes pagination_js(): its three page-size selects threw on change and did nothing.
  • a92dfe0. The page-size select carried four handler attributes and its page an inline script of four functions, and the cross compare result carried the matrix's arrow-key and tooltip handlers as an inline script. Both came with every copy of the page and are used only once it is painted.
    • The select says where it loads and with which parameter in data-pager-* attributes, and post_action.js does the waiting for Enter or for focus to leave.
    • The matrix's handlers are the new static/cross_matrix.js, queued by the result page.
    • A size chosen before post_action.js has run is applied when it has, on a page the browser opened fresh; one restored on reload or going back is the browser's own and is left alone.

Tab lists (3b5eb6f). Bootstrap 5.0.2's tab plugin has no arrow keys; they came in 5.3. Every tab list now has:

  • one tab stop, with Left, Right, Home and End moving between tabs and disabled tabs skipped;
  • on cross compare, tabs that wait for Enter, because each one builds its matrix;
  • with ?tab=, the opened tab marked aria-selected.

Sample pickers (700c9e6). The four pickers selected by a click on the row and showed the choice only by a background tint.

  • Each row leads with a radio button (compare pages) or a checkbox (cross compare, unique blocks).
  • Samples already held are ticked and disabled.
  • Picked rows are framed in forced colours.

Ordering (38c8625, 4f24bd7). The column order on /settings and the sample order on cross compare were drag-only, with no keyboard and, on cross compare, no touch.

  • The new static/reorder_list.js adds move-up and move-down buttons, plus move-to-the-other-list on settings.
  • Focus stays on the button, and a status region says where the item went.
  • Dragging is unchanged.
    1. The per-column move buttons wrote three buttons and their icons into each of the 67 items of /settings, which took the page from about 42 KB to 100 KB. The page carries the API token, so it is sent uncompressed against BREACH, and the extra weight cost a point of mobile Lighthouse performance.
    • An item is now its name alone. reorder_list.js, which runs after the first paint, adds each item's buttons with the same names, titles and icons, and the across button's name still follows a drag.
    • The stylesheet keeps room at the end of every item for them (three buttons in a column list, two in the cross compare order), so adding them moves nothing and the name never runs under them. Nothing orders without the script, so nothing is lost without it. /settings is about 46 KB.
  • f4a99c7. The script adds the move buttons out of the flow, so an item no longer grows to hold them. The cross compare order's items are a line of small text, 21.6 px, and each item's 24 px buttons ran 2.4 px over the next item's, which failed Lighthouse's target-size audit on the result page (accessibility 97). An item is at least 24 px tall, set by the stylesheet from the first paint, so adding the buttons still moves nothing.
  • a175bb7. The check that the move buttons stay out of /settings used a budget for the whole page, which other forms on it also grow. It bounds the column list per item instead: about 990 bytes an item with the buttons, under 200 without.

The cross-compare matrix (bedc2f9). Each score was an unnamed colour swatch, with its value in a hover tooltip and its drill-down on a mouse click.

  • Each score is a link to its report, or, without matches, a role="img" span, named by its score in both cases.
  • The matrix has a caption, row headers and column headers.
  • It is one tab stop, with arrow keys, Home and End.
  • The tooltip shows on focus, and a colour key explains the swatches.
  • There is still one element per cell. The delegated td.clickable handler is gone, and AGENTS.md says so (16fe250).

Measured on the corpus job (5×5), 8 alternating runs, desktop Chromium: no blocking time either side. Style went 9.2 → 7.8 ms median, layout 25.8 → 22.0 ms.

On a 100×100 matrix built from fabricated samples, measured on a loaded machine (load average 12-16 on 4 cores): DOM nodes went 117,309 → 118,392. The timings swung too widely to read, from load TBT 190 → 660 ms median to tab-switch TBT 2503 → 2428 ms. A controlled test puts <a> cells about 10-15% above the old spans in first style time. #334's idle-tooltip rule halves this page's layout. Both are measured together on a quiet machine before merging, and the numbers go into the merge-order comment on #316.

Since review was requested.

  • cc111bc. Integration with Give pages their headings, landmarks, table semantics, names and status regions #336, which names each pager after its table ("Last page of functions, ...", "Rows per page of samples"). The disabled-pager check allows an " of <table>" before the comma, and the browser tests find the page-size select by the start of its name.
  • 8c8f3fc. The same secret-key race fix as Follow-ups from the batch E review: read-only database, backup command, key file without hard links, upper-case job ids #322: without hard links the key is staged and renamed into place under a lock on the instance folder, so workers cannot end up with different keys.
  • 07dff03. The pickers, the cross compare result and the table rows explained their handlers in // comments inside inline scripts, 29 lines that went to the browser with every copy of those pages. They are Jinja comments now, which are dropped on rendering. testInlineScriptComments.py keeps the count: no template may send more comment lines in its inline scripts than it did before.
  • With the comment and script changes of the other PRs, the sample result page on the build of all PRs is back at 14.1 KB gzipped, from 17.1 KB; the base is 14.1 KB.
  • 222fe08. The dialogs', tab lists' and page-size select's key handling was keyboard.js, a file of its own queued on every page. Every file the queue holds costs blocking time in Lighthouse's mobile run however little it does: on the build of all PRs the index page took 35 to 45 ms against the base's 8 to 15, and 10 ms against 15 once the every-page scripts were folded into files the base already queues (numbers in Make tooltips reachable and keep them in the window, report copies in a status message, and keep a stray drop off the page #334). The code now ends post_action.js and keyboard.js is gone. It runs just before page_loading.js instead of just after it, so the step that applies a page size chosen before the queue had run waits in whenReady(); without that it would skip the spinner.

Tests. Each fix has a test that fails on the base:

  • tests/testKeyboardAccess.py (CI) and tests/testKeyboardAccessBrowser.py (Chromium; skips in CI without playwright) are new; 1965087, f4a99c7, a175bb7 and a92dfe0 extend them.
    • 222fe08 adds a test that keyboard.js has no file of its own: the page does not queue it, the file is gone and post_action.js holds the tab code. The browser test that holds the script back now holds post_action.js.
  • tests/testInlineScriptComments.py is new (07dff03).
  • tests/testSecretKeyRace.py replaces the test that pinned the old create-then-lock order with two that pin the new one (8c8f3fc).
  • tests/testPagination.py is extended by a92dfe0.
  • About a dozen existing tests read the new ids and markup.
  • Last runs: every test file the change touches, 2334 passed. The 7 failures in that run were fixed in fa991dc and 4f24bd7, after which the reruns passed 221 and 122. ruff is clean.

Lighthouse. Accessibility, Best Practices and SEO are 100 on the 18 touched pages, mobile and desktop. Desktop Performance is 100, apart from one page at 98. Mobile was measured under load; in alternating runs on 5 pages the base scored 86-100 and this branch 97-100.

Merge notes.

The controls that open these dialogs were anchors without an href,
role="button" and data-bs-toggle="modal". An anchor without an href is not
focusable, so Tab passed over every one of them and a keyboard user could
not edit or delete a family or sample, rename a function or read its API
usage. They are buttons now, with the same ids and data-bs-* attributes the
show.bs.modal handlers read, and the function page's "Compare with
function" menu entry, a link to "#", is a button as well. The disabled
rename stays focusable through aria-disabled.
Fifteen links that go to another page (a row's export, unique blocks,
compare and Show result buttons, the function page's sample, family and
graph buttons) carried role="button", so a screen reader announced a button
and its user pressed Space, which follows no link. The role is gone.

The navbar's Explore, Analyze, Data and account menus and the jobs page's
category menus were the opposite: links to "#" that open a menu, on which
Space did nothing. They are buttons now, which Bootstrap opens the same
way, and navbar.css keeps them looking like the links they replace. For
an account waiting for a role the three menus carried `disabled`, which an
anchor ignores, so assistive technology read three working buttons; on a
button it disables them.
Bootstrap's disabled class greys a control out and stops the pointer;
nothing else. The pager's First and Previous on the first page, and Next
and Last on the last, kept a live href (Previous pointed at page 0), so
they were tab stops that reloaded the page, and a screen reader read them
as working links. They render without an href, as role="link" with
aria-disabled, like the cursor pager's Last page already did.

That Last page put its tab stop on the span around it, which had no role,
and its reason only in a title Bootstrap moves into a tooltip. The link is
the tab stop now and its name gives the reason; focus moving into the span
still shows the tooltip.

The jobs page's greyed-out category entries were links Tab stopped on, and
the YARA tab of a report without a rule said nothing; both carry
aria-disabled.
sortable_header_col rendered the header as `th role="button" tabindex="0"`
with the sort in an inline onclick. The role replaced the column header, so
a screen reader announced no column for the cells below a sortable header,
and no header anywhere carried aria-sort. It is a plain `th scope="col"`
now, with aria-sort on the column the table is sorted by, holding a link
that loads the table sorted by it; the href keeps it middle-clickable and an
onclick still adds the other tables' state where a page needs it. A header
given no pagination is no longer a click that reloads the page.
page_loading.js watches the sort links as it watches the pager's.

The Unique Blocks statistics sort in the page and their headers took a
click and nothing else. The label is a button inside the header now, and
the script sets aria-sort where it sets the sort direction.

style.css keeps both looking like the headers they were.
The select loaded the page from its onchange. A select changes its value at
every press of an arrow key, so a keyboard user stepping from 25 to 100 got
the page loaded at 50, with focus back at the top. A change made with a key
now waits for Enter or for focus to leave the select; one made with the
pointer, or a touch screen's picker, still loads at once. The handlers are
in pagination_js(), next to pagination_js_helper.

The search page rendered three of these selects without pagination_js(),
so their onchange threw and they did nothing; it includes it now.
Bootstrap 5.0.2 focuses a dialog's own box when it opens, so the
`autofocus` field of the function page's compare and rename dialogs never
got the cursor. On close it hands focus back only to a data-bs-toggle
opener that is still visible: the jobs page's delete dialog, which a script
opens, and the compare dialog, opened from a menu entry the menu hides
again, left focus on <body>, and a keyboard user started over at the top of
the page.

static/keyboard.js, queued from base.html for every page, listens to the
dialogs' events: on shown it focuses an [autofocus] field, and on hidden,
when focus has gone nowhere else, it returns to the element that opened the
dialog, or to the toggle of the menu that held it.
Bootstrap 5.0.2's tab plugin shows a tab on a click and does nothing else
(the keyboard model came in 5.3): every tab was a tab stop of its own and
the arrow keys did nothing. static/keyboard.js gives every role="tablist"
one tab stop, its selected tab, kept in step on shown.bs.tab, and moves
between tabs with Left, Right, Home and End, past a disabled tab. A tab is
shown as focus reaches it, except in the cross compare result's list,
marked data-tab-activation="manual": each of its tabs builds a matrix the
first time it is shown, so there Enter or Space shows it.

result_unique_blocks.html wrote aria-selected="true" on the statistics tab
and "false" on the other two whichever was active, so ?tab=blocks showed
the blocks and announced the statistics as selected. It follows active_tab
now, as users.html does.
Compare 1vsN, Compare 1vs1, Cross Compare and Unique Blocks picked a sample
when its row was clicked, and only then: a row had no tab stop and no key,
so a keyboard user could compare only the sample 1vsN picks by default and
could not fill a cross compare or Unique Blocks at all, except from a hash
list. The state was a background tint and nothing else, about 1.1:1 against
the rows around it in the light theme and lost entirely in forced colours.

Each picker row now leads with its control, from one pick_cell macro: a
radio button, one group per table, on the two compare pages, and a checkbox
on the other two, ticked and disabled for a sample the page already holds
and takes back with the x of its own table. The page scripts keep the
control, the tint and their `selected` lists in step, whether the row or the
control is clicked or a key changes it. In forced colours a picked row is
framed in Highlight.
A click on a row was the only way from the sample, family, function and
job lists, the search results and a cross compare result into what a row
names: the handlers sat on tr and td, which no key reaches, and a queued or
running job's page had no link anywhere. The id cell of each row holds a
real link now, the same format_*_id links the function rows' family and
sample columns and the home page's sample list already use, and the job
number links to the job's page. The click handlers stay as a pointer's
shortcut and leave any link or button in the row to itself, so a click on
the id is not handled twice.

On a cross compare result the row's id was a td.clickable that read the
job id out of a hidden cell; it is the row's header now, with a link to the
row sample's report, and the hidden cell and its delegated handler are
gone. A picker's row keeps its plain id, since a click there picks.

A row-header link gets the same 24px minimum width as the table links in
cells, for WCAG 2.5.8.
The column lists under Settings (SortableJS) and a cross compare result's
sample order (jQuery UI) were ordered by dragging and nothing else. Their
items had no tab stop and no key, and jQuery UI's drag binds the mouse only,
so a keyboard user could not choose the columns of any of the seven tables
and nobody on a touch screen could set a custom sample order.

Every item now has Move up and Move down buttons, and a column a third that
moves it to the other list of its table. static/reorder_list.js, queued by
both pages, moves the item, keeps focus on the button pressed and says in a
polite status region where the item went; it keeps the third button's name
and arrow right after a drag between lists too, from SortableJS's add
event. The save and the "Change order" button read the item's data
attribute rather than its text, which now includes the buttons. Dragging
is unchanged.
Each score of the matrix was an empty span coloured by score_to_color: its
number was in a data-hint tooltip shown on hover only, a pair with matches
opened its report from an onclick on the span, and the cells had no row or
column headers, so a screen reader read bare cells and a keyboard reached
none of them. Colour was the only encoding a pointer did not have to ask
for, and the page named no scale.

A pair with matches is now a link to that report and a pair without one a
role="img" span, either named by its score in aria-label. The table has a
caption, the row's id cell is its row header, and the second header row has
a header for every column, showing every fifth sample id as before and the
rest visually hidden. To keep the matrix from adding up to N*N tab stops it
is one, its first score: links carry tabindex="-1", and the arrow keys,
Home and End move between scores and the tab stop with them. Focus puts
the pair's samples into the tooltip as hover does, so a keyboard user sees
the same text. A pane filled on its tab's first show clones all of this
and writes its own score names and tab stop.

A key above the tabs shows which range of scores each colour stands for,
with the matrix's own .score-swatch class so the dark theme dims it alike.

Every cell is still one element, as before.
The greyed-out entries of the jobs page's category menus lost their href
when they were marked aria-disabled, and the menu is how a maintenance job
the server page started is found by its type while the queue holds none of
it (testMaintenanceJobs). They keep the href now, as Bootstrap's own
disabled menu entries do, with tabindex="-1" beside aria-disabled, so Tab
still passes them and a screen reader still hears them as unavailable.
The column test now saves and reads the lists back from the page the save
loads, so it pins the order stored rather than the order on screen. The
matrix test read a focused score's tooltip in the frame focus arrived,
before hint.css's transition had made it visible, and failed under load; it
waits for it.
#336 names each pager after its table: "Last page of functions, ...",
"Rows per page of samples". #335's tests looked for the cursor pager's
"Last page," and for select[aria-label='Rows per page'] exactly, so the
disabled-pager check and five page-size tests failed. The pager check
allows an " of <table>" before the comma, and the browser tests find the
select by the start of its name.
The per-column move buttons wrote three buttons and their icons into each of
the 67 items of /settings, taking the page from about 42 KB to 100 KB. The
page carries the API token, so it is sent uncompressed against BREACH, and the
extra weight cost a point of mobile Lighthouse performance.

An item is now its name alone. static/reorder_list.js, which runs after the
first paint, adds each item's buttons with the same names, titles and icons,
and the across button's name still follows a drag. The stylesheet keeps room at
the end of every item for them (three buttons in a column list, two in the
cross compare order), so adding them moves nothing and the name never runs
under them. Nothing orders without the script, so nothing is lost without it.
/settings is now about 46 KB.

The tests check that the pages carry no buttons, that the items measure the same
with and without them at 1280 and 390 px, that no name runs under them, and that
the lists shift by 0.
Without hard links the key was written into a file created with O_EXCL,
empty until filled. A worker that opened that file in the gap could
replace it and find the creator's key still written into the file it
had displaced; a third worker that had opened the displaced file before
the replacement then read the loser's key and used it, while everyone
else used the winner's. One round in about 1600 ended that way.

The staged key, complete and private from mkstemp, is now renamed into
place under a lock on the instance folder, looking at the key file again
once the lock is held. No key file is opened for writing any more, and
none is ever visible unfinished.

The test that pinned the old create-then-lock order is replaced by two
that pin the new one.
Since the script adds the move buttons, they sit out of the flow, so an item no
longer grows to hold them. The cross compare order's items are a line of small
text, 21.6px, and each item's 24px buttons ran 2.4px over the next item's: they
covered each other and Lighthouse's target-size audit failed the result page
(accessibility 97). An item is now at least 24px tall, which the stylesheet sets
from the first paint, so adding the buttons still moves nothing.
The check that the move buttons stay out of /settings used a budget for the
whole page, which other forms on the page also grow, so it failed for reasons
that have nothing to do with the buttons. It now bounds the column list per
item, which is what the buttons inflated: about 990 bytes an item with them,
under 200 without.
The page-size select carried four handler attributes and its page an inline
script of four functions, so that a key held on it does not load the page at
every size it passes. The cross compare result carried the matrix's arrow-key
and tooltip handlers as an inline script. Both came with every copy of the page
and are only used once it is painted.

The select now says where it loads and with which parameter, in data-pager-*
attributes, and static/keyboard.js does the waiting for Enter or for focus to
leave. The matrix's handlers are static/cross_matrix.js, queued by the result
page. A size chosen before keyboard.js has run is applied when it has, on a page
the browser opened fresh; one restored on reload or going back is the browser's
own and is left alone.
The pickers, the cross compare result and the table rows explained their new
handlers in // comments inside inline scripts, 29 lines that went to the browser
with every copy of those pages. A Jinja comment says the same to whoever reads the
template and is dropped on rendering.

A ratchet test keeps the count: no template may send more comment lines in its
inline scripts than it did before, which is also what a template that carried none
may not start to do.
The dialogs', tab lists' and page size select's key handling was keyboard.js,
queued on every page. Each file the queue adds is one more ordered request before
the page's scripts have run, and in Lighthouse's mobile run it costs blocking time
however little it does. On the build of all the pull requests the index page took 35
to 45 ms against the base's 8 to 15, and /data/export 50 to 57 ms against 5 to 12.
With keyboard.js, icon_titles.js and hints.js folded into files the base already
queues, the index page is at 10 ms against 15 and /data/export at 14 ms against 5,
all 100.

The code goes at the end of post_action.js, which every page queues already, in its
own function with its own "use strict". It now runs just before page_loading.js
instead of just after it, so the size chosen before the queue had run, which it
applies on a fresh page, waits in whenReady(): the load shows the spinner through
page_loading.js. keyboard.js is gone, with its later() line, and the comments and
the browser test that held it back name post_action.js.
The colour key above the cross compare tabs is eleven empty inline spans, and
an empty inline span is 0px wide: the key showed its ranges and no colours.
Each swatch is now a 1em square with a frame in the swatch border colour. In
forced colours the swatches keep their colours, since the scale is the
information and the labels name every step, and take the text colour for
their frame. The labels no longer break between a swatch and its range.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant