Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: [a11y docs] DAYL-93 Input Checkbox a11y docn #4977

Merged
merged 3 commits into from
Sep 24, 2024
Merged

feat: [a11y docs] DAYL-93 Input Checkbox a11y docn #4977

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dcdda37
Update Input Checkbox docn
ChrisLabattD2L Sep 16, 2024
99b810d
Apply Margaree's suggestions
ChrisLabattD2L Sep 18, 2024
dcd461c
Apply Jeff's suggestions
ChrisLabattD2L Sep 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 10 additions & 12 deletions components/inputs/docs/input-checkbox.md
View file
Open in desktop
ChrisLabattD2L marked this conversation as resolved.
Show resolved Hide resolved
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 | Use when text in `Default` slot in checkbox does not provide enough context |
ChrisLabattD2L marked this conversation as resolved.
Show resolved Hide resolved
| `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 instead of the `Enter` key
ChrisLabattD2L marked this conversation as resolved.
Show resolved Hide resolved
- 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
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In addition to adding " for screen reader users" to the aria-label property, I'm wondering how we can clarify when to use aria-label vs the description property? There's no guidance on this, so we should either make it clear in the property descriptions or in a special note in the Accessibility section 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The more I think about it, the more I think what I wrote for aria-label is wrong, or at least the does not provide enough context part, since the providing more context is the responsibility of the description, not the label.

I'm thinking of changing it to: Use to override the text in the Default slot for screenreader users

What do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not actually sure why we offer this. It might be helpful to find cases where it's used, to see if there are any clues as to why we introduced it?

Otherwise the "why" can just be left out, like you suggested. I would just start with "Overrides the text..." though for simplicity.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I seem to recall us having this type of discussion in one of our meetings, I think the end result was we'd leave it in for now, but would talk with Gaudi about it to see if it was something that could just get removed, or changed to just being label

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated it, but am going to leave this thread unresolved in case others wanted to weigh in on this topic

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: Use when text in `Default` slot in checkbox does not provide enough context
* @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
Loading