From b37f3ddf79c139d0cff6f7510e0bc916abf8e87c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6=20=28skjnldsv=29?=
 <skjnldsv@protonmail.com>
Date: Tue, 12 May 2026 21:28:18 +0200
Subject: [PATCH 1/3] fix(a11y): use <button> with aria-expanded for the
 version toggle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 _shared_assets/static/custom.css          | 12 +++++++++
 admin_manual/_templates/versions.html     | 28 +++++++++++++++++----
 developer_manual/_templates/versions.html | 28 +++++++++++++++++----
 user_manual/_templates/versions.html      | 30 ++++++++++++++++++-----
 4 files changed, 82 insertions(+), 16 deletions(-)

diff --git a/_shared_assets/static/custom.css b/_shared_assets/static/custom.css
index 04b115a40e0..c3b288eeb1c 100644
--- a/_shared_assets/static/custom.css
+++ b/_shared_assets/static/custom.css
@@ -46,6 +46,18 @@ h6 {
 .rst-versions .rst-current-version .fa-book {
 	display: none;
 }
+
+/* The version toggle is now a <button> element. Reset default button
+   styling so it looks identical to the old <span>. */
+button.rst-current-version {
+	background: none;
+	border: none;
+	padding: 12px;
+	font-family: inherit;
+	font-size: 90%;
+	width: 100%;
+	cursor: pointer;
+}
 .rst-versions .rst-current-version:before {
 	content: 'Nextcloud';
 	margin-right: auto;
diff --git a/admin_manual/_templates/versions.html b/admin_manual/_templates/versions.html
index 70c5e22dee2..6c037362d64 100644
--- a/admin_manual/_templates/versions.html
+++ b/admin_manual/_templates/versions.html
@@ -1,11 +1,18 @@
 {% if READTHEDOCS %}
 {# Add rst-badge after rst-versions for small badge style. #}
   <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
-    <span class="rst-current-version" data-toggle="rst-current-version">
+    {# Use <button> so the toggle has native keyboard semantics and can
+       carry aria-expanded. The RTD theme JS uses [data-toggle] selectors
+       so the element type does not matter for the toggle behaviour. #}
+    <button type="button"
+            class="rst-current-version"
+            data-toggle="rst-current-version"
+            aria-expanded="false"
+            aria-controls="rst-other-versions-admin">
       ☁️ {{ current_version }}
-      <span class="fa fa-caret-down"></span>
-    </span>
-    <div class="rst-other-versions">
+      <span class="fa fa-caret-down" aria-hidden="true"></span>
+    </button>
+    <div id="rst-other-versions-admin" class="rst-other-versions">
       <dl>
         <dt>☁️ {{ _('Versions') }}</dt>
         {% for slug, url in versions|reverse %}
@@ -22,4 +29,15 @@
       </dl>
     </div>
   </div>
-{% endif %}
\ No newline at end of file
+  <script>
+    /* Keep aria-expanded in sync with the RTD theme toggle class. */
+    (function () {
+      var btn = document.querySelector('.rst-current-version[aria-expanded]');
+      if (!btn) return;
+      btn.addEventListener('click', function () {
+        var expanded = this.getAttribute('aria-expanded') === 'true';
+        this.setAttribute('aria-expanded', expanded ? 'false' : 'true');
+      });
+    }());
+  </script>
+{% endif %}
diff --git a/developer_manual/_templates/versions.html b/developer_manual/_templates/versions.html
index 70c5e22dee2..ea5cd040551 100644
--- a/developer_manual/_templates/versions.html
+++ b/developer_manual/_templates/versions.html
@@ -1,11 +1,18 @@
 {% if READTHEDOCS %}
 {# Add rst-badge after rst-versions for small badge style. #}
   <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
-    <span class="rst-current-version" data-toggle="rst-current-version">
+    {# Use <button> so the toggle has native keyboard semantics and can
+       carry aria-expanded. The RTD theme JS uses [data-toggle] selectors
+       so the element type does not matter for the toggle behaviour. #}
+    <button type="button"
+            class="rst-current-version"
+            data-toggle="rst-current-version"
+            aria-expanded="false"
+            aria-controls="rst-other-versions-dev">
       ☁️ {{ current_version }}
-      <span class="fa fa-caret-down"></span>
-    </span>
-    <div class="rst-other-versions">
+      <span class="fa fa-caret-down" aria-hidden="true"></span>
+    </button>
+    <div id="rst-other-versions-dev" class="rst-other-versions">
       <dl>
         <dt>☁️ {{ _('Versions') }}</dt>
         {% for slug, url in versions|reverse %}
@@ -22,4 +29,15 @@
       </dl>
     </div>
   </div>
-{% endif %}
\ No newline at end of file
+  <script>
+    /* Keep aria-expanded in sync with the RTD theme toggle class. */
+    (function () {
+      var btn = document.querySelector('.rst-current-version[aria-expanded]');
+      if (!btn) return;
+      btn.addEventListener('click', function () {
+        var expanded = this.getAttribute('aria-expanded') === 'true';
+        this.setAttribute('aria-expanded', expanded ? 'false' : 'true');
+      });
+    }());
+  </script>
+{% endif %}
diff --git a/user_manual/_templates/versions.html b/user_manual/_templates/versions.html
index 78076e86268..d5ab32f072c 100644
--- a/user_manual/_templates/versions.html
+++ b/user_manual/_templates/versions.html
@@ -58,13 +58,20 @@
   {% set sorted_languages = language_tuples | sort(attribute='name') %}
 
   <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
-    <span class="rst-current-version" data-toggle="rst-current-version">
+    {# Use <button> so the toggle has native keyboard semantics and can
+       carry aria-expanded. The RTD theme JS uses [data-toggle] selectors
+       so the element type does not matter for the toggle behaviour. #}
+    <button type="button"
+            class="rst-current-version"
+            data-toggle="rst-current-version"
+            aria-expanded="false"
+            aria-controls="rst-other-versions-user">
       🌐 {{ language_names.get(language, language) }}
-      <span class="fa fa-caret-down"></span>
-       ☁️ {{ current_version }}
-      <span class="fa fa-caret-down"></span>
-    </span>
-    <div class="rst-other-versions">
+      <span class="fa fa-caret-down" aria-hidden="true"></span>
+       ☁️ {{ current_version }}
+      <span class="fa fa-caret-down" aria-hidden="true"></span>
+    </button>
+    <div id="rst-other-versions-user" class="rst-other-versions">
       <dl>
         <dt>🌐 {{ _('Languages') }}</dt>
         {% for lang in sorted_languages %}
@@ -97,4 +104,15 @@
       </dl>
     </div>
   </div>
+  <script>
+    /* Keep aria-expanded in sync with the RTD theme toggle class. */
+    (function () {
+      var btn = document.querySelector('.rst-current-version[aria-expanded]');
+      if (!btn) return;
+      btn.addEventListener('click', function () {
+        var expanded = this.getAttribute('aria-expanded') === 'true';
+        this.setAttribute('aria-expanded', expanded ? 'false' : 'true');
+      });
+    }());
+  </script>
 {% endif %}

From 7acdb698417c718beb3a2d9d050707790e44581c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?= <skjnldsv@users.noreply.github.com>
Date: Tue, 12 May 2026 22:09:42 +0200
Subject: [PATCH 2/3] fix(a11y): ensure proper spacing in version select button
 content
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>
---
 _shared_assets/static/custom.css | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/_shared_assets/static/custom.css b/_shared_assets/static/custom.css
index c3b288eeb1c..f18e42ab338 100644
--- a/_shared_assets/static/custom.css
+++ b/_shared_assets/static/custom.css
@@ -69,6 +69,12 @@ button.rst-current-version {
 }
 .rst-versions .rst-current-version .fa-caret-down {
 	margin-left: 5px;
+.rst-versions .rst-current-version .fa-caret-down {
+	margin-left: 5px;
+}
+
+.rst-versions .rst-current-version .fa-caret-down:not(:last-of-type) {
+	margin-right: 10px;
 }
 
 /* Code blocks */

From 5af7f455c34a6bea0674d77e281f35a9d71c6e00 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?= <skjnldsv@users.noreply.github.com>
Date: Tue, 12 May 2026 22:11:06 +0200
Subject: [PATCH 3/3] fix(a11y): unwanted duplicate css line
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>
---
 _shared_assets/static/custom.css | 2 --
 1 file changed, 2 deletions(-)

diff --git a/_shared_assets/static/custom.css b/_shared_assets/static/custom.css
index f18e42ab338..f3faaa05b9a 100644
--- a/_shared_assets/static/custom.css
+++ b/_shared_assets/static/custom.css
@@ -67,8 +67,6 @@ button.rst-current-version {
 	align-items: center;
 	color: #0082c9;
 }
-.rst-versions .rst-current-version .fa-caret-down {
-	margin-left: 5px;
 .rst-versions .rst-current-version .fa-caret-down {
 	margin-left: 5px;
 }