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

Jump to bottom

Add listview and listviewitem roles to support interactive lists of interactive widgets, cards, tiles, etc. #2328

Draft
wants to merge 10 commits into
base: main
Choose a base branch
from
Draft

Add listview and listviewitem roles to support interactive lists of interactive widgets, cards, tiles, etc. #2328

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
8d8a9e6
Start drafting listview and listviewitem
mcking65 Sep 15, 2024
75dfb28
Support aria-level on listviewitem
mcking65 Sep 16, 2024
f035fd4
Add more information about keyboard requirements
mcking65 Sep 16, 2024
2c61fcc
Add more authoring guidance and aria-orientation
mcking65 Sep 16, 2024
bcc00a5
clarify authoring requirements for nested collections.
mcking65 Sep 16, 2024
d91e5fd
change naming requirements
mcking65 Sep 16, 2024
5ae91ab
fix some errors
mcking65 Sep 16, 2024
3d530c2
fix more errors
mcking65 Sep 16, 2024
5117f45
editorial changes
mcking65 Sep 16, 2024
82f61ff
remove formatting changes, remove duplicate listitem definition
smhigley Sep 23, 2024
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
271 changes: 271 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4551,6 +4551,277 @@ <h2>Definition of Roles</h2>
</tbody>
</table>
</div>
<div class="role" id="listview"></div>
<rdef>listview</rdef>
<div class="role-description">
<p>
A composite <rref>widget</rref> containing a collection of interactive elements that can also contain interactive elements where some or all items in the collection are focusable by using methods of directional navigation, such as directional arrow keys.
See related <rref>grid</rref> and <rref>treegrid</rref>.
</p>
<p>
A <code>listview</code> contains <rref>listviewitem</rref> elements.
Authors can use the <rref>listviewitem</rref> elements in a <code>listview</code> to present a wide variety of collections.
For example, each item in a collection might contain:
</p>
<ul>
<li>A single element, such as an image, link, or checkbox.</li>
<li>a complex card or tile containing rich content that could include widgets.</li>
</ul>
<p>
A <code>listview</code> can be used to present a hierarchical collection.
a <rref>listviewitem</rref> can contain a <rref>group</rref> that contains other <rref>listviewitem</rref> elements.
As described in the definition of <rref>listviewitem</rref>, authors MAY use <sref>aria-expanded</sref> on a <rref>listviewitem</rref> to indicate that a nested collection can be expanded or collapsed.
</p>
<p>
The primary purpose of a <code>listview</code> is to make a collection navigable and interactive.
Elements in A listview can also be selectable, but they are not selectable by default.
Authors MAY specify either <sref>aria-selected</sref> or <sref>aria-checked</sref> for items in a listview to indicate selection (see <rref>listviewitem</rref>).
If a <code>listview</code> allows multiple <rref>listviewitem</rref> elements to be selected, authors SHOULD set <pref>aria-multiselectable</pref> to <code>true</code> on the element with role <code>listview</code>.
</p>
<p>
To be <a>keyboard accessible</a>, authors SHOULD manage focus of descendants of a <code>listview</code> as described in <a href="#managingfocus">Managing Focus</a>.
When users are moving focus among items in a <code>listview</code>, authors SHOULD set focus as follows:
</p>
<ul>
<li>
If a <rref>listviewitem</rref> contains a single interactive <rref>widget</rref> that does not consume arrow key presses when it is focus, such as a <rref>checkbox</rref>, <rref>button</rref>, or <rref>link</rref>, focus is set on that contained interactive element instead of on the containing <rref>listviewitem</rref>.
This allows the contained widget to be immediately operable and enables assistive technologies to expose the role, name, value, and state of the contained element.
</li>
<li>Otherwise, focus is set on a <rref>listviewitem</rref> element.</li>
</ul>
<p>Authors SHOULD provide a mechanism for moving focus into and out of a <rref>listviewitem</rref> that allows users to navigate and interact with content contained by the <rref>listviewitem</rref> if the <rref>listviewitem</rref> contains any of the following:</p>
<ul>
<li>a widget that requires arrow keys to operate, e.g., a <rref>combobox</rref> or <rref>radiogroup</rref></li>
<li>multiple interactive elements</li>
<li>editable content</li>
</ul>
<p>
Depending on the implementation, pressing <kbd>Enter</kbd>, <kbd>Space</kbd>, or another key would move focus from the <rref>listviewitem</rref> to a focusable element inside the <rref>listviewitem</rref>.
Then, pressing <kbd>Enter</kbd> again, <kbd>Tab</kbd>, <kbd>Escape</kbd>, or another key would place focus back on the parent <rref>listviewitem</rref> element so users can continue navigating the <code>listview</code>.
For example, if an item in a list of video preview cards contains a video player, the <kbd>Enter</kbd> key might be used to move focus from the <rref>listviewitem</rref> to the play button of the contained player.
The card might then trap focus so users can easily use the <kbd>Tab</kbd> key to navigate among the player's controls and then use the <kbd>Esc</kbd> key or a dynamically rendered close button to return focus to the card.
</p>
<p>
The <code>listview</code> role does not assume any particular form of visual presentation.
A <code>listview</code> can scroll in any direction as users move focus.</code>
Items can be arranged in a single column, a single row, or in multiple columns or rows.
Authors SHOULD indicate whether the order of the collection is presented horizontally or vertically with <pref>aria-orientation</pref>.
For example, if a set of twenty cards is presented in a vertical list that is wrapped into five columns that contain four cards, authors SHOULD set <pref>aria-orientation</pref> to <code>vertical</code>.
Copy link
Contributor

