import { Notice } from "@cerner/terra-docs";
import { Badge } from 'terra-dropdown-button/package.json?dev-site-package';
import Whitespace from '../../common/layout-helpers/Whitespace';
import AccessibilityDropdown from './example/AccessibilityDropdown';

<Badge />

# Terra Dropdown Accessibility Guide

## Why the accessibility of Dropdown is important

Dropdowns are one of the most used menu controls to gather data within an interface. Because they are so ubiquitous, users need to understand their purpose and be able to interact with them predictably. However, if Dropdowns are not implemented following best practices, users may fail to understand what the button is for, or worse, they may not be able to interact with the Dropdown menu. It is critical to users that Dropdowns must be accessible to understand and interact with the menu effectively.

There are many ways a poorly implemented Dropdown can make unusable to users:
- All users rely on the Dropdown label to accurately describe the purpose of the menu.
- All users rely upon good error messaging to help the user understand when a button is invalid and what they must do to succeed in completing a form.
- Blind users need the label to be programmatically associated with the Dropdown menu for the screen reader to read the label; otherwise, they will not understand the purpose of the menu.
- Speech input device users will not be able to activate a dropdown button if the button label is not unique or programmatically associated with the button.
- If the Dropdown does not provide meaningful helper text or is not programmatically marked as required, the user may not understand how to meet the button requirements.

<Whitespace />

## Accessibility Considerations

<Notice variant="important" ariaLevel="3">

### Content Considerations: What do content creators need to do?

- Ensure each Dropdown has a descriptive label that accurately describes its purpose.
  - Ensure each Dropdown label is unique to the page.
    - The best practice is to never use the same label for multiple dropdowns that ask for different data on the same page.
  - If there is any specific requirement for the user to make a dropdown menu valid, that requirement must be presented visibly either in the button label or within the helper text.
    - If a Dropdown is required, it must be set as required, have the required red asterisk, and its parent form should have instructions that any item marked with the asterisk is required.
  - When creating error messaging, ensure the message provides enough context so the user can understand the problem and how to fix it. Use clear and concise messaging.
  - If any icons are used to convey meaning in conjunction with a Dropdown, the icon must have an accessible name (alternate content). For example, a help icon next to the dropdown menu.
    - The icon must be intuitive for the functionality it represents.
    - The icon must be named consistently across the product and accurately reflect the purpose of the icon.
    - The icons must be used to consistently represent the same function (do not use multiple icons for the same functionality).
    - The icon must have alternate content that reflects the Dropdown it is related to, or it must be programmatically associated with the button. Work with engineers to add a programmatic association of icons to the button.
  - Any purely decorative icon (does not convey ANY meaning) must be marked as decorative.
  - Consider how a dropdown menu resizes and reflows at different breakpoints and form factors.
    - Convey to engineers how content should resize and reflow.
  - Do not override default Dropdown colors.
    - If colors are changed, all Dropdown content (visible label, required asterisk, helper text, instructions, menu options, and the button itself) must meet color contrast requirements against their respective backgrounds.
- Ensure the engineer understands the logical reading order of the page so they may code the dropdown in to reflect the user’s expectations.
- After coded:
  - Ensure nothing unexpected happens on focus or selection of the Dropdown.
  - Ensure all Dropdowns can receive keyboard focus, have a visible keyboard focus indication when in focus, and can be interacted with and acted upon using only the keyboard.
  - Ensure all Dropdowns receive focus in the user’s logical reading order and that the focus order does not affect the meaning of the content.

### Code Considerations: What do engineers need to do?

- Do not override the implicit or explicit role of the Dropdown.
- Ensure the code order of the Dropdown matches the user’s logical reading order.
  - Ensure that the Dropdown can receive keyboard focus.
  - Do not override the default keyboard focus indicator unless to reverse out of a dark background for perceivability.
  - Do not implement a TABINDEX value of anything greater than zero.
  - Ensure nothing unexpected happens on focus or on select of a Dropdown.
- Work with Content Creators to understand how content should resize and reflow at different breakpoints and form factors to ensure content is not artificially constrained or cut off at smaller viewports.
- Ensure that Dropdown is implemented correctly to ensure that programmatic association is made with all related content (e.g., visible label, helper text, error messaging).

