Skip to content

Commit a8b5b2b

Browse files
cwickhamcderv
andauthored
Make website sidebar section toggles keyboard-operable buttons (#14826)
* Make website sidebar section toggles keyboard-operable buttons The expandable sidebar sections were <a> elements with no href, so the keyboard could not reach them at all, and they carried role="navigation", which made each one an unnamed nested navigation landmark instead of a named control. Sections without their own page now render one <button> that holds both the label and the chevron, so there is a single tabstop. Sections that do have a page keep their link and get a <button> chevron beside it, named after the section. Every disclosed list is named with aria-labelledby pointing at its own section label. Also removes the duplicated `role` attribute from the mobile sidebar toggle in nav-before-body.ejs, which was invalid HTML. Fixes #12116 Fixes #4935 * Use plainText for section-toggle aria-label, ignore rendered fixture output item.text can carry rendered markup for formatted titles; the aria-label attribute doesn't parse it, so use item.plainText (falling back to text) like the pagination labels do. Also cover the sidebar-disclosure fixture's rendered *.html/*.json/site_libs/ output in .gitignore, matching the sidebar-content fixture. --------- Co-authored-by: Christophe Dervieux <christophe.dervieux@gmail.com>
1 parent eb126f9 commit a8b5b2b

12 files changed

Lines changed: 139 additions & 10 deletions

File tree

‎news/changelog-1.11.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ All changes included in 1.11:
77
## Accessibility
88

99
- ([#14615](https://github.com/quarto-dev/quarto-cli/issues/14615)): Fix invalid `role="menu"` on the website navbar's collapse toggle button, flagged by axe-core (`aria-allowed-role`) and WAVE (`aria_menu_broken`) when the navbar collapses to the hamburger at narrow viewports.
10+
- ([#12116](https://github.com/quarto-dev/quarto-cli/issues/12116), [#4935](https://github.com/quarto-dev/quarto-cli/issues/4935)): Website sidebar section toggles are now `<button>` elements, so the keyboard can reach them and `Enter` or `Space` can operate them. Each toggle carries `aria-expanded`, and `aria-labelledby` names each disclosed list after its own section. The toggles no longer carry `role="navigation"`, which removed a spurious navigation landmark from every section.
1011

1112
## Engines
1213

‎src/resources/projects/website/navigation/quarto-nav.scss‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -375,6 +375,48 @@ $sidebar-section-bottom-margin: 0.2em;
375375
cursor: pointer;
376376
}
377377

378+
// Section disclosure controls are <button> elements so that they are reachable
379+
// by keyboard and expose the button role (quarto-cli#12116, quarto-cli#4935).
380+
// Strip the browser's default button styling so they still look like the
381+
// sidebar links beside them.
382+
.sidebar-item .sidebar-item-toggle,
383+
.sidebar-item button.sidebar-item-text {
384+
background: none;
385+
border: none;
386+
padding: 0;
387+
font: inherit;
388+
color: inherit;
389+
text-align: inherit;
390+
}
391+
392+
// In a section without its own page, the label and the chevron are one control,
393+
// so that button has to lay out its own children instead of relying on the
394+
// flex container. `margin-left: auto` keeps the chevron hard right whether or
395+
// not the item also has a navicon.
396+
//
397+
// `align-items: baseline` is deliberate, not a typo for `center`: it reproduces
398+
// the line box of the inline `<a>` this button replaced, so row heights and the
399+
// chevron position are unchanged from 1.10. `center` renders 1-2px shorter per
400+
// section, which shifts every row below it.
401+
.sidebar-item button.sidebar-item-text {
402+
display: flex;
403+
align-items: baseline;
404+
width: 100%;
405+
}
406+
407+
.sidebar-item button.sidebar-item-text > .bi-chevron-right {
408+
margin-left: auto;
409+
padding-left: 0.5rem;
410+
}
411+
412+
// A bare button gets no focus ring from Bootstrap's reboot, so state one
413+
// explicitly rather than depend on the UA default (quarto-cli#14774).
414+
.sidebar-item .sidebar-item-toggle:focus-visible,
415+
.sidebar-item button.sidebar-item-text:focus-visible {
416+
outline: 2px solid currentColor;
417+
outline-offset: 2px;
418+
}
419+
378420
.sidebar-item .sidebar-item-toggle .bi {
379421
// The dongle for opening and closing sections
380422
font-size: 0.7rem;

‎src/resources/projects/website/templates/nav-before-body.ejs‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,13 +71,11 @@ const navbarTocRight = nav['toc-location'] === "right" || nav['toc-location'] ==
7171
</button>
7272
<% if (nav.showBreadCrumbs) { %>
7373
<h1 class="quarto-secondary-nav-title no-breadcrumbs"></h1>
74-
<a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" role="link"
75-
aria-controls="quarto-sidebar" aria-expanded="false" aria-label="<%- nav.language['toggle-sidebar'] %>"
74+
<a class="flex-grow-1" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"
7675
onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
7776
</a>
7877
<% } else { %>
79-
<a class="flex-grow-1 no-decor" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" role="link"
80-
aria-controls="quarto-sidebar" aria-expanded="false" aria-label="<%- nav.language['toggle-sidebar'] %>"
78+
<a class="flex-grow-1 no-decor" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"
8179
onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
8280
<h1 class="quarto-secondary-nav-title"></h1>
8381
</a>

‎src/resources/projects/website/templates/sidebaritem.ejs‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,15 @@
1919
<% if (item.contents.length > 0) { %>
2020
<div class="sidebar-item-container">
2121
<% if (item.href) { %>
22-
<a href="<%- item.href %>" class="sidebar-item-text sidebar-link<%- item.active ? " active" : "" %>"<%= item.rel ? ` rel="${item.rel}"` : "" %><%= item.target ? ` target="${item.target}"` : "" %>><% partial('navicon.ejs', { item }) %> <span class="menu-text"><%= item.text %></span></a>
22+
<a href="<%- item.href %>" class="sidebar-item-text sidebar-link<%- item.active ? " active" : "" %>"<%= item.rel ? ` rel="${item.rel}"` : "" %><%= item.target ? ` target="${item.target}"` : "" %>><% partial('navicon.ejs', { item }) %> <span class="menu-text"<%= sectionId ? ` id="${sectionId}-label"` : "" %>><%= item.text %></span></a>
23+
<button type="button" class="sidebar-item-toggle text-start<%- isCollapsed ? " collapsed" : "" %>" data-bs-toggle="collapse" data-bs-target="#<%- sectionId %>"<%= sectionId ? ` aria-controls="${sectionId}"` : "" %> aria-expanded="<%- isCollapsed ? "false" : "true" %>" aria-label="<%- language['toggle-section'] %>: <%- item.plainText || item.text %>">
24+
<i class="bi bi-chevron-right ms-2" aria-hidden="true"></i>
25+
</button>
2326
<% } else { %>
24-
<a class="sidebar-item-text sidebar-link text-start<%- isCollapsed ? " collapsed" : "" %>" data-bs-toggle="collapse" data-bs-target="#<%- sectionId %>" role="navigation" aria-expanded="<%- isCollapsed ? "false" : "true" %>"><% partial('navicon.ejs', { item }) %> <span class="menu-text"><%= item.text %></span></a>
27+
<button type="button" class="sidebar-item-text sidebar-item-toggle sidebar-link text-start<%- isCollapsed ? " collapsed" : "" %>" data-bs-toggle="collapse" data-bs-target="#<%- sectionId %>"<%= sectionId ? ` aria-controls="${sectionId}"` : "" %> aria-expanded="<%- isCollapsed ? "false" : "true" %>"><% partial('navicon.ejs', { item }) %> <span class="menu-text"<%= sectionId ? ` id="${sectionId}-label"` : "" %>><%= item.text %></span><i class="bi bi-chevron-right" aria-hidden="true"></i></button>
2528
<% } %>
26-
<a class="sidebar-item-toggle text-start<%- isCollapsed ? " collapsed" : "" %>" data-bs-toggle="collapse" data-bs-target="#<%- sectionId %>" role="navigation" aria-expanded="<%- isCollapsed ? "false" : "true" %>" aria-label="<%- language['toggle-section'] %>">
27-
<i class="bi bi-chevron-right ms-2"></i>
28-
</a>
2929
</div>
30-
<ul id="<%- sectionId %>" class="collapse list-unstyled sidebar-section depth<%-depth%> <%- isCollapsed ? "" : "show" %>">
30+
<ul id="<%- sectionId %>"<%= sectionId ? ` aria-labelledby="${sectionId}-label"` : "" %> class="collapse list-unstyled sidebar-section depth<%-depth%> <%- isCollapsed ? "" : "show" %>">
3131
<% item.contents.forEach(subItem => { %>
3232
<% partial('sidebaritem.ejs', { item: subItem, depth: depth + 1, collapse: collapse, borderColor: borderColor, language: language, draftMode }) %>
3333
<% }) %>
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/.quarto/
2+
*.html
3+
*.json
4+
site_libs/
5+
**/*.quarto_ipynb
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
project:
2+
type: website
3+
output-dir: .
4+
5+
website:
6+
title: "Sidebar disclosure"
7+
sidebar:
8+
style: docked
9+
collapse-level: 1
10+
contents:
11+
- index.qmd
12+
- section: "Group"
13+
contents:
14+
- group-a.qmd
15+
- group-b.qmd
16+
- section: "Nested"
17+
contents:
18+
- nested.qmd
19+
- section: section.qmd
20+
contents:
21+
- section-child.qmd
22+
23+
format:
24+
html:
25+
theme: cosmo
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: "Group A"
3+
_quarto:
4+
tests:
5+
html:
6+
ensureHtmlElements:
7+
- ['button.sidebar-item-toggle[data-bs-target="#quarto-sidebar-section-1"][aria-expanded="true"]',
8+
'ul#quarto-sidebar-section-1.show[aria-labelledby="quarto-sidebar-section-1-label"]',
9+
'button.sidebar-item-toggle[data-bs-target="#quarto-sidebar-section-2"][aria-expanded="false"]']
10+
- ['#quarto-sidebar a.sidebar-item-toggle',
11+
'#quarto-sidebar a[role="navigation"]']
12+
---
13+
14+
The section holding the active page reports `aria-expanded="true"`, while a
15+
nested section that stays closed still reports `false`.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "group-b"
3+
---
4+
5+
Page group-b.
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "Index"
3+
_quarto:
4+
tests:
5+
html:
6+
ensureHtmlElements:
7+
- ['button.sidebar-item-text.sidebar-item-toggle[data-bs-toggle="collapse"][data-bs-target="#quarto-sidebar-section-1"][aria-controls="quarto-sidebar-section-1"][aria-expanded="false"]',
8+
'button.sidebar-item-text.sidebar-item-toggle span.menu-text#quarto-sidebar-section-1-label',
9+
'ul#quarto-sidebar-section-1[aria-labelledby="quarto-sidebar-section-1-label"]',
10+
'button.sidebar-item-text.sidebar-item-toggle[data-bs-target="#quarto-sidebar-section-2"][aria-expanded="false"]',
11+
'ul#quarto-sidebar-section-2[aria-labelledby="quarto-sidebar-section-2-label"]',
12+
'a.sidebar-item-text[href="./section.html"] span.menu-text#quarto-sidebar-section-3-label',
13+
'button.sidebar-item-toggle[aria-label="Toggle section: section"][aria-expanded="false"][aria-controls="quarto-sidebar-section-3"]',
14+
'ul#quarto-sidebar-section-3[aria-labelledby="quarto-sidebar-section-3-label"]']
15+
- ['#quarto-sidebar a.sidebar-item-toggle',
16+
'#quarto-sidebar a[data-bs-toggle="collapse"]',
17+
'#quarto-sidebar a[role="navigation"]',
18+
'#quarto-sidebar a[aria-expanded]']
19+
---
20+
21+
Every sidebar section toggle is a `<button>` with `aria-expanded`, and every
22+
disclosed list is named by its own section label. See quarto-cli#12116 and
23+
quarto-cli#4935.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "nested"
3+
---
4+
5+
Page nested.

0 commit comments

Comments
 (0)