Clarification of when live regions are meant to be announced by AT

[patrickhlauke]

Describe your concern

This is a wider point related to the more specific #2153

One of the most common gotchas/pitfalls I see around the use of live regions with developers is that in many cases, developers add/generate already "populated" live regions that already contain their intended message they want announced:

• including a live region already in their server-sent markup for a document
  e.g. having <div aria-live="assertive">Some message intended to announce on page load</div> already in their page on load
• dynamically generating a live region element complete with the message

  const newLiveRegion= document.createElement("div");
  newLiveRegion.setAttribute("aria-live","assertive");
  const message = document.createTextNode("The message they want announced");
  newLiveRegion.appendChild(message);
  document.body.appendChild(newLiveRegion);
  

• having the populated live region present, but hidden/display:noned, and changing the node's visibility dynamically

  <div id="msg" aria-live="assertive" class="hidden">The message they want announced</div>
  ...
  document.getElementById("msg").classList.toggle("hidden")
  

In all these cases (barring a few very odd cases where, by some fluke, they "may" actually work in a particular browser/screen reader combination, under particular circumstances), the live region isn't actually announced.

The only (mostly) reliable way to get live regions to work is to make sure that the empty live region is present/recognised first - giving screen readers a chance to register for any future updates/changes - and then, in a second step (after a few milliseconds), actually populating them with the content/message that you want announced.

In short, is seems that the logic/idea here is: live regions need to be "present" first (and whatever content they initially have in them is not announced - unless it's a role="alert" which, as per #2153 seems to have additional magic/heuristics built in, likely because devs have historically used it incorrectly so much that browsers decided to special-case them?), and only subsequent updates to the content of these live regions are then announced.

What does the spec say

This reading seems consistent with what the spec currently says in various places:

https://www.w3.org/TR/wai-aria-1.3/#dfn-live-region (emphasis on "update")

Live regions are perceivable regions of a web page that are typically updated as a result of an external event. These regions are not always updated as a result of a user interaction and can receive these updates even when they do not have focus. Examples of live regions include a chat log, stock ticker, or a sport scoring section that updates periodically to reflect game statistics. Since these asynchronous areas are expected to update outside the user's area of focus, assistive technologies such as screen readers have either been unaware of their existence or unable to process them for the user. WAI-ARIA has provided a collection of properties that allow the author to identify these live regions and process them: aria-live, aria-relevant, aria-atomic, and aria-busy.

https://www.w3.org/TR/wai-aria-1.3/#attrs_liveregions (emphasis on "content changes" and "updates")

… The purpose of these attributes is to indicate that content changes might occur without the element having focus, and to provide assistive technologies with information on how to process those content updates …

https://www.w3.org/TR/wai-aria-1.3/#aria-live (emphasis on "updates" and "changes")

Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.

The values of this attribute are expressed in degrees of importance. When regions are specified as polite, assistive technologies will notify users of updates but generally do not interrupt the current task, and updates take low priority. When regions are specified as assertive, assistive technologies will immediately notify the user, and could potentially clear the speech queue of previous updates.

Politeness levels are essentially an ordering mechanism for updates and serve as a strong suggestion to user agents or assistive technologies.

…

When the property is not set on an object that needs to send updates, the politeness level is the value of the nearest ancestor that sets the aria-live attribute.

The aria-live attribute is the primary determination for the order of presentation of changes to live regions.

…

When live regions are marked as polite, assistive technologies SHOULD announce updates at the next graceful opportunity…

And of course, the description of the aria-live values all start with

Indicates that updates to the region …

So, the overwhelming sense I get here from the spec is that the intention is in line with what we're currently experiencing: when live region "appears" the first time around (either on page load, or being dynamically created, or has its node's visibility changed), there is no intention for it to also immediately be announced.

