Skip to content

Commit 5c710d6

Browse files
committed
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
1 parent abc6a78 commit 5c710d6

12 files changed

Lines changed: 134 additions & 10 deletions

File tree

‎news/changelog-1.11.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
All changes included in 1.11:
22

3+
## Accessibility
4+
5+
- ([#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.
6+
37
## Engines
48

59
### `knitr`

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -375,6 +375,43 @@ $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+
.sidebar-item button.sidebar-item-text {
397+
display: flex;
398+
align-items: center;
399+
width: 100%;
400+
}
401+
402+
.sidebar-item button.sidebar-item-text > .bi-chevron-right {
403+
margin-left: auto;
404+
padding-left: 0.5rem;
405+
}
406+
407+
// A bare button gets no focus ring from Bootstrap's reboot, so state one
408+
// explicitly rather than depend on the UA default (quarto-cli#14774).
409+
.sidebar-item .sidebar-item-toggle:focus-visible,
410+
.sidebar-item button.sidebar-item-text:focus-visible {
411+
outline: 2px solid currentColor;
412+
outline-offset: 2px;
413+
}
414+
378415
.sidebar-item .sidebar-item-toggle .bi {
379416
// The dongle for opening and closing sections
380417
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.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: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/.quarto/
2+
**/*.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)