Skip to content

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

Open
wants to merge 11 commits into
base: main
Choose a base branch
from

Conversation

giacomo-petri
Copy link
Contributor

@giacomo-petri giacomo-petri commented Mar 21, 2025

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:

<div role="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>
</div>

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.

<div role="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>
		<button>Test</button>
		<input type="text aria-label="Test">
	</div>
</div>

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.

  • "author MUST" tests:
  • "user agent MUST" tests:
  • Browser implementations (link to issue or commit):
    • WebKit:
    • Gecko:
    • Blink:
  • Does this need AT implementations?
  • Related APG Issue/PR:
  • MDN Issue/PR:

Preview | Diff

Copy link

netlify bot commented Mar 21, 2025

Deploy Preview for wai-aria ready!

Name Link
🔨 Latest commit cecd778
🔍 Latest deploy log https://app.netlify.com/sites/wai-aria/deploys/67e2fa5116ad9400081d9a69
😎 Deploy Preview https://deploy-preview-2483--wai-aria.netlify.app
📱 Preview on mobile
Toggle QR Code...

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 pkra added the clarification clarifying or correcting language that is either confusing, misleading or under-specified label Mar 21, 2025
pkra
pkra previously requested changes Mar 21, 2025
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>.
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 this still allows for group > group > menuItem.

If we resolve #2016, it might be enough to require "accessibility ancestor of menu or menubar".

Copy link
Contributor Author

@giacomo-petri giacomo-petri Mar 21, 2025

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>

Copy link
Member

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>

Copy link
Contributor Author

@giacomo-petri giacomo-petri Mar 24, 2025

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.

Copy link
Member

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

Copy link
Contributor Author

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.

Copy link
Member

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 😉

Copy link
Contributor Author

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

Copy link
Member

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.

Copy link
Contributor Author

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.

giacomo-petri and others added 4 commits March 21, 2025 20:53
Co-authored-by: Peter Krautzberger <p.krautzberger@gmail.com>
Co-authored-by: Peter Krautzberger <p.krautzberger@gmail.com>
@giacomo-petri giacomo-petri requested a review from pkra March 21, 2025 20:14
@giacomo-petri giacomo-petri dismissed pkra’s stale review March 21, 2025 20:14

suggestions applied

@spectranaut
Copy link
Contributor

@np-at to review as well!

@scottaohara scottaohara removed their request for review March 27, 2025 17:27
@scottaohara
Copy link
Member

actually, taking myself off as a reviewer since we have so many others.

@giacomo-petri
Copy link
Contributor Author

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

@pkra
Copy link
Member

pkra commented Apr 3, 2025

@giacomo-petri sounds good. Hopefully it's simpler since #2094 prevents group as child of tree.

@spectranaut spectranaut moved this from All PRS to Needs Consensus/Review in ARIA Normative PR Tracking Jun 13, 2025
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.
Copy link
Member

@pkra pkra Jun 14, 2025

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

Copy link
Member

@pkra pkra Jun 14, 2025

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

Copy link
Contributor

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

@pkra pkra Jun 14, 2025

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.

Copy link
Contributor

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

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>
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 be able to reduce this to just group's again.

@pkra pkra added the Agenda label Jun 14, 2025
@spectranaut
Copy link
Contributor

Discussed in today's meeting: https://www.w3.org/2025/07/03-aria-minutes.html#3a9f

Copy link
Contributor

@spectranaut spectranaut left a 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.
Copy link
Contributor

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

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Agenda clarification clarifying or correcting language that is either confusing, misleading or under-specified spec:aria
Projects
Status: Needs Review
Development

Successfully merging this pull request may close these issues.

Group as allowed acc child of role menu if acc child of menuitem
4 participants