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: DAYL-96 Update Count Badge a11y docn #5077

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

feat: DAYL-96 Update Count Badge a11y docn #5077

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1274ae0
Update count-badge docn
ChrisLabattD2L Oct 16, 2024
a2e1ea8
Implement some of Margaree's suggestions
ChrisLabattD2L Oct 16, 2024
1538954
Merge branch 'main' into clabatt/DAYL-96-a11y-docn-count-badge
ChrisLabattD2L Oct 17, 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
65 changes: 28 additions & 37 deletions components/count-badge/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,30 +24,21 @@ The `d2l-count-badge` element is a web component to display a number count, depe
</script>
<d2l-count-badge size="small" type="notification" text="100 new notifications" number="100" has-tooltip tab-stop></d2l-count-badge>
```

### Accessibility Properties
| Attribute | Description |
|---|---|
| `text` | REQUIRED: Only the text will be read by screen-readers (not the number), so include the number in the text. |
| `tab-stop` | A tab stop allows screen-reader users to easily tab to the badge. Otherwise, screen-reader users will need to arrow through to the badge. |
| `announce-changes` | Use "announce-changes" if screen-reader users should be notified that the badge has been updated, such as a new notification. The "text" property will be read as soon as the screen-reader is idle. |
| `has-tooltip` | The tooltip will be visible on hover/tab-stop, and read out by screen-readers. |

<!-- docs: start hidden content -->
### Properties

| Property | Type | Description |
|---|---|---|
| `number` | Number, required | The number to display on the badge. Must be a positive integer. |
| `size`, default: `small` | String | The size of the badge. Valid options are `"small"` and `"large"`. |
| `type`, default: `count` | String | The type of the badge. Valid options are `"notification"` and `"count"`. Notification badges are orange and count badges are grey. |
| `max-digits`, default: `2` when `type="notification"`, `5` when `type="count"` | Number | Optionally specify a digit limit, after which numbers are truncated. Defaults to two for `"notification"` type and five for `"count"` type. Must be between 1-5.
| `hide-zero`, default: `false` | Boolean | Optionally choose not to show the count badge when the number is zero. |
| `text`, required | String | Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled. |
| `tab-stop`, default: `false` | Boolean | Optionally choose to make the badge a tab stop. |
| `announce-changes`, default: `false` | Boolean | Optionally choose to announce changes to the badge with an aria-live region. If the text property is changed, the text will be read by screen-readers. |
| `has-tooltip`, default: `false` | Boolean | Optionally choose to have a tooltip below the badge. |
| `focus-ring`, default: `false` | Boolean | Optionally force a focus ring around the badge. This property can be used to highlight the badge when the parent element is focused. |
| `size` | String, default: `small` | The size of the badge. Valid options are `"small"` and `"large"`. |
| `type` | String, default: `count` | The type of the badge. Valid options are `"notification"` and `"count"`. Notification badges are orange and count badges are grey. |
| `max-digits` | Number, default: `2` when `type="notification"`, `5` when `type="count"` | Specifies a digit limit, after which numbers are truncated. Defaults to two for `"notification"` type and five for `"count"` type. Must be between 1-5.
| `hide-zero` | Boolean, default: `false` | Hides the count badge when `number` is zero. |
| `text` | String, required | Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled. |
| `tab-stop` | Boolean, default: `false` | Adds a tab stop to the badge, which allows screen-reader users to easily tab to the badge. |
| `announce-changes` | Boolean, default: `false` | Announces changes to the badge with an `aria-live` region. If the number property is changed, the text will be read by screenreaders. |
| `has-tooltip` | Boolean, default: `false` | Adds a tooltip on the badge, which will be visible on hover/tab-stop, and read out by screen-readers. |
| `focus-ring` | Boolean, default: `false` | Forces the focus ring around the badge. This property can be used to highlight the badge when the parent element is focused. |
<!-- docs: end hidden content -->

## Count Badge: Icon [d2l-count-badge-icon]
Expand All @@ -62,28 +53,28 @@ The `d2l-count-badge-icon` element is a web component to display a number count,
<d2l-count-badge-icon size="small" icon="tier1:gear" type="notification" text="100 new settings applied." number="100" tab-stop has-tooltip></d2l-count-badge-icon>
```

### Accessibility Properties
| Attribute | Description |
|---|---|
| `text` | REQUIRED: Only the text will be read by screen-readers (not the number), so include the number in the text. |
| `tab-stop` | A tab stop allows screen-reader users to easily tab to the badge. Otherwise, screen-reader users will need to arrow through to the badge. |
| `announce-changes` | Use "announce-changes" if screen-reader users should be notified that the badge has been updated, such as a new notification. The "text" property will be read as soon as the screen-reader is idle. |
| `has-tooltip` | The tooltip will be visible on hover/tab-stop, and read out by screen-readers. |

<!-- docs: start hidden content -->
### Properties

| Property | Type | Description |
|--|--|--|
| `number` | Number | Required: The number to display on the badge. Must be a positive integer. |
| `icon` | String | Required: [Preset icon key](../icons#preset-icons) (e.g. `tier1:gear`) |
| `size`, default: `small` | String | The size of the badge. Valid options are `"small"` and `"large"`. |
| `type`, default: `count` | String | The type of the badge. Valid options are `"notification"` and `"count"`. Notification badges are orange and count badges are grey. |
| `max-digits`, default: `2` when `type="notification"`, `5` when `type="count"` | Number | Optionally specify a digit limit, after which numbers are truncated. Defaults to two for `"notification"` type and five for `"count"` type. Must be between 1-5.
| `hide-zero`, default: `false` | Boolean | Optionally choose not to show the count badge when the number is zero. |
| `text` | String | REQUIRED: Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled. |
| `tab-stop`, default: `false` | Boolean | Optionally choose to make the badge a tab stop. |
| `announce-changes`, default: `false` | Boolean | Optionally choose to announce changes to the badge with an aria-live region. If the text property is changed, the text will be read by screen-readers. |
| `has-tooltip`, default: `false` | Boolean | Optionally choose to have a tooltip below the badge. |
| `focus-ring`, default: `false` | Boolean | Optionally force a focus ring around the badge. This property can be used to highlight the badge when the parent element is focused. |
| `number` | Number, required | The number to display on the badge. Must be a positive integer. |
| `icon` | String, required | [Preset icon key](../icons#preset-icons) (e.g. `tier1:gear`) |
| `size` | String, default: `small` | The size of the badge. Valid options are `"small"` and `"large"`. |
| `type` | String, default: `count` | The type of the badge. Valid options are `"notification"` and `"count"`. Notification badges are orange and count badges are grey. |
| `max-digits` | Number, default: `2` when `type="notification"`, `5` when `type="count"` | Specifies a digit limit, after which numbers are truncated. Defaults to two for `"notification"` type and five for `"count"` type. Must be between 1-5.
| `hide-zero` | Boolean, default: `false` | Hides the count badge when `number` is zero. |
| `text` | String, required | Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled. |
| `tab-stop` | Boolean, default: `false` | Adds a tab stop to the badge, which allows screen-reader users to easily tab to the badge. |
| `announce-changes` | Boolean, default: `false` | Announces changes to the badge with an `aria-live` region. If the number property is changed, the text will be read by screenreaders. |
| `has-tooltip` | Boolean, default: `false` | Adds a tooltip on the badge, which will be visible on hover/tab-stop, and read out by screen-readers. |
| `focus-ring` | Boolean, default: `false` | Forces a focus ring around the badge. This property can be used to highlight the badge when the parent element is focused. |
<!-- docs: end hidden content -->

## Accessibility

- While non-interactable components traditionally shouldn't be focusable, the `tab-stop` property greatly helps screen-reader users find the the count badge
- Otherwise, screen-reader users would have to use the arrow keys to get to the badge, which can take considerably longer
- If the optional tooltip is used, then `tab-stop` isn't necessary, as the count-badge becomes focusable to render the tooltip
- The optional tooltip makes use of the [`d2l-toolip`](../../components/tooltip), which follows the [W3C best practices for Tooltips](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
- The use of this tooltip can help provide additional context such as providing the exact number, if it were to go above the limit set in `max-digits`
Comment on lines +76 to +80
Copy link
Contributor

Choose a reason for hiding this comment

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

Just trying to make it a bit more clear, though probably needs @geurts input on wording

Suggested change
- While non-interactable components traditionally shouldn't be focusable, the `tab-stop` property greatly helps screen-reader users find the the count badge
- Otherwise, screen-reader users would have to use the arrow keys to get to the badge, which can take considerably longer
- If the optional tooltip is used, then `tab-stop` isn't necessary, as the count-badge becomes focusable to render the tooltip
- The optional tooltip makes use of the [`d2l-toolip`](../../components/tooltip), which follows the [W3C best practices for Tooltips](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
- The use of this tooltip can help provide additional context such as providing the exact number, if it were to go above the limit set in `max-digits`
Notable accessibility features:
- `tab-stop`:
- While non-interactable components traditionally shouldn't be focusable, this property greatly helps screen reader users find the the count badge, and removes the need to use the arrow keys to navigate to it.
- If the optional tooltip is used, it isn't necessary, as the count-badge becomes focusable in order to display the tooltip
- `has-tooltip`:
- The optional tooltip makes use of the [`d2l-tooltip`](../../components/tooltip), which follows the [W3C best practices for Tooltips](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
- This tooltip can help provide additional context, such as by providing the exact count badge number if it were to go above the limit set in `max-digits`

Copy link
Contributor Author

Choose a reason for hiding this comment

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

While I do like some of the changes, I'm not sure about the formatting, so I'd also likely to hear Jeff's input

Copy link
Contributor

Choose a reason for hiding this comment

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

Totally fair!

18 changes: 9 additions & 9 deletions components/count-badge/count-badge-mixin.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ export const CountBadgeMixin = superclass => class extends LocalizeCoreElement(S
static get properties() {
return {
/**
* Optionally choose to announce changes to the badge with an aria-live region. If the number property is changed, the text will be read by screenreaders. Defaults to false.
* ACCESSIBILITY: Announces changes to the badge with an `aria-live` region. If the number property is changed, the text will be read by screenreaders.
ChrisLabattD2L marked this conversation as resolved.
Show resolved Hide resolved
* @type {boolean}
*/
announceChanges: {
type: Boolean,
attribute: 'announce-changes'
},
/**
* Optionally choose to force the focus ring around the badge. Defaults to false.
* Forces the focus ring around the badge.
ChrisLabattD2L marked this conversation as resolved.
Show resolved Hide resolved
* @type {boolean}
*/
forceFocusRing: {
Expand All @@ -33,23 +33,23 @@ export const CountBadgeMixin = superclass => class extends LocalizeCoreElement(S
reflect: true
},
/**
* Optionally add a tooltip on the badge. Defaults to false.
* ACCESSIBILITY: Adds a tooltip on the badge, which will be visible on hover/tab-stop, and read out by screen-readers.
ChrisLabattD2L marked this conversation as resolved.
Show resolved Hide resolved
* @type {boolean}
*/
hasTooltip: {
type: Boolean,
attribute: 'has-tooltip'
},
/**
* Optionally choose to not render the count badge when the number is zero. Defaults to false.
* Hides the count badge when `number` is zero.
* @type {boolean}
*/
hideZero: {
type: Boolean,
attribute: 'hide-zero'
},
/**
* Optionally specify a digit limit, after which numbers are truncated.
* Specifies a digit limit, after which numbers are truncated.
* Defaults to two for "notification" type and five for "count" type.
* @type {number}
*/
Expand All @@ -66,7 +66,7 @@ export const CountBadgeMixin = superclass => class extends LocalizeCoreElement(S
attribute: 'number'
},
/**
* The size of the badge. Defaults to "small".
* The size of the badge.
* @type {'small'|'large'}
*/
size: {
Expand All @@ -75,22 +75,22 @@ export const CountBadgeMixin = superclass => class extends LocalizeCoreElement(S
attribute: 'size'
},
/**
* Optionally choose to add a tab stop to the badge. Defaults to false.
* ACCESSIBILITY: Adds a tab stop to the badge, which allows screen-reader users to easily tab to the badge.
ChrisLabattD2L marked this conversation as resolved.
Show resolved Hide resolved
* @type {boolean}
*/
tabStop: {
type: Boolean,
attribute: 'tab-stop'
},
/**
* REQUIRED: Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled.
* ACCESSIBILITY: REQUIRED: Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled.
* @type {string}
*/
text: {
type: String
},
/**
* The type of the badge. Defaults to "count".
* The type of the badge.
* @type {'count'|'notification'}
*/
type: {
Expand Down
Loading