diff --git a/.github/COMPONENT-GUIDE.md b/.github/COMPONENT-GUIDE.md index fb9de8eb38..5e54bec125 100644 --- a/.github/COMPONENT-GUIDE.md +++ b/.github/COMPONENT-GUIDE.md @@ -11,6 +11,7 @@ * [References](#references) - [Accessibility](#accessibility) * [Checkbox](#checkbox) + * [Switch](#switch) - [Rendering Anchor or Button](#rendering-anchor-or-button) * [Example Components](#example-components-1) * [Component Structure](#component-structure-1) @@ -371,7 +372,6 @@ ion-ripple-effect { #### Example Components - [ion-checkbox](https://github.com/ionic-team/ionic/tree/master/core/src/components/checkbox) -- [ion-toggle](https://github.com/ionic-team/ionic/tree/master/core/src/components/toggle) #### VoiceOver @@ -432,9 +432,13 @@ const { label, labelId, labelText } = getAriaLabel(el, inputId); where `el` and `inputId` are the following: ```tsx -private inputId = `ion-cb-${checkboxIds++}`; +export class Checkbox implements ComponentInterface { + private inputId = `ion-cb-${checkboxIds++}`; -@Element() el!: HTMLElement; + @Element() el!: HTMLElement; + + ... +} ``` This can then be added to the `Host` like the following: @@ -448,7 +452,7 @@ This can then be added to the `Host` like the following: > ``` -In addition to that, the checkbox should have a label added: +In addition to that, the checkbox input should have a label added: ```tsx + + ... + + ); +} +``` + +#### 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 + + ## Rendering Anchor or Button Certain components can render an `` or a `