<AccessibilityDropdown />

```jsx
const AccessibilityDropdown = () => {
  const [message, setMessage] = useState('No option clicked');

  return (
    <Card>
      <Card.Body>
        <React.Fragment>
          <DropdownButton
            label="Patient Allergies"
          >
            <Item label="Cats" onSelect={() => setMessage('Clicked Cat allergies')} />
            <Item label="Dogs" onSelect={() => setMessage('Clicked Dogs allergies')} />
            <Item label="Dust" onSelect={() => setMessage('Clicked Dust allergies')} />
            <Item label="Mold" onSelect={() => setMessage('Clicked Mold allergies')} />
            <Item label="Latex" onSelect={() => setMessage('Clicked Latex allergies')} />
          </DropdownButton>
          <p>{message}</p>
        </React.Fragment>
      </Card.Body>
    </Card>
  );
};

```
- Ensure the visible dropdown Label matches any artificially applied programmatic label.
- Do not change the placement of any related content to other areas around the button. For example, do not move the dropdown label creating large gaps between the button and the label.

</Notice>

## Usability Expectations

### Interaction Detail
- The dropdown should be able to receive focus and have an item selected through multiple modalities (e.g., mouse, keyboard, assistive technologies, mobile, and mobile using a screen reader).

### Usability Expectations 
- The user expects to understand the purpose of the Dropdown.
- The user expects to understand the state (Expand or collapse) of Dropdown.
- The user expects to understand any requirements of the Dropdown. For example, is it required, etc.

### Keyboard Expectations

| Key/Sequence | Expectation  |
|---|---|
|*Tab*| Moves forward or backward to any interactive element including Dropdown |
|*Space*| When Dropdown is focused, will open, or close the Dropdown menu depending upon its current state. |
|*Up/Down*| With Dropdown in focus and dropdown menu closed, will open the dropdown. Moves focus up/down the Dropdown list of options.  |
|*Enter*| When the Dropdown is open, Enter selects a dropdown menu option.  |
|*Escape*|  When the Dropdown is open, Escape will close the dropdown. |


## Support Compliance

### How does Terra Action Header support compliance?

Terra is committed to ensuring its components provide the maximum possible accessibility. Terra provides the ability to make accessibility products. However, using Terra components will not automatically make a product accessible.

The final responsibility lies with the consumers of Terra components — ensuring proper usage, any programmatic context where needed, the words used to label elements, engineers following correct implementation patterns, and authors crafting content that follows best practice guidance — to make a product fully accessible.

### Primary accessibility criteria for Action Header
- [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) – Supports
  - Terra Dropdown provides the ability to associate the label, error messaging, and helper text with the dropdown menu.
  - Engineers must ensure the label, helper text, and error messaging are correctly hooked up to the Dropdown. 
  - Content creators must convey any visible relationships of content to the Dropdown to the engineer. 
- [1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG21/Understanding/meaningful-sequence) – Supports
  - Terra Dropdown supports having content read in a meaningful order. 
  - Engineers must ensure that content is coded in the user’s logical order. Engineers must not use a TABINDEX value greater than zero.
  - Creators must ensure the keyboard focus order meets the users expected order and does not affect the meaning of the content.
- [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum)  – Supports
  - Terra Dropdown labels and text meet the required contrast ratios based on the default text and color backgrounds.
  - If colors are changed, engineers and content creators must ensure text colors meet the appropriate contrast ratio based on their font size and the color they appear against. See 1.4.3 Contrast (Minimum) for more information.
- [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) – Supports
  - Terra ensures keyboard accessibility is built into the component.
  - Engineers and Content Creators must ensure all Dropdown menus can be accessed and acted upon using only the keyboard after implementing within the code.
- [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order) – Supports
  - Terra Dropdown can be coded in the user’s logical read order.
  - Engineers must code the dropdown elements to match the user’s logical reading order.
  - Engineers must not add a TABINDEX greater than zero.
  - Content creators must ensure the Dropdown receives focus in the user’s logical reading order.
