Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
15.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file listbox.ts
 * @input Uses the shared accessibility contract vocabulary
 * @output LISTBOX_PATTERN and ListboxStateFacts
 * @position Standards-derived semantics for listbox, group, and option parts.
 */

import {definePattern, type WcagCriterion} from '../contract';
import {MissingBindingCapability} from '../check';
import type {Subject} from '../harness';

const NAME_ROLE_VALUE: WcagCriterion = {
  standard: 'wcag',
  id: '4.1.2',
  name: 'Name, Role, Value',
  level: 'A',
  url: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
};

export interface ListboxStateFacts {
  readonly part: 'listbox' | 'group' | 'option';
  readonly multiple: boolean;
  readonly selected?: boolean;
  readonly disabled?: boolean;
  readonly selectionAttribute?: 'aria-selected' | 'aria-checked';
  readonly ownerGroup?: string;
  readonly optionRelations?: readonly string[];
}

export const LISTBOX_PATTERN = definePattern<ListboxStateFacts>({
  pattern: 'listbox',
  url: 'https://www.w3.org/TR/wai-aria-1.2/#listbox',
  scope:
    'ARIA-authored listbox, group, and option semantics; native select/option mapping and interaction policy are separate owners.',
  expectations: [
    {
      id: 'listbox.state.multiselectable',
      outcome:
        'The listbox exposes whether more than one option may be selected.',
      sources: [NAME_ROLE_VALUE],
      covers: ['4.1.2-name-role-value'],
      appliesWhen: {
        condition: 'the subject is a listbox',
        test: facts => facts.part === 'listbox',
      },
      evidenceLayer: 'dom',
      enforcement: 'required',
      run: async ({subject, facts}) => {
        const multiple = await subject.attribute('aria-multiselectable');
        if (facts.multiple && multiple !== 'true') {
          throw new Error(
            'the listbox permits multiple selection but aria-multiselectable is not true',
          );
        }
        if (!facts.multiple && multiple !== null && multiple !== 'false') {
          throw new Error(
            'the listbox permits only one selection but aria-multiselectable is not false or absent',
          );
        }
      },
    },
    {
      id: 'listbox.option.selection-state',
      outcome: 'An option exposes the selection state its owner supplies.',
      sources: [NAME_ROLE_VALUE],
      covers: ['4.1.2-name-role-value'],
      appliesWhen: {
        condition: 'the subject is an option',
        test: facts => facts.part === 'option',
      },
      evidenceLayer: 'dom',
      enforcement: 'required',
      run: async ({subject, facts}) => {
        if (facts.selected == null) {
          throw new MissingBindingCapability(
            'an option binding must declare selected state',
          );
        }
        const attribute = facts.selectionAttribute ?? 'aria-selected';
        const selected = await subject.attribute(attribute);
        if (selected !== String(facts.selected)) {
          throw new Error(
            `the option is ${facts.selected ? 'selected' : 'unselected'} but ${attribute} is ${selected ?? 'absent'}`,
          );
        }
      },
    },
    {
      id: 'listbox.option.disabled-state',
      outcome:
        'An option exposes its availability without choosing a focus policy.',
      sources: [NAME_ROLE_VALUE],
      covers: ['4.1.2-name-role-value'],
      appliesWhen: {
        condition: 'the subject is an option',
        test: facts => facts.part === 'option',
      },
      evidenceLayer: 'dom',
      enforcement: 'required',
      run: async ({subject, facts}) => {
        if (facts.disabled == null) {
          throw new MissingBindingCapability(
            'an option binding must declare disabled state',
          );
        }
        const disabled = await subject.attribute('aria-disabled');
        if (
          facts.disabled
            ? disabled !== 'true'
            : disabled !== null && disabled !== 'false'
        ) {
          throw new Error(
            `the option is ${facts.disabled ? 'disabled' : 'available'} but aria-disabled is ${disabled ?? 'absent'}`,
          );
        }
      },
    },
    {
      id: 'listbox.relationship.owned',
      outcome: 'Options and groups keep their declared listbox relationship.',
      sources: [
        {
          standard: 'wcag',
          id: '1.3.1',
          name: 'Info and Relationships',
          level: 'A',
          url: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
        },
        {
          standard: 'web-standard',
          specification: 'WAI-ARIA 1.2',
          requirement:
            'Authors MUST ensure elements with role option are contained in, or owned by, an element with the role listbox or group within a listbox.',
          url: 'https://www.w3.org/TR/wai-aria-1.2/#option',
        },
      ],
      covers: ['1.3.1-info-and-relationships'],
      appliesWhen: {
        condition: 'the subject is an option or option group',
        test: facts => facts.part !== 'listbox',
      },
      evidenceLayer: 'dom',
      enforcement: 'required',
      run: async ({harness, subject, facts}) => {
        const listbox = await harness.related('listbox');
        const owner =
          facts.part === 'option' && facts.ownerGroup != null
            ? await harness.related(facts.ownerGroup)
            : listbox;
        const owns = async (parent: Subject, child: Subject) =>
          (await harness.contains(parent, child)) ||
          (await harness.references(parent, 'aria-owns', child));
        if (
          !(await owns(owner, subject)) ||
          (owner !== listbox && !(await owns(listbox, owner)))
        ) {
          throw new Error(
            `the ${facts.part} is neither contained nor owned by its listbox`,
          );
        }
      },
    },
    {
      id: 'listbox.exposure.identity',
      outcome:
        'The browser exposes each part with its role and any required identifying name.',
      sources: [NAME_ROLE_VALUE],
      covers: ['4.1.2-name-role-value'],
      appliesWhen: {
        condition: 'the declared semantic part is rendered',
        test: () => true,
      },
      evidenceLayer: 'accessibility-tree',
      enforcement: 'required',
      run: async ({subject, facts}) => {
        const {role, name} = await subject.computed();
        if (role !== facts.part) {
          throw new Error(
            `the browser exposes ${role ?? 'no role'} instead of ${facts.part}`,
          );
        }
        if (facts.part !== 'group' && name.trim() === '') {
          throw new Error(
            `the browser exposes the ${facts.part} without an accessible name`,
          );
        }
      },
    },
    {
      id: 'listbox.selection.single',
      outcome:
        'A single-selection listbox does not expose multiple selected options.',
      sources: [
        NAME_ROLE_VALUE,
        {
          standard: 'web-standard',
          specification: 'WAI-ARIA 1.2',
          requirement: 'Only one item can be selected.',
          url: 'https://www.w3.org/TR/wai-aria-1.2/#aria-multiselectable',
        },
      ],
      covers: ['4.1.2-name-role-value'],
      appliesWhen: {
        condition: 'the listbox permits only one selected option',
        test: facts => facts.part === 'listbox' && !facts.multiple,
      },
      evidenceLayer: 'dom',
      enforcement: 'required',
      run: async ({harness, facts}) => {
        if (facts.optionRelations == null) {
          throw new MissingBindingCapability(
            'a single-selection listbox must declare its option relations',
          );
        }
        const attribute = facts.selectionAttribute ?? 'aria-selected';
        let selected = 0;
        for (const relation of facts.optionRelations) {
          if (
            (await (await harness.related(relation)).attribute(attribute)) ===
            'true'
          ) {
            selected += 1;
          }
        }
        if (selected > 1) {
          throw new Error(
            `the single-selection listbox exposes ${selected} selected options`,
          );
        }
      },
    },
  ],
  exemptions: {
    '1.1.1-non-text-content': {
      owner: 'Caller content and Icon/Indicator components',
      verifiedBy: 'Content review and the existing component-scoped axe audit',
      reason:
        'A semantic part name does not establish the meaning of every image or decorative asset in caller-rendered content.',
    },
    '1.3.1-info-and-relationships': {
      owner: 'Component markup and axe ARIA content-model checks',
      verifiedBy: 'Existing pr-a11y checks and component composition tests',
      reason:
        'This contract checks the declared listbox ownership; allowed child-role structure and other composed relationships retain their existing checks.',
      coversRemainderOnly: true,
    },
    '1.3.2-meaningful-sequence': {
      owner: 'Selector/MultiSelector ordering and caller content',
      verifiedBy:
        'Component sorting/filtering suites and browser reading-order review',
      reason:
        'This semantic slice does not choose a sorting or visual-order policy.',
    },
    '1.3.5-identify-input-purpose': {
      owner: 'Form callsite and combobox input',
      verifiedBy: 'Form-purpose and autocomplete review',
      reason:
        'A popup option container does not determine which personal-information purpose the surrounding field collects.',
    },
    '1.4.1-use-of-color': {
      owner: 'Component and theme selection indicators',
      verifiedBy:
        'Indicator tests and visual review of selected/unselected states',
      reason:
        'Programmatic selection exposure does not prove a non-color visual cue.',
    },
    '1.4.3-contrast-minimum': {
      owner: 'Component themes and caller content',
      verifiedBy: 'Existing contrast audit and rendered theme review',
      reason:
        'Contrast needs rendered pixels and is not established by DOM or accessibility-tree semantics.',
    },
    '1.4.11-non-text-contrast': {
      owner: 'Component themes and indicator/focus styling',
      verifiedBy: 'Existing contrast audit and rendered selected/focus states',
      reason:
        'The semantic contract does not measure painted controls or graphics.',
    },
    '2.1.1-keyboard': {
      owner: 'Selector/MultiSelector interaction and combobox contracts',
      verifiedBy:
        'Existing component keyboard suites; separate real-browser interaction review',
      reason:
        'This first slice does not adopt a shared focus/selection model. Its results are not keyboard-conformance evidence.',
    },
    '2.1.2-no-keyboard-trap': {
      owner: 'Combobox, Popover, and BottomSheet lifecycle',
      verifiedBy:
        'Popup keyboard/dismissal suites and native-browser Tab checks',
      reason:
        'Entry and exit belong to the active host presentation rather than the static option semantics bound here.',
    },
    '2.4.2-page-titled': {
      owner: 'Page shell',
      verifiedBy: 'Page-level accessibility review',
      reason: 'Neither a listbox nor an option owns the document title.',
    },
    '2.4.3-focus-order': {
      owner: 'Combobox and popup focus owners',
      verifiedBy: 'Existing focus suites and real-browser presentation review',
      reason:
        'Selection state and focus are distinct; this contract does not choose or attest a focus movement model.',
    },
    '2.4.4-link-purpose': {
      owner: 'Link and caller content',
      verifiedBy: 'Navigation-destination contract and content review',
      reason: 'An option selects a value; it is not a navigation link.',
    },
    '2.4.6-headings-and-labels': {
      owner: 'Caller labels and component content review',
      verifiedBy: 'Review of field, group, and option wording',
      reason:
        'A nonempty computed name does not prove that its wording describes the intended topic.',
    },
    '2.4.7-focus-visible': {
      owner: 'Component themes and interaction-modality system',
      verifiedBy: 'Rendered keyboard-focus review and the existing visual lane',
      reason: 'No pixel or focus-ring claim is made by these semantic checks.',
    },
    '2.4.11-focus-not-obscured': {
      owner: 'Popup host and application layout',
      verifiedBy: 'Constrained-viewport real-browser focus review',
      reason:
        'Geometry and occlusion depend on the presentation and surrounding layout.',
    },
    '2.5.2-pointer-cancellation': {
      owner: 'Selector/MultiSelector option interaction',
      verifiedBy: 'Separate real-browser press/abort/release regression checks',
      reason:
        'The binding observes state without adopting or claiming a pointer-selection transition contract.',
    },
    '2.5.3-label-in-name': {
      owner: 'Component rendering and caller option content',
      verifiedBy: 'Rendered-label versus computed-name review',
      reason:
        'Identity presence is narrower than matching painted label text; custom option content remains separately reviewed.',
    },
    '2.5.8-target-size': {
      owner: 'Component themes and composition',
      verifiedBy: 'Browser target geometry and WCAG exception review',
      reason:
        'Target dimensions and spacing cannot be proved from semantic state.',
    },
    '3.1.1-language-of-page': {
      owner: 'Page shell and localization provider',
      verifiedBy: 'Document-language and locale integration checks',
      reason: 'The popup does not own the document language.',
    },
    '3.2.2-on-input': {
      owner: 'Component interaction and application response to selection',
      verifiedBy: 'Component interaction suites and end-to-end task review',
      reason:
        'This contract does not activate options or decide what the application does with a selected value.',
    },
    '3.2.4-consistent-identification': {
      owner: 'Design system and application content',
      verifiedBy: 'Cross-control content/design review',
      reason:
        'One popup fixture cannot establish consistent identification across an application.',
    },
    '3.3.1-error-identification': {
      owner: 'Field validation and status-message owners',
      verifiedBy: 'Existing input/status suites and textual-error review',
      reason:
        'Validation feedback belongs to the surrounding field, not each option.',
    },
    '3.3.2-labels-or-instructions': {
      owner: 'Field and caller instructions',
      verifiedBy: 'Field-label and form-content review',
      reason:
        'A named popup does not establish every instruction needed by its enclosing task.',
    },
    '4.1.3-status-messages': {
      owner: 'Status-message contract and component live-region owners',
      verifiedBy: 'Status-message bindings; AST-009 for speech/timing claims',
      reason:
        'Loading, result-count, empty, and selection announcements are not static listbox identity.',
    },
    'apg-interaction': {
      owner:
        'Current component interaction authority and future bounded migration',
      verifiedBy: 'Current-record review plus component keyboard suites',
      reason:
        'WAI-ARIA semantics apply here, but this slice does not adopt APG selection-follows-focus, unavailable-option navigation, Home/End, or typeahead policy.',
    },
    'forced-colors': {
      owner: 'Component themes and indicators',
      verifiedBy: 'Real-browser forced-color paint review',
      reason:
        'State exposure does not prove that a selection mark or focus indicator remains visible.',
    },
    'reduced-motion': {
      owner: 'Popover/BottomSheet and component themes',
      verifiedBy: 'Existing reduced-motion tests and browser review',
      reason:
        'The semantic part contract owns no opening or closing animation.',
    },
    'at-facing-strings': {
      owner: 'Component localization and caller labels',
      verifiedBy:
        'Catalog checks and localized component tests; AST-009 for speech claims',
      reason:
        'The binding uses deterministic labels without claiming translation completeness or spoken output.',
    },
  },
});