Nutritious Pumpkin Meal

    aria-live-capture
    TypeScript icon, indicating that this package has built-in type declarations

    0.5.1 • Public • Published

    aria-live-capture

    version

    Installation | Usage | Announcement detection examples | Support

    Capture announcements of ARIA live regions.

    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.

    For validating ARIA live regions in tests see extend-to-be-announced.

    For Storybook integration see storybook-addon-aria-live.

    Installation

    aria-live-capture should be included in development dependencies.

    yarn add --dev aria-live-capture

    Usage

    Import CaptureAnnouncements from entrypoint.

    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
    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.

    CaptureAnnouncements({
        includeShadowDom: true,
    });

    cleanup

    The CaptureAnnouncements method returns cleanup function for clearing DOM interceptors.

    const cleanup = CaptureAnnouncements(options);
    
    cleanup();

    Announcement detection examples

    Test online

    Render#1 | <div role="status"></div>
    Render#2 | <div role="status">Loading</div>
    PASS ✅  | "Loading" is announced
    Render#1 | <div aria-live="polite"></div>
    Render#2 | <div aria-live="polite">Loading</div>
    PASS ✅  | "Loading" is announced
    Render#1 | <div role="log"></div>
    Render#2 | <div role="log">Loading</div>
    PASS ✅  | "Loading" is announced
    Render#1 | <output></output>
    Render#2 | <output>Loading</output>
    PASS ✅  | "Loading" is announced
    Render#1 | <div role="status">Loading</div>
    FAIL ❌  | "Loading" is not announced
    Render#1 | <div></div>
    Render#2 | <div role="status">Loading</div>
    FAIL ❌  | "Loading" is not announced
    Render#1 | <div></div>
    Render#2 | <div aria-live="polite">Loading</div>
    FAIL ❌  | "Loading" is not announced
    Render#1 | <div role="alert">Error</div>
    PASS ✅  | "Error" is announced
    Render#1 | <div aria-live="assertive">Error</div>
    FAIL ❌  | "Error" is not announced
    Render#1 | <div></div>
    Render#2 | <div role="alert">Error</div>
    PASS ✅  | "Error" is announced
    Render#1 | <div role="status">
             |     <div aria-hidden="true">Loading</div>
             | </div>
             |
    Render#2 | <div role="status">
             |     <div aria-hidden="false">Loading</div>
             | </div>
             |
    PASS ✅  | "Loading" is announced
    Render#1 | <div role="status" aria-hidden="true">Loading</div>
    Render#2 | <div role="status" aria-hidden="false">Loading</div>
    FAIL ❌  | "Loading" is not announced

    With option { includeShadowDom: true }:

    Render#1 | <div role="status">
             |     #shadow-root
             |     <div></div>
             | </div>
             |
    Render#2 | <div role="status">
             |     #shadow-root
             |     <div>Loading</div>
             | </div>
             |
    PASS ✅  | "Loading" is announced

    Support

    Feature Status
    role
    aria-live
    aria-atomic 👷
    aria-busy
    aria-relevant

    Install

    npm i aria-live-capture

    DownloadsWeekly Downloads

    3

    Version

    0.5.1

    License

    MIT

    Unpacked Size

    36.3 kB

    Total Files

    23

    Last publish

    Collaborators

    • ariperkkio