Choose a reason for hiding this comment

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

IMO: The value "vertical" would inform screen reader users only that they can use up and down arrow keys to muve through the list. To signal to the users that they can move vertically and horizontally - such as the case in a dashboard - would require a new value for "aria-orientation" in addition to vertical and horizontal. It could be "gridlike", "all" or something similar.

Copy link
Contributor

Choose a reason for hiding this comment

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

My first thought was that this could provide support for languages that are vertical. I wonder if aria-orientation could have a default value of any (or similar) but could also accept author provided values of horizontal or vertical?

This would inform assistive technology users that moving focus with the down arrow key would move focus from the first card to the second card whereas pressing the right arrow key (if supported) would move focus from the first card to the fifth card.
</p>
<p>
Since <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> can augment an element of the host language, a <code>listview</code> can reuse the elements and attributes of a native list, such as an HTML <code>ul</code> element.
For example, if an author applies the <code>listview</code> role to an HTML <code>ul</code> element, the author does not need to apply the <rref>listviewitem</rref> role to the descendant HTML <code>li</code> elements because the <a>user agent</a> will automatically make the appropriate translations.
</p>
</div>
<table class="role-features">
<caption>Characteristics:</caption>
<thead>
<tr>
<th scope="col">Characteristic</th>
<th scope="col">Value</th>
</tr>
</thead>
<tbody>
<tr>
<th class="role-abstract-head" scope="row">Is Abstract:</th>
<td class="role-abstract"> </td>
</tr>
<tr>
<th class="role-parent-head" scope="row">Superclass Role:</th>
<td class="role-parent">
<ul>
<li><rref>composite</rref></li>
<li><rref>list</rref></li>
</ul>
</td>
</tr>
<tr>
<th class="role-children-head" scope="row">Subclass Roles:</th>
<td class="role-children">Placeholder</td>
</tr>
<tr>
<th class="role-base-head" scope="row">Base Concept:</th>
<td class="role-base"><code>&lt;[^ul^]&gt;</code> in HTML</td>
</tr>
<tr>
<th class="role-related-head" scope="row">Related Concepts:</th>
<td class="role-related"> </td>
</tr>
<tr>
<th class="role-scope-head" scope="row">Required Accessibility Parent Roles:</th>
<td class="role-scope"></td>
</tr>
<tr>
<th class="role-mustcontain-head" scope="row">Allowed Accessibility Child Roles:</th>
<td class="role-mustcontain"><rref>listviewitem</rref></td>
</tr>
<tr>
<th class="role-required-properties-head">Required States and Properties:</th>
<td class="role-required-properties"> </td>
</tr>
<tr>
<th class="role-properties-head" scope="row">Supported States and Properties:</th>
<td class="role-properties">
<ul>
<li><pref>aria-multiselectable</pref></li>
<li><pref>aria-orientation</pref></li>
</ul>
</td>
</tr>
<tr>
<th class="role-inherited-head" scope="row">Inherited States and Properties:</th>
<td class="role-inherited">Placeholder</td>
</tr>
<tr>
<th class="role-namefrom-head" scope="row">Name From:</th>
<td class="role-namefrom">author</td>
</tr>
<tr>
<th class="role-namerequired-head" scope="row">Accessible Name Required:</th>
<td class="role-namerequired">True</td>
</tr>
<tr>
<th class="role-namerequired-inherited-head" scope="row">Inherits Name Required:</th>
<td class="role-namerequired-inherited"> </td>
</tr>
<tr>
<th class="role-childpresentational-head" scope="row">Children Presentational:</th>
<td class="role-childpresentational"> </td>
</tr>
<tr>
<th class="role-presentational-inherited-head" scope="row">Inherits Presentational:</th>
<td class="role-presentational-inherited"> </td>
</tr>
</tbody>
</table>
</div>
<div class="role" id="listviewitem">
<rdef>listviewitem</rdef>
<div class="role-description">
<p>An item in a <rref>listview</rref>.</p>
<p>
A <code>listviewitem</code> can be focusable and selectable.
As described in the definition of <rref>listview</rref>, if a <code>listviewitem</code> contains a single interactive element, authors SHOULD set focus on the contained element in lieu of focusing the <code>listviewitem</code>.
Otherwise, authors SHOULD ensure a <code>listviewitem</code> is focusable.
</p>
<p>
If a <code>listviewitem</code> is focusable, authors MUST specify an accessible name.
For simple items, authors MAY simply specify a label that contains all the item's content, e.g., specify an <code>id</code> for the item and reference it with <pref>aria-labelledby</pref>.
However, for more complex rich content where authors have provided a method for moving focus inside of the <code>listviewitem</code> as described in <rref>listview</rref>, authors can provide assistive technology users with a more efficient navigation experience by providing a concise accessible name and description.
In such implementations, authors MAY use <pref>aria-labelledby</pref> or <pref>aria-label</pref> to specify a sufficiently distinct and concise name.
In addition, authors MAY apply <pref>aria-describedby</pref> to <rref>listviewitem</rref> elements in a <code>listview</code> to suggest to screen readers which elements contained by the <code>listviewitem </code> to announce after its label when users navigate by <rref>listviewitem</rref>.
This enables authors to create a navigation experience that filters out repetitive or less important elements, such as embedded interaction widgets that appear in every item.
</p>
<p>
A <code>listviewitem</code> <a>element</a> can contain a nested collection of <code>listviewitem</code> elements.
A nested collection of <code>listviewitem</code> elements is enclosed in an element with the <rref>group</rref> <a>role</a>.
Authors can enable users to control the visibility and focusability of a nested collection, i.e., make it expandable and collapsable.
If the nested group of <code>listviewitem</code> elements can be expanded and collapsed, authors MUST specify a value for <sref>aria-expanded</sref> on the <code>listviewitem</code that contains the group.
</p>
<p>Authors MUST ensure [=elements=] with <a>role</a> <code>listviewitem</code> are <a>accessibility children</a> of an element with <a>role</a> <rref>listview</rref> or an element with <a>role</a> <rref>group</rref> that is the <a>accessibility child</a> of an element with role <rref>listviewitem</rref>.</p>
<p>
Authors MAY indicate selection for <rref>listviewitem</rref> elements using either <sref>aria-selected</sref> or <sref>aria-checked</sref>.
Some user interfaces indicate selection with <sref>aria-selected</sref> in single-select listviews and with <sref>aria-checked</sref> in multi-select listviews.
Authors SHOULD NOT specify both <sref>aria-selected</sref> and <sref>aria-checked</sref> on <rref>listviewitem</rref> elements contained by the same <rref>listview</rref> except in the extremely rare circumstances where all the following conditions are met:
</p>
<ul>
<li>The meaning and purpose of <sref>aria-selected</sref> is different from the meaning and purpose of <sref>aria-checked</sref> in the user interface.</li>
<li>The user interface makes the meaning and purpose of each state apparent.</li>
<li>The user interface provides a separate method for controlling each state.</li>
</ul>
<p>User agents MUST NOT provide an implicit value for <sref>aria-selected</sref> for <code>listviewitem</code> elements.</p>
</div>
<table class="role-features">
<caption>Characteristics:</caption>
<thead>
<tr>
<th scope="col">Characteristic</th>
<th scope="col">Value</th>
</tr>
</thead>
<tbody>
<tr>
<th class="role-abstract-head" scope="row">Is Abstract:</th>
<td class="role-abstract"> </td>
</tr>
<tr>
<th class="role-parent-head" scope="row">Superclass Role:</th>
<td class="role-parent">
<ul>
<li><rref>listitem</rref></li>
<li><rref>widget</rref></li>
</ul>
</td>
</tr>
<tr>
<th class="role-children-head" scope="row">Subclass Roles:</th>
<td class="role-children">Placeholder</td>
</tr>
<tr>
<th class="role-base-head" scope="row">Base Concept:</th>
<td class="role-base"><code>&lt;[^li^]&gt;</code> in HTML</td>
</tr>
<tr>
<th class="role-related-head" scope="row">Related Concepts:</th>
<td class="role-related"> </td>
</tr>
<tr>
<th class="role-scope-head" scope="row">Required Accessibility Parent Roles:</th>
<td class="role-scope">
<ul>
<li><rref>listview</rref></li>
<li><rref>group</rref> with <a>accessibility parent</a> <rref>listviewitem</rref></li>
</ul>
</td>
</tr>
<tr>
<th class="role-mustcontain-head" scope="row">Allowed Accessibility Child Roles:</th>
<td class="role-mustcontain"> </td>
</tr>
<tr>
<th class="role-required-properties-head">Required States and Properties:</th>
<td class="role-required-properties"> </td>
</tr>
<tr>
<th class="role-properties-head" scope="row">Supported States and Properties:</th>
<td class="role-properties">
<ul>
<li><rref>aria-checked</rref></li>
<li><sref>aria-disabled</sref></li>
<li><sref>aria-expanded</sref></li>
<li><pref>aria-level</pref></li>
<li><sref>aria-selected</sref></li>
</ul>
</td>
</tr>
<tr>
<th class="role-inherited-head" scope="row">Inherited States and Properties:</th>
<td class="role-inherited">Placeholder</td>
</tr>
<tr>
<th class="role-namefrom-head" scope="row">Name From:</th>
<td class="role-namefrom">author</td>
</tr>
<tr>
<th class="role-namerequired-head" scope="row">Accessible Name Required:</th>
<td class="role-namerequired">When Focusable</td>
</tr>
<tr>
<th class="role-namerequired-inherited-head" scope="row">Inherits Name Required:</th>
<td class="role-namerequired-inherited"> </td>
</tr>
<tr>
<th class="role-childpresentational-head" scope="row">Children Presentational:</th>
<td class="role-childpresentational"> </td>
</tr>
<tr>
<th class="role-presentational-inherited-head" scope="row">Inherits Presentational:</th>
<td class="role-presentational-inherited"> </td>
</tr>
</tbody>
</table>
</div>
<div class="role" id="log">
<rdef>log</rdef>
<div class="role-description">
Expand Down
Loading