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

smhigley · 2024-01-12T03:50:11Z

As discussed in the issue, this PR adds normative wording on requiring user agents to calculate aria-level, aria-posinset, and aria-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.

Related Core AAM Issue/PR:
Related AccName Issue/PR: N/A
Any other dependent changes? N/A

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.

Related APG Issue/PR: N/A
MDN Issue/PR: N/A
"author MUST" tests: N/A
"user agent MUST" tests: issue created at Write tests for implicit value calculation for ARIA positioning attributes, once testing is unblocked web-platform-tests/interop-accessibility#99
Browser implementations (link to issue or when done, link to commit):
- WebKit:
- Gecko:
- Blink:
Does this need AT implementations? N/A

Preview | Diff

cookiecrook · 2025-01-29T01:54:43Z

index.html

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


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.

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.

I think it's unfortunate the didn't catch that this ARIA 1.1 spec change increased SR verbosity unnecessarily, but since we didn't, and the implementations have moved on, I will forego my worry. It's not so problematic a user change that we should break the IDL reflection and force multiple implementations to revert it.

pkra · 2025-01-29T10:06:26Z

index.html

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


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 · 2025-01-29T10:09:59Z

index.html

@@ -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>


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

pkra · 2025-01-29T10:13:07Z

index.html

 &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>


Could we 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 · 2025-01-29T10:13:48Z

index.html

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


I would suggest the same as with posinset.

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

pkra · 2025-01-29T10:16:13Z

index.html

+			<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>


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 · 2025-01-29T10:17:18Z

index.html

+				<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>


"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 · 2025-01-29T10:21:35Z

index.html

+
+			<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>


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

@scottaohara's PR for addressing a value of -1 (indeterminate): #2341

pkra

I like the new section on calculating. I'm just not certain how to integrate it into the rest of the spec.

Reviewing this as "request changes" for just the two minor issues (the copy&paste error and the -1 issue at the very end.)

spectranaut · 2025-02-06T19:26:09Z

Discussed in today's ARIA meeting: https://www.w3.org/2025/02/06-aria-minutes#3ad8

netlify · 2025-03-17T10:55:06Z

✅ Deploy Preview for wai-aria ready!

Name	Link
🔨 Latest commit	`a7d4659`
🔍 Latest deploy log	https://app.netlify.com/sites/wai-aria/deploys/67d7ff9ab50e5d00087779c8
😎 Deploy Preview	https://deploy-preview-2104--wai-aria.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

pkra · 2025-03-17T10:55:08Z

Rebased on main.

pkra · 2025-03-17T10:56:43Z

@smhigley unfortunately, this disconnects the old comments from the lines in the rebased commit. I hope the thread is sufficient to reconstruct.

spectranaut · 2025-04-29T17:41:31Z

@smhigley I think you never got to @pkra review on this is one?

and @pkra, you added agenda but then we didn't end up discussing this. Do we still need to discuss?

pkra · 2025-04-30T08:46:21Z

and @pkra, you added agenda but then we didn't end up discussing this. Do we still need to discuss?

Not from my end.

smhigley · 2025-06-26T18:05:34Z

@rahimabdi wanted your review here to make sure this doesn't add any snags for IDL mappings (based on what was said in the call I think this may not affect IDL, but would be nice to get your review to confirm)

spectranaut · 2025-07-01T17:30:21Z

Link to discussion from last weeks meeting: https://www.w3.org/2025/06/26-aria-minutes.html#b9b5

rahimabdi

Agreed with @keithamus, I don't anticipate any IDL impact however, it does raise the question of whether ARIA should add additional numeric IDL counterparts for these attributes. Similar to the class content attribute supporting dual IDL attributes (className, classList), aria-level/aria-posinset/aria-setsize could be supplied with an additional, author-friendly IDL attribute that is truly numeric:

For example, each attribute could get a secondary IDL attribute but the original one would remain. Numeric IDL attributes also have a "default value" (similar to a missing value default) that could be specified for the numeric IDL counterparts:

