ARIA-compatible collapsible navigation for Python DevGuide

[abitrolly]

Originally posted as python/devguide#1785 and redirected here.

Describe the enhancement or feature you would like

The discussion about keyboard shortcuts python/devguide#1784 (comment) revealed that there are might expectations about arrow keys to the collapsible tree items.

From ARIA Guide.

Just as familiar visual styling helps users discover how to expand a tree branch with a mouse, ARIA attributes give the tree the sound and feel of a tree in a desktop application. So, screen reader users will commonly expect that pressing the right arrow key will expand a collapsed node.

The implementation should add a local keyboard shortcut to left/right keys similar to global one defined for page navigation here https://github.com/sphinx-doc/sphinx/blob/cc7c6f435ad37bb12264f8118c8461b230e6830c/sphinx/themes/basic/static/doctools.js#L106 that should do the ARIA thing.

I suggest we find real ARIA users who can define what the right ARIA thing should do and help test it.

Additional context

• https://webaim.org/techniques/keyboard/

[opensource-joe]

I read the sidebar implementation before commenting, and I think there are two questions here that have been treated as one.

Furo already does more than the thread implies. src/furo/navigation.py gives every collapsible section a real <input type="checkbox"> with role="switch", a computed aria-label of "Toggle navigation of {section}", and checked when that section is current. So each expander is reachable by Tab, operable with Space, and names what it controls. That is a deliberate design, and better than the label-only or :target patterns other themes use.

What is missing is expansion state, not focusability. There is no aria-expanded in the theme, no tree roles, and no keydown handling in furo.js. A switch communicates on and off; it does not say that a section of navigation is expanded, or that the control owns the list beneath it. From the markup I would expect assistive tech to announce roughly "Toggle navigation of Reference, switch, off" where the useful announcement is "Reference, collapsed". I have not verified that against a built site with a screen reader, so treat it as inference.

The real question is which pattern, and I would push back on the one implied above. Arrow keys point at the APG Treeview pattern, which makes the sidebar a single composite widget with one tab stop and a roving tabindex, needs real JavaScript, and changes how every Furo site behaves. The APG's Disclosure Navigation pattern is much closer to what Furo already has: aria-expanded on a control that owns the list beneath it, Tab between controls, Space to toggle. Mostly expressing state correctly rather than restructuring, and the CSS-only collapse largely survives.

For documentation sidebars I think disclosure is usually right and treeview is over-applied. People scan and click links there; it is not a file explorer. But that is a judgement about your users.

If disclosure is a direction you would accept, I am happy to do it and to test with NVDA and VoiceOver rather than assert it works. If you would rather not change the pattern, that is a fine answer, and having it written here would help: this has been quiet since April while the same request keeps resurfacing in python/devguide.

For context, I ran the US federal government's open source program office and spent much of it on Section 508 and WCAG conformance. Not looking to relitigate the design, only to help if the answer is yes.

[pradyunsg]

I'd like to see what the disclosure navigation pattern would look like. A PR for this would be welcome. One of the things I've tried to do with Furo is maintain the functionality even if JS is disabled. I'd be OK with JS doing progressive enhancement and aiding accessibility here.