dashorst opened a new issue, #1885: URL: https://github.com/apache/wicket/issues/1885
The reference guide's table of contents (#1845) shows a chapter's sections only while that chapter is being read. `guide.js` adds `is-open` to the current chapter's `li` as you scroll. Every other chapter's sections are `display: none`. A chapter's sections also open while focus is inside the chapter (`:focus-within`). With that, keyboard users can reach every section by tabbing onto a chapter link. Screen reader users in browse mode don't get there. The virtual cursor of NVDA and JAWS, and VoiceOver's reading cursor, move through the page without moving focus, so `:focus-within` never matches. The collapsed sections are not in the accessibility tree, and the only way to reach them is to scroll to the chapter. @papegaaij raised this in the review of #1845 ([comment](https://github.com/apache/wicket/pull/1845#discussion_r4527623984)). ## Proposal Give every chapter with sections a disclosure button next to its link: a real `<button>` with `aria-expanded` and `aria-controls` pointing at the chapter's `<ul>`, showing a chevron (▸/▾). A screen reader announces it as "button, collapsed" or "button, expanded", and activating it opens or closes the sections. This is the [WAI-ARIA disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/). ## Considerations - **Interaction with the scroll spy.** This is the actual design question. The spy now opens the current chapter and closes all others on every section change. With manual toggles there are three options: 1. The spy keeps control and closes a manually opened chapter as soon as the reader scrolls into another chapter. This is simple, but a chapter the user opened on purpose collapses under them. 2. Manual state wins. A chapter opened by hand stays open until it is closed by hand, and the spy only adds and removes its own automatic opening. This needs two states per chapter (`is-open` from the spy, `is-expanded` from the user), and `aria-expanded` has to reflect their union. 3. The spy stops collapsing altogether once the user has toggled anything. Option 2 matches what users expect from a tree. It also keeps `aria-expanded` truthful, because the button never says "collapsed" while the spy has the list open. - **`aria-expanded` must follow the spy.** Whatever the option, every time the spy opens or closes a chapter it has to update the button's `aria-expanded` too. Otherwise the announced state is wrong. - **Layout.** There are about 40 chapters with sections. The button needs a target of at least 24×24 px (44 px on `pointer: coarse`, as the masthead already does) without pushing the chapter titles out of line with chapters that have no sections. The ribbon-rail markers (`#toc li::before/::after`) sit on the left edge, so the chevron probably goes on the right or between the rail and the number. - **Tab order.** The button adds one tab stop per chapter, about 40 in all, next to the existing links. The skip link already lets keyboard users jump past the TOC. Alternatively, the buttons could use `tabindex="-1"` with arrow-key navigation (the tree view pattern), but that is much more script and a different ARIA role. The plain disclosure pattern is the smaller step. - **`:focus-within`.** This can stay: tabbing onto a chapter link still opens it. It also shouldn't fight the button. A chapter closed by its button while focus is inside it would reopen at once, so a manual close must override `:focus-within` (for example with an `is-collapsed` class that wins). - **Without JavaScript.** Nothing changes. The `js-toc` class is only set by the script, so without it every section stays visible and no buttons are needed. - **Mobile.** Below 768 px the TOC is not fixed. Check whether collapsing it there is wanted at all, or whether the buttons should only exist on wide screens. ## Acceptance - With NVDA in browse mode and with VoiceOver, every section of every chapter can be reached from the TOC without scrolling the content. - The announced expanded state always matches what is visible. - Keyboard behaviour from #1845 (skip link, `:focus-within`, `aria-current`) keeps working. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