ariaLevel
- currently string reflects as DOMString?
- 🆕 ariaLevelNumeric could reflect as an unsigned Long (default value = 0)
ariaPosInSet
- currently string reflects as nullable DOMString?
- 🆕 ariaPosInSetNumeric could reflect as unsigned Long (default value = 1)
ariaSetSize
- currently string reflects as nullable DOMString?
- 🆕 ariaSetSizeNumeric could reflect as Long (default value = -1)

rahimabdi · 2025-07-09T05:14:57Z

index.html

+            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


I raised a core-aam issue that this isn't necessarily the case for WebKit (for the reasons @cookiecrook mentioned on the June 26 2025 ARIA WG meeting: w3c/core-aam#249

smhigley marked this pull request as draft January 12, 2024 03:50

smhigley marked this pull request as ready for review January 18, 2024 18:07

cookiecrook self-requested a review January 18, 2024 18:09

spectranaut requested review from Jaunita-George and pkra January 18, 2024 18:11

shirsha self-requested a review January 18, 2024 18:15

smhigley mentioned this pull request Jan 18, 2024

Write tests for implicit value calculation for ARIA positioning attributes, once testing is unblocked web-platform-tests/interop-accessibility#99

Open

9 tasks

smhigley mentioned this pull request Feb 8, 2024

Allow treeitems to omit groups by specifiying aria-level, aria-posinset, and aria-setsize #2091

Open

8 tasks

pkra added the spec:aria label Jun 14, 2024

cookiecrook reviewed Jan 29, 2025

View reviewed changes

pkra added the Agenda label Jan 29, 2025

pkra reviewed Jan 29, 2025

View reviewed changes

pkra requested changes Jan 29, 2025

View reviewed changes

pkra added the Agenda-Editors label Feb 6, 2025

pkra mentioned this pull request Feb 9, 2025

revisit PRs touching on posinset, setsize, level #2430

Open

jnurthen removed the Agenda label Feb 11, 2025

pkra removed the Agenda-Editors label Feb 12, 2025

add section on calculating aria-level, aria-posinset, and aria-setsize

28b4628

pkra force-pushed the position-required branch from f33028d to 28b4628 Compare March 17, 2025 10:54

chore: prettier

a7d4659

spectranaut moved this to All PRS in ARIA Normative PR Tracking Jun 13, 2025

spectranaut added this to ARIA Normative PR Tracking Jun 13, 2025

jnurthen moved this from All PRS to Needs Review in ARIA Normative PR Tracking Jun 13, 2025

daniel-montalvo requested a review from rahimabdi June 26, 2025 18:03

rahimabdi reviewed Jul 9, 2025

View reviewed changes

spectranaut moved this from Needs Review to Needs updates from review in ARIA Normative PR Tracking Aug 26, 2025

spectranaut assigned smhigley Aug 26, 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>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>

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

smhigley commented Jan 12, 2024 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR tracking

Test, Documentation and Implementation tracking

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkra Jan 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkra Jan 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rahimabdi Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkra left a comment

Choose a reason for hiding this comment

Uh oh!

spectranaut commented Feb 6, 2025

Uh oh!

netlify bot commented Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for wai-aria ready!

Uh oh!

pkra commented Mar 17, 2025

Uh oh!

pkra commented Mar 17, 2025

Uh oh!

spectranaut commented Apr 29, 2025

Uh oh!

pkra commented Apr 30, 2025

Uh oh!

smhigley commented Jun 26, 2025

Uh oh!

spectranaut commented Jul 1, 2025

Uh oh!

rahimabdi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

smhigley commented Jan 12, 2024 •

edited by pr-preview bot

Loading

pkra Jan 29, 2025 •

edited

Loading

pkra Jan 29, 2025 •

edited

Loading

rahimabdi Jul 9, 2025 •

edited

Loading

netlify bot commented Mar 17, 2025 •

edited

Loading