[Tree View] Polish the default design & revise the simple version pages

docs/data/tree-view/overview/overview.md

@@ -9,31 +9,36 @@ packageName: '@mui/x-tree-view'
 
 # MUI X Tree View
 
-<p class="description">A Tree View widget presents a hierarchical list.</p>
-
-Tree views can be used to represent a file system navigator displaying folders and files, an item representing a folder can be expanded to reveal the contents of the folder, which may be files, folders, or both.
+<p class="description">The Tree View component lets users navigate hierarchical lists of data with nested levels that can be expanded and collapsed.</p>
 
 {{"component": "modules/components/ComponentLinkHeader.js"}}
 
 ## Available components
 
-There are two versions of the Tree View available.
+The MUI X Tree View package exposes two different versions of the component:
+
+### Simple Tree View
 
-### SimpleTreeView
+```jsx
+import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
+```
 
-The `SimpleTreeView` component receives its items as JSX children.
-It is designed for simple use-cases where the items are hardcoded.
+The simple version of the Tree View component receives its items as JSX children.
+This is the recommended version for hardcoded items.
 
 {{"demo": "BasicSimpleTreeView.js"}}
 
-:::warning
-Most new advanced features won't be available on this component.
-If you are waiting for features like editing or virtualization, you should use `RichTreeView` instead.
-:::
+### Rich Tree View
 
-### RichTreeView
+```jsx
+import { RichTreeView } from '@mui/x-tree-view/RichTreeView';
+```
 
-The `RichTreeView` component receives its items through the `items` prop.
-It is designed for more advanced use-cases where the items are dynamically loaded from a data source.
+The rich version of the Tree View component receives its items dynamically from an external data source.
+This is the recommended version for larger trees, as well as those that require more advanced features like editing and virtualization.
 
 {{"demo": "BasicRichTreeView.js"}}
+
+:::info
+At the moment, the Simple and Rich Tree Views are similar in terms of feature support. But as the component grows, you can expect to see the more advanced ones appear primarily on the Rich Tree View.
+:::

docs/data/tree-view/rich-tree-view/items/items.md

@@ -100,7 +100,7 @@ Unlike the `SimpleTreeView` component, the `RichTreeView` component only support
 
 ## Disabled items
 
-You can disable some of the items using the `isItemDisabled` prop on the `RichTreeView` component:
+Use the `isItemDisabled` prop on the Rich Tree View to disable interaction and focus on a Tree Item:
 
 ```tsx
 function isItemDisabled(item) {
@@ -116,29 +116,27 @@ function isItemDisabled(item) {
 Just like the `items` prop, the `isItemDisabled` function should keep the same JavaScript reference between two renders.
 Otherwise, the Tree View will re-generate its entire structure.
 
-It could be achieved by either defining the prop outside the component scope or by memoizing using the `React.useCallback` hook if the function reuses something from the component scope.
+This can be achieved by either defining the prop outside the component scope or by memoizing using the `React.useCallback` hook if the function reuses something from the component scope.
 :::
 
-### Interact with disabled items
+### The disabledItemsFocusable prop
 
-The behavior of disabled tree items depends on the `disabledItemsFocusable` prop.
+Use the `disabledItemsFocusable` prop to control whether or not a disabled Tree Item can be focused.
 
-If it is false:
+When this prop is set to false:
 
-- Arrow keys will not focus disabled items, and the next non-disabled item will be focused.
-- Typing the first character of a disabled item's label will not focus the item.
+- Navigating with keyboard arrow keys will not focus the disabled items, and the next non-disabled item will be focused instead.
+- Typing the first character of a disabled item's label will not move the focus to it.
 - Mouse or keyboard interaction will not expand/collapse disabled items.
 - Mouse or keyboard interaction will not select disabled items.
-- Shift + arrow keys will skip disabled items, and the next non-disabled item will be selected.
+- <kbd class="key">Shift</kbd> + arrow keys will skip disabled items, and the next non-disabled item will be selected instead.
 - Programmatic focus will not focus disabled items.
 
-If it is true:
+When it's set to true:
 
-- Arrow keys will focus disabled items.
-- Typing the first character of a disabled item's label will focus the item.
+- Navigating with keyboard arrow keys will focus disabled items.
+- Typing the first character of a disabled item's label will move focus to it.
 - Mouse or keyboard interaction will not expand/collapse disabled items.
 - Mouse or keyboard interaction will not select disabled items.
-- Shift + arrow keys will not skip disabled items but, the disabled item will not be selected.
+- <kbd class="key">Shift</kbd> + arrow keys will not skip disabled items, but the disabled item will not be selected.
 - Programmatic focus will focus disabled items.
-
-{{"demo": "DisabledItemsFocusable.js", "defaultCodeOpen": false}}

docs/data/tree-view/simple-tree-view/customization/CustomContentTreeView.js

@@ -56,7 +56,7 @@ const CustomContent = React.forwardRef(function CustomContent(props, ref) {
       ref={ref}
     >
       <div className={classes.iconContainer}>{icon}</div>
-      <Box sx={{ flexGrow: 1, display: 'flex', gap: 2 }}>
+      <Box sx={{ flexGrow: 1, display: 'flex', gap: 1 }}>
         <Avatar
           sx={(theme) => ({
             background: theme.palette.primary.main,

docs/data/tree-view/simple-tree-view/customization/CustomContentTreeView.tsx

@@ -64,7 +64,7 @@ const CustomContent = React.forwardRef(function CustomContent(
       ref={ref as React.Ref<HTMLDivElement>}
     >
       <div className={classes.iconContainer}>{icon}</div>
-      <Box sx={{ flexGrow: 1, display: 'flex', gap: 2 }}>
+      <Box sx={{ flexGrow: 1, display: 'flex', gap: 1 }}>
         <Avatar
           sx={(theme) => ({
             background: theme.palette.primary.main,

docs/data/tree-view/simple-tree-view/customization/customization.md

@@ -66,4 +66,7 @@ The demo below shows many of the previous customization examples brought togethe
 Google's Gmail side nav is potentially one of the web's most famous tree view components.
 The demo below shows how to replicate it.
 
+The Gmail sidebar is one of the most well known examples of a tree view.
+The demo below shows how to recreate it with the Tree View component:
+
 {{"demo": "GmailTreeView.js"}}

docs/data/tree-view/simple-tree-view/expansion/expansion.md

@@ -9,13 +9,12 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
 
 # Simple Tree View - Expansion
 
-<p class="description">Handle how users can expand items.</p>
+<p class="description">Learn how to handle expanding and collapsing Tree View items.</p>
 
 ## Controlled expansion
 
 Use the `expandedNodes` prop to control the expanded items.
-
-You can use the `onExpandedNodesChange` prop to listen to changes in the expanded items and update the prop accordingly.
+You can also use the `onExpandedNodesChange` prop to listen to changes in the expanded items and update the prop accordingly.
 
 {{"demo": "ControlledExpansion.js"}}
 
@@ -29,6 +28,6 @@ Learn more about the _Controlled and uncontrolled_ pattern in the [React documen
 
 ## Track node expansion change
 
-Use the `onNodeExpansionToggle` prop if you want to react to a node expansion change:
+Use the `onNodeExpansionToggle` prop to trigger an action upon a node being expanded.
 
 {{"demo": "TrackNodeExpansionToggle.js"}}

docs/data/tree-view/simple-tree-view/items/items.md

@@ -9,68 +9,65 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
 
 # Simple Tree View - Items
 
-<p class="description">Pass data to your Tree View.</p>
+<p class="description">Learn how to add simple data to the Tree View component.</p>
 
-## Basic usage
+## Basics
 
-The items can be defined as JSX children of the `SimpleTreeView` component:
+```jsx
+import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
+import { TreeItem } from '@mui/x-tree-view/TreeItem';
+```
 
-{{"demo": "BasicSimpleTreeView.js"}}
+The Simple Tree View component receives its items directly as JSX children.
 
-## Item identifier
+{{"demo": "BasicSimpleTreeView.js"}}
 
-Each `TreeItem` must have a unique `nodeId`.
+### Item identifier
 
-This identifier is used internally to identify the item in the various models and to track the item across updates.
+Each Tree Item must have a unique `nodeId`.
+This is used internally to identify the item in the various models, and to track it across updates.
 
 ```tsx
 <SimpleTreeView>
-  <TreeItem nodeId="tree-view-community" {...otherItemProps} />
+  <TreeItem nodeId="item-unique-id" {...otherItemProps} />
 </SimpleTreeView>
 ```
 
-## Item label
+### Item label
 
-You must pass a `label` prop to each `TreeItem` component:
+You must pass a `label` prop to each Tree Item component, as shown below:
 
 ```tsx
 <SimpleTreeView>
-  <TreeItem label="@mui/x-tree-view" {...otherItemProps} />
+  <TreeItem label="Item label" {...otherItemProps} />
 </SimpleTreeView>
 ```
 
-## Disabled items
+### Disabled items
 
-You can disable some of the items using the `disabled` prop on the `TreeItem` component:
+Use the `disabled` prop on the Tree Item component to disable interaction and focus:
 
-```tsx
-<SimpleTreeView>
-  <TreeItem disabled {...otherItemProps} />
-</SimpleTreeView>
-```
-
-{{"demo": "DisabledJSXItem.js", "defaultCodeOpen": false}}
+{{"demo": "DisabledItemsFocusable.js", "defaultCodeOpen": false}}
 
-### Interact with disabled items
+#### The disabledItemsFocusable prop
 
-The behavior of disabled tree items depends on the `disabledItemsFocusable` prop.
+Note that the demo above also includes a switch.
+This toggles the `disabledItemsFocusable` prop, which controls whether or not a disabled Tree Item can be focused.
 
-If it is false:
+When this prop is set to false:
 
-- Arrow keys will not focus disabled items, and the next non-disabled item will be focused.
-- Typing the first character of a disabled item's label will not focus the item.
+- Navigating with keyboard arrow keys will not focus the disabled items, and the next non-disabled item will be focused instead.
+- Typing the first character of a disabled item's label will not move the focus to it.
 - Mouse or keyboard interaction will not expand/collapse disabled items.
 - Mouse or keyboard interaction will not select disabled items.
-- Shift + arrow keys will skip disabled items, and the next non-disabled item will be selected.
+- <kbd class="key">Shift</kbd> + arrow keys will skip disabled items, and the next non-disabled item will be selected instead.
 - Programmatic focus will not focus disabled items.
 
-If it is true:
+When it's set to true:
 
-- Arrow keys will focus disabled items.
-- Typing the first character of a disabled item's label will focus the item.
+- Navigating with keyboard arrow keys will focus disabled items.
+- Typing the first character of a disabled item's label will move focus to it.
 - Mouse or keyboard interaction will not expand/collapse disabled items.
 - Mouse or keyboard interaction will not select disabled items.
-- Shift + arrow keys will not skip disabled items but, the disabled item will not be selected.
+- <kbd class="key">Shift</kbd> + arrow keys will not skip disabled items, but the disabled item will not be selected.
 - Programmatic focus will focus disabled items.
-
-{{"demo": "DisabledItemsFocusable.js", "defaultCodeOpen": false}}

docs/data/tree-view/simple-tree-view/selection/selection.md

@@ -9,11 +9,11 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
 
 # Simple Tree View - Selection
 
-<p class="description">Handle how users can select items.</p>
+<p class="description">Learn how to enable item selection for the Tree View component.</p>
 
 ## Multi selection
 
-The Tree View also supports multi-selection:
+Apply the `multiSelect` prop on the Tree View to let users select multiple items.
 
 {{"demo": "MultiSelectTreeView.js"}}
 
@@ -25,9 +25,8 @@ Use the `disableSelection` prop if you don't want your items to be selectable:
 
 ## Controlled selection
 
-Use the `selectedNodes` prop to control the selected items.
-
-You can use the `onSelectedNodesChange` prop to listen to changes in the selected items and update the prop accordingly.
+Use the `selectedNodes` prop to control selected Tree View items.
+You can also use the `onSelectedNodesChange` prop to listen to changes in the selected items and update the prop accordingly.
 
 {{"demo": "ControlledSelection.js"}}
 

packages/x-tree-view/src/TreeItem/TreeItem.tsx

@@ -58,11 +58,13 @@ const StyledTreeItemContent = styled(TreeItemContent, {
     ];
   },
 })<{ ownerState: TreeItemOwnerState }>(({ theme }) => ({
-  padding: '0 8px',
+  padding: theme.spacing(0.5, 1),
+  borderRadius: theme.shape.borderRadius,
   width: '100%',
   boxSizing: 'border-box', // prevent width + padding to overflow
   display: 'flex',
   alignItems: 'center',
+  gap: theme.spacing(1),
   cursor: 'pointer',
   WebkitTapHighlightColor: 'transparent',
   '&:hover': {
@@ -107,8 +109,7 @@ const StyledTreeItemContent = styled(TreeItemContent, {
     },
   },
   [`& .${treeItemClasses.iconContainer}`]: {
-    marginRight: 4,
-    width: 15,
+    width: 16,
     display: 'flex',
     flexShrink: 0,
     justifyContent: 'center',
@@ -117,7 +118,6 @@ const StyledTreeItemContent = styled(TreeItemContent, {
     },
   },
   [`& .${treeItemClasses.label}`]: {
-    paddingLeft: 4,
     width: '100%',
     boxSizing: 'border-box', // prevent width + padding to overflow
     // fixes overflow - see https://github.com/mui/material-ui/issues/27372
@@ -134,7 +134,7 @@ const TreeItemGroup = styled(Collapse, {
 })({
   margin: 0,
   padding: 0,
-  marginLeft: 17,
+  paddingLeft: 12,
 });
 
 /**