Clarify wording in "Including Elements in the Accessibility Tree" section

[carmacleod]

Resolves #841

Starting fresh with only the relevant changes from PR #950 to ensure that nothing bogus gets merged.

So... "take two": @cookiecrook @jnurthen @joanmarie @mcking65

---

Preview (#tree_exclusion) (#tree_inclusion) | Diff

[mcking65]

I think this is better than the original, but still not sufficiently clear.

The item that addresses aria-activedescendant is not accurate. I provided a suggestion. It's a tricky one to get right. I hope the suggestion is clear. Alternatively, because there are 4 important conditions, it might be more clear if those conditions were formatted in a sublist. However, that would make the list structure itself a bit more complex by creating 3 layers of conditions.

[jnurthen]

@mcking65 please re-review

[carmacleod]

@jnurthen @joanmarie @mcking65 Please review this. Other recent issues have been quoting the including/excluding sections that this PR covers, and I'm worried that pieces of the old sections may be reworded, and then we will have complicated conflicting words and thoughts to merge. It would be way easier to merge this first, before people start layering on new content.

[carmacleod]

@jnurthen @joanmarie @mcking65 - ping.

Note that this PR will now close #1172 as well (from the wide review).

[JAWS-test]

I'm not sure, if the following at role=presentation is clear enough:

In addition, the element's descendants and text content are generally included

Because not all descendants are included, but only those that are not required for the current role with role=presentation

[carmacleod]

@JAWS-test

I'm not sure, if the following at role=presentation is clear enough:

In addition, the element's descendants and text content are generally included

Because not all descendants are included, but only those that are not required for the current role with role=presentation

The information is there... but unfortunately finding it requires reading the whole presentation role section, and not just the conflict resolution subsection.

Specifically, these 3 paragraphs, when taken together, explain fairly clearly:

The presentation role is used on an element that has implicit native semantics, meaning that there is a default accessibility API role for the element. Some elements are only complete when additional descendant elements are provided. For example, in HTML, table elements (matching the table role) require tr descendants (the row role), which in turn require th or td children (the cell, columnheader, rowheader roles). Similarly, lists require list item children. The descendant elements that complete the semantics of an element are described in WAI-ARIA as required owned elements.

When an explicit or inherited role of presentation is applied to an element with the implicit semantic of a WAI-ARIA role that has required owned elements, in addition to the element with the explicit role of presentation, the user agent MUST apply an inherited role of presentation to any owned elements that do not have an explicit role defined. Also, when an explicit or inherited role of presentation is applied to a host language element which has required children as defined by the host language specification, in addition to the element with the explicit role of presentation, the user agent MUST apply an inherited role of presentation to any required children that do not have an explicit role defined.

For any element with a role of presentation and which is not focusable, the user agent MUST NOT expose the implicit native semantics of the element (the role and its states and properties) to accessibility APIs. However, the user agent MUST expose content and descendant elements that do not have an explicit or inherited role of presentation. Thus, the presentation role causes a given element to be treated as having no role or to be removed from the accessibility tree, but does not cause the content contained within the element to be removed from the accessibility tree.

So I will keep the sentence you pointed out:

In addition, the element's descendants and text content are generally included.

but I will change the sentence right after that to point to the presentation role section instead of the conflict resolution subsection:

These exceptions and conditions are documented in the presentation (role) section.

[carmacleod]

@jnurthen Build is passing, there are no conflicts, and all review comments have been addressed, so even though pr-preview is failing, the 2 links in the opening comment still show an up-to-date preview:
Excluding Elements from the Accessibility Tree
Including Elements in the Accessibility Tree

So, this PR is ready for final review.

[carmacleod]

@cookiecrook @jnurthen @joanmarie @mcking65 Please review.

The preview links are good. Note that both the Excluding elements and the Including elements sections have changes. The diff is broken - it's only showing deletions for some reason - so you'll have to look at the code to see what changed. 😄

Please note: this PR and it's (closed) parent PR have been waiting for almost a year (April 11, 2019). All previous review comments have been addressed, but there were enough changes that this should be reviewed again by all concerned parties. :)

Also please note that this contains changes that address wide review comments for 1.2.

It would be great if this could go in really soon, because I've started forgetting what's in here and accidentally making some of the same changes again. 😅

[jnurthen]

@cookiecrook @mcking65 @joanmarie please re-review. I need to merge this.

[mcking65]

The aria-activedescendant wording is still not quite accurate. Made a suggestion that avoids duplicating the aria-activedescendant specification.

[carmacleod]

@cookiecrook @joanmarie @mcking65 All comments addressed. Ready for re-re-review. :)

Note that I had to add the definition of focusable over in w3c/aria-common#39. Here's the prose:

An element is focusable if it can be given the input focus by either the user (for example, using mouse or keyboard) or by script.

I was afraid to open cans of worms if I mentioned tabindex or activedescendant. Keep it simple...

Let me know if any further changes are needed.

[cookiecrook]

Getting pretty close. Thanks @carmacleod

[carmacleod]

Just waiting on 2 things:

1. need PR Add definition for Focusable aria-common#39 (definition of focusable) reviewed and merged first:

Focusable
An element is focusable if it can be given the input focus by either the user (for example, using mouse or keyboard) or by script.

2. waiting on @aleventhal to answer @cookiecrook's question in Clarify wording in "Including Elements in the Accessibility Tree" section #1100 (comment) about this point in the tree inclusion section:

Elements that are focusable even if the element or one of its ancestor elements has its aria-hidden attribute set to true.

[cookiecrook]

@carmacleod wrote:

1. waiting on @aleventhal to answer @cookiecrook's question in #1100 (comment) about this point in the tree inclusion section:

We can address that in a follow-up issue. I don't think it needs to delay this one... Marking PR as Reviewed.

[carmacleod]

Only waiting on 1 thing:

@jamesn @cookiecrook Please review PR w3c/aria-common#39 - you may not be receiving notifications from that repo. All that PR does is add a definition for focusable. For convenience, here are the words:

Focusable
An element is focusable if it can be given the input focus by either the user (for example, using mouse or keyboard) or by script.

@jnurthen Please merge this (#1100) as soon as possible. Today would be good. People are still trying to make conflicting changes in these 2 sections because this PR (and its parent) have been sitting here for so long. I don't think you need to wait for @joanmarie and @mcking65 to re-re-review. They have seen it many times.