Converge suggested actions into live region twin and add roving tab index

[compulim]

Fixes #4293. Fixes #4296.

Changelog Entry

Fixed

• Fixes #4293 and #4296. Fixed accessibility issues for suggested actions, by @compulim, in PR #4314
  • Centralized live region of suggested actions into chat history live region for better live region control
  • Suggested actions container is now a role="toolbar" and uses roving tab index for multiple suggested action

Description

We have multiple live regions in Web Chat. Since browser isn't great at handling multiple of them with simultaneously updates. To workaround browser issues, we need to consolidate all live regions.

Suggested actions container is an element with aria-live="polite" and role="status". Both defines the liveliness for this container. We are removing both tags. Then, use the chat history live region twin to narrate the suggested actions.

As suggested actions container is no longer a live region, it can be unmounted when there are no suggested actions. Thus, we no longer need to narrate "Suggested actions container: Is empty."

Design

Consolidating live regions

For #4296, the issue is likely because both chat history live region and suggested actions live region are being updated at the same time. If they are updated at a slightly different time, browser may interrupt the earlier update and favor the latter update. This means either one of the live regions could skipped by the screen reader.

We are removing live region (aria-live="polite" and role="status") from suggested actions. Instead, using the chat history live region twin to read the suggested actions (through the <LiveRegionSuggestedActions>).

This will likely reduce browser issues around "suggested actions are not narrated" as no more than one live region will be updated at the same time.

Removing "is empty" narration from the suggested action container

As the suggested actions container is no longer a live region, it does not need to persist on the screen (the basic requirement of live region is the container must always appear in the DOM tree). Thus, it should not narrate "Suggested actions container: Is empty".

Updating role of suggested actions

Also, as suggested actions are all buttons next to each other. The role="toolbar" is a better fit for this type of UI. To fulfill the accessibility requirement of role="toolbar", we are implementing roving tab index and end-users will navigate across suggested action buttons using navigational keys (left/right for carousel/flow layout, up/down for stacked layout).

Since we are using roving tab index for the suggested actions, we will have 2 layers of focus: focus on the container and focus on each individual button. We added style options to show both focii (solid/wide for container, dashed/thin for button), similar to chat history.

<RovingTabIndexProvider>

This provider will provide roving tab index functionality to all components.

We tried 2 ways to implement this component:

1. React props
   1. useTabIndex(index: number): [number] to return a tabindex value of either 0 or -1
   2. useFocusHandler(index: number): () => void and useBlurHandler(index: number): () => void to return an event listener that should hook to the element
2. DOM-based
   1. useItemRef(ref: RefObject<HTMLElement>, index: number) to automatically attach focus/blur handler and patch tabindex attribute via DOM

We opted for the latter approach as it deemed more lightweight on the API side, despite, it is hacking React-controlled component via setAttribute(). We think this is reasonable balance.

Specific Changes

• Added 3 style options for styling the visual keyboard indicator for suggested actions
  • suggestedActionsVisualKeyboardIndicatorColor
  • suggestedActionsVisualKeyboardIndicatorStyle
  • suggestedActionsVisualKeyboardIndicatorWidth
• Fixed typing issues in useDateFormatter.ts
• Restructure live region activity into its own folder
  • <LiveRegionActivity> (entrypoint), <LiveRegionAttachments> and <LiveRegionSuggestedActions>
  • Renamed <ScreenReaderActivity> to <LiveRegionActivity>, this component is used by live region twin only
• New <RovingTabIndexProvider> and useItemRef() hook to bring the roving tab index functionality to all components
• Chat history live region will narrate non-presentational message activities, regardless they are rendered in the visible chat history or not
  • This will help narrating suggested actions from a message activity without text field (which will not be rendered in the visible chat history)
• Added new visual keyboard focus indicator for suggested actions container
  • This is required as suggested action buttons are now using roving tab index
• Added useFocusWithin for polyfilling browsers that does not support :focus-within pseudo class
• Added footnote when a message with suggested actions arrive, this is similar to footnote for messages with interactive elements or links
  • Screen reader should read "Suggested action container: Has content. Press CTRL + SHIFT + A to select."
  • This narrative should be updated in the future for clarity
• Updated port numbers for development server
  • Default server is now explicitly hosting on port 5000, as serve updated its default to 3000 instead
  • Embed server is now hosting on port 5002

• I have added tests and executed them locally
• I have updated CHANGELOG.md
• I have updated documentation

Review Checklist

This section is for contributors to review your work.

• Accessibility reviewed (tab order, content readability, alt text, color contrast)
• Browser and platform compatibilities reviewed
• CSS styles reviewed (minimal rules, no z-index)
• Documents reviewed (docs, samples, live demo)
• Internationalization reviewed (strings, unit formatting)
• package.json and package-lock.json reviewed
• Security reviewed (no data URIs, check for nonce leak)
• Tests reviewed (coverage, legitimacy)