Description at aria-relevant incomprehensible and wrong

[JAWS-test]

https://rawgit.com/w3c/aria/master/#aria-relevant:

When text changes are denoted as relevant, user agents MUST monitor any descendant node change that affects the accessible name and description computation of the live region as if the accessible name were determined from contents (nameFrom: contents).

• Does this mean that the elements in the live region should be treated as if their name is derived from the content? I.e. button aria-label=button should be output if its text content changes and not be output if its aria-label changes? This would be quite misleading, because then a change in the source code would be output, which would not be noticeable anywhere on the page when navigating with the screenreader.
• Or does this mean, only elements, which are labelled by content, should be output when changing? Then many updates would not be noticeable, especially since some elements cannot be labeled via content at all according to the specification, but only by the author.
• "When text changes are denoted as relevant": Does this mean that this only applies to aria-relevant=text and not to aria-relevant=additions? Should the Accessible name be output instead of the text content for aria-relevant=additions? This would be very strange, because by default aria-relevant has the value "additions text", which means that the button above would be output twice when inserted into the DOM: once with the label in the aria label and once with the label in the text content.
• See also: Change of accessible name within a Live Region is output inconsistently FreedomScientific/standards-support#274

For example, a text change would be triggered if the HTML alt attribute of a contained image changed. However, no change would be triggered if there was a text change to a node outside the live region, even if that node was referenced (via aria-labelledby) by an element contained in the live region.

The example with the alt attribute seems to me to be wrong, because when I follow the link (https://rawgit.com/w3c/aria/master/#namecalculation), it explains that the alt attribute is name from author and not name from content

additions: Element nodes are added to the accessibility tree within the live region

• What should be the output when a node element is added? Name, value and role of the element or its text content? If it is the text content, what would be the difference to aria-relevant=text? Or should aria-relevant=text be used to output only the text change and not the insertion of new nodes? What if I add a heading and a text inside a live region? The heading is a new element node, the text is not. Does this mean that with aria-relevant=additions only the heading should be output and with aria-relevant=text only the text?
• There is no reference (via link) to the term "accessibility tree", which is explained at https://rawgit.com/w3c/aria/master/#accessibility_tree
• What is meant by "element nodes"? The one of the DOM or of the "accessibility tree"? In the accessibility tree, text nodes are their own objects. Is adding a span element in a live region an action that is output by aria-relevant=text or aria-relevant=addition?
• See also: aria-relevant is not output correctly in Live Region FreedomScientific/standards-support#279

The longer I think about aria-relevant, the more unclear it becomes to me what the difference between text and additions should be.. And the developers of Firefox and Chrome don't seem to know any difference either, because they don't make any.

[jnurthen]

When text changes are denoted as relevant, user agents MUST monitor any descendant node change that affects the accessible name and description computation of the live region as if the accessible name [of the live element] were determined from contents (nameFrom: contents).

Would adding the text in [ ] above help clarify. The text does not mean that all descendants would be calculated using contents but that the live node itself would use contents for its text but all child nodes would use the standard accessible name calculation.

[JAWS-test]

@jnurthen:

I'm sorry, I don't understand. It would probably help if you explained

• what is the difference between text and additions good for?
• which output would be correct for my test cases: Live Region: The mix of text and element nodes leads to a strange output FreedomScientific/standards-support#283, aria-relevant is not output correctly in Live Region FreedomScientific/standards-support#279 and Change of accessible name within a Live Region is output inconsistently FreedomScientific/standards-support#274?

While there was a discussion about the meaningfulness of removals (#712), I would rather suggest talking about the sense of text and additions. Probably there is no practical sense and it is enough to distinguish between addition+text, all and removals.

[jnurthen]

The entire premise of this issue seems to be based this statement

When text changes are denoted as relevant, user agents MUST monitor any descendant node change that affects the accessible name and description computation of the live region as if the accessible name were determined from contents (nameFrom: contents).

What this means is that the live region element itself has a name for the purposes of the live region calculation as if that element were determined from contents. This does not change how child elements have their name calculated. Thus my attempted rephrasing of this sentence to

When text changes are denoted as relevant, user agents MUST monitor any descendant node change that affects the accessible name and description computation of the live region as if the accessible name of the live element itself were determined from contents (nameFrom: contents).

So to try to tackle your questions:

• Does this mean that the elements in the live region should be treated as if their name is derived from the content? I.e. button aria-label=button should be output if its text content changes and not be output if its aria-label changes? This would be quite misleading, because then a change in the source code would be output, which would not be noticeable anywhere on the page when navigating with the screenreader.

If it is the live region itself then yes - if it is a child of the live region then no.

• Or does this mean, only elements, which are labelled by content, should be output when changing? Then many updates would not be noticeable, especially since some elements cannot be labeled via content at all according to the specification, but only by the author.

Again if the live region is on the element then yes - if the element is a child of the live region then no.

• "When text changes are denoted as relevant": Does this mean that this only applies to aria-relevant=text and not to aria-relevant=additions? Should the Accessible name be output instead of the text content for aria-relevant=additions? This would be very strange, because by default aria-relevant has the value "additions text", which means that the button above would be output twice when inserted into the DOM: once with the label in the aria label and once with the label in the text content.

The same thing is generally output for the live region. Text vs Additions is used when calculating whether a live region event is triggered. Additions is only looking for the addition of nodes whereas text needs to look at the calculated accessible name to determine if the text has changed.

[jnurthen]

The example with the alt attribute seems to me to be wrong, because when I follow the link (https://rawgit.com/w3c/aria/master/#namecalculation), it explains that the alt attribute is name from author and not name from content

No - it is a contained image so the text is absolutely correct

What should be the output when a node element is added? Name, value and role of the element or its text content? If it is the text content, what would be the difference to aria-relevant=text? Or should aria-relevant=text be used to output only the text change and not the insertion of new nodes? What if I add a heading and a text inside a live region? The heading is a new element node, the text is not. Does this mean that with aria-relevant=additions only the heading should be output and with aria-relevant=text only the text?

if aria-atomic is set to false then I'd expect the new node to be output. Exactlly how AT decides to output a node in a live region is a decision of the AT.

There is no reference (via link) to the term "accessibility tree", which is explained at https://rawgit.com/w3c/aria/master/#accessibility_tree

Happy to add this

What is meant by "element nodes"? The one of the DOM or of the "accessibility tree"? In the accessibility tree, text nodes are their own objects. Is adding a span element in a live region an action that is output by aria-relevant=text or aria-relevant=addition?

Good question. This needs defining as it is unclear.

[JAWS-test]

@jnurthen Many thanks for the detailed explanations and changes to the specification. I have now understood. It might be important to note that a live region has two accessible names: one that can only be explicitly assigned by the author (Name From: author, and which does not change or whose change is unlikely to result in an output of the live region by AT), and the content of the live region whose change leads to the output of the live region.

I understand it at least in such a way that the following refers only to the second type

What this means is that the live region element itself has a name for the purposes of the live region calculation as if that element were determined from contents.

Shall I leave the issue open or create a new one for

What is meant by "element nodes"? The one of the DOM or of the "accessibility tree"? In the accessibility tree, text nodes are their own objects. Is adding a span element in a live region an action that is output by aria-relevant=text or aria-relevant=addition?

[jnurthen]

Related #712

[jnurthen]

consult with @aleventhal

[jnurthen]

Closed the previous PR as I don't think it actually clarified anything (and I messed up the rebasing)