Contained list versus Structured List, and their place within the list <> data table continuum ♿

[mbgower]

Intro

This is a summary of the various conflicting information and considerations between the documentation of Contained List versus Structured list (as well as how they fit on the spectrum between List and the single selectable row version of Data table).

It is drawn from comments in the PDF reviews of these topics, which have more detailed comments and should be reviewed independently by anyone considering updating the documentation:

• Structure list reviews
• Contained list review

It is also additional to existing issues opened against these components, such as carbon-design-system/carbon-website#3632, #11506, #14174

---

The high level themes are as follows:

• structured and contained lists, despite having very similar origins (data table 'lite') and intended uses, have unaligned variants
• both of them deviate significantly from the presentation of selectable data tables, and the reasons are unclear
• the contained list has 2 kinds of search mechanisms; the structured list has none. Yet they both offer single-select versions
• both are considered 'read-only' but both also allow deletion; so maybe it would be better to call them something else like "uneditable" or "unalterable" data?

I'll discuss each of these themes in turn.

Unaligned variants

The structured lists are divided by function (Default, Selectable) while the contained lists are divided by visual style differences (On-page list, Disclosed list).

The contained lists have dedicated sub-sections listing each of these interactions:

• clickable rows
• inline actions
• interactive elements
• search and filtering
• scrolling

Structured list has a simple Interactions heading with a few 'rules' listed under "Selectable structured list" (few if any of which are given for contained lists):

– Only one item can be selected from the list.
– By default, one option should be selected.
– If you need to select multiple items, use a data table.
– When the user selects an item from the list, the selected row will appear
with the icon.

I infer that both list types share most if not all these features -- and where they do not, those become some of the distinguishing features between them. The distinction (and shared features) should be much more clearly indicated for both components.

I think consistent variant names between them (where they share similar qualities) would really help. For example, 'Read-only' and 'Interactive' (or 'Selectable' or 'Actionable' -- or possibly those are additional variants, where warranted).

I think a lot of the visual differences discussed in the contained list variants could be tackled in the Style tab -- and I suspect they apply to all variants for both components? As always, I tend to advocate for differences in interaction being a really good decision point for defining variants. It allows for matching anatomy sections, and provides much clearer abilities to describe accessibility considerations (since non-operable versions have little to cover).

I also wonder if the components should be renamed to make them easier to compare (e.g., List-simple, List-contained, List-structured). Obviously the organizing/naming of the components within Carbon has quite a bit to do with how important it is seen to position them within the List <> Data table continuum. (Also bearing in mind that Data table--which lists variants of Default, Selection and Expansion--fails to add in Sortable and other interactions which could themselves be variants).

List versus table row selection indicators.

I already have an issue open about Structured list selection indicators, #11506 . All the concerns there seem to apply to selectable contained lists as well. There was a proposed WCAG addition to ensure that elements that were operable had a visual affordance before the user began interacting with it (i.e., users should understand component operation without having to 'accidentally' discover it based on hover, etc). Unfortunately wording could not be proposed to make this predictably testable, but the need is real.

I encourage Carbon to adopt a consistent single-select model, based on the radio-button group behaviour.

Search/FIltering mechanisms

The contained list has 2 kinds of search mechanisms; the structured list gives none. Is that accurate, or does the structured list also have search/filtering capabilities, just not specified?

An issue has already been opened against the On Focus failure of the expandable search. While the persistent search doesn't have the same problem, I would like to better understand the intended usage of both search/filter mechanisms. I note there is a stated limit of 25 items on structured list. Is that why there is no filter mechanism? Perhaps contained lists have an unlimited number, and so need the filtering? I don't really understand the use case for this. Are these lists expected to get into the tens and hundreds of items?
Is that really a good use case for a persistent list? Isn't that more of a dropdown function?

'Read-only' versus 'deletion'

Both components offer single-select versions. Both are considered 'read-only' but both also allow deletion. Normally, you cannot do anything to read-only material. For example, here's a first hit on searching "read-only data features":

Read-only is a file attribute which only allows a user to view a file, restricting any writing to the file. Setting a file to “read-only” will still allow that file to be opened and read; however, changes such as deletions, overwrites, edits or name changes cannot be made.

So I feel like maybe Carbon needs another term. I think the idea being discussed is that the information cannot be edited or altered, but list items can be deleted? It might be better to call them something else like "uneditable" or "unalterable" data? I don't have any great suggestion, except to expand on the intended interaction in the usage sections.

[mbgower]

This comment may become its own issue (or part of a future issue I'll likely open on Contained list) but based on a slack with @janhassel and @andreancardona, I thought I'd better add a bit of that conversation here.

Hey folks. Quick question irt to the a11y discussion around ContainedList. I’ve been trying to follow the conversation through the GitHub issues but am unsure if I get the whole picture.
#13950
In this issue Andrea mentioned that the semantics should be switched to a table. Are you only talking about the example with the column-style or the entire component? Because from Taylor’s comment in #13849 (comment) it sounds like the entire component should be refactored from a list to a table and I wonder how to properly implement use cases like these then where the individual items have different structures?

Andrea Cardona
7:02 AM
Hey
@jan.hassel
that's a good question! I'm not sure - we haven't looked at this specific use case - I'll have to talk to Gower and Taylor more about this - thank you for bringing it up!

Michael Gower
7:40 AM
Wow, that’s a pretty interesting interaction! From what I see, it has the following

• disclosure pattern (which isn’t a surprise in a disclosed list, I guess!)
• superfluous heading. Unless there’s a situation where multiple different kinds of lists are stacked in this dropdown, wouldn’t the name of this button be “Tasks” with no need to list that in the disclosure?
• Non-interactive section names (Active, Failed), which interestingly enough would appear to be status categorizations, and so may appear dynamically? I also wondered if something that’s run is really “Active”, or if there’s going to be an additional category called “Successfuly” or something
• second (dynamic?) line for one item (“Data task”)
• real-time information on status (“Processing” plus blue animated icon)
• Icon-based outcome status (green tick mark, red fail)
• Ability to delete/remove items from list?! (icons at end of each list item)

I realize that this visual is on the Usage page. In hindsight, I ’bleeped” over some of these examples when I was doing my review, because a) the particulars are not documented on the Usage page, b) there is no such implementation on storybook, c) experience has led me to spend less time on non-interactive examples. So my apologies I’m only flagging these things now. We could probably spend quite a bit of time on some of these points, so maybe I should transfer this into part of the issue I opened on Contained lists…?

In regard to Jan’s statement, IMO these single-column lists (disregarding the action icons) don’t need to be constructed as tables. I suspect that the disclosed contained lists, overall, are less beneficial to be tables. It just seems a bit problematic to me at a gut level for a screen reader to navigate a table in a disclosure pattern, where the arrow key interaction of table navigation is likely to conflict with the arrow key navigation of the dropdown items.