Skip to content

A programming framework for agentic AI

[Accessibility] Fix: screen reader does not announce theme change and nested nav label (#6061)

cheng-tan6f784ac18609
diff --git a/python/packages/autogen-core/docs/src/_static/custom.js b/python/packages/autogen-core/docs/src/_static/custom.js
index 8c77eea71..3cfd649c7 100644
--- a/python/packages/autogen-core/docs/src/_static/custom.js
+++ b/python/packages/autogen-core/docs/src/_static/custom.js
@@ -1,4 +1,6 @@
document.addEventListener('DOMContentLoaded', function () {
+ let liveRegion = createLiveRegion();
+
document.querySelectorAll('.copybtn').forEach(button => {
// Return focus to copy button after activation
button.addEventListener('click', async function (event) {
@@ -7,6 +9,7 @@ document.addEventListener('DOMContentLoaded', function () {
// Perform the copy action
await copyToClipboard(this);
+ announceMessage(liveRegion, 'Copied to clipboard');
// Restore the focus
focusedElement.focus();
@@ -29,7 +32,7 @@ document.addEventListener('DOMContentLoaded', function () {
});
// Set active TOCtree elements with aria-current=page
- document.querySelectorAll('.bd-sidenav .active').forEach(function(element) {
+ document.querySelectorAll('.bd-sidenav .active').forEach(function (element) {
element.setAttribute('aria-current', 'page');
});
@@ -47,9 +50,27 @@ document.addEventListener('DOMContentLoaded', function () {
});
});
+ const themeButton = document.querySelector('.theme-switch-button');
+ if (themeButton) {
+ themeButton.addEventListener('click', function () {
+ const mode = document.documentElement.getAttribute('data-mode');
+ announceMessage(liveRegion, `Theme changed to ${mode}`);
+ });
+ }
+
+ // Enhance TOC sections for accessibility
+ document.querySelectorAll('.caption-text').forEach(caption => {
+ const sectionTitle = caption.textContent.trim();
+ const captionContainer = caption.closest('p.caption');
+ if (!captionContainer) return;
+
+ // Find and process navigation lists that belong to this section
+ findSectionNav(captionContainer, sectionTitle);
+ });
+
// Version dropdown menu is dynamically generated after page load. Listen for changes to set aria-selected
- var observer = new MutationObserver(function() {
- document.querySelectorAll('.dropdown-item').forEach(function(element) {
+ var observer = new MutationObserver(function () {
+ document.querySelectorAll('.dropdown-item').forEach(function (element) {
if (element.classList.contains('active')) {
element.setAttribute('aria-selected', 'true');
}
@@ -61,7 +82,7 @@ document.addEventListener('DOMContentLoaded', function () {
var config = { childList: true, subtree: true };
if (targetNode) {
- observer.observe(targetNode, config);
+ observer.observe(targetNode, config);
}
});
@@ -70,29 +91,118 @@ async function copyToClipboard(button) {
const codeBlock = document.querySelector(targetSelector);
try {
await navigator.clipboard.writeText(codeBlock.textContent);
-
- // Add a visually hidden element for screen readers to announce
- const srAnnouncement = document.createElement('div');
- srAnnouncement.textContent = 'Copied to clipboard';
- srAnnouncement.setAttribute('role', 'status');
- srAnnouncement.setAttribute('aria-live', 'polite');
- srAnnouncement.style.position = 'absolute';
- srAnnouncement.style.width = '1px';
- srAnnouncement.style.height = '1px';
- srAnnouncement.style.padding = '0';
- srAnnouncement.style.margin = '-1px';
- srAnnouncement.style.overflow = 'hidden';
- srAnnouncement.style.clipPath = 'inset(50%)';
- srAnnouncement.style.whiteSpace = 'nowrap';
- srAnnouncement.style.border = '0';
-
- document.body.appendChild(srAnnouncement);
-
- // Remove the announcement element after it's been read
- setTimeout(() => {
- document.body.removeChild(srAnnouncement);
- }, 3000);
} catch (err) {
console.error('Failed to copy text: ', err);
}
}
+
+function createLiveRegion() {
+ const liveRegion = document.createElement('div');
+ liveRegion.setAttribute('role', 'status');
+ liveRegion.setAttribute('aria-live', 'assertive');
+ liveRegion.style.position = 'absolute';
+ liveRegion.style.width = '1px';
+ liveRegion.style.height = '1px';
+ liveRegion.style.padding = '0';
+ liveRegion.style.margin = '-1px';
+ liveRegion.style.overflow = 'hidden';
+ liveRegion.style.clipPath = 'inset(50%)';
+ liveRegion.style.whiteSpace = 'nowrap'; ` `
+ liveRegion.style.border = '0';
+ document.body.appendChild(liveRegion);
+
+ return liveRegion;
+}
+
+function announceMessage(liveRegion, message) {
+ liveRegion.textContent = '';
+ setTimeout(() => {
+ liveRegion.textContent = message;
+ }, 50);
+}
+
+/**
+ * Find navigation lists belonging to a section and process them
+ */
+function findSectionNav(captionContainer, sectionTitle) {
+ let nextElement = captionContainer.nextElementSibling;
+
+ while (nextElement) {
+ if (nextElement.classList && nextElement.classList.contains('caption')) {
+ break;
+ }
+
+ if (nextElement.matches('ul.bd-sidenav')) {
+ enhanceNavList(nextElement, sectionTitle);
+ }
+
+ nextElement = nextElement.nextElementSibling;
+ }
+}
+
+/**
+ * Process a navigation list by enhancing its links for accessibility
+ */
+function enhanceNavList(navList, sectionTitle) {
+ const topLevelItems = navList.querySelectorAll(':scope > li');
+
+ topLevelItems.forEach(item => {
+ const link = item.querySelector(':scope > a.reference.internal');
+ if (!link) return;
+
+ const linkText = link.textContent.trim();
+ link.setAttribute('aria-label', `${sectionTitle}: ${linkText}`);
+
+ enhanceExpandableSections(item, link, linkText, sectionTitle);
+ });
+}
+
+/**
+ * Process expandable sections (details elements) within a navigation item
+ */
+function enhanceExpandableSections(item, parentLink, parentText, sectionTitle) {
+ const detailsElements = item.querySelectorAll('details');
+
+ detailsElements.forEach(details => {
+ enhanceToggleButton(details, parentText);
+ enhanceNestedLinks(details, parentLink, parentText, sectionTitle);
+ });
+}
+
+/**
+ * Make toggle buttons more accessible by adding appropriate aria labels
+ */
+function enhanceToggleButton(details, parentText) {
+ const summary = details.querySelector('summary');
+ if (!summary) return;
+
+ function updateToggleLabel() {
+ const isExpanded = details.hasAttribute('open');
+ const action = isExpanded ? 'Collapse' : 'Expand';
+ summary.setAttribute('aria-label', `${action} ${parentText} section`);
+ }
+
+ updateToggleLabel();
+
+ summary.addEventListener('click', () => {
+ setTimeout(updateToggleLabel, 10);
+ });
+}
+
+/**
+ * Enhance nested links with hierarchical aria-labels
+ */
+function enhanceNestedLinks(details, parentLink, parentText, sectionTitle) {
+ const nestedLinks = details.querySelectorAll('a.reference.internal');
+
+ nestedLinks.forEach(link => {
+ const linkText = link.textContent.trim();
+ const parentLabel = parentLink.getAttribute('aria-label');
+
+ if (parentLabel) {
+ link.setAttribute('aria-label', `${parentLabel}: ${linkText}`);
+ } else {
+ link.setAttribute('aria-label', `${sectionTitle}: ${parentText}: ${linkText}`);
+ }
+ });
+}