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.

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

[doc update] Structured list #2717

Merged
merged 3 commits into from
Feb 18, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
118 changes: 92 additions & 26 deletions src/pages/components/structured-list/usage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,46 @@ definitions.

<AnchorLinks>

<AnchorLink>Overview</AnchorLink>
<AnchorLink>Live demo</AnchorLink>
<AnchorLink>Formatting</AnchorLink>
<AnchorLink>Content</AnchorLink>
<AnchorLink>Interactions</AnchorLink>
<AnchorLink>Related</AnchorLink>
<AnchorLink>Feedback</AnchorLink>

</AnchorLinks>

## Overview

Structured list displays a simple list with a considerable amount of items of
read-only values. It helps organize and present grouped information into logical
and scannable patterns. The content within a list can be stacked to create
hierarchy within the data.

#### When to use

- To browse information or select certain information within the group in the
simplest form
- To view description and detailed information, present features, or compare
pricing plans

#### When not to use

Nesting items is not recommended, as structured lists are used to present simple
data. If you have more than 25 items or additional content that needs to be
shown, consider using a
[data table](https://www.carbondesignsystem.com/components/data-table/usage/),
which supports nesting items and presents a larger set of content.

### Variants

| Variant | Purpose |
| ------------ | ----------------------------------------------------------------------------- |
| _Default_ | Allows the user to quickly browse and view information within a group of data |
| _Selectable_ | Allows the user to mark or select a desired option within a group of data |

## Live demo

import { CheckmarkFilled16 } from '@carbon/icons-react';

<ComponentDemo
Expand All @@ -34,19 +68,21 @@ import { CheckmarkFilled16 } from '@carbon/icons-react';
label: 'Selectable structured list',
},
]}
scope={{ CheckmarkFilled16 }}>
scope={{ CheckmarkFilled16 }}
>
<ComponentVariant
id="default-structured-list"
links={{
React:
'https://react.carbondesignsystem.com/?path=/story/components-structuredlist--simple',
Angular:
'https://angular.carbondesignsystem.com/?path=/story/components-structured-list--basic',
Vue:
'http://vue.carbondesignsystem.com/?path=/story/components-cvstructuredlist--default',
Vue: 'http://vue.carbondesignsystem.com/?path=/story/components-cvstructuredlist--default',
Vanilla: 'https://the-carbon-components.netlify.com/?nav=structured-list',
"Web Components": 'https://web-components.carbondesignsystem.com/?path=/story/components-structured-list--default',
}}>{`
'Web Components':
'https://web-components.carbondesignsystem.com/?path=/story/components-structured-list--default',
}}
>{`
<StructuredListWrapper ariaLabel="Structured list">
<StructuredListHead>
<StructuredListRow
Expand Down Expand Up @@ -97,11 +133,12 @@ import { CheckmarkFilled16 } from '@carbon/icons-react';
'https://react.carbondesignsystem.com/?path=/story/components-structuredlist--selection',
Angular:
'https://angular.carbondesignsystem.com/?path=/story/components-structured-list--with-selection',
Vue:
'http://vue.carbondesignsystem.com/?path=/story/components-cvstructuredlist--selectable-with-events',
Vue: 'http://vue.carbondesignsystem.com/?path=/story/components-cvstructuredlist--selectable-with-events',
Vanilla: 'https://the-carbon-components.netlify.com/?nav=structured-list',
"Web Components": 'https://web-components.carbondesignsystem.com/?path=/story/components-structured-list--default',
}}>{`
'Web Components':
'https://web-components.carbondesignsystem.com/?path=/story/components-structured-list--default',
}}
>{`
<StructuredListWrapper selection ariaLabel="Structured list">
<StructuredListHead>
<StructuredListRow
Expand Down Expand Up @@ -199,20 +236,44 @@ import { CheckmarkFilled16 } from '@carbon/icons-react';
`}</ComponentVariant>
</ComponentDemo>

## Formatting

### Anatomy

Structured list is composed of two sections—column header and data row.

<Row>
<Column colLg={8}>

![data table anatomy](images/structured-list-usage-1.png)

</Column>
</Row>

1. **Column header**: Shows titles for the row header description.
2. **Data row**: Shows different types of data. Rows can be selectable and
modified to show alternating zebra stripe background colors

### Sizing

Row height varies based on content and can expand to fit multiple lines. In a
single list, all rows do not have to be the same height. Column widths can
either be equally proportional or proportioned based on content.

## Content

- Row height varies based on content and can expand to fit multiple lines.
- In a single list, all rows do not have to be the same height.
- Column widths can either be equally proportional or proportioned based on
content.
- If a list extends past 25 items, consider using a
[data table](/components/data-table/usage) to present this larger set of
content.
- A maximum of one paragraph of text is recommended per row.
- Nesting items is not recommended, as structured lists are used to present
simple data. If you have additional content that needs to be shown, consider
using a [data table](/components/data-table/usage), which supports nesting
items.
- A maximum of three paragraphs of text is recommended per row.
- A structured list’s title and row information should use sentence-case
capitalization.

#### Column header titles

- Column header titles should be short and clear, sticking to one or two words
that describe the data in that column.
- In cases where a column header title is too long, wrap the text to two lines
and then truncate the rest of the text. The full text should be shown in a
tooltip on hover.
- Column header titles should use sentence-case capitalization.

<Row>
<Column colLg={8}>
Expand All @@ -224,10 +285,7 @@ import { CheckmarkFilled16 } from '@carbon/icons-react';

## Interactions

Structured lists can be single-select if a user is choosing between a set of
options.

#### Guidelines:
#### Selectable structured list

- Only one item can be selected from the list.
- By default, one option should be selected.
Expand All @@ -236,6 +294,14 @@ options.
- When the user selects an item from the list, the selected row will appear with
the `checkmark--filled` icon.

## Related

These following components are additional ways to organize a group of data.

- [Accordion](https://www.carbondesignsystem.com/components/accordion/usage/)
- [Data table](https://www.carbondesignsystem.com/components/data-table/usage/)
- [List](https://www.carbondesignsystem.com/components/list/usage/)

## Feedback

Help us improve this component by providing feedback, asking questions, and
Expand Down