import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
import {AriaLiveRegion} from '@workday/canvas-kit-react/common';
import FilterListWithLiveStatus from './examples/AriaLiveRegions/FilterListWithLiveStatus';
import VisibleLiveRegion from './examples/AriaLiveRegions/VisibleLiveRegion';
import HiddenLiveRegion from './examples/AriaLiveRegions/HiddenLiveRegion';
import CommentBoxWithCharLimit from './examples/AriaLiveRegions/CommentBoxWithCharLimit';


# ARIA Live Regions

These examples are provided to demonstrate a variety of different use cases for the `AriaLiveRegion`
component. For the full experience, get started by first turning on your favorite screen reading
software. On Windows, we recommend the open source
[NVDA (Non-Visual Desktop Access)](https://www.nvaccess.org/download/) software, or
[JAWS (Job Access With Speech)](https://support.freedomscientific.com/Downloads/JAWS) if you have
purchased a license. MacOS and iOS include VoiceOver, which can be turned on in your settings.

Live regions work by designating specific DOM nodes for screen readers to monitor for any content
updates inside the node. When an update occurs, screen readers will announce the update to users in
real time, based on a few rules:

1. `polite` will “politely” wait for users to finish what they are doing before announcing an update
2. `assertive` will interrupt what users are doing (or reading) by immediately announcing an update

### CAUTION: Don't get carried away

Key things to understand about live regions:

1. A live region update will only be announced once. Users are unable to repeat them or re-examine
   them if the announcement was not understood.
2. Users may be able to pause a live region announcement, but they cannot prevent a live region
   announcement from occurring. Sending frequent, repetitive, or simply too much information to a
   live region can be very disruptive to users.
3. Users cannot act on, or navigate to, a live region. Live regions must only contain plain text.
   (No images, links, buttons, or other input.)
4. Support for live regions is limited across platforms, browsers, and screen reader software. Real
   time announcements may not be perfectly reliable.

## Visible Live Regions

Live regions can be applied to dynamic text on the UI. When the dynamic text is updated, screen
readers can describe the text update in live time as it occurs. In the example below, type text into
the input field and activate the "Send Message" button. Listen and observe the screen reader
automatically announce the text update.

<ExampleCodeBlock code={VisibleLiveRegion} />

## Hidden Live Regions

Live regions don't need to be visible UI text, they can be used to assist the non-visual listening
experience when moving the keyboard focus to a new element on screen isn't feasible.

<ExampleCodeBlock code={HiddenLiveRegion} />

## Filtering lists with a live status

In this example, a live region is applied to a short UI text describing the number of items shown in
the list. As you type characters into the input, listen for the screen reader to automatically
describe how many items in the list are shown.

<ExampleCodeBlock code={FilterListWithLiveStatus} />

## Debouncing an `AriaLiveRegion`: `TextArea` with character limit

Using a live region to announce the character count of a text area can help screen reader users
track their progress. However, announcing on every keystroke would be extremely disruptive—imagine
hearing "5 of 200 characters... 6 of 200 characters... 7 of 200 characters" for each letter typed!
In this example, we've implemented debouncing to wait 2 seconds after the user stops typing before
announcing the count.

**Note:** Turn on a screen reader for this experience.

- Used the `as={AccessibleHide}` prop to hide the live region from view with CSS
- The live region will only update when a 2 second timer expires after the last keystroke
- If users have reached the maximum number of characters, the live region will update immediately to
  inform users that they have reached the limit
- The live region will be cleared on blur events when users leave the field

<ExampleCodeBlock code={CommentBoxWithCharLimit} />