{"id":16739358,"url":"https://github.com/ariperkkio/aria-live-capture","last_synced_at":"2025-03-21T22:31:32.190Z","repository":{"id":37014197,"uuid":"378375653","full_name":"AriPerkkio/aria-live-capture","owner":"AriPerkkio","description":"Capture announcements of ARIA live regions","archived":false,"fork":false,"pushed_at":"2025-03-15T06:12:05.000Z","size":73167,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-15T22:39:38.022Z","etag":null,"topics":["a11y","accessibility","aria-live","developer-experience","testing"],"latest_commit_sha":null,"homepage":"https://ariperkkio.github.io/aria-live-capture/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AriPerkkio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-19T09:39:08.000Z","updated_at":"2025-03-10T08:16:47.000Z","dependencies_parsed_at":"2023-10-16T16:48:02.400Z","dependency_job_id":"bcf1a0f3-6bed-4d02-8b90-dd2a1bcb4c1e","html_url":"https://github.com/AriPerkkio/aria-live-capture","commit_stats":{"total_commits":301,"total_committers":3,"mean_commits":"100.33333333333333","dds":0.4717607973421927,"last_synced_commit":"cf8306c62da292923130c1c94b04169bfe12e17a"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AriPerkkio%2Faria-live-capture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AriPerkkio%2Faria-live-capture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AriPerkkio%2Faria-live-capture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AriPerkkio%2Faria-live-capture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AriPerkkio","download_url":"https://codeload.github.com/AriPerkkio/aria-live-capture/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244880187,"owners_count":20525505,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a11y","accessibility","aria-live","developer-experience","testing"],"created_at":"2024-10-13T00:50:31.010Z","updated_at":"2025-03-21T22:31:31.866Z","avatar_url":"https://github.com/AriPerkkio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aria-live-capture\n\n\u003ca href=\"https://www.npmjs.com/package/aria-live-capture\"\u003e\n    \u003cimg alt=\"version\" src=\"https://img.shields.io/npm/v/aria-live-capture\" /\u003e\n\u003c/a\u003e\n\n[Installation](#installation) | [Usage](#usage) | [Announcement detection examples](#announcement-detection-examples) | [Support](#support)\n\n\u003e Capture announcements of [ARIA live regions](https://www.w3.org/TR/wai-aria-1.2/#dfn-live-region).\n\n`aria-live-capture` is an utility tool for inspecting announcements of ARIA live regions.\nWhen 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.\nThis tool aims to help developers easily see announcements without having to use actual screen readers.\nHowever final assertion should always be made with the actual target assistive technology.\n\nFor online demo see [Storybook playground](https://ariperkkio.github.io/aria-live-capture).\n\nFor validating ARIA live regions in tests see [`extend-to-be-announced`](https://github.com/AriPerkkio/extend-to-be-announced).\n\nFor Storybook integration see [`storybook-addon-aria-live`](https://github.com/AriPerkkio/storybook-addon-aria-live).\n\n## Installation\n\n`aria-live-capture` should be included in development dependencies.\n\n```bash\nnpm install --save-dev aria-live-capture\n```\n\n## Usage\n\nImport `CaptureAnnouncements` from entrypoint.\n\n```ts\nimport CaptureAnnouncements from 'aria-live-capture';\n```\n\n### onCapture\n\nPass `onCapture` callback to handle announcements.\n\n| Callback argument |   type   | value                            |\n| :---------------: | :------: | -------------------------------- |\n|   announcement    | `string` | Text content of the announcement |\n| politenessSetting | `string` | `polite\\|assertive`              |\n\n\u003c!-- prettier-ignore --\u003e\n```ts\nCaptureAnnouncements({\n    onCapture: (announcement, politenessSetting) =\u003e {\n        console.log(`\"${announcement}\" was announced with politeness setting \"${politenessSetting}\"`);\n    },\n});\n```\n\n```\n\"Loading\" was announced with politeness setting \"polite\"\n\"Failed to load user details\" was announced with politeness setting \"assertive\"\n```\n\n### includeShadowDom\n\nPass an optional boolean `includeShadowDom` option to include tracking of live regions in Shadow DOM.\nDefault value is `false`.\n\n```ts\nCaptureAnnouncements({\n    includeShadowDom: true,\n});\n```\n\n### cleanup\n\nThe `CaptureAnnouncements` method returns `cleanup` function for clearing DOM interceptors.\n\n```ts\nconst cleanup = CaptureAnnouncements(options);\n\ncleanup();\n```\n\n## Announcement detection examples\n\n[Test online](https://ariperkkio.github.io/aria-live-capture)\u0026nbsp;\u0026nbsp;\u003ca href=\"https://ariperkkio.github.io/aria-live-capture\" target=\"_blank\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/storybooks/brand/master/badge/badge-storybook.svg\" /\u003e\u003c/a\u003e\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv role=\"status\"\u003e\u003c/div\u003e\nRender#2 | \u003cdiv role=\"status\"\u003eLoading\u003c/div\u003e\nPASS ✅  | \"Loading\" is announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv aria-live=\"polite\"\u003e\u003c/div\u003e\nRender#2 | \u003cdiv aria-live=\"polite\"\u003eLoading\u003c/div\u003e\nPASS ✅  | \"Loading\" is announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv role=\"log\"\u003e\u003c/div\u003e\nRender#2 | \u003cdiv role=\"log\"\u003eLoading\u003c/div\u003e\nPASS ✅  | \"Loading\" is announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003coutput\u003e\u003c/output\u003e\nRender#2 | \u003coutput\u003eLoading\u003c/output\u003e\nPASS ✅  | \"Loading\" is announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv role=\"status\"\u003eLoading\u003c/div\u003e\nFAIL ❌  | \"Loading\" is not announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv\u003e\u003c/div\u003e\nRender#2 | \u003cdiv role=\"status\"\u003eLoading\u003c/div\u003e\nFAIL ❌  | \"Loading\" is not announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv\u003e\u003c/div\u003e\nRender#2 | \u003cdiv aria-live=\"polite\"\u003eLoading\u003c/div\u003e\nFAIL ❌  | \"Loading\" is not announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv role=\"alert\"\u003eError\u003c/div\u003e\nPASS ✅  | \"Error\" is announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv aria-live=\"assertive\"\u003eError\u003c/div\u003e\nFAIL ❌  | \"Error\" is not announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv\u003e\u003c/div\u003e\nRender#2 | \u003cdiv role=\"alert\"\u003eError\u003c/div\u003e\nPASS ✅  | \"Error\" is announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv role=\"status\"\u003e\n         |     \u003cdiv aria-hidden=\"true\"\u003eLoading\u003c/div\u003e\n         | \u003c/div\u003e\n         |\nRender#2 | \u003cdiv role=\"status\"\u003e\n         |     \u003cdiv aria-hidden=\"false\"\u003eLoading\u003c/div\u003e\n         | \u003c/div\u003e\n         |\nPASS ✅  | \"Loading\" is announced\n```\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv role=\"status\" aria-hidden=\"true\"\u003eLoading\u003c/div\u003e\nRender#2 | \u003cdiv role=\"status\" aria-hidden=\"false\"\u003eLoading\u003c/div\u003e\nFAIL ❌  | \"Loading\" is not announced\n```\n\nWith option `{ includeShadowDom: true }`:\n\n\u003c!-- prettier-ignore --\u003e\n```html\nRender#1 | \u003cdiv role=\"status\"\u003e\n         |     #shadow-root\n         |     \u003cdiv\u003e\u003c/div\u003e\n         | \u003c/div\u003e\n         |\nRender#2 | \u003cdiv role=\"status\"\u003e\n         |     #shadow-root\n         |     \u003cdiv\u003eLoading\u003c/div\u003e\n         | \u003c/div\u003e\n         |\nPASS ✅  | \"Loading\" is announced\n```\n\n## Support\n\n|     Feature     | Status |\n| :-------------: | :----: |\n|     `role`      |   ✅   |\n|   `aria-live`   |   ✅   |\n|  `aria-atomic`  | ❌ 👷  |\n|   `aria-busy`   |   ❌   |\n| `aria-relevant` |   ❌   |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fariperkkio%2Faria-live-capture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fariperkkio%2Faria-live-capture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fariperkkio%2Faria-live-capture/lists"}