From fac55943a5c4ffa3f983e833a12008c3f56ff95f Mon Sep 17 00:00:00 2001
From: skjnldsv <skjnldsv@protonmail.com>
Date: Wed, 13 May 2026 09:35:03 +0200
Subject: [PATCH 1/2] =?UTF-8?q?fix(a11y):=20fix=20nav=20tree=20ARIA=20?=
 =?UTF-8?q?=E2=80=94=20move=20expand=20buttons=20out=20of=20links?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

sphinx-rtd-theme inserts a <button class="toctree-expand"> inside each
<a> nav link, and places aria-expanded on <li>/<ul>/<a> elements.
Both are invalid: interactive children of <a> are forbidden in HTML,
and aria-expanded must be on the controlling widget (the button).

Add fix-nav-a11y.js (loaded deferred via html_js_files) that:
1. Moves each .toctree-expand button from inside <a> to be its next
   sibling (still inside the same <li>), fixing the invalid nesting.
2. Sets aria-expanded on the button with the correct initial value.
3. Uses MutationObserver to intercept all future aria-expanded changes
   the theme makes to <a>/<li>/<ul> and redirects them to the button.

Fixes #9746

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
---
 _shared_assets/static/fix-nav-a11y.js | 103 ++++++++++++++++++++++++++
 conf.py                               |   4 +
 2 files changed, 107 insertions(+)
 create mode 100644 _shared_assets/static/fix-nav-a11y.js

diff --git a/_shared_assets/static/fix-nav-a11y.js b/_shared_assets/static/fix-nav-a11y.js
new file mode 100644
index 00000000000..a0a34cf7e6d
--- /dev/null
+++ b/_shared_assets/static/fix-nav-a11y.js
@@ -0,0 +1,103 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Fix sphinx-rtd-theme navigation accessibility (BITV 9.4.1.2 / WCAG 4.1.2):
+ *
+ * Problem 1 — sphinx-rtd-theme prepends a <button class="toctree-expand">
+ *   inside each <a> nav link. Buttons inside links are invalid HTML and break
+ *   assistive technology.
+ *
+ * Problem 2 — the theme sets aria-expanded on <li>, <ul>, and <a> elements.
+ *   The attribute belongs only on the interactive element that controls the
+ *   expand/collapse action — i.e. the expand button itself.
+ *
+ * Fix: after the theme's own DOM-ready callback has inserted the buttons,
+ * move each button to be a sibling of its <a> parent (inserted immediately
+ * after it), and redirect all aria-expanded mutations from <a>/<li>/<ul> to
+ * the button via MutationObserver.
+ */
+(function () {
+  'use strict';
+
+  /** Return the toctree-expand button that is a direct child of `li`. */
+  function getExpandButton(li) {
+    return li.querySelector(':scope > button.toctree-expand');
+  }
+
+  /**
+   * Transfer aria-expanded from `sourceEl` to the expand button of the
+   * nearest ancestor (or self) <li>.  Remove the attribute from `sourceEl`
+   * so it no longer appears on an invalid element.
+   */
+  function transferAriaExpanded(sourceEl) {
+    var val = sourceEl.getAttribute('aria-expanded');
+    if (val === null) {
+      return;
+    }
+    sourceEl.removeAttribute('aria-expanded');
+
+    var li = sourceEl.closest('li');
+    if (!li) {
+      return; // top-level container element — just remove, no button to update
+    }
+    var btn = getExpandButton(li);
+    if (btn) {
+      btn.setAttribute('aria-expanded', val);
+    }
+  }
+
+  /** Watch an element and call transferAriaExpanded whenever aria-expanded changes. */
+  function watchAriaExpanded(el) {
+    new MutationObserver(function (mutations) {
+      for (var i = 0; i < mutations.length; i++) {
+        if (mutations[i].attributeName === 'aria-expanded') {
+          transferAriaExpanded(el);
+          return;
+        }
+      }
+    }).observe(el, { attributes: true, attributeFilter: ['aria-expanded'] });
+  }
+
+  function fixNavTree() {
+    var nav = document.querySelector('.wy-menu-vertical');
+    if (!nav) {
+      return;
+    }
+
+    // Step 1: move each toctree-expand <button> out of its <a> parent.
+    // The RTD theme does `anchor.prepend(button)` which produces invalid HTML.
+    // We re-insert the button immediately after the <a> so it is a sibling,
+    // not a descendant, of the link.
+    nav.querySelectorAll('a > button.toctree-expand').forEach(function (btn) {
+      var anchor = btn.parentElement; // <a>
+      var li = anchor.parentElement;  // <li>
+
+      anchor.removeChild(btn);
+      // insertBefore(btn, anchor.nextSibling) == insertAfter(anchor)
+      li.insertBefore(btn, anchor.nextSibling);
+
+      // Set initial aria-expanded based on whether this item is active.
+      btn.setAttribute('aria-expanded',
+        li.classList.contains('current') ? 'true' : 'false');
+    });
+
+    // Step 2: flush any aria-expanded already placed on <a>/<li>/<ul> by the
+    // theme's reset() call (which fires immediately in the theme's init).
+    nav.querySelectorAll('[aria-expanded]').forEach(transferAriaExpanded);
+
+    // Step 3: observe future mutations so that toggleCurrent() and reset()
+    // changes are transparently redirected to the button.
+    nav.querySelectorAll('li, ul, a').forEach(watchAriaExpanded);
+  }
+
+  // The RTD theme registers its jQuery-ready callback before this file is
+  // evaluated (it is loaded earlier in the HTML).  jQuery fires ready
+  // callbacks in registration order, so our callback runs after the theme
+  // has already inserted the expand buttons into the DOM.
+  if (typeof jQuery !== 'undefined') {
+    jQuery(fixNavTree);
+  } else {
+    document.addEventListener('DOMContentLoaded', fixNavTree);
+  }
+}());
diff --git a/conf.py b/conf.py
index 7b05a687c30..21dc9fa3dd4 100644
--- a/conf.py
+++ b/conf.py
@@ -109,6 +109,10 @@ def generateVersionsDocs(current_docs):
 html_css_files = [
 	'custom.css'
 ]
