Listbox and tree: clarify requirements for selected and checked #1340
Conversation
|
I like this! 🎉 |
|
Still need to fix up the wording in aria-selected to match these new words. This sentence is particularly problematic:
It should either say "may be managed by the user agent", or be completely deleted. |
|
(Accidentally clicked the wrong button and closed this - have reopened.) |
|
This is now ready for working group review. Please see the top comment for a complete summary of changes. |
|
@jcsteh can you please review this. Thanks. |
|
Matt King requests reviewers re-read conversation in #1052 before providing PR review. |
This is no longer "Weakly suggesting use of checked instead of selected in multi-select listboxes and trees." I preferred the previous wording:
Are we certain that we want to make this a strong recommendation? |
| </p> | ||
| <p> | ||
| The <rref>option</rref> role supports both <sref>aria-selected</sref> and <sref>aria-checked</sref> because it is recommended that authors indicate selection with <sref>aria-selected</sref> in single-select list boxes and with <sref>aria-checked</sref> in multi-select list boxes. | ||
| Authors SHOULD NOT specify both <sref>aria-selected</sref> and <sref>aria-checked</sref> on <rref>option</rref> elements contained by the same <rref>listbox</rref> except in the extremely rare circumstances where all the following conditions are met: |
There was a problem hiding this comment.
My one suggestion would be to tweak the "except when" wording, since (colloquially) it currently implies that authors should use both selected and checked when they think those three conditions are met.
Could we split up this line into two sentences, something like "Authors SHOULD NOT specify both aria-selected and aria-checked on option elements contained by the same listbox. However, authors MAY use both in the extremely rare circumstances where all the following conditions are met: [...]" (though probably with some more wording tweaks)
|
@aleventhal @jcsteh @cookiecrook please review as would love to merge this |
There was a problem hiding this comment.
The treeitem role supports both aria-selected and aria-checked because it is recommended that authors indicate selection with aria-selected in single-select trees and with aria-checked in multi-select trees.
Note that the new wording for treeitem (and for option, as mentioned in #1340 (comment)) uses the word "recommended", which is an RFC 2119 word equivalent to SHOULD.
I think we need to be careful about saying that authors SHOULD use aria-checked instead of aria-selected in multi-select trees and listboxes. Many (most?) of the multi-select trees and listboxes I've seen do not use checkboxes on the items. For example:
- File Explorer's listview (default does not have checkboxes),
- Finder's "list" view (which is a tree),
- VSCode file tree, and other IDE file trees (desktop and online).
The only time I can think of where checkboxes make more sense than selection in a multi-select listbox or tree is when the control represents a bunch of user settings, for example:
- macOS Settings - Keyboard (Services is a checkbox tree, other keyboard categories are checkbox lists),
- Windows Control Panel "Windows Features" dialog has a checkbox tree.
There was a problem hiding this comment.
I agree with @carmacleod's concerns about saying authors should use aria-checked instead of aria-selected in multi-select listboxes/trees. This might be what we want to happen in future (and there are even some conversations about changing this in the HTML select widget), but as far as I've seen, this isn't what's happening today. Even saying that it's "common" as in the previous wording probably isn't accurate, certainly not from what I've seen.
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>tab</rref> in a <rref>tablist</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> | ||
| <ul> | ||
| <li>The value of <pref>aria-multiselectable</pref> on the <rref>tablist</rref> is <code>false</code> or <code>undefined</code>.</li> | ||
| <li>None of the <rref>tab</rref> elements in the <rref>tablist</rref> have an explicitly declared value for <sref>aria-selected</sref> or <sref>aria-expanded</sref>.</li> |
There was a problem hiding this comment.
It's probably silly to use aria-expanded in a single-select tablist. However, I think this sentence means that if aria-expanded is set in a single-select tablist, there is no implicit aria-selected. Why does aria-expanded have this effect in this case?
There was a problem hiding this comment.
Same as the argument for aria-checked similarly effecting a listbox.
If the author is using aria-expanded, we assume it is in lieu of aria-selected. If it is not, then it is up to the author to explicitly declare both. We don't want the user agent to assume the author wants both.
index.html
Outdated
| <p>Elements with the role <code>option</code> have an implicit <sref>aria-selected</sref> value of <code>false</code>.</p> | ||
| <p>An item in a <rref>listbox</rref>.</p> | ||
| <p>Authors MUST ensure <a>elements</a> with <a>role</a> <code>option</code> are contained in, or <a>owned</a> by, an element with the <a>role</a> <rref>listbox</rref> or <rref>group</rref> within a <code>listbox</code>. Options not associated with a <rref>listbox</rref> might not be correctly mapped to an <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a>.</p> | ||
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>option</rref> in a <rref>listbox</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> |
There was a problem hiding this comment.
Editorial nit. Is is possible to rephrase some of the negative inversions: "…but user agents MUST NOT provide an implicit value [if conditions] are not met"… Also, some of the referenced list items start with "None of" so I'm having to triple invert when reading this. (A "None of" condition is "not met" so therefore the UA "must not" do what?)
Perhaps "MUST NOT provide an implicit value [unless one/some/all of the following conditions are true]" and then include related inversions of the bullets? (e.g. "One or more of" instead of "None of") Okay to keep the extra nots if inverting the list items becomes too problematic. I think it's accurate, just a little hard to read.
There was a problem hiding this comment.
How about "if and only if" the following conditions are met -- that seems clearer than what's there now.
There was a problem hiding this comment.
Fixed with 2df964f.
@aleventhal I kept both the may only if and the then changed must not to must. I think it's important to have a MUST so the requirement is tested. Hopefully the new wording is much easier to read.
index.html
Outdated
|
|
||
| <p>In either case, authors SHOULD ensure that a selected tab has its <sref>aria-selected</sref> attribute set to <code>true</code>, that inactive tab elements have their <sref>aria-selected</sref> attribute set to <code>false</code>, and that the currently selected tab provides a visual indication that it is selected. In the absence of an <sref>aria-selected</sref> attribute on the current tab, <a>user agents</a> SHOULD indicate to <a>assistive technologies</a> through the platform <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a> that the currently focused tab is selected.</p> | ||
| <p>Authors SHOULD ensure that a selected tab has its <sref>aria-selected</sref> attribute set to <code>true</code>, that inactive tab elements have their <sref>aria-selected</sref> attribute set to <code>false</code>, and that the currently selected tab provides a visual indication that it is selected.</p> | ||
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>tab</rref> in a <rref>tablist</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> |
There was a problem hiding this comment.
ditto re: "MUST NOT" if "none of" are "not met"
There was a problem hiding this comment.
Resolved by a25047b
index.html
Outdated
| <p>An item in a <rref>tree</rref>.</p> | ||
| <p>A <rref>treeitem</rref> <a>element</a> may contain a sub-level group of elements that can be expanded or collapsed. An expandable collection of <code>treeitem</code> elements are enclosed in an element with the <rref>group</rref> <a>role</a>.</p> | ||
| <p>Authors MUST ensure <a>elements</a> with <a>role</a> <code>treeitem</code> are contained in, or <a>owned</a> by, an element with role <rref>tree</rref> or an element with role <rref>group</rref> that is contained in, or owned by, an element with role <rref>treeitem</rref>.</p> | ||
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>treeitem</rref> in a <rref>tree</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> |
There was a problem hiding this comment.
Resolved by d97ef54
index.html
Outdated
| <p>Elements with the role <code>option</code> have an implicit <sref>aria-selected</sref> value of <code>false</code>.</p> | ||
| <p>An item in a <rref>listbox</rref>.</p> | ||
| <p>Authors MUST ensure <a>elements</a> with <a>role</a> <code>option</code> are contained in, or <a>owned</a> by, an element with the <a>role</a> <rref>listbox</rref> or <rref>group</rref> within a <code>listbox</code>. Options not associated with a <rref>listbox</rref> might not be correctly mapped to an <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a>.</p> | ||
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>option</rref> in a <rref>listbox</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> |
There was a problem hiding this comment.
How about "if and only if" the following conditions are met -- that seems clearer than what's there now.
| <p>Authors MUST ensure <a>elements</a> with <a>role</a> <code>option</code> are contained in, or <a>owned</a> by, an element with the <a>role</a> <rref>listbox</rref> or <rref>group</rref> within a <code>listbox</code>. Options not associated with a <rref>listbox</rref> might not be correctly mapped to an <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a>.</p> | ||
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>option</rref> in a <rref>listbox</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> | ||
| <ul> | ||
| <li>The value of <pref>aria-multiselectable</pref> on the <rref>listbox</rref> is <code>false</code> or <code>undefined</code>.</li> |
There was a problem hiding this comment.
So this includes when the author literally has the attribute aria-multiselectable="undefined"
There was a problem hiding this comment.
Is that a problem? Should we word it so it does not? That would be some real hair splitting.
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>option</rref> in a <rref>listbox</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> | ||
| <ul> | ||
| <li>The value of <pref>aria-multiselectable</pref> on the <rref>listbox</rref> is <code>false</code> or <code>undefined</code>.</li> | ||
| <li>None of the <rref>option</rref> elements in the <rref>listbox</rref> have an explicitly declared value for <sref>aria-selected</sref> or <sref>aria-checked</sref>.</li> |
There was a problem hiding this comment.
If there are 300 options, do you want us to go through each one and check? Or can the UA optimize a bit here?
There was a problem hiding this comment.
Good question.
I think we've figured out that if UA never provides implicit values, nothing will break in a way that harms users. So, one approach could be to limit conditions where implicit values are provided if you want a UA to provide them at all.
When building the AX tree, isn't it necessary to process every option and at the same time set its states and props? So, you might be doing this anyway just to create the tree.
There was a problem hiding this comment.
The main problem occurs when there are updates. We try to only process changed nodes, because as a page changes due to interactions, users expect things to be responsive. However, if we optimize so that once an implicit value is used, that it can be used going forward, then we should be ok on the browser performance front. I don't think the optimization needs any verbiage here, but we should clarify that it's a good approach.
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>treeitem</rref> in a <rref>tree</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> | ||
| <ul> | ||
| <li>The value of <pref>aria-multiselectable</pref> on the <rref>tree</rref> is <code>false</code> or <code>undefined</code>.</li> | ||
| <li>None of the <rref>treeitem</rref> elements in the <rref>tree</rref> have an explicitly declared value for <sref>aria-selected</sref> or <sref>aria-checked</sref>.</li> |
There was a problem hiding this comment.
Since is is basically the same text as for option, does it make sense to create a separate section for Multiselectable Container Widgets Supporting Checked or Selected, and then redirect the reader to there? That way we don't have to wonder if it's exactly the same.
There was a problem hiding this comment.
Also, that will make it easier to provide the same functionality in the future, e.g. if we ever add a listgrid role.
Finally, why are we only doing this for tree and listbox? What about treegrid? Can't rows be checked or selected there? Imagine a threaded email interface.
There was a problem hiding this comment.
I don't think it would simplify the wording to consolidate; it would still have to explicitly mention the option, listbox, tree, and treeitem roles.
In grid and treegrid, aria-checked is not supported on rows. In those widgets, if you were crazy enough to use both checked and selected states, you can just put a checkbox in a cell. That is not possible in listbox and tree; you can't put a checkbox inside an option or treeitem.
…y with other roles
Co-authored-by: James Teh <jamie@jantrid.net>
Co-authored-by: Carolyn MacLeod <Carolyn_MacLeod@ca.ibm.com>
…A requirement calc of implicit values Co-authored-by: Carolyn MacLeod <Carolyn_MacLeod@ca.ibm.com>
Co-authored-by: Carolyn MacLeod <Carolyn_MacLeod@ca.ibm.com>
Co-authored-by: Carolyn MacLeod <Carolyn_MacLeod@ca.ibm.com>
mcking65
force-pushed
the
issue700-and-issue1052
branch
from
9fc3e28
to
ce8e890
Compare
|
@sinabahram @carmacleod @smhigley @cookiecrook Editorial changes based on your feedback are all complete now. Thank you for all the great feedback. All the wording seems much easier to understand now. @joanmarie Note for testing: This PR introduces a new user agent must in option, treeitem, and tab. However, it is only a must for a UA that chooses to provide implicit values for aria-selected. |
|
@sinabahram @carmacleod @smhigley @cookiecrook @jcsteh @aleventhal this is ready to merge. Any objections please speak up before tomorrow's ARIA meeting. |
There was a problem hiding this comment.
I'm ok with this, but @mcking65 and @jcsteh, I'd like your feedback about by optimization comment. Namely that I want to avoid constantly checking whether there are any descendants that have aria-selected or aria-checked. I'd much prefer that if there ever are, we cache that info and never recompute it, and therefore the implicit selected decision would be based on a prior state.
| <p>User agents MAY provide an implicit value for <sref>aria-selected</sref> for each <rref>option</rref> in a <rref>listbox</rref> if the following conditions are met, but user agents MUST NOT provide an implicit value for <sref>aria-selected</sref> if any of the following conditions are not met:</p> | ||
| <ul> | ||
| <li>The value of <pref>aria-multiselectable</pref> on the <rref>listbox</rref> is <code>false</code> or <code>undefined</code>.</li> | ||
| <li>None of the <rref>option</rref> elements in the <rref>listbox</rref> have an explicitly declared value for <sref>aria-selected</sref> or <sref>aria-checked</sref>.</li> |
There was a problem hiding this comment.
The main problem occurs when there are updates. We try to only process changed nodes, because as a page changes due to interactions, users expect things to be responsive. However, if we optimize so that once an implicit value is used, that it can be used going forward, then we should be ok on the browser performance front. I don't think the optimization needs any verbiage here, but we should clarify that it's a good approach.
This PR will resolve #700 and resolve #1052. It supercedes #799.
Changes include the following.
Removes "selectable" from the definition of option to support cases where either an item is checkable instead of selectable or an item is neither selectable nor checkable (i.e., similar to disabled). The definition of option is then:
Similarly simplifies the definition of treeitem.
Replaces the statement:
with a list of conditions that must be met before a user agent can provide an implicit value for aria-selected.
Adds the same restrictions on user agent provision of implicit aria-selected values to treeitem and tab.
These user agent restrictions enable authors to:
Adds authoring guidance that:
In the characteristics table for option:
💥 Error: 500 Internal Server Error 💥
PR Preview failed to build. (Last tried on Jan 20, 2021, 10:59 PM UTC).
More
PR Preview relies on a number of web services to run. There seems to be an issue with the following one:
🚨 Spec Generator - Spec Generator is the web service used to build specs that rely on ReSpec.
🔗 Related URL
If you don't have enough information above to solve the error by yourself (or to understand to which web service the error is related to, if any), please file an issue.