Defines keyboard, focus, filtering, selection, and announcement behavior for a combobox pattern aligned with WAI-ARIA Authoring Practices without claiming WCAG conformance by default.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Implement comboboxes following the WAI-ARIA Authoring Practices combobox pattern: an editable or readonly input with a linked listbox popup, active descendant management, and predictable keyboard behavior. This block specifies interaction contracts for engineering and QA; it does not certify WCAG conformance for any particular implementation.
Scope
- Roles, labeling, popup visibility, and active option management.
- Keyboard bindings documented in
keyboard-contract.yaml. - Filtering, async loading, selection commit, and dismissal behavior.
- Announcements for open, filter results, and selection changes.
Outside this block
- Visual design tokens and styling.
- WCAG conformance audits or legal accessibility sign-off.
- Server-side search relevance ranking.
Contract
- The input exposes role combobox with accessible name, aria-expanded, and aria-controls referencing the listbox popup when open.
- When popup opens, active option is indicated via aria-activedescendant; DOM focus remains on the combobox input at all times.
- Escape and Tab close the popup and clear aria-activedescendant while restoring the input value per profile rules.
- Arrow keys move active descendant; Enter selects active option and closes popup.
- Tab closes popup, clears aria-activedescendant, and follows standard document tab order without focus trap inside the popup.
- Typing filters options when autocomplete is list or both; filter debounce follows profile timing for async sources.
- Selection updates input value and emits one concise announcement naming the selected value; loading and empty states are announced without spamming on every keystroke.
Implementation guidance
- Follow the WAI-ARIA APG combobox pattern for editable combobox with listbox popup.
- Implement bindings from
keyboard-contract.yamlin automated keyboard tests. - Use polite live regions for result counts and selection confirmations.
- Test with keyboard-only navigation and at least one screen reader on target browsers.
Failure handling and safeguards
- On async fetch failure, keep focus in combobox and announce error with retry affordance.
- If zero results, announce empty state and preserve typed input for correction.
- Do not convert combobox into a non-standard widget without updating the contract and tests.
Verification and operations
- Run automated tests for each keyboard binding context in
keyboard-contract.yaml. - Manual assistive technology review before marking stable.
- Track bug reports related to focus loss, double announcement, and trapped focus.
The executable-looking examples in this package are fixtures and acceptance contracts. Validate package structure before adoption; then implement and execute the scenarios in the target repository.
Adoption assumptions
- Debounce, list size, and label text in
example.yamlare profile choices for a country picker, not universal defaults. - Multiselect comboboxes require a separate contract extension if adopted later.