+# Extra JS relative to html_static_path
+html_js_files = [
+	('fix-nav-a11y.js', {'defer': 'defer'}),
+]
 
 edit_on_github_project = 'nextcloud/documentation'
 edit_on_github_branch = 'master'

From 344896f34788078b7899c707195c7a89b397c821 Mon Sep 17 00:00:00 2001
From: skjnldsv <skjnldsv@protonmail.com>
Date: Wed, 13 May 2026 09:55:27 +0200
Subject: [PATCH 2/2] fix(a11y): patch theme.js to fix nav tree ARIA violations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the MutationObserver runtime workaround with a direct override
of sphinx-rtd-theme's theme.js via Sphinx's static-path override
mechanism (files in html_static_path shadow theme files of the same
relative path at build time — zero runtime overhead).

Eight targeted patches to the minified source (pinned to 3.1.0):

1. `t.prepend(expand)` → `t.after(expand)`: places the expand button
   as a sibling of <a>, not a child — fixes button-inside-link invalid
   HTML (BITV 9.4.1.2 / WCAG 4.1.2).

2–8. All `aria-expanded` mutations on <li>/<ul>/<a> redirected to
   `button.toctree-expand` via `.children()` / `.parent("li")` chains
   in reset() and toggleCurrent() — aria-expanded now lives only on
   the interactive widget that controls expand/collapse.

Fixes #9746

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
---
 _shared_assets/static/fix-nav-a11y.js | 103 --------------------------
 _shared_assets/static/js/theme.js     |   1 +
 conf.py                               |   4 -
 3 files changed, 1 insertion(+), 107 deletions(-)
 delete mode 100644 _shared_assets/static/fix-nav-a11y.js
 create mode 100644 _shared_assets/static/js/theme.js

