Accessible vertical tablist with arrow keys and a skipped tab
The docs site for a shipping API has a sidebar of sections next to the content. Each section is a tab in a vertical tablist. Mouse users click a section. Keyboard users press Tab once to reach the list, then move between sections with the arrow keys, the way the WAI-ARIA tabs pattern describes. One section isn’t written yet and must be skipped.
The starter code includes the sections:
const API_SECTIONS = [
{ id: 'overview', title: 'Overview', body: 'The Parcel API lets you create shipments, buy labels and track packages over HTTPS.' },
{ id: 'authentication', title: 'Authentication', body: 'Send your secret key in the Authorization header as a Bearer token on every request.' },
{ id: 'rate-limits', title: 'Rate limits', body: 'Rate limit headers arrive in the next release.', disabled: true },
{ id: 'webhooks', title: 'Webhooks', body: 'Register an HTTPS endpoint to receive tracking events as signed JSON payloads.' },
{ id: 'errors', title: 'Errors', body: 'Failed requests return a 4xx or 5xx status with a machine-readable error code.' },
];
role="tablist" element with aria-orientation="vertical", named API reference (with aria-label, or aria-labelledby pointing at a visible heading).<button type="button" role="tab"> per section, in order, with the section’s title as its text.role="tabpanel" element per section showing its body. Each tab has an id and aria-controls set to its panel’s id; each panel has aria-labelledby set to its tab’s id. Only the selected tab’s panel is visible.aria-selected="true"; every other tab has aria-selected="false". Overview is selected at first.disabled: true renders a tab with aria-disabled="true". It can never be selected.The selected tab has tabindex="0". Every other tab has tabindex="-1". This way Tab enters the list on the selected tab and the next Tab leaves the list, instead of stopping on every section.
When a tab has focus and the user presses one of these keys, move focus (with .focus()) to the target tab and select it at the same time (automatic activation). Call preventDefault() on these keys so the page doesn’t scroll.
Clicking an enabled tab selects it. Clicking the disabled tab does nothing.
Focus Overview, ArrowDown Authentication focused and selected, its panel shown
Authentication, ArrowDown Webhooks (Rate limits is skipped)
Webhooks, ArrowUp Authentication
Overview, ArrowUp Errors (wraps)
Errors, ArrowDown Overview (wraps)
Any tab, End / Home Errors / Overview
Click "Rate limits" nothing changes
aria-disabled rather than relying only on the disabled attribute, so screen reader users can still discover it.aria-selected without moving focus leaves keyboard users stranded on the old tab. Updating focus without tabindex means Shift+Tab back into the list lands on the wrong tab.The tests focus a tab, dispatch keydown events (key: 'ArrowDown', 'ArrowUp', 'Home', 'End', 'ArrowRight') on the focused tab, and click tabs. You don’t need test ids or class names. The test frame is hidden, so the browser can’t move focus by itself. The tests track focus through element.focus() calls and document.activeElement, so move focus only with .focus(). They check that:
[role="tablist"] with aria-orientation="vertical" is named API reference and contains five [role="tab"] elements in order. The Rate limits tab has aria-disabled="true".aria-selected and tabindex are correct on every tab after every key press and click.document.activeElement is the expected tab after every key press, and the handled keys are cancelled (defaultPrevented).[role="tabpanel"] is visible, its aria-labelledby is the selected tab’s id, and the visible text includes only the selected section’s body.Hide inactive panels with the hidden attribute or display: none. Capitalization and extra spacing don’t matter.