Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add normative text on calculating aria-level, aria-posinset, and aria-setsize #2104

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add normative text on calculating aria-level, aria-posinset, and aria-setsize #2104

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should remove the second sentence (see my other comment).

<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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@pkra pkra Jan 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

<p class="note"> In the case of a <rref>treegrid</rref>, <pref>aria-level</pref> is supported on elements with the role <rref>row</rref>, not elements with role <rref>gridcell</rref>. At first glance, this might seem inconsistent with the application of <pref>aria-level</pref> on <rref>treeitem</rref> elements, but it is consistent in that the <rref>row</rref> acts as the leaf node within the vertical orientation of the <rref>grid</rref>, whereas the <rref>gridcell</rref> is a leaf node within the horizontal orientation of each <rref>row</rref>. Level is not supported on sets of cells within rows, so the <pref>aria-level</pref> attribute is applied to the element with the role <rref>row</rref>.</p>
<p class="note">On elements with role <pref>heading</pref>, values for <pref>aria-level</pref> above 6 can create difficulties for users. Also, at the time of this writing, most combinations of user agents and assistive technologies only support <pref>aria-level</pref> integers 1-9 on headings.</p>
</div>
Expand Down Expand Up @@ -12258,6 +12258,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
&lt;/ul&gt;</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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

</div>
<table class="property-features">
<caption>Characteristics:</caption>
Expand Down Expand Up @@ -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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest the same as with posinset.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also: copy&paste error - "aria-posinset" should be "aria-setsize" here.

<p>The following example shows items 5 through 8 in a set of 16.</p>
<pre class="example highlight">&lt;h2 id="label_fruit"&gt; Available Fruit &lt;/h2&gt;
&lt;ul role="listbox" aria-labelledby="label_fruit"&gt;
Expand Down Expand Up @@ -13278,6 +13280,36 @@ <h2>Relationships in the Accessibility Tree</h2>
&lt;div role="listitem"&gt;The "list" is my accessibility parent.&lt;/div&gt;
&lt;/div&gt;
</pre>

<section id="tree_groups">
<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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

<ul>
<li>
Walk up the accessibility tree, and count the number of accessibility ancestors with the relevant grouping role. Those roles are as follows:
<ul>
<li>For <rref>comment</rref>, count the number of ancestors with role <rref>comment</rref>.</li>
<li>For <rref>row</rref> within a <rref>treegrid</rref>, count the number of ancestors within the same <rref>treegrid</rref> with role <rref>rowgroup</rref>.</li>
<li>For <rref>treeitem</rref>, count the number of ancestors within the same <rref>tree</rref> with role <rref>group</rref>.</li>
</ul>
</li>
<li>Return 1 + the number of ancestors with the relevant grouping role.</li>
</ul>

<p>If <pref>aria-posinset</pref> or <pref>aria-setsize</pref> is not specified on any role the supports it with the exception of <rref>article</rref>, user agents MUST compute them as follows:</p>
<ul>
<li>For <rref>treeitem</rref> and <rref>comment</rref>: walk the accessibility tree backward and forward until the explicit or computed level becomes less than the current item's level. Count items only if they are at the same level as the current item.</li>
<li>For all other supported roles: process the accessibility parent, counting all accessibility children that have the same role.</li>
<li>For <pref>aria-posinset</pref>, return 1 + the number of group items before the current item in the accessibility tree.</li>
<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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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?


<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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last sentence needs a change since setsize allows -1.

</section>
</section>
</section>
<section class="normative" id="host_languages">
Expand Down
Loading