Add normative text on calculating aria-level, aria-posinset, and aria-setsize #2104
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
9 tasks
Open
8 tasks
cookiecrook
reviewed
Jan 29, 2025
| @@ -11846,7 +11846,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2> | |||
| <p>This can be applied inside trees to tree items, to headings inside a document, to nested grids, nested tablists and to other structural items that might appear inside a container or participate in an ownership hierarchy. The value for <pref>aria-level</pref> is an integer greater than or equal to 1.</p> | |||
| <p>Levels increase with depth. If the <abbr title="Document Object Model">DOM</abbr> ancestry does not accurately represent the level, authors SHOULD explicitly define the <pref>aria-level</pref> <a>attribute</a>.</p> | |||
| <p>This attribute is applied to elements that act as leaf nodes within the orientation of the set, for example, on elements with role <rref>treeitem</rref> rather than elements with role <rref>group</rref>. This means that multiple elements in a set can have the same value for this attribute. Although it would be less repetitive to provide a single value on the container, restricting this to leaf nodes ensures that there is a single way for <a>assistive technologies</a> to use the attribute.</p> | |||
| <p>If the <abbr title="Document Object Model">DOM</abbr> ancestry accurately represents the level, the <a>user agent</a> can calculate the level of an item from the document structure. This attribute can be used to provide an explicit indication of the level when that is not possible to calculate from the document structure or the <pref>aria-owns</pref> attribute. User agent support for automatic calculation of level might vary; authors SHOULD test with [=user agents=] and assistive technologies to determine whether this attribute is needed. If the author intends for the user agent to calculate the level, the author SHOULD omit this attribute.</p> | |||
| <p>If the <abbr title="Document Object Model">DOM</abbr> ancestry accurately represents the level, the <a>user agent</a> can calculate the level of an item from the document structure as defined in the <a href="#tree_groups">Calculating Group Position</a> section. This attribute can be used to provide an explicit indication of the level when that is not possible to calculate from the document structure or the <pref>aria-owns</pref> attribute. User agent support for automatic calculation of level might vary; authors SHOULD test with [=user agents=] and assistive technologies to determine whether this attribute is needed. If the author intends for the user agent to calculate the level, the author SHOULD omit this attribute.</p> | |||
There was a problem hiding this comment.
VoiceOver assumes no level on headings when not supplied by an author, and just speaks "heading" not the more verbose "heading level 0" or an arbitrary "heading level 2." I worry this change will advise AT to verbosely convey info that the author may not have intended.
There was a problem hiding this comment.
A quick test indicates that Chrome and Firefox appear to calculate a level of 2 for a role=heading with no level.
While NVDA and JAWS expose that level in speech and braille, Orca does not.
pkra
reviewed
Jan 29, 2025
| @@ -11846,7 +11846,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2> | |||
| <p>This can be applied inside trees to tree items, to headings inside a document, to nested grids, nested tablists and to other structural items that might appear inside a container or participate in an ownership hierarchy. The value for <pref>aria-level</pref> is an integer greater than or equal to 1.</p> | |||
| <p>Levels increase with depth. If the <abbr title="Document Object Model">DOM</abbr> ancestry does not accurately represent the level, authors SHOULD explicitly define the <pref>aria-level</pref> <a>attribute</a>.</p> | |||
| <p>This attribute is applied to elements that act as leaf nodes within the orientation of the set, for example, on elements with role <rref>treeitem</rref> rather than elements with role <rref>group</rref>. This means that multiple elements in a set can have the same value for this attribute. Although it would be less repetitive to provide a single value on the container, restricting this to leaf nodes ensures that there is a single way for <a>assistive technologies</a> to use the attribute.</p> | |||
| <p>If the <abbr title="Document Object Model">DOM</abbr> ancestry accurately represents the level, the <a>user agent</a> can calculate the level of an item from the document structure. This attribute can be used to provide an explicit indication of the level when that is not possible to calculate from the document structure or the <pref>aria-owns</pref> attribute. User agent support for automatic calculation of level might vary; authors SHOULD test with [=user agents=] and assistive technologies to determine whether this attribute is needed. If the author intends for the user agent to calculate the level, the author SHOULD omit this attribute.</p> | |||
| <p>If the <abbr title="Document Object Model">DOM</abbr> ancestry accurately represents the level, the <a>user agent</a> can calculate the level of an item from the document structure as defined in the <a href="#tree_groups">Calculating Group Position</a> section. This attribute can be used to provide an explicit indication of the level when that is not possible to calculate from the document structure or the <pref>aria-owns</pref> attribute. User agent support for automatic calculation of level might vary; authors SHOULD test with [=user agents=] and assistive technologies to determine whether this attribute is needed. If the author intends for the user agent to calculate the level, the author SHOULD omit this attribute.</p> | |||
There was a problem hiding this comment.
The DOM order is mentioned and then aria-owns as an example of things being problematic - but the algorithm only operates on the accessibility tree. (The other properties also reference the DOM which seems to me should change.)
Something like
Unless required by a role, authors SHOULD not use this property; instead authors SHOULD ensure that Calculating Group Position works correctly. If that is not the case, this property MAY be used to provide explicit information of the level.
These properties nowadays almost feel like a case for #1480 to me.
pkra
reviewed
Jan 29, 2025
| @@ -11846,7 +11846,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2> | |||
| <p>This can be applied inside trees to tree items, to headings inside a document, to nested grids, nested tablists and to other structural items that might appear inside a container or participate in an ownership hierarchy. The value for <pref>aria-level</pref> is an integer greater than or equal to 1.</p> | |||
| <p>Levels increase with depth. If the <abbr title="Document Object Model">DOM</abbr> ancestry does not accurately represent the level, authors SHOULD explicitly define the <pref>aria-level</pref> <a>attribute</a>.</p> | |||
There was a problem hiding this comment.
I think we should remove the second sentence (see my other comment).
pkra
reviewed
Jan 29, 2025
| @@ -12258,6 +12258,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2> | |||
| </ul></pre> | |||
| <p>When specifying <pref>aria-posinset</pref>, authors MUST specify a value that is an integer greater than or equal to 1, and less than or equal to the size of the set when that size is known. If authors specify <pref>aria-posinset</pref>, authors MUST also specify a value for <pref>aria-setsize</pref>.</p> | |||
| <p>When specifying <code>aria-posinset</code> on a <rref>menuitem</rref>, <rref>menuitemcheckbox</rref>, or <rref>menuitemradio</rref>, authors SHOULD set the value of <code>aria-posinset</code> with respect to the total number of items in the <rref>menu</rref>, excluding any separators.</p> | |||
| <p>If <code>aria-posinset</code> is not specified by the author, user agents MUST compute it as defined in the <a href="#tree_groups">Calculating Group Position</a> section.</p> | |||
There was a problem hiding this comment.
Could we make replace the second sentence of the paragraph of this section with this? And then update the second paragraph similarly to my comment on aria-level?
pkra
reviewed
Jan 29, 2025
| @@ -12897,6 +12898,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2> | |||
| <p>If all items up to the current item in a set are present in the document structure, it is not necessary to set this <a>attribute</a>, as the <a>user agent</a> can automatically calculate the position for these items. However, if all previous items in the set are not present in the document structure at a given moment, the author MUST set this <a>attribute</a>to provide an explicit indication of an element's position.</p> | |||
| <p>When specifying <code>aria-setsize</code>, authors MUST set the value to an integer equal to the number of items in the set. If the total number of items is unknown, authors SHOULD set the value of <code>aria-setsize</code> to <code>-1</code>.</p> | |||
| <p>When specifying <code>aria-setsize</code> on a <rref>menuitem</rref>, <rref>menuitemcheckbox</rref>, or <rref>menuitemradio</rref>, authors SHOULD set the value of <code>aria-setsize</code> based on the total number of items in the <rref>menu</rref>, excluding any separators.</p> | |||
| <p>If <code>aria-posinset</code> is not specified by the author, user agents MUST compute it as defined in the <a href="#tree_groups">Calculating Group Position</a> section.</p> | |||
There was a problem hiding this comment.
I would suggest the same as with posinset.
There was a problem hiding this comment.
Also: copy&paste error - "aria-posinset" should be "aria-setsize" here.
pkra
reviewed
Jan 29, 2025
| <h3>Calculating Group Position in the Accessibility Tree</h3> | ||
| <p>When <pref>aria-level</pref>, <pref>aria-posinset</pref>, or <pref>aria-setsize</pref> are defined on supported roles, they allow authors to override the default group position and level calculation. When those attributes are not specified by the author, user agents MUST compute them following the rules in this section.</p> | ||
|
|
||
| <p>If <pref>aria-level</pref> is not specified on <rref>comment</rref>, <rref>row</rref> within a <rref>treegrid</rref>, or <rref>treeitem</rref>, user agents MUST compute the level as follows:</p> |
There was a problem hiding this comment.
I don't like listing roles but I don't see a good alternative. The best I can come up with "when not required by the role".
pkra
reviewed
Jan 29, 2025
| <li>For <pref>aria-setsize</pref>, return the total number of group items, including the current item.</li> | ||
| </ul> | ||
|
|
||
| <p>If the author provides one or more of <pref>aria-setsize</pref> and <pref>aria-posinset</pref>, it is the author's responsibility to supply them for all elements in the set. User agent correction of missing values in this case is not defined.</p> |
There was a problem hiding this comment.
"it is the author's responsibility to"
Maybe: "authors MUST"?
User agent correction of missing values in this case is not defined.
Are UAs ok with this?
pkra
reviewed
Jan 29, 2025
|
|
||
| <p>If the author provides one or more of <pref>aria-setsize</pref> and <pref>aria-posinset</pref>, it is the author's responsibility to supply them for all elements in the set. User agent correction of missing values in this case is not defined.</p> | ||
|
|
||
| <p><pref>aria-level</pref>, <pref>aria-posinset</pref>, and <pref>aria-setsize</pref> are all 1-based. When the property is not present or is "0", it indicates the property is not computed or not supported. If any of these properties are specified by the author as either "0" or a negative number, user agents SHOULD use "1" instead.</p> |
There was a problem hiding this comment.
The last sentence needs a change since setsize allows -1.
pkra
requested changes
Jan 29, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #1194
As discussed in the issue, this PR adds normative wording on requiring user agents to calculate
aria-level,aria-posinset, andaria-setsize. It also adds a section outlining how to compute each attribute, based on the current Core AAM wording that will be removed after this is merged.PR tracking
Check these when the relevant issue or PR has been made, OR after you have confirmed the
related change is not necessary (add N/A). Leave unchecked if you are unsure. Read the
Process Document or
Test Overview for more information.
Test, Documentation and Implementation tracking
Once this PR and all related PRs have been been approved by the working group, tests
should be written and issues should be opened on browsers. Add N/A and check when not
applicable.
Preview | Diff