-
Notifications
You must be signed in to change notification settings - Fork 134
Clarify Accessibility Parent-Child Relationships for menu, group, and menuitem #2483
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.
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
base: main
Are you sure you want to change the base?
Conversation
✅ Deploy Preview for wai-aria ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
index.html
Outdated
@@ -6520,7 +6535,7 @@ <h4>Plain HTML or Polyfill DOM Result of the MathML Quadratic Formula</h4> | |||
<p>A <rref>menuitem</rref> with a checkable state whose possible <span>values</span> are <code>true</code>, <code>false</code>, or <code>mixed</code>.</p> | |||
<p> | |||
Authors MUST ensure [=elements=] with <a>role</a> <code>menuitemcheckbox</code> are <a>accessibility children</a> of an element with role <rref>menu</rref>, <rref>menubar</rref>, or an | |||
element with role <rref>group</rref> that is an <a>accessibility child</a> of an element with role <rref>menu</rref> or <rref>menubar</rref>. | |||
element with role <rref>group</rref> that is an <a>accessibility child</a> of an element with role <rref>group</rref>, <rref>menu</rref> or <rref>menubar</rref>. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this still allows for group > group > menuItem
.
If we resolve #2016, it might be enough to require "accessibility ancestor of menu or menubar".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this still allows for group > group > menuItem.
yes, it looks like people would like to use menu > group > group > menuitem, so I adjusted the PR accordingly
e.g.
<menu>
<div role="group">
<span role="menuitem">Item 1</span>
<div role="group">
<span role="menuitem">Item 2</span>
<span role="menuitem">Item 3</span>
</div>
</div>
</menu>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks. I meant that this seems to be technically valid
<div role="group">
<div role="group">
<span role="menuitem">Item</span>
</div>
</div>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right, sorry I didn't get it.
What about adding at the end:
All group elements containing menuitem (TODO for all the menuitem roles - menuitemcheckbox...***) MUST be accessibility descendant of an element with role menu or menubar.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's one way. (I think adding a term for accessibility ancestor might make things easier to understand.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
But menu would not allow navigation as an accessibility child, right?
Exactly, menu would not allow navigation; that's why the "top-level group" wording.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Exactly, menu would not allow navigation; that's why the "top-level group" wording.
I meant that menu already prevents the example, without the additional wording.
But yes, the wording would work around
<body>
<div role="navigation">
<div role="group">
<div role="group">
<span role="menuitem">Item</span>
</div>
</div>
</div>
</body>
being valid.
I still think "menuitem MUST have an accessibility ancestor menu or menubar" would be easier to understand, especially since the opening line of the role basically says so: "An option in a set of choices contained by a menu or menubar."
Another term that could be helpful: "intervening" (as used for generics): menus (of various types) contain items (of various types) but allow intervening groups.
Anyway, we need another reviewer 😉
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I believe my confusion regarding the term "accessibility ancestor" stems from the lack of a clear definition. As I understand it, the term should allow for structures like the following:
<div role="menu">
<div role="navigation">
<div role="group">
<div role="group">
<span role="menuitem">Item</span>
</div>
</div>
</div>
</div>
However, as you pointed out:
"I meant that menu already prevents the example, without the additional wording."
That said, I love your proposal:
"Intervening" (as used for generics): menus (of various types) contain items (of various types) but allow intervening groups.
This clarification ensures that both menu/menubar and menuitem/menuitemcheckbox/... definitions are explicitly clear about the group stuff. By combining the concepts of "accessibility ancestor" and "intervening," I believe we effectively address all concerns.
I'll update my PR by the end of the day with the following changes:
- drafting a definition for "accessibility ancestor"
- replacing the current wording with menuitem MUST have an "accessibility ancestor" of menu or menubar
- adding the "intervening" clarification
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, Giacomo.
We currently have
The accessibility descendants of a DOM element are all DOM elements which correspond to descendants of the corresponding accessible object in the accessibility tree.
Rough idea for ancestor:
The accessibility ancestors of a DOM element are all DOM elements of which the given DOM element is an accessibility descendant.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Content updated as per items above.
Co-authored-by: Peter Krautzberger <p.krautzberger@gmail.com>
Co-authored-by: Peter Krautzberger <p.krautzberger@gmail.com>
fix typo
@np-at to review as well! |
actually, taking myself off as a reviewer since we have so many others. |
@pkra, I just realized the same issue affects tree/group/treeitem structures. Should we include this change in this PR or create a separate one? |
@giacomo-petri sounds good. Hopefully it's simpler since #2094 prevents group as child of tree. |
However, when a <code>group</code> is used in the context of a <rref>listbox</rref>, for example, authors MUST limit its children to <rref>option</rref> elements. Similarly, when a | ||
<code>group</code> is used in the context of a <rref>menu</rref> or <rref>menubar</rref>, authors MUST limit its <a>accessibility descendants</a> to <rref>menuitem</rref>, | ||
<rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref> and <rref>separator</rref>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and | ||
<rref>none</rref> intervening. Therefore, proper handling of <code>group</code> by authors and assistive technologies is determined by the context in which it is provided. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Coming back to this I'm not sure about this addition. "MUST limit its accessibility descendants" seems too strong - groups can have other descendants because, e.g., menuitem does not have any restrictions on its descendants.
IIRC we're really after "donut scoping". If that's the case I'm wondering if this addition is necessary. Does donut scoping not follow from the new requirements on menuitem etc now that we have accessibility ancestor?
If that's the case, then perhaps a note is more appropriate, describing this effect. (There could be a follow up issue to do the same with listbox and option.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, I think what I wrote is not right either. Maybe children instead of descendants? E.g., "if a group has an accessibility ancestor of role menu, then allowed children are ...".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In the working group meeting, I suggested using "accessibility children", but now I realize that can't quite be used the way I suggested, so I took a try at re-writing this whole section, which doesn't solve Peter's problem of making it "less wordy" but it does make it more clear, at least to me:
A set of user interface objects that is not intended to be included in a page summary or table of contents by assistive technologies.
Contrast with region, which is a grouping of user interface objects that will be included in a page summary or table of contents. If a section is significant enough to warrant inclusion in the web page's table of contents, the author SHOULD assign it a role of region or a standard landmark role.
Authors SHOULD use a group to form a logical collection of items in a widget, such as children in a tree widget forming a collection of siblings in a hierarchy. Authors MAY nest group elements.
The proper handling of group by authors and assistive technologies is determined by the context in which it is provided. For example, when a group is the accessibility child of a menu or menubar, authors MAY nest additional groups, however, the accessibility children of the innermost group MUST be limited to menuitems, menuitemcheckboxs, menuitemradios and separators. Whereas when a group is the accessibility child of a listbox, authors MUST NOT nest groups and MUST limit the groups accessibility children to option elements.
I don't think "accessibility descendant" quite works here, because we never want to say something about all descendants.
@@ -6200,6 +6202,10 @@ <h4>Plain HTML or Polyfill DOM Result of the MathML Quadratic Formula</h4> | |||
</p> | |||
<p>To be <a>keyboard accessible</a>, authors SHOULD manage focus of descendants for all instances of this <a>role</a>, as described in <a href="#managingfocus">Managing Focus</a>.</p> | |||
<p>Elements with the role <code>menu</code> have an implicit <pref>aria-orientation</pref> value of <code>vertical</code>.</p> | |||
<p class="note"> | |||
The <code>menu</code> <a>role</a> allows only role <rref>menuitem</rref>, <rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref>, and <rref>separator</rref> as | |||
<a>accessibility descendants</a>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and <rref>none</rref> intervening. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As above, I think menu can have other descendants (below e.g. menuitem). In which case this should be rephrased to describe the effects of donut scoping.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reading this I think I finally understand your concern @pkra. This is hard to write.
But since it's a note, maybe it can be more informal, here is a suggestion:
Let's call the elements that are contained in a menu and have roles menuitems, menuitemcheckboxes, menuitemradios or separator the "items" of that menu. These items can be arranged for logical purposes with groups, or styling purposes with generics. However, no semantically meaningful elements other than group are allowed between the individual items of the menu and the element with role menu. This is similar to the definition and constraints of "accessibility children", however, along with allowing intervening elements of role generic or none, we allow intervening elements of role group.
Also, I realize, the "allowed accessibility children" isn't clear enough. "Allowed accessibility children" only tells you what the next accessibility child should be. So if we add to that list "group with the accessibility child of group", then it's not clear that the child of THAT group MUST be either a group or (....). Is it possible to say this without being recursive?
@@ -6304,6 +6312,10 @@ <h4>Plain HTML or Polyfill DOM Result of the MathML Quadratic Formula</h4> | |||
</p> | |||
<p>To be <a>keyboard accessible</a>, authors SHOULD manage focus of descendants for all instances of this <a>role</a>, as described in <a href="#managingfocus">Managing Focus</a>.</p> | |||
<p>Elements with the role <code>menubar</code> have an implicit <pref>aria-orientation</pref> value of <code>horizontal</code>.</p> | |||
<p class="note"> | |||
The <code>menubar</code> <a>role</a> allows only role <rref>menuitem</rref>, <rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref>, and <rref>separator</rref> as | |||
<a>accessibility descendants</a>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and <rref>none</rref> intervening. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sames as above for menu.
<li><rref>group</rref> with <a>accessibility child</a> <rref>menuitem</rref></li> | ||
<li><rref>group</rref> with <a>accessibility child</a> <rref>menuitemradio</rref></li> | ||
<li><rref>group</rref> with <a>accessibility child</a> <rref>menuitemcheckbox</rref></li> | ||
<li><rref>group</rref> with <a>accessibility child</a> <rref>separator</rref></li> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should be able to reduce this to just group's again.
Discussed in today's meeting: https://www.w3.org/2025/07/03-aria-minutes.html#3a9f |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for this effort @giacomo-petri! I've contributed some ideas...
However, when a <code>group</code> is used in the context of a <rref>listbox</rref>, for example, authors MUST limit its children to <rref>option</rref> elements. Similarly, when a | ||
<code>group</code> is used in the context of a <rref>menu</rref> or <rref>menubar</rref>, authors MUST limit its <a>accessibility descendants</a> to <rref>menuitem</rref>, | ||
<rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref> and <rref>separator</rref>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and | ||
<rref>none</rref> intervening. Therefore, proper handling of <code>group</code> by authors and assistive technologies is determined by the context in which it is provided. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In the working group meeting, I suggested using "accessibility children", but now I realize that can't quite be used the way I suggested, so I took a try at re-writing this whole section, which doesn't solve Peter's problem of making it "less wordy" but it does make it more clear, at least to me:
A set of user interface objects that is not intended to be included in a page summary or table of contents by assistive technologies.
Contrast with region, which is a grouping of user interface objects that will be included in a page summary or table of contents. If a section is significant enough to warrant inclusion in the web page's table of contents, the author SHOULD assign it a role of region or a standard landmark role.
Authors SHOULD use a group to form a logical collection of items in a widget, such as children in a tree widget forming a collection of siblings in a hierarchy. Authors MAY nest group elements.
The proper handling of group by authors and assistive technologies is determined by the context in which it is provided. For example, when a group is the accessibility child of a menu or menubar, authors MAY nest additional groups, however, the accessibility children of the innermost group MUST be limited to menuitems, menuitemcheckboxs, menuitemradios and separators. Whereas when a group is the accessibility child of a listbox, authors MUST NOT nest groups and MUST limit the groups accessibility children to option elements.
I don't think "accessibility descendant" quite works here, because we never want to say something about all descendants.
@@ -6200,6 +6202,10 @@ <h4>Plain HTML or Polyfill DOM Result of the MathML Quadratic Formula</h4> | |||
</p> | |||
<p>To be <a>keyboard accessible</a>, authors SHOULD manage focus of descendants for all instances of this <a>role</a>, as described in <a href="#managingfocus">Managing Focus</a>.</p> | |||
<p>Elements with the role <code>menu</code> have an implicit <pref>aria-orientation</pref> value of <code>vertical</code>.</p> | |||
<p class="note"> | |||
The <code>menu</code> <a>role</a> allows only role <rref>menuitem</rref>, <rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref>, and <rref>separator</rref> as | |||
<a>accessibility descendants</a>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and <rref>none</rref> intervening. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reading this I think I finally understand your concern @pkra. This is hard to write.
But since it's a note, maybe it can be more informal, here is a suggestion:
Let's call the elements that are contained in a menu and have roles menuitems, menuitemcheckboxes, menuitemradios or separator the "items" of that menu. These items can be arranged for logical purposes with groups, or styling purposes with generics. However, no semantically meaningful elements other than group are allowed between the individual items of the menu and the element with role menu. This is similar to the definition and constraints of "accessibility children", however, along with allowing intervening elements of role generic or none, we allow intervening elements of role group.
Also, I realize, the "allowed accessibility children" isn't clear enough. "Allowed accessibility children" only tells you what the next accessibility child should be. So if we add to that list "group with the accessibility child of group", then it's not clear that the child of THAT group MUST be either a group or (....). Is it possible to say this without being recursive?
Closes #2438
The current specifications for menu and menubar contradict those for menuitem, menuitemcheckbox, and menuitemradio.
Specifically, the following structure is allowed under the menu role but not when considering the menuitem role:
This PR clarifies that this structure is indeed allowed.
Additionally, it explicitly clarifies in a note that the following example, where a group contains a button and an input as accessibility children, is not permitted. This prevents ambiguity by making it clear that having at least one menuitem as an accessibility child of the group does not justify including other unrelated elements, which was not clearly stated.
This update refines the specifications for menu, menubar, menuitem, menuitemcheckbox, and menuitemradio roles consistently.
Test, Documentation and Implementation tracking
Once this PR has been reviewed and has consensus from the working group, tests should be written and issues should be opened on browsers. Add N/A and check when not applicable.
Preview | Diff