If that is the case - and I'd love confirmation on this - the spec should perhaps even more strongly emphasise this particular wrinkle/aspect, as developers seem to consistently miss it. Perhaps a large boxout/note in various places related to live regions (e.g. the ones listed above, as a start) that warns developers of this fact - that they need to first have the live region element "present", and then only subsequent updates to the content of that live region will be announced (and not the initial content itself, if present). Unless...that's not the official/intended way?

What about Core-AAM?

Cross-referencing this with Core-AAM, the live regions refer back to "Changes to document content or node visibility" https://w3c.github.io/core-aam/#mapping_events_visibility

Here again it initially seems to suggest that it's changes that will trigger events. However, one small aspect that perhaps is also causing confusion is in the "Table of document change scenarios and events to be fired in each API", where it lists the following:

• When an accessibility subtree is shown
• When an accessibility subtree is inserted
• When an accessibility subtree is changed (e.g. replaceNode)

Initially, I understood "accessibility subtree" to mean the content/children of the live region element. However, the definition of "accessibility subtree" https://w3c.github.io/core-aam/#dfn-accessibility-subtree seems to suggest that the subtree contains the parent element itself.

An accessible object in the accessibility tree and its descendants in that tree. …

Would this lead developers to infer that even when the live region element/container itself is shown/inserted (as in the dynamic scenarios listed earlier, and arguably even the page load example), the expectation is that the events are fired (in which case, the ARIA spec should then clarify (contrary to what browsers/screen readers currently do) that there is indeed an expectation that live regions should be announced even when they appear/are created fully populated? Or is the intention here just about the children of the live region element (in which case Core-AAM should disambiguate this)

In short (for real this time)

If live regions are intended to only announce updates, then it would be good to explain this even more explicitly in the ARIA spec. Additionally, Core-AAM may need to have a bit of a tweak as well to explain that events are meant to be sent out when the accessibility subtree excluding the initial live region node/parent itself is shown/inserted/changed.

Otherwise, if the intention is also to announce fully populated live regions as they appear in the DOM/accessibility tree in the first place with content, then that aspect should be made very clear in the ARIA spec as well, and that fact more explicitly highlighted in Core-AAM too.

Link to the version of the specification or documentation you were looking at at.

Link to documentation: (see sprinkled in above)

Does the issue exists in the editors draft (the editors draft is the most recent draft of the specification)? Yes

[patrickhlauke]

/cc @scottaohara

[patrickhlauke]

If it's any help, I made a naive test page for myself here https://codepen.io/patrickhlauke/pen/zYbgvdL

[spectranaut]

This was discussed in today's meeting, but it turned out to be a big topic and we didn't have quite enough time: https://www.w3.org/2024/04/18-aria-minutes.html#t07

Will have to continue the discussion next week (or in a deep dive?).

[cookiecrook]

Following up on those minutes, several people continued the discussion about the recent browser changes for live regions... There was some misunderstanding in the call, and thankfully the implementations are still aligning. For a moment there, it seemed otherwise... Whew! 😅

@benbeaudry et al please edit this comment directly if corrections are needed:

• Recent changes in VO/WebKit keep notifications at the time of insertion/render for role=alert, and other live region types send notifications on change, but not at insertion/render... This matches the intended Windows browser and SR behaviors for end-users...
• The point of confusion on the call was due to Edge and Firefox using UIA and Chrome currently using IA2 on Windows, where the Windows SRs (NVDA And JAWS) prefer UIA if available. Due to Chrome missing UIA support, there were some live region differences that Ben fixed recently, by both resolving the IA2 notifications to match UIA, and by shipping beta UIA support in Chrome. He is investigating whether there is additional work left to do for role=alert in this Chromium issue.

So it seems like we're back to a shared understanding of expected behavior in the engines, and we now need the ARIA spec to reflect that alignment. Agreed with the point of this issue that it's underspecified.

[spectranaut]

Discussed in today's meeting: https://www.w3.org/2024/04/25-aria-minutes.html#t06