- [2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels) – Partially Supports
  - Terra Dropdown provides the ability to create unique and descriptive headings and labels.
  - Engineers must implement a meaningful label provided by content creators.
  - Content creators must provide development a label that accurately describes the purpose of the Dropdown.
- [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible) – Supports
  - Terra Dropdown ensures a visible keyboard focus is built into the component.
  - Engineers and Content Creators must ensure all dropdowns have a visible keyboard focus after being implemented within the code.
- [2.5.3 Label in Name](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name) – Supports
  - Terra Dropdown provides the consuming team to have a visible label and a programmatic label.
  - Engineers must ensure the programmatic name matches that of the visible Dropdown label.
- [3.2.1 On Focus](https://www.w3.org/WAI/WCAG21/Understanding/on-focus) – Supports
  - Terra Dropdown does not initiate a change of context on its own.
  - Engineers and Content Creators must ensure nothing unexpected happens on focus of the Dropdown.
- [3.2.2 On Input](https://www.w3.org/WAI/WCAG21/Understanding/on-input) – Supports
  - Terra Dropdown does not initiate a change of context on the selection of the menu or its options.
  - Engineers and content creators must not initiate any change of context on focus of the Dropdown.
- [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG21/Understanding/error-identification) – Supports
  - Terra Dropdown provides the ability to validate a dropdown menu and provide error notifications on the field with error messaging.
  - Engineers must ensure validation is hooked up correctly and the error messaging is appropriately associated with the errant button.
  - Content creators must provide engineers with error messaging for any potential validation error of the button.
- [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions) – Partially Supports 
  - Terra Dropdown provides a label and the ability to have helper text for instructions.
  - Engineers must ensure dropdown menus are coded correctly for helper text or other instructions to be properly associated with the menu. 
  - Content creators must provide engineers with text string for the label and any helper text instructions for users to understand the purpose and requirements of the button clearly.
- [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG21/Understanding/error-suggestion) – Supports
  - Terra Dropdown provides the ability to include error suggestions when forms are validated.
  - When the cause of the error can be known to the system, engineers must ensure validation is hooked up correctly and can provide the appropriate error messaging to the user.
  - Content creators must provide engineers with appropriate error messaging to account for a known invalid entry. If possible, the error messaging must provide guidance to the user on how to correct the issue.
- [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) – Supports
  - Terra Dropdown ensures that the proper role is applied and allows consuming teams to set the appropriate label for the button.
  - Engineers must not overwrite the default role of the Dropdown.
  - Content creators must provide development an appropriate label for the Dropdown.

### Related accessibility criteria that apply when adding content to dropdown menus.
- [1.4.10 Reflow](https://www.w3.org/WAI/WCAG21/Understanding/reflow) – Supports
  - Terra Dropdown can reflow with content by default.
  - Engineers and content creators must ensure their dropdown layouts can reflow without loss of functionality or scrolling in two directions at up to 400% except when used within tables.
- [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG21/Understanding/text-spacing) – Supports
  - Terra Dropdown meets this criterion by default.
  - Engineers and content creators must ensure support for this criterion.
- [1.4.4 Resize text](https://www.w3.org/WAI/WCAG21/Understanding/resize-text) – Supports
  - Terra Dropdown resizes natively.
  - Engineers and content creators must ensure their dropdown layouts allow users to resize text up to 200% without the loss of content or functionality.
- [4.1.1 Parsing](https://www.w3.org/WAI/WCAG21/Understanding/parsing) – Supports
  - Terra Dropdown creates valid HTML code.
  - Engineers must ensure their code is valid.

## Supported Features and Technology 

- Keyboard Interactions
- JAWS Support with Chrome (PC)
- VoiceOver Support with Chrome, Safari (MAC) 
- Speech Input Interactions with assistive technology
- Mobile Touch Interactions with Screen Reader assistive technology

### Partial Support & Requiring Further Enhancement 
- [Report a problem with this component on GitHub](https://github.com/cerner/terra-core/issues/new/choose)

## References:
- [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/WCAG21/Understanding/)
- [WebAim.org: Creating More Accessible Forms](https://webaim.org/techniques/forms/)