`VersionSelector` is not accessible for screen readers

[knowler]

The <VersionSelector> component used in the package code page is not accessible for screen readers.

The root of the problem is that ARIA role option shouldn’t nest interactive content (or really any semantic content). Its children are expected to be presentational.

The current incorrect structure is like this:

• role=listbox
  • role=option
    • role=button
    • role=link
    • (then a list of role=option shown when the button is aria-expanded=true)

ARIA doesn’t expect there to be anything past the role=option (i.e. the contents are meant to be used for its accessible name).

On Windows 11, NVDA (in Firefox and Edge) is able to focus the expand/collapse button and link and even trigger the buttons, however, it cannot trigger the link.

On macOS and iOS, VoiceOver both do not go further than the role=option widgets (and do nothing when activated).

We will need different semantics which I can research. I suspect it might be a multi-level list of expand/collapse buttons + links that is focus trapped while it’s open. A treeview could be another option, but that has some significant complexity to it and shouldn’t be used lightly. The README table of contents is also using role=listbox when it probably shouldn’t, so it would be good to unify on an approach (even if the components are styled different).

I could add some screen caps when I get a change to better demonstrate the issue.

[knowler]

To avoid a whole lot of ARIA complexity (e.g. a tree view), this is an example of the structure I’m recommending:

<nav aria-label="version">
	<button popovertarget="version-selector" popovertargetaction="toggle">
		<span>4.3.1</span>
		<span>latest</span>
		<span class="i-lucide:chevron-down" aria-hidden="true"></span>
	</button>
	<ul aria-label="nuxt versions" id="version-selector" popover>
		<li>
			<a href="/package-docs/nuxt/v/4.3.1" aria-current="page">
				<span>4.3.1</span>
				<span>latest</span>
			</a>
			<button id="prior-to-4-3-1-trigger" aria-expanded=false aria-controls="prior-to-4-3-1" aria-label="versions prior to 4.3.1">
				<span class="i-lucide:chevron-down" aria-hidden="true"></span>
			</button>
			<ol id="prior-to-4-3-1" reversed hidden aria-labelledby="prior-to-4-3-1-trigger">
				<li><a href="/package-docs/nuxt/v/4.3.0">4.3.0</a></li>
				<li><a href="/package-docs/nuxt/v/4.2.2">4.2.2</a></li>
				<!-- etc. -->
			</ol>
		</li>
		<li>
			<a href="/package-docs/nuxt/v/4.0.0-rc.0">
				<span>4.0.0-rc.0</span>
				<span>rc</span>
			</a>
		</li>
		<li>
			<a href="/package-docs/nuxt/v/4.0.0-alpha.4">
				<span>4.0.0-alpha.4</span>
				<span>alpha</span>
			</a>
			<button id="prior-to-4-0-0-alpha-4-trigger" aria-expanded=false aria-controls="prior-to-4-0-0-alpha-4" aria-label="versions prior to 4.0.0-alpha.4">
				<span class="i-lucide:chevron-down" aria-hidden="true"></span>
			</button>
			<ol id="prior-to-4-0-0-alpha-4" reversed hidden aria-labelledby="prior-to-4-0-0-alpha-4-trigger">
				<li><a href="/package-docs/nuxt/v/4.0.0-alpha.3">4.0.0-alpha.3</a></li>
				<li><a href="/package-docs/nuxt/v/4.0.0-alpha.2">4.0.0-alpha.2</a></li>
				<li><a href="/package-docs/nuxt/v/4.0.0-alpha.1">4.0.0-alpha.1</a></li>
			</ol>
		</li>
		<!-- etc. -->
	</ul>
</nav>

Some notes:

• We’re wrapping everything with a <nav> element which has an implicit ARIA role of navigation and is a landmark, so it’s easy to find for assistive tech users.
• The top-level popover button is just labelled by the contents. This is fine for non-visual scenarios, because since it controls a popover, it gains an implicit aria-expanded value.
  • To style the chevron icon we’ll need to leverage a sibling selector and :popover-open. I believe that the Uno/Tailwind open: variant includes :popover-open and there are other utilities we can use here for the sibling selector.
• This top-level list will need to remain in the DOM. We can use the beforetoggle event to conditionally and lazily render the contents if desired.
• Since the version list is a popover, it’ll appear in the top-layer.
  • We can use absolute positioning relative to the <nav> element to position the popover.
  • (Optional) we could use anchor positioning as a progressive enhancement to anchor the popover to the button. We would need the positioning relative to the parent approach as a fallback.
• Within the popover, there are the top-level groupings of versions. For each of these, I think we should place the link of what version it is first and then the button second. We can use CSS to change the visual order. This is an exception to the rule.
• The button is controls the hidden attribute on the adjacent list. It should also update its aria-expanded state (either "true" or "false" — note these are strings not JavaScript booleans).
• Set aria-current="page" on whatever link within the entire popover is the current one for the page.
• I omitted a lot of necessary class names from all elements here. This example is mostly to communicate the final rendered, semantic structure.

If we get this in place, I can follow up with some thinking around focus management, however, I don’t think it’s required, it just could improve the experience.