diff --git a/Accessibility.md b/Accessibility.md new file mode 100644 index 0000000..f6959ed --- /dev/null +++ b/Accessibility.md @@ -0,0 +1,257 @@ +## Accessibility + +### Checkbox + +#### Example Components + +- [ion-checkbox](https://github.com/ionic-team/ionic/tree/master/core/src/components/checkbox) + +#### VoiceOver + +In order for VoiceOver to work properly with a checkbox component there must be a native `input` with `type="checkbox"`, and `aria-checked` and `role="checkbox"` **must** be on the host element. The `aria-hidden` attribute needs to be added if the checkbox is disabled, preventing iOS users from selecting it: + +```tsx +render() { + const { checked, disabled } = this; + + return ( + + + ... + + ); +} +``` + +#### NVDA + +It is required to have `aria-checked` on the native input for checked to read properly and `disabled` to prevent tabbing to the input: + +```tsx +render() { + const { checked, disabled } = this; + + return ( + + + ... + + ); +} +``` + +#### Labels + +A helper function has been created to get the proper `aria-label` for the checkbox. This can be imported as `getAriaLabel` like the following: + +```tsx +const { label, labelId, labelText } = getAriaLabel(el, inputId); +``` + +where `el` and `inputId` are the following: + +```tsx +export class Checkbox implements ComponentInterface { + private inputId = `ion-cb-${checkboxIds++}`; + + @Element() el!: HTMLElement; + + ... +} +``` + +This can then be added to the `Host` like the following: + +```tsx + +``` + +In addition to that, the checkbox input should have a label added: + +```tsx + + + +``` + +#### Hidden Input + +A helper function to render a hidden input has been added, it can be added in the `render`: + +```tsx +renderHiddenInput(true, el, name, (checked ? value : ''), disabled); +``` + +> This is required for the checkbox to work with forms. + +#### Known Issues + +When using VoiceOver on macOS, Chrome will announce the following when you are focused on a checkbox: + +``` +currently on a checkbox inside of a checkbox +``` + +This is a compromise we have to make in order for it to work with the other screen readers & Safari. + + +### Switch + +#### Example Components + +- [ion-toggle](https://github.com/ionic-team/ionic/tree/master/core/src/components/toggle) + +#### Voiceover + +In order for VoiceOver to work properly with a switch component there must be a native `input` with `type="checkbox"` and `role="switch"`, and `aria-checked` and `role="switch"` **must** be on the host element. The `aria-hidden` attribute needs to be added if the switch is disabled, preventing iOS users from selecting it: + +```tsx +render() { + const { checked, disabled } = this; + + return ( + + + ... + + ); +} +``` + +#### NVDA + +It is required to have `aria-checked` on the native input for checked to read properly and `disabled` to prevent tabbing to the input: + +```tsx +render() { + const { checked, disabled } = this; + + return ( + + + ... + + ); +} +``` + +#### Labels + +A helper function has been created to get the proper `aria-label` for the switch. This can be imported as `getAriaLabel` like the following: + +```tsx +const { label, labelId, labelText } = getAriaLabel(el, inputId); +``` + +where `el` and `inputId` are the following: + +```tsx +export class Toggle implements ComponentInterface { + private inputId = `ion-tg-${toggleIds++}`; + + @Element() el!: HTMLElement; + + ... +} +``` + +This can then be added to the `Host` like the following: + +```tsx + +``` + +In addition to that, the checkbox input should have a label added: + +```tsx + + + +``` + + +#### Hidden Input + +A helper function to render a hidden input has been added, it can be added in the `render`: + +```tsx +renderHiddenInput(true, el, name, (checked ? value : ''), disabled); +``` + +> This is required for the switch to work with forms. + + +#### Known Issues + +When using VoiceOver on macOS or iOS, Chrome will announce the switch as a checked or unchecked `checkbox`: + +``` +You are currently on a switch. To select or deselect this checkbox, press Control-Option-Space. +``` + +There is a WebKit bug open for this: https://bugs.webkit.org/show_bug.cgi?id=196354 \ No newline at end of file