A proposal for an interactive lists role

interactive-list-role.md

Interactive list proposal

This gist is intended to pull in all the various ideas around creating an interactive list ARIA pattern, and document a cohesive proposal for moving forward.

Summary of need

The need for an interactive list pattern has been documented in multiple previous issues, including the following:

• Interactive Lists #2036
• New roles listview and listviewitem needed #1325
• Complex dashboards and standalone cards #2162
• Proposal for "dashboard" and "tile" roles #1994

As a quick overview, the main problem is that while we have an interactive version of a table (grid), the only one-dimensional interactive roles (listbox, menu, tablist, menubar, radiogroup) do not address the need for a more generic invokable list with potentially structured content and nested interactives. The existing roles fall short in the following ways:

• Most are too specific to a given use case (radiogroup, menu/menubar, and tablist)
• Listbox enforces a selected state on options
• All the existing roles either have explicitly presentational children, or (for menuitem) effectively have presentational children with the exception of nested menus.

This previous proposal includes more specifics on why we need an interactive list semantic pattern in addition to other existing roles, as well as a collection of real-world examples. This proposal will focus more on specific spec wording and AAM mappings.

Proposal for API mappings

All existing platforms tested have some type of native interactive list, which gives a good reference for defining a web pattern. A draft proposal for those mappings could be:

• UIA: same as listbox, no implicit SelectionItemPattern, can have InvokePattern, ValuePattern
• IA2: ROLE_SYSTEM_LIST, no implicit accSelect or get_accSelection
• AX API: AXList, no subrole, can have children be AXGroup

Pros/cons of different approaches

There are a few different ways we could approach allowing authors to define interactive lists using roles, attributes, or heuristics. This doc will look at the following possibilities:

1. Add a single new role, listview, that uses the already-existing listitem role for children. Pros: fewer new role additions, don't need to think of a name for the child roles. Cons: creates branching logic for mapping & aria- support tables for listitem.
2. Add two new roles, listview and listviewitem (or something more concise?). Pros: straightforward attribute support tables. Cons: an extra role that seems very similar to listitem in most respects (including mappings).
3. No new roles, and focusable listitems are treated as composite widget roles. Pros: no new roles, could catch and improve existing implementations. Cons: could falsely catch focusable listitems and treat them as part of a composite widget even if that was not the author intent; naming could be divergent between focusable and non-focusable listitems, ref #1800

Proposal for spec language (using listview/listitem)

Draft spec language for listview:

A composite widget that contains a one-dimensional set of list items were some or all of the list items are focusable and navigable with the keyboard, commonly with arrow keys. Listviews contain children whose role is listitem or elements whose role is group which in turn contain children whose role is listitem.

Listview is similar to listbox in that it is a composite widget that contains a list of interactive children. The difference is that listbox enforces a selected state on child options, and enforces presentational children within options. Listview allows selected and checked states on listitems, but does not provide an implicit selected state when not defined by the author. List item children of a listview can contain nested interactive items and phrasing content.

To be keyboard accessible, authors SHOULD manage focus of descendants of a listview as described in Managing Focus.

Characteristics table:

Characteristic	Value
Superclass Role:	section
Related Concepts:	list listbox
Allowed Accessibility Child Roles:	group with child listitem listitem
Supported States and Properties:	aria-errormessage aria-invalid aria-multiselectable aria-orientation aria-required
Inherited States and Properties:	(copy from list)
Name from:	author
Implicit Value for Role:	Default for aria-orientation is vertical.

Draft updated spec language for listitem

A single item in a list, listview, or directory.

Authors MUST ensure elements whose role is listitem are accessibility children of an element whose role is list, listview, or directory, or are accessibility children of an element of role group that is an accessibility child of an element with role listview.

Authors MAY indicate selection for listitem children of a listview using either aria-selected or aria-checked. Some user interfaces indicate selection with aria-selected in single-select listviews and with aria-checked in multi-select listviews. Authors SHOULD NOT specify both aria-selected and aria-checked on listitem elements contained by the same listview except in the extremely rare circumstances where all the following conditions are met:

• The meaning and purpose of aria-selected is different from the meaning and purpose of aria-checked in the user interface.
• The user interface makes the meaning and purpose of each state apparent.
• The user interface provides a separate method for controlling each state.

User agents MUST NOT provide implicit an implicit value for aria-selected for listitems in a listview.

While the listitem role can be used in both interactive listviews and non-interactive lists, the use of the following attributes is only applicable to interactive elements. Therefore, authors SHOULD NOT use any of the attributes in the following list on a listitem that does not descend from a listview, and user agents SHOULD NOT expose these properties to assistive technologies unless the listitem descends from a listview:

• aria-checked
• aria-disabled
• aria-errormessage
• aria-expanded
• aria-haspopup
• aria-invalid
• aria-readonly
• aria-required
• aria-selected

Characteristics table

(only including changed rows)

Characteristic	Value
Required Accessibility Parent Roles:	directory list listview group with accessibility parent tree
Supported States and Properties:	aria-checked aria-disabled aria-errormessage aria-expanded aria-haspopup aria-invalid aria-posinset aria-readonly aria-required aria-selected aria-setsize
Name from:	contents author

Open Questions

• For screen reader vendors: do you forsee any issues with allowing virtual cursor navigation inside an interactive list, and with including rich content?
• For screen reader vendors: are there any concerns with being able to differentiate listviews that have children with aria-selected from listboxes? Or with differentiating listviews from static lists, especially for the purpose of automatic mode switching?
• Should we allow aria-expanded on listitems as something like a more simple tree with better support for phrasing content?
• Should we allow nested listviews, similar to HTML lists? (Another option might be group instead, since no other composite widgets have that nesting pattern, and I also haven't seen any native OS examples of this)