diff --git a/_shared_assets/static/fix-nav-a11y.js b/_shared_assets/static/fix-nav-a11y.js
deleted file mode 100644
index a0a34cf7e6d..00000000000
--- a/_shared_assets/static/fix-nav-a11y.js
+++ /dev/null
@@ -1,103 +0,0 @@
-/**
- * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
- * SPDX-License-Identifier: AGPL-3.0-or-later
- *
- * Fix sphinx-rtd-theme navigation accessibility (BITV 9.4.1.2 / WCAG 4.1.2):
- *
- * Problem 1 — sphinx-rtd-theme prepends a <button class="toctree-expand">
- *   inside each <a> nav link. Buttons inside links are invalid HTML and break
- *   assistive technology.
- *
- * Problem 2 — the theme sets aria-expanded on <li>, <ul>, and <a> elements.
- *   The attribute belongs only on the interactive element that controls the
- *   expand/collapse action — i.e. the expand button itself.
- *
- * Fix: after the theme's own DOM-ready callback has inserted the buttons,
- * move each button to be a sibling of its <a> parent (inserted immediately
- * after it), and redirect all aria-expanded mutations from <a>/<li>/<ul> to
- * the button via MutationObserver.
- */
-(function () {
-  'use strict';
-
-  /** Return the toctree-expand button that is a direct child of `li`. */
-  function getExpandButton(li) {
-    return li.querySelector(':scope > button.toctree-expand');
-  }
-
-  /**
-   * Transfer aria-expanded from `sourceEl` to the expand button of the
-   * nearest ancestor (or self) <li>.  Remove the attribute from `sourceEl`
-   * so it no longer appears on an invalid element.
-   */
-  function transferAriaExpanded(sourceEl) {
-    var val = sourceEl.getAttribute('aria-expanded');
-    if (val === null) {
-      return;
-    }
-    sourceEl.removeAttribute('aria-expanded');
-
-    var li = sourceEl.closest('li');
-    if (!li) {
-      return; // top-level container element — just remove, no button to update
-    }
-    var btn = getExpandButton(li);
-    if (btn) {
-      btn.setAttribute('aria-expanded', val);
-    }
-  }
-
-  /** Watch an element and call transferAriaExpanded whenever aria-expanded changes. */
-  function watchAriaExpanded(el) {
-    new MutationObserver(function (mutations) {
-      for (var i = 0; i < mutations.length; i++) {
-        if (mutations[i].attributeName === 'aria-expanded') {
-          transferAriaExpanded(el);
-          return;
-        }
-      }
-    }).observe(el, { attributes: true, attributeFilter: ['aria-expanded'] });
-  }
-
-  function fixNavTree() {
-    var nav = document.querySelector('.wy-menu-vertical');
-    if (!nav) {
-      return;
-    }
-
-    // Step 1: move each toctree-expand <button> out of its <a> parent.
-    // The RTD theme does `anchor.prepend(button)` which produces invalid HTML.
-    // We re-insert the button immediately after the <a> so it is a sibling,
-    // not a descendant, of the link.
-    nav.querySelectorAll('a > button.toctree-expand').forEach(function (btn) {
-      var anchor = btn.parentElement; // <a>
-      var li = anchor.parentElement;  // <li>
-
-      anchor.removeChild(btn);
-      // insertBefore(btn, anchor.nextSibling) == insertAfter(anchor)
-      li.insertBefore(btn, anchor.nextSibling);
-
-      // Set initial aria-expanded based on whether this item is active.
-      btn.setAttribute('aria-expanded',
-        li.classList.contains('current') ? 'true' : 'false');
-    });
-
-    // Step 2: flush any aria-expanded already placed on <a>/<li>/<ul> by the
-    // theme's reset() call (which fires immediately in the theme's init).
-    nav.querySelectorAll('[aria-expanded]').forEach(transferAriaExpanded);
-
-    // Step 3: observe future mutations so that toggleCurrent() and reset()
-    // changes are transparently redirected to the button.
-    nav.querySelectorAll('li, ul, a').forEach(watchAriaExpanded);
-  }
-
-  // The RTD theme registers its jQuery-ready callback before this file is
-  // evaluated (it is loaded earlier in the HTML).  jQuery fires ready
-  // callbacks in registration order, so our callback runs after the theme
-  // has already inserted the expand buttons into the DOM.
-  if (typeof jQuery !== 'undefined') {
-    jQuery(fixNavTree);
-  } else {
-    document.addEventListener('DOMContentLoaded', fixNavTree);
-  }
-}());
diff --git a/_shared_assets/static/js/theme.js b/_shared_assets/static/js/theme.js
new file mode 100644
index 00000000000..6ffa19a018f
--- /dev/null
+++ b/_shared_assets/static/js/theme.js
@@ -0,0 +1 @@
+!function(n){var e={};function t(i){if(e[i])return e[i].exports;var o=e[i]={i:i,l:!1,exports:{}};return n[i].call(o.exports,o,o.exports,t),o.l=!0,o.exports}t.m=n,t.c=e,t.d=function(n,e,i){t.o(n,e)||Object.defineProperty(n,e,{enumerable:!0,get:i})},t.r=function(n){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(n,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(n,"__esModule",{value:!0})},t.t=function(n,e){if(1&e&&(n=t(n)),8&e)return n;if(4&e&&"object"==typeof n&&n&&n.__esModule)return n;var i=Object.create(null);if(t.r(i),Object.defineProperty(i,"default",{enumerable:!0,value:n}),2&e&&"string"!=typeof n)for(var o in n)t.d(i,o,function(e){return n[e]}.bind(null,o));return i},t.n=function(n){var e=n&&n.__esModule?function(){return n.default}:function(){return n};return t.d(e,"a",e),e},t.o=function(n,e){return Object.prototype.hasOwnProperty.call(n,e)},t.p="",t(t.s=0)}([function(n,e,t){t(1),n.exports=t(3)},function(n,e,t){(function(){var e="undefined"!=typeof window?window.jQuery:t(2);n.exports.ThemeNav={navBar:null,win:null,winScroll:!1,winResize:!1,linkScroll:!1,winPosition:0,winHeight:null,docHeight:null,isRunning:!1,enable:function(n){var t=this;void 0===n&&(n=!0),t.isRunning||(t.isRunning=!0,e((function(e){t.init(e),t.reset(),t.win.on("hashchange",t.reset),n&&t.win.on("scroll",(function(){t.linkScroll||t.winScroll||(t.winScroll=!0,requestAnimationFrame((function(){t.onScroll()})))})),t.win.on("resize",(function(){t.winResize||(t.winResize=!0,requestAnimationFrame((function(){t.onResize()})))})),t.onResize()})))},enableSticky:function(){this.enable(!0)},init:function(n){n(document);var e=this;this.navBar=n("div.wy-side-scroll:first"),this.win=n(window),n(document).on("click","[data-toggle='wy-nav-top']",(function(){n("[data-toggle='wy-nav-shift']").toggleClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift")})).on("click",".wy-menu-vertical .current ul li a",(function(){var t=n(this);n("[data-toggle='wy-nav-shift']").removeClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift"),e.toggleCurrent(t),e.hashChange()})).on("click","[data-toggle='rst-current-version']",(function(){n("[data-toggle='rst-versions']").toggleClass("shift-up")})),n("table.docutils:not(.field-list,.footnote,.citation)").wrap("<div class='wy-table-responsive'></div>"),n("table.docutils.footnote").wrap("<div class='wy-table-responsive footnote'></div>"),n("table.docutils.citation").wrap("<div class='wy-table-responsive citation'></div>"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n('<button class="toctree-expand" title="Open/close menu"></button>'),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.after(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current"),$(".wy-menu-vertical button.toctree-expand").attr("aria-expanded","false"),t.addClass("current"),t.parent("li").children("button.toctree-expand").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").children("button.toctree-expand").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").children("button.toctree-expand").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").children("button.toctree-expand").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").children("button.toctree-expand").attr("aria-expanded","false"),e.toggleClass("current"),e.children("button.toctree-expand").attr("aria-expanded",e.hasClass("current")?"true":"false"))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t<e.length&&!window.requestAnimationFrame;++t)window.requestAnimationFrame=window[e[t]+"RequestAnimationFrame"],window.cancelAnimationFrame=window[e[t]+"CancelAnimationFrame"]||window[e[t]+"CancelRequestAnimationFrame"];window.requestAnimationFrame||(window.requestAnimationFrame=function(e,t){var i=(new Date).getTime(),o=Math.max(0,16-(i-n)),r=window.setTimeout((function(){e(i+o)}),o);return n=i+o,r}),window.cancelAnimationFrame||(window.cancelAnimationFrame=function(n){clearTimeout(n)})}()}).call(window)},function(n,e){n.exports=jQuery},function(n,e,t){}]);
\ No newline at end of file
diff --git a/conf.py b/conf.py
index 21dc9fa3dd4..7b05a687c30 100644
--- a/conf.py
+++ b/conf.py
@@ -109,10 +109,6 @@ def generateVersionsDocs(current_docs):
 html_css_files = [
 	'custom.css'
 ]
-# Extra JS relative to html_static_path
-html_js_files = [
-	('fix-nav-a11y.js', {'defer': 'defer'}),
-]
 
 edit_on_github_project = 'nextcloud/documentation'
 edit_on_github_branch = 'master'