Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ariperkkio/aria-live-capture
Capture announcements of ARIA live regions
https://github.com/ariperkkio/aria-live-capture
a11y accessibility aria-live developer-experience testing
Last synced: 17 days ago
JSON representation
Capture announcements of ARIA live regions
- Host: GitHub
- URL: https://github.com/ariperkkio/aria-live-capture
- Owner: AriPerkkio
- Created: 2021-06-19T09:39:08.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-06-10T06:45:46.000Z (5 months ago)
- Last Synced: 2024-06-11T17:34:56.398Z (5 months ago)
- Topics: a11y, accessibility, aria-live, developer-experience, testing
- Language: TypeScript
- Homepage: https://ariperkkio.github.io/aria-live-capture/
- Size: 58.6 MB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# aria-live-capture
[Installation](#installation) | [Usage](#usage) | [Announcement detection examples](#announcement-detection-examples) | [Support](#support)
> Capture announcements of [ARIA live regions](https://www.w3.org/TR/wai-aria-1.2/#dfn-live-region).
`aria-live-capture` is an utility tool for inspecting announcements of ARIA live regions.
When developing an application which utilizes ARIA live announcements it is often frustrating to toggle screen readers and other assistive technologies constantly on/off during development.
This tool aims to help developers easily see announcements without having to use actual screen readers.
However final assertion should always be made with the actual target assistive technology.
For online demo see [Storybook playground](https://ariperkkio.github.io/aria-live-capture).
For validating ARIA live regions in tests see [`extend-to-be-announced`](https://github.com/AriPerkkio/extend-to-be-announced).
For Storybook integration see [`storybook-addon-aria-live`](https://github.com/AriPerkkio/storybook-addon-aria-live).
## Installation
`aria-live-capture` should be included in development dependencies.
```bash
npm install --save-dev aria-live-capture
```
## Usage
Import `CaptureAnnouncements` from entrypoint.
```ts
import CaptureAnnouncements from 'aria-live-capture';
```
### onCapture
Pass `onCapture` callback to handle announcements.
| Callback argument | type | value |
| :---------------: | :------: | -------------------------------- |
| announcement | `string` | Text content of the announcement |
| politenessSetting | `string` | `polite\|assertive` |
```ts
CaptureAnnouncements({
onCapture: (announcement, politenessSetting) => {
console.log(`"${announcement}" was announced with politeness setting "${politenessSetting}"`);
},
});
```
```
"Loading" was announced with politeness setting "polite"
"Failed to load user details" was announced with politeness setting "assertive"
```
### includeShadowDom
Pass an optional boolean `includeShadowDom` option to include tracking of live regions in Shadow DOM.
Default value is `false`.
```ts
CaptureAnnouncements({
includeShadowDom: true,
});
```
### cleanup
The `CaptureAnnouncements` method returns `cleanup` function for clearing DOM interceptors.
```ts
const cleanup = CaptureAnnouncements(options);
cleanup();
```
## Announcement detection examples
[Test online](https://ariperkkio.github.io/aria-live-capture) 
```html
Render#1 |
Render#2 | Loading
PASS ✅ | "Loading" is announced
```
```html
Render#1 |
Render#2 | Loading
PASS ✅ | "Loading" is announced
```
```html
Render#1 |
Render#2 | Loading
PASS ✅ | "Loading" is announced
```
```html
Render#1 |
Render#2 | Loading
PASS ✅ | "Loading" is announced
```
```html
Render#1 |
Loading
FAIL ❌ | "Loading" is not announced
```
```html
Render#1 |
Render#2 | Loading
FAIL ❌ | "Loading" is not announced
```
```html
Render#1 |
Render#2 | Loading
FAIL ❌ | "Loading" is not announced
```
```html
Render#1 |
Error
PASS ✅ | "Error" is announced
```
```html
Render#1 |
Error
FAIL ❌ | "Error" is not announced
```
```html
Render#1 |
Render#2 | Error
PASS ✅ | "Error" is announced
```
```html
Render#1 |
| Loading
|
|
Render#2 |
| Loading
|
|
PASS ✅ | "Loading" is announced
```
```html
Render#1 |
Loading
Render#2 | Loading
FAIL ❌ | "Loading" is not announced
```
With option `{ includeShadowDom: true }`:
```html
Render#1 |
| #shadow-root
|
|
|
Render#2 |
| #shadow-root
| Loading
|
|
PASS ✅ | "Loading" is announced
```
## Support
| Feature | Status |
| :-------------: | :----: |
| `role` | ✅ |
| `aria-live` | ✅ |
| `aria-atomic` | ❌ 👷 |
| `aria-busy` | ❌ |
| `aria-relevant` | ❌ |