Skip to content

Commit b37f3dd

Browse files
skjnldsvskjnldsv
committed
fix(a11y): use <button> with aria-expanded for the version toggle
The version selector used a <span> as an interactive toggle, which has no native keyboard role or state indication (WCAG 4.1.2 / BITV 9.4.1.2). Screen readers could not announce whether the panel was expanded or collapsed. Changes across all three manual version templates: - Replace the <span> with a <button type="button"> so the element has native keyboard focus, click-on-Enter, and an implicit role. - Add aria-expanded="false" (updated to "true" on click via a small inline script that mirrors the RTD theme toggle). - Add aria-controls pointing to the versioned dropdown container. - Mark decorative caret icons with aria-hidden="true". Add CSS to reset default <button> styles so the visual appearance is unchanged. Fixes #9747 Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>
1 parent c5c2990 commit b37f3dd

4 files changed

Lines changed: 82 additions & 16 deletions

File tree

‎_shared_assets/static/custom.css‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,18 @@ h6 {
4646
.rst-versions .rst-current-version .fa-book {
4747
display: none;
4848
}
49+
50+
/* The version toggle is now a <button> element. Reset default button
51+
styling so it looks identical to the old <span>. */
52+
button.rst-current-version {
53+
background: none;
54+
border: none;
55+
padding: 12px;
56+
font-family: inherit;
57+
font-size: 90%;
58+
width: 100%;
59+
cursor: pointer;
60+
}
4961
.rst-versions .rst-current-version:before {
5062
content: 'Nextcloud';
5163
margin-right: auto;

‎admin_manual/_templates/versions.html‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
11
{% if READTHEDOCS %}
22
{# Add rst-badge after rst-versions for small badge style. #}
33
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
4-
<span class="rst-current-version" data-toggle="rst-current-version">
4+
{# Use <button> so the toggle has native keyboard semantics and can
5+
carry aria-expanded. The RTD theme JS uses [data-toggle] selectors
6+
so the element type does not matter for the toggle behaviour. #}
7+
<button type="button"
8+
class="rst-current-version"
9+
data-toggle="rst-current-version"
10+
aria-expanded="false"
11+
aria-controls="rst-other-versions-admin">
512
☁️ {{ current_version }}
6-
<span class="fa fa-caret-down"></span>
7-
</span>
8-
<div class="rst-other-versions">
13+
<span class="fa fa-caret-down" aria-hidden="true"></span>
14+
</button>
15+
<div id="rst-other-versions-admin" class="rst-other-versions">
916
<dl>
1017
<dt>☁️ {{ _('Versions') }}</dt>
1118
{% for slug, url in versions|reverse %}
@@ -22,4 +29,15 @@
2229
</dl>
2330
</div>
2431
</div>
25-
{% endif %}
32+
<script>
33+
/* Keep aria-expanded in sync with the RTD theme toggle class. */
34+
(function () {
35+
var btn = document.querySelector('.rst-current-version[aria-expanded]');
36+
if (!btn) return;
37+
btn.addEventListener('click', function () {
38+
var expanded = this.getAttribute('aria-expanded') === 'true';
39+
this.setAttribute('aria-expanded', expanded ? 'false' : 'true');
40+
});
41+
}());
42+
</script>
43+
{% endif %}

‎developer_manual/_templates/versions.html‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
11
{% if READTHEDOCS %}
22
{# Add rst-badge after rst-versions for small badge style. #}
33
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
4-
<span class="rst-current-version" data-toggle="rst-current-version">
4+
{# Use <button> so the toggle has native keyboard semantics and can
5+
carry aria-expanded. The RTD theme JS uses [data-toggle] selectors
6+
so the element type does not matter for the toggle behaviour. #}
7+
<button type="button"
8+
class="rst-current-version"
9+
data-toggle="rst-current-version"
10+
aria-expanded="false"
11+
aria-controls="rst-other-versions-dev">
512
☁️ {{ current_version }}
6-
<span class="fa fa-caret-down"></span>
7-
</span>
8-
<div class="rst-other-versions">
13+
<span class="fa fa-caret-down" aria-hidden="true"></span>
14+
</button>
15+
<div id="rst-other-versions-dev" class="rst-other-versions">
916
<dl>
1017
<dt>☁️ {{ _('Versions') }}</dt>
1118
{% for slug, url in versions|reverse %}
@@ -22,4 +29,15 @@
2229
</dl>
2330
</div>
2431
</div>
25-
{% endif %}
32+
<script>
33+
/* Keep aria-expanded in sync with the RTD theme toggle class. */
34+
(function () {
35+
var btn = document.querySelector('.rst-current-version[aria-expanded]');
36+
if (!btn) return;
37+
btn.addEventListener('click', function () {
38+
var expanded = this.getAttribute('aria-expanded') === 'true';
39+
this.setAttribute('aria-expanded', expanded ? 'false' : 'true');
40+
});
41+
}());
42+
</script>
43+
{% endif %}

‎user_manual/_templates/versions.html‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -58,13 +58,20 @@
5858
{% set sorted_languages = language_tuples | sort(attribute='name') %}
5959

6060
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
61-
<span class="rst-current-version" data-toggle="rst-current-version">
61+
{# Use <button> so the toggle has native keyboard semantics and can
62+
carry aria-expanded. The RTD theme JS uses [data-toggle] selectors
63+
so the element type does not matter for the toggle behaviour. #}
64+
<button type="button"
65+
class="rst-current-version"
66+
data-toggle="rst-current-version"
67+
aria-expanded="false"
68+
aria-controls="rst-other-versions-user">
6269
🌐 {{ language_names.get(language, language) }}
63-
<span class="fa fa-caret-down"></span>
64-
 ☁️ {{ current_version }}
65-
<span class="fa fa-caret-down"></span>
66-
</span>
67-
<div class="rst-other-versions">
70+
<span class="fa fa-caret-down" aria-hidden="true"></span>
71+
☁️ {{ current_version }}
72+
<span class="fa fa-caret-down" aria-hidden="true"></span>
73+
</button>
74+
<div id="rst-other-versions-user" class="rst-other-versions">
6875
<dl>
6976
<dt>🌐 {{ _('Languages') }}</dt>
7077
{% for lang in sorted_languages %}
@@ -97,4 +104,15 @@
97104
</dl>
98105
</div>
99106
</div>
107+
<script>
108+
/* Keep aria-expanded in sync with the RTD theme toggle class. */
109+
(function () {
110+
var btn = document.querySelector('.rst-current-version[aria-expanded]');
111+
if (!btn) return;
112+
btn.addEventListener('click', function () {
113+
var expanded = this.getAttribute('aria-expanded') === 'true';
114+
this.setAttribute('aria-expanded', expanded ? 'false' : 'true');
115+
});
116+
}());
117+
</script>
100118
{% endif %}

0 commit comments

Comments
 (0)