From ab1c307e93e4952990b05e931bd80bf3a53f35ee Mon Sep 17 00:00:00 2001
From: Sarah <gerrardsarah@gmail.com>
Date: Tue, 5 Sep 2023 14:48:27 -0700
Subject: [PATCH] [joy-ui][docs] Revise the Lists page (#36324)

Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>
Signed-off-by: Danilo Leal <67129314+danilo-leal@users.noreply.github.com>
Co-authored-by: siriwatknp <siriwatkunaporn@gmail.com>
Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Co-authored-by: Danilo Leal <67129314+danilo-leal@users.noreply.github.com>
---
 .../components/autocomplete/autocomplete.md   |   2 +-
 docs/data/joy/components/list/list.md         | 228 +++++++++++-------
 docs/data/joy/components/menu/menu-pt.md      |   2 +-
 docs/data/joy/components/menu/menu-zh.md      |   2 +-
 docs/data/joy/components/menu/menu.md         |   2 +-
 5 files changed, 142 insertions(+), 94 deletions(-)

diff --git a/docs/data/joy/components/autocomplete/autocomplete.md b/docs/data/joy/components/autocomplete/autocomplete.md
index 76752ae8c694ce..5368acaf2b8b82 100644
--- a/docs/data/joy/components/autocomplete/autocomplete.md
+++ b/docs/data/joy/components/autocomplete/autocomplete.md
@@ -173,7 +173,7 @@ You could also display a dialog when the user wants to add a new value.
 {{"demo": "FreeSoloCreateOptionDialog.js"}}
 
 :::info
-The `AutocompleteOption` uses the same styles and variables as [`ListItemButton`](/joy-ui/react-list/#actionable), so that you get the same customization experience.
+The `AutocompleteOption` uses the same styles and variables as [`ListItemButton`](/joy-ui/react-list/#interactive-list-items), so that you get the same customization experience.
 :::
 
 ### Validation
diff --git a/docs/data/joy/components/list/list.md b/docs/data/joy/components/list/list.md
index 5ebd9217aa5757..3d641b86a6a0d2 100644
--- a/docs/data/joy/components/list/list.md
+++ b/docs/data/joy/components/list/list.md
@@ -7,108 +7,151 @@ githubLabel: 'component: list'
 
 # Lists
 
-<p class="description">Lists are continuous, vertical indexes of text or images.</p>
+<p class="description">Lists are organizational tools that enhance the readability and organization of content.</p>
 
 ## Introduction
 
-Joy UI provides four list-related components:
+Lists present information in a concise, easy-to-follow format through a continuous, vertical index of text or images.
 
-- [`List`](#basic-usage): A wrapper for list items (defaulting as `ul`).
-- [`ListItem`](#basic-usage): A common list item (default as `li`).
-- [`ListItemButton`](#actionable): An action element to be used inside a list item.
-- [`ListItemDecorator`](#decorator): A decorator of a list item, usually used to display an icon.
-- [`ListItemContent`](#ellipsis-content): A container inside a list item, used to display text content.
-- [`ListDivider`](#divider): A separator between list items.
-- [`ListSubheader`](#nested-list): A label for a nested list.
+Joy UI Lists are implemented using a collection of related components:
 
-{{"demo": "ListUsage.js", "hideToolbar": true, "bg": "gradient"}}
+- [List](#basics) - a wrapper for list items. Renders as a `<ul>` by default.
+- [List Item](#basics) - a common list item. Renders as an `<li>` by default.
+- [List Item Button](#interactive-list-items) - an action element to be used inside a list item.
+- [List Item Decorator](#decorators) - a decorator of a list item, usually used to display an icon.
+- [List Item Content](#ellipsis-content) - a container inside a list item, used to display text content.
+- [List Divider](#divider) - a separator between list items.
+- [List Subheader](#nested-list) - a label for a nested list.
 
-## Component
+{{"demo": "ListUsage.js", "hideToolbar": true, "bg": "gradient"}}
 
-After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements:
+## Basics
 
 ```jsx
 import List from '@mui/joy/List';
 import ListItem from '@mui/joy/ListItem';
-
-export default function MyApp() {
-  return (
-    <List aria-label="basic-list">
-      <ListItem>Hello, world!</ListItem>
-      <ListItem>Bye bye, world!</ListItem>
-    </List>
-  );
-}
 ```
 
-### Basic usage
+## Customization
 
-Use the `List` and `ListItem` components to create a basic, non-interactive, list.
-Make sure to use a meaningful name that describe the content of the list in the `aria-labelledby` prop.
+### Variants
 
-{{"demo": "BasicList.js"}}
+The List component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft`, `outlined`, and `plain`.
 
 ### Sizes
 
-Use the `size` prop to control font-size and general list density.
+The List component comes in three sizes: `sm`, `md`, and `lg`.
+The size of the List determines its font size and density.
 
 {{"demo": "SizesList.js"}}
 
 :::info
-To learn how to add more sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
+To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
 :::
 
-### Decorator
+### Colors
 
-Use the `ListItemDecorator` component to add supporting icons or elements to the list item.
+Every palette included in the theme is available via the `color` prop.
 
-It comes with a minimum set width that you can adjust via the `--ListItemDecorator-size` CSS variable within the `List` component.
+### Decorators
+
+```jsx
+import ListItemDecorator from '@mui/joy/ListItemDecorator';
+```
+
+Use the List Item Decorator component to add supporting icons or elements to the list item.
 
 {{"demo": "DecoratedList.js"}}
 
+:::info
+The List Item Decorator comes with a minimum set width that can be adjusted using the `--list-decorator-size` CSS variable within the List component.
+:::
+
+### Horizontal list
+
+Use the `orientation="horizontal"` prop on the List component to display the List horizontally.
+
+{{"demo": "HorizontalList.js"}}
+
+:::warning
+While nested lists will not work in a horizontal direction, you can create a custom pop-up component to achieve a similar effect (see the [Navigation menu](#navigation-menu) example).
+:::
+
+### Semantic elements
+
+Use the `component` prop to control which HTML tag is rendered.
+
+```js
+<List component="ol">
+```
+
+The example below renders the List component as an HTML `<nav>` element.
+
+{{"demo": "NavList.js"}}
+
+:::info
+The List Item component is optional in this case.
+If used, it will automatically change the semantic element from the default `<li>` to `<div>`.
+:::
+
 ### Ellipsis content
 
-When dealing with long content, use the `ListItemComponent` together with `<Typography noWrap>` to show ellipsis.
+```jsx
+import ListItemContent from '@mui/joy/ListItemContent';
+```
+
+When working with longer content in a List, you can use the List Item Content component in combination with `<Typography noWrap />` to display an ellipsis when the content exceeds the available space.
+This can help to keep the List Items visually consistent and prevent text from overflowing outside of the List Item's container.
 
 {{"demo": "EllipsisList.js"}}
 
 ### Divider
 
-The `ListDivider` component comes with four `inset` patterns:
+```jsx
+import ListDivider from '@mui/joy/ListDivider';
+```
+
+The List Divider component comes with four `inset` patterns:
 
-- Default (without providing the `inset` prop): stretches from edge to edge of the list.
-- `inset="gutter"`: from the start of the decorator to the end of the content.
-- `inset="startDecorator"`: from the start of the decorator to the end of the list.
-- `inset="startContent"`: from the start of the content to the end of the list.
+- Default (no `inset` prop provided): stretches form one edge of the List to the other.
+- `inset="gutter"`: from the start of List Item Decorator to the end of the content.
+- `inset="startDecorator"`: from the start of List Item Decorator to the end of the edge of the container.
+- `inset="startContent"`: from the start of the content to the edge of the container.
 
 {{"demo": "DividedList.js"}}
 
-For horizontal list, only `inset="gutter"` works on list divider.
+If you're using a horizontal list, only `inset="gutter"` will work as the list divider.
 
 {{"demo": "HorizontalDividedList.js"}}
 
 ### Sticky item
 
-To have a sticky list item, use a `List` as a child of the `Sheet` component.
-Then, on the item you wish to stick, add the `sticky` prop.
+Use the List component as a child of the Sheet component to create "sticky" items.
+On the item you wish to stick, you can then add the `sticky` prop.
 
-The `Sheet` component automatically adjusts the `sticky` list item to have the same background so that the content does not overflow when scroll.
-It works by default on both light and dark modes.
+The Sheet component automatically adjusts the `sticky` list item to have the same background so that content does not overflow when scrolling.
 
 {{"demo": "StickyList.js"}}
 
+:::info
+By default, this works on both light and dark modes.
+:::
+
 ### Nested list
 
-Use the `nested` prop, within the `ListItem` component, to create a nested list.
-Note that layout and spacing of the nested list remain intact, as if it isn't nested.
+```jsx
+import ListSubheader from '@mui/joy/ListSubheader';
+```
 
-The nested list inherits the list `size` and a few other CSS variables, such as `--List-radius` and `--ListItem-radius` from the root `List` component to adjust the design consistently.
+You can create a nested list using the `nested` prop on a List Item.
+This enables you to add a List Subheader as well as a new List component as children of the List Item.
+The nested List will inherit its `size` as well as other CSS variables like `--List-radius` and `--ListItem-radius` from the root List component to keep the design consistent.
+The layout and spacing of the nested List will remain independent.
 
 {{"demo": "NestedList.js"}}
 
 :::info
-By default, nested lists stick to the left of the root list.
-To add spacing to the start of the nested list, use `--List-nestedInsetStart: ${value}`:
+Nested lists will stick to the left of the root list, by default. If you need to add spacing to the start of the nested list you can use `--List-nestedInsetStart: ${value}`.
 
 ```js
 <List sx={{ '--List-nestedInsetStart': '1rem' }}> {/* This is the root List */}
@@ -116,48 +159,22 @@ To add spacing to the start of the nested list, use `--List-nestedInsetStart: ${
 
 :::
 
-### Horizontal list
-
-To show a list in a horizontal direction, use the `orientation="horizontal"` prop on the `List` component.
-
-:::warning
-Nested lists don't work in the horizontal direction.
-To do that, create a custom pop-up component instead (see the [Navigation menu](#navigation-menu) example).
-:::
-
-{{"demo": "HorizontalList.js"}}
-
-### Changing the semantic element
-
-To control which HTML tag should be rendered in a given, one-off, situation, use the `component` prop.
+### Interactive list items
 
-```js
-<List component="ol">
+```jsx
+import ListItemButton from '@mui/joy/ListItemButton';
 ```
 
-#### Non-list
-
-In the example below, we're rendering a `List` as a HTML `<nav>` element.
-
-:::info
-**Tip**: The `ListItem` component is optional in this case－if used, it will change the semantic element from the default `li` to `div` automatically.
-:::
-
-{{"demo": "NavList.js"}}
-
-### Actionable
-
-To make a list item interactive, use `ListItemButton` **inside** a `ListItem`.
+To make a List Item interactive, you can use List Item Button inside a List Item.
 
 {{"demo": "ActionableList.js"}}
 
-### Secondary action
-
-To add a secondary action to the `ListItemButton`, wrap it in a `ListItem` component and then add the desired start or end action elements to it.
+To add a secondary action to the List Item Button, wrap it in a List Item component and then add the desired start or end action elements to it.
 
 {{"demo": "SecondaryList.js"}}
 
-The `ListItemButton` and the secondary action render as siblings, that way, the semantic rendered element is appropriately adjusted.
+:::info
+The List Item Button and the secondary action render as siblings so that the rendered semantic element is appropriately adjusted.
 
 ```js
 <ul>                    {/* List */}
@@ -166,22 +183,23 @@ The `ListItemButton` and the secondary action render as siblings, that way, the
     <button>            {/* IconButton */}
 ```
 
+:::
+
 ### Selected
 
-Use the `selected` prop to signal whether a `ListItemButton` is selected or not.
-It applies `color="primary"` of the active variant to visually communicate the selected state.
+Use the `selected` prop on the List Item Button component to indicate whether or not an item is currently selected.
+When the item is selected, it applies `color="primary"` and a few extra styles—like font weight—to visually communicate the selected state.
+
+{{"demo": "SelectedList.js"}}
 
 :::info
-A selected `ListItemButton` does not apply `:hover` and `:active` global variant styles.
+A selected List Item Button does not apply `:hover` and `:active` global variant styles.
 :::
 
-{{"demo": "SelectedList.js"}}
-
 ## CSS variables playground
 
-Play around with all the CSS variables available in the list component to see how the design changes.
-
-You can use those to customize the component on both the `sx` prop and the theme.
+Play around with the CSS variables available to the List components to see how the design changes.
+You can use these to customize the components with both the `sx` prop and the theme.
 
 {{"demo": "ListVariables.js", "hideToolbar": true, "bg": "gradient"}}
 
@@ -195,14 +213,14 @@ This example uses nested lists to split the settings into groups.
 
 ### Gmail navigation
 
-Inspired by Gmail's web sidenav.
+Inspired by Gmail's desktop navigation bar.
 
 {{"demo": "ExampleGmailList.js"}}
 
 ### Collapsible list
 
-Inspired by [Gatsby's documentation](https://www.gatsbyjs.com/docs) sidenav.
-This example uses the start action (a prop of `ListItem`) prop to create a collapsible button.
+Inspired by the [Gatsby documentation](https://www.gatsbyjs.com/docs) navbar.
+This example uses the `startAction` prop to create a collapsible button.
 
 {{"demo": "ExampleCollapsibleList.js"}}
 
@@ -214,3 +232,33 @@ This example uses a combination of horizontal and vertical lists to form the nav
 It also supports keyboard navigation, inspired by the [Roving UX](https://github.com/argyleink/roving-ux) technique.
 
 {{"demo": "ExampleNavigationMenu.js"}}
+
+## Accessibility
+
+To ensure that your List is accessible, here are some factors you should consider:
+
+- Use the appropriate HTML semantic element for the list (eg. `ol` or `ul`), to ensure that assistive technologies can correctly interpret the list structure.
+- Make sure to use a meaningful name that describes the content of the list in the `aria-labelledby` prop.
+- Use `role` attributes to provide additional information about the purpose of the list and its items.
+  For example, use `role="list"` for the list and `role="listitem"` for each list item.
+
+## Anatomy
+
+The List component is composed of a root `<ul>` element with one or more child `<li>` elements rendered by the List Item component.
+All components nested inside the List Item are optional.
+The [List Divider](#divider) (when present) renders an `<li>` with `role="separator"`, while the [List Subheader](#nested-list) renders a `<div>`.
+
+```html
+<ul class="MuiList-root">
+  <li class="MuiListItem-root">
+    <div class="MuiListItemButton-root" role="button">
+      <span class="MuiListItemDecorator-root">
+        <!-- Icon for List Item Decorator -->
+      </span>
+      <div class="MuiListItemContent-root">
+        <!-- List Item content -->
+      </div>
+    </div>
+  </li>
+</ul>
+```
diff --git a/docs/data/joy/components/menu/menu-pt.md b/docs/data/joy/components/menu/menu-pt.md
index ea5d562d2509cf..378ef12e9f36e8 100644
--- a/docs/data/joy/components/menu/menu-pt.md
+++ b/docs/data/joy/components/menu/menu-pt.md
@@ -58,7 +58,7 @@ When specifying a size for the `Menu` component, menu items inside of it will in
 
 Use the `selected` prop to signal whether a `MenuItem` is selected or not.
 
-The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#selected).
+The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#interactive-list-items).
 
 {{"demo": "SelectedMenu.js"}}
 
diff --git a/docs/data/joy/components/menu/menu-zh.md b/docs/data/joy/components/menu/menu-zh.md
index ea5d562d2509cf..378ef12e9f36e8 100644
--- a/docs/data/joy/components/menu/menu-zh.md
+++ b/docs/data/joy/components/menu/menu-zh.md
@@ -58,7 +58,7 @@ When specifying a size for the `Menu` component, menu items inside of it will in
 
 Use the `selected` prop to signal whether a `MenuItem` is selected or not.
 
-The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#selected).
+The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#interactive-list-items).
 
 {{"demo": "SelectedMenu.js"}}
 
diff --git a/docs/data/joy/components/menu/menu.md b/docs/data/joy/components/menu/menu.md
index 523e352adf56e5..c6fdcf0f6941eb 100644
--- a/docs/data/joy/components/menu/menu.md
+++ b/docs/data/joy/components/menu/menu.md
@@ -75,7 +75,7 @@ To learn how to add more sizes to the component, check out [Themed components—
 
 Use the `selected` prop to signal whether a `MenuItem` is selected or not.
 
-The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#selected).
+The menu item uses the same styles as the [`ListItemButton`](/joy-ui/react-list/#interactive-list-items).
 
 {{"demo": "SelectedMenu.js"}}