Skip to content

Commit

Permalink
feat: [a11y docs] DAYL-93 Input Checkbox a11y docn (#4977)
Browse files Browse the repository at this point in the history
* Update Input Checkbox docn

* Apply Margaree's suggestions

* Apply Jeff's suggestions
  • Loading branch information
ChrisLabattD2L authored Sep 24, 2024
1 parent 34c6ee9 commit 533baf9
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 15 deletions.
22 changes: 10 additions & 12 deletions components/inputs/docs/input-checkbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,13 @@ The `<d2l-input-checkbox>` element can be used to get a checkbox and optional vi

| Property | Type | Description |
|---|---|---|
| `aria-label` | String | Set instead of placing label inside to hide the visible label |
| `aria-label` | String | Overrides the text in the `Default` slot for screenreader users |
| `checked` | Boolean | Checked state |
| `description` | String | A description to be added to the `input` for accessibility |
| `description` | String | Additional information communicated to screenreader users when focusing on the input |
| `disabled` | Boolean | Disables the input |
| `indeterminate` | Boolean | Sets checkbox to an indeterminate state |
| `name` | String | Name of the input |
| `not-tabbable` | Boolean | Sets `tabindex="-1"` on the checkbox |
| `not-tabbable` | Boolean | Sets `tabindex="-1"` on the checkbox. Note that an alternative method of focusing is necessary to implement if using this property. |
| `value` | String | Value of the input |

### Events
Expand All @@ -75,18 +75,10 @@ checkbox.addEventListener('change', (e) => {

### Slots

* `default`: Primary text that will appear next to the input box and function as the label for the checkbox.
* `inline-help`: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
<!-- docs: end hidden content -->

### Accessibility Properties

To make your usage of `d2l-input-checkbox` accessible, use the following properties when applicable:

| Attribute | Description |
|---|---|
| `aria-label` | Use when text on checkbox does not provide enough context |
| `description` | Use when label on input does not provide enough context. |

### Methods

- `simulateClick()`: useful for testing, it simulates the user clicking on the checkbox, which toggles the state of the checkbox and fires the `change` event
Expand Down Expand Up @@ -135,3 +127,9 @@ As an alternative to using the `<d2l-input-checkbox>` custom element, you can st
</script>
<d2l-my-checkbox-elem></d2l-my-checkbox-elem>
```

## Accessibility

The `d2l-input-checkbox` component follows W3C's best practice recommendations for a [checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/). This means that the component works in the following way:
- The `Space` key is used to select a focused checkbox (not the `Enter` key)
- The `aria-checked` state is set to `true`, `false` or `mixed` to represent if it's selected, unselected, or partially selected
6 changes: 3 additions & 3 deletions components/inputs/input-checkbox.js
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ class InputCheckbox extends InputInlineHelpMixin(FocusMixin(SkeletonMixin(RtlMix
static get properties() {
return {
/**
* Use when text on checkbox does not provide enough context
* ACCESSIBILITY: Overrides the text in the `Default` slot for screenreader users
* @type {string}
*/
ariaLabel: { type: String, attribute: 'aria-label' },
Expand All @@ -79,7 +79,7 @@ class InputCheckbox extends InputInlineHelpMixin(FocusMixin(SkeletonMixin(RtlMix
*/
checked: { type: Boolean },
/**
* Additional information communicated in the aria-describedby on the input
* ACCESSIBILITY: Additional information communicated to screenreader users when focusing on the input
* @type {string}
*/
description: { type: String },
Expand All @@ -99,7 +99,7 @@ class InputCheckbox extends InputInlineHelpMixin(FocusMixin(SkeletonMixin(RtlMix
*/
name: { type: String },
/**
* Sets "tabindex="-1"" on the checkbox
* ACCESSIBILITY: ADVANCED: Sets "tabindex="-1"" on the checkbox. Note that an alternative method of focusing is necessary to implement if using this property.
* @type {boolean}
*/
notTabbable: { type: Boolean, attribute: 'not-tabbable' },
Expand Down

0 comments on commit 533baf9

Please sign in to comment.