Implement KLiveRegion and useKLiveRegion

[MisRob]

Summary

This is a proposal for a new component and an accompanying composable, <KLiveRegion> and useKLiveRegion.

<KLiveRegion> will render itself as two live regions, one with a status role and another with an alert role:

<div role="status">
  {{ statusMessage }}
</div>

<div role="alert">
  {{ alertMessage }}
</div>

A single <KLiveRegion> is supposed to be used in an app and high in the app's structure.

useKLiveRegion can be imported to multiple places in an app that can send status or alert messages to <KLiveRegion> via useKLiveRegion.sendStatusMessage(<string>) or useKLiveRegion.sendAlertMessage(<string>).

The documentation will contain brief guidance with relevant references guiding developers on when to use or not use live regions, and what types of information should be sent as status messages and what should be alert messages.

Background

Originally motivated by the ongoing sortable table work. Upon discussing with @radinamatic, it seems that the table will need to utilize live region in some use-cases, particularly to communicate loading/loaded states when re-fetching data when sorting is done on the backend. However, the table itself shouldn’t contain the live region as this would only add another live region to the already many regions in Kolibri. Additionally, a Kolibri audit revealed we use many live regions and we wrap whole components in them, which can lead to a number of problems.

The Value Add

• Encapsulates commonly re-used logic
• By design enforces best practices that prevent messages from getting lost, conflicting with each other, or from irrelevant and confusing information being announced. Such problems are often caused by:
  • multiple live regions
  • live region loaded into the DOM too late
  • wrapping rich HTML content by live region
  • wrapping interactive content by live region
• Possible integration with some KDS components that could send messages to the live region by default (to be decided, see the discussion below)

Possible Tradeoffs

• Not aware of any

Related

• Migrate live regions to KDS useKLiveRegion kolibri#12326

Resources

• https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions
• https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-1/
• https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-2/

[MisRob]

To decide/discuss

(1) aria-live vs role

Would it be better if <KLiveRegion> rendered itself as

<div aria-live="polite">
  {{ politeMessage }}
</div>

<div aria-live="assertive">
  {{ assertiveMessage }}
</div>

rather than using the aforementioned roles?

• The roles add semantic meaning and can enhance some screen readers. For example, role=alert prepends announcements with “Alert: …”, whereas aria-live doesn’t do that.
• There seems to be a tension between semantics and universality. Roles provide better semantics that, on the other hand, may not be suitable for such a general component. For example, not all polite messages may not necessarily represent status messages.

(2) Internal integration of KDS components with the live region

I imagine that useKLiveRegion could be in some cases internally integrated with relevant KDS components. However, this approach's main advantage seems to also be its main drawback. For example, consider a table component that internally sends announcements about loading/finished loading to the live region. For this purpose, it receives the region’s ID and translated announcement strings.

• Pros:
  • Eliminates the need to write guidance on what should and should not be announced from the table
  • Enforces some parts of a11y without any extra steps needed
  • Simple default behavior, no need to re-implement sending same announcements at multiple app places
• Cons:
  • The table needs to be fed by more data
  • Some announcements are hidden from developers' eyes. This risks sending duplicate messages unintentionally (consider the situation we’d decide to show snackbars for loading state in Kolibri where all snackbars updates are currently announced)

I can think of mitigating some of the cons of both approaches to at least some extent technically as well as by documentation but for now, I’d be particularly grateful for higher-level feedback on whether introducing such approach would be an interesting pattern in KDS, or not.

[MisRob]

Discussed with the team, so moving from the proposal stage.

Decisions:

• Use aria-live rather than role. Reason: General component.
• KDS components will integrate with the live region internally. Reason: Efficiency, robustness.
  • @rtibbles feedback: a component that wants to use live region it should throw warning if the live region is not available