[TreeView] Replace <TreeItem /> with <TreeItem2 /> and migrate all the components and utils

docs/data/migration/migration-tree-view-v7/migration-tree-view-v7.md

@@ -0,0 +1,178 @@
+---
+productId: x-tree-view
+---
+
+# Migration from v7 to v8
+
+<p class="description">This guide describes the changes needed to migrate the Tree View from v7 to v8.</p>
+
+## Introduction
+
+This is a reference guide for upgrading `@mui/x-tree-view` from v7 to v8.
+
+## Start using the new release
+
+In `package.json`, change the version of the Tree View package to `^8.0.0`.
+
+```diff
+-"@mui/x-tree-view": "7.x.x",
++"@mui/x-tree-view": "^8.0.0",
+```
+
+Since `v8` is a major release, it contains changes that affect the public API.
+These changes were done for consistency, improved stability and to make room for new features.
+Described below are the steps needed to migrate from v7 to v8.
+
+## Run codemods
+
+The `preset-safe` codemod will automatically adjust the bulk of your code to account for breaking changes in v8. You can run `v8.0.0/tree-view/preset-safe` targeting only Tree View or `v8.0.0/preset-safe` to target the other packages as well.
+
+You can either run it on a specific file, folder, or your entire codebase when choosing the `<path>` argument.
+
+<!-- #default-branch-switch -->
+
+```bash
+// Tree View specific
+npx @mui/x-codemod@latest v8.0.0/tree-view/preset-safe <path>
+
+// Target the other packages as well
+npx @mui/x-codemod@latest v8.0.0/preset-safe <path>
+```
+
+:::info
+If you want to run the transformers one by one, check out the transformers included in the [preset-safe codemod for the Tree View](https://github.com/mui/mui-x/blob/HEAD/packages/x-codemod/README.md#preset-safe-for-tree-view-v800) for more details.
+:::
+
+Breaking changes that are handled by this codemod are denoted by a ✅ emoji in the table of contents on the right side of the screen.
+
+If you have already applied the `v8.0.0/tree-view/preset-safe` (or `v8.0.0/preset-safe`) codemod, then you should not need to take any further action on these items.
+
+All other changes must be handled manually.
+
+:::warning
+Not all use cases are covered by codemods. In some scenarios, like props spreading, cross-file dependencies, etc., the changes are not properly identified and therefore must be handled manually.
+
+For example, if a codemod tries to rename a prop, but this prop is hidden with the spread operator, it won't be transformed as expected.
+
+```tsx
+<RichTreeView {...pickerProps} />
+```
+
+After running the codemods, make sure to test your application and that you don't have any console errors.
+
+Feel free to [open an issue](https://github.com/mui/mui-x/issues/new/choose) for support if you need help to proceed with your migration.
+:::
+
+## New API to customize the Tree Item
+
+The `ContentComponent` or `ContentProps` props of the `TreeItem` component have been removed in favor of the new `slots`, `slotProps` props and of the `useTreeItem` hook.
+
+Learn more about the anatomy of the Tree Items and the customization utilities provided on the [Tree Item Customization page](/x/react-tree-view/tree-item-customization/).
+
+## Behavior change on the `onClick` and `onMouseDown` props of `TreeItem`
+
+The `onClick` and `onMouseDown` were the only event callback that were passed to the content of the Tree Item instead of its root.
+The goal was to make sure that the callback was not fired when clicking on a descendant of a giving item.
+This inconsistency has been solved, all the event manager now target the root of the item, and you can use the `onItemClick` prop on the Tree View component to target the content of an item:
+
+```diff
+-<SimpleTreeView>
++<SimpleTreeView onItemClick={handleItemClick}>
+-  <TreeItem onClick={handleItemClick}>
++  <TreeItem >
+ </SimpleTreeView>
+```
+
+## Rename the `TreeItem2` (and related utils)
+
+All the new Tree Item-related components and utils (introduced in the previous major to improve the DX of the Tree Item component) are becoming the default way of using the Tree Item and are therefore losing their `2` suffix:
+
+```diff
+ import * as React from 'react';
+ import {
+-  TreeItem2,
++  TreeItem,
+-  TreeItem2Root,
++  TreeItemRoot,
+-  TreeItem2Content,
++  TreeItemContent,
+-  TreeItem2IconContainer,
++  TreeItemIconContainer,
+-  TreeItem2GroupTransition,
++  TreeItemGroupTransition,
+-  TreeItem2Checkbox,
++  TreeItemCheckbox,
+-  TreeItem2Label,
++  TreeItemLabel,
+-  TreeItem2Props,
++  TreeItemProps,
+-  TreeItem2Slots,
++  TreeItemSlots,
+-  TreeItem2SlotProps,
++  TreeItemSlotProps,
+- } from '@mui/x-tree-view/TreeItem2';
++ } from '@mui/x-tree-view/TreeItem';
+ import {
+-  useTreeItem2,
++  useTreeItem,
+-  unstable_useTreeItem2 as useAliasedTreeItem,
++  unstable_useTreeItem as useAliasedTreeItem,
+-  UseTreeItem2Parameters,
++  UseTreeItemParameters,
+-  UseTreeItem2ReturnValue,
++  UseTreeItemReturnValue,
+-  UseTreeItem2Status,
++  UseTreeItemStatus,
+-  UseTreeItem2RootSlotOwnProps,
++  UseTreeItemRootSlotOwnProps,
+-  UseTreeItem2ContentSlotOwnProps,
++  UseTreeItemContentSlotOwnProps,
+-  UseTreeItem2LabelInputSlotOwnProps,
++  UseTreeItemLabelInputSlotOwnProps,
+-  UseTreeItem2LabelSlotOwnProps,
++  UseTreeItemLabelSlotOwnProps,
+-  UseTreeItem2CheckboxSlotOwnProps,
++  UseTreeItemCheckboxSlotOwnProps,
+-  UseTreeItem2IconContainerSlotOwnProps,
++  UseTreeItemIconContainerSlotOwnProps,
+-  UseTreeItem2GroupTransitionSlotOwnProps,
++  UseTreeItemGroupTransitionSlotOwnProps,
+-  UseTreeItem2DragAndDropOverlaySlotOwnProps,
++  UseTreeItemDragAndDropOverlaySlotOwnProps,
+- } from '@mui/x-tree-view/useTreeItem2';
++ } from '@mui/x-tree-view/useTreeItem';
+- import { useTreeItem2Utils } from '@mui/x-tree-view/hooks';
++ import { useTreeItemUtils } from '@mui/x-tree-view/hooks';
+ import {
+-  TreeItem2Provider,
++  TreeItemProvider,
+-  TreeItem2ProviderProps,
++  TreeItemProviderProps,
+- } from '@mui/x-tree-view/TreeItem2Provider';
++ } from '@mui/x-tree-view/TreeItemProvider';
+ import {
+-  TreeItem2Icon,
++  TreeItemIcon,
+-  TreeItem2IconProps,
++  TreeItemIconProps,
+-  TreeItem2IconSlots,
++  TreeItemIconSlots,
+-  TreeItem2IconSlotProps,
++  TreeItemIconSlotProps,
+- } from '@mui/x-tree-view/TreeItem2Icon';
++ } from '@mui/x-tree-view/TreeItemIcon';
+ import {
+-  TreeItem2DragAndDropOverlay,
++  TreeItemDragAndDropOverlay,
+-  TreeItem2DragAndDropOverlayProps,
++  TreeItemDragAndDropOverlayProps,
+- } from '@mui/x-tree-view/TreeItem2DragAndDropOverlay';
++ } from '@mui/x-tree-view/TreeItemDragAndDropOverlay';
+ import {
+-  TreeItem2LabelInput,
++  TreeItemLabelInput,
+-  TreeItem2LabelInputProps,
++  TreeItemLabelInputProps,
+- } from '@mui/x-tree-view/TreeItem2LabelInput';
++ } from '@mui/x-tree-view/TreeItemLabelInput';
+```

docs/data/pages.ts

@@ -545,6 +545,10 @@ const pages: MuiPage[] = [
             pathname: '/x/migration/migration-pickers-v7',
             title: 'Breaking changes: Date and Time Pickers',
           },
+          {
+            pathname: '/x/migration/migration-tree-view-v7',
+            title: 'Breaking changes: Tree View',
+          },
         ],
       },
       {

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

@@ -41,75 +41,3 @@ This is the recommended version for larger trees, as well as those that require
 :::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.
 :::
-
-### Tree Item components
-
-The `@mui/x-tree-view` package exposes two different components to define your tree items:
-
-- `<TreeItem />`
-- `<TreeItem2 />`
-
-#### Tree Item
-
-This is the long-standing component that is very similar to the one used in previous versions (`@mui/x-tree-view@6` and `@mui/lab`).
-
-When using Simple Tree View,
-you can import it from `@mui/x-tree-view/TreeItem` and use it as a child of the Simple Tree View component:
-
-```tsx
-import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
-import { TreeItem } from '@mui/x-tree-view/TreeItem';
-
-export default function App() {
-  return (
-    <SimpleTreeView>
-      <TreeItem itemId="1" label="Item 1" />
-      <TreeItem itemId="2" label="Item 2" />
-    </SimpleTreeView>
-  );
-}
-```
-
-When using Rich Tree View,
-you don't have to import anything; it's the default component used to render the items:
-
-```tsx
-import { RichTreeView } from '@mui/x-tree-view/RichTreeView';
-
-export default function App() {
-  return <RichTreeView items={ITEMS} />;
-}
-```
-
-#### Tree Item 2
-
-This is a new component that provides a more powerful customization API, and will eventually replace `<TreeItem />`.
-
-When using Simple Tree View,
-you can import it from `@mui/x-tree-view/TreeItem2` and use it as a child of the Simple Tree View component:
-
-```tsx
-import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
-import { TreeItem2 } from '@mui/x-tree-view/TreeItem2';
-
-export default function App() {
-  return (
-    <SimpleTreeView>
-      <TreeItem2 itemId="1" label="Item 1" />
-      <TreeItem2 itemId="2" label="Item 2" />
-    </SimpleTreeView>
-  );
-}
-```
-
-When using Rich Tree View,
-you can import it from `@mui/x-tree-view/TreeItem2` and pass it as a slot of the Rich Tree View component:
-
-```tsx
-import { RichTreeView } from '@mui/x-tree-view/RichTreeView';
-import { TreeItem2 } from '@mui/x-tree-view/TreeItem2';
-
-export default function App() {
-  return <RichTreeView items={ITEMS} slots={{ item: TreeItem2 }} />;
-}
-```

docs/data/tree-view/rich-tree-view/customization/FileExplorer.js

@@ -14,18 +14,18 @@ import ImageIcon from '@mui/icons-material/Image';
 import PictureAsPdfIcon from '@mui/icons-material/PictureAsPdf';
 import VideoCameraBackIcon from '@mui/icons-material/VideoCameraBack';
 import { RichTreeView } from '@mui/x-tree-view/RichTreeView';
-import { treeItemClasses } from '@mui/x-tree-view/TreeItem';
-import { useTreeItem2 } from '@mui/x-tree-view/useTreeItem2';
+import { useTreeItem } from '@mui/x-tree-view/useTreeItem';
 import {
-  TreeItem2Checkbox,
-  TreeItem2Content,
-  TreeItem2IconContainer,
-  TreeItem2Label,
-  TreeItem2Root,
-} from '@mui/x-tree-view/TreeItem2';
-import { TreeItem2Icon } from '@mui/x-tree-view/TreeItem2Icon';
-import { TreeItem2Provider } from '@mui/x-tree-view/TreeItem2Provider';
-import { TreeItem2DragAndDropOverlay } from '@mui/x-tree-view/TreeItem2DragAndDropOverlay';
+  TreeItemCheckbox,
+  TreeItemContent,
+  TreeItemIconContainer,
+  TreeItemLabel,
+  TreeItemRoot,
+  treeItemClasses,
+} from '@mui/x-tree-view/TreeItem';
+import { TreeItemIcon } from '@mui/x-tree-view/TreeItemIcon';
+import { TreeItemProvider } from '@mui/x-tree-view/TreeItemProvider';
+import { TreeItemDragAndDropOverlay } from '@mui/x-tree-view/TreeItemDragAndDropOverlay';
 
 const ITEMS = [
   {
@@ -79,7 +79,7 @@ function DotIcon() {
   );
 }
 
-const StyledTreeItemRoot = styled(TreeItem2Root)(({ theme }) => ({
+const StyledTreeItemRoot = styled(TreeItemRoot)(({ theme }) => ({
   color: theme.palette.grey[400],
   position: 'relative',
   [`& .${treeItemClasses.groupTransition}`]: {
@@ -90,7 +90,7 @@ const StyledTreeItemRoot = styled(TreeItem2Root)(({ theme }) => ({
   }),
 }));
 
-const CustomTreeItemContent = styled(TreeItem2Content)(({ theme }) => ({
+const CustomTreeItemContent = styled(TreeItemContent)(({ theme }) => ({
   flexDirection: 'row-reverse',
   borderRadius: theme.spacing(0.7),
   marginBottom: theme.spacing(0.5),
@@ -156,7 +156,7 @@ const StyledTreeItemLabelText = styled(Typography)({
 
 function CustomLabel({ icon: Icon, expandable, children, ...other }) {
   return (
-    <TreeItem2Label
+    <TreeItemLabel
       {...other}
       sx={{
         display: 'flex',
@@ -174,7 +174,7 @@ function CustomLabel({ icon: Icon, expandable, children, ...other }) {
 
       <StyledTreeItemLabelText variant="body2">{children}</StyledTreeItemLabelText>
       {expandable && <DotIcon />}
-    </TreeItem2Label>
+    </TreeItemLabel>
   );
 }
 
@@ -219,7 +219,7 @@ const CustomTreeItem = React.forwardRef(function CustomTreeItem(props, ref) {
     getDragAndDropOverlayProps,
     status,
     publicAPI,
-  } = useTreeItem2({ id, itemId, children, label, disabled, rootRef: ref });
+  } = useTreeItem({ id, itemId, children, label, disabled, rootRef: ref });
 
   const item = publicAPI.getItem(itemId);
   const expandable = isExpandable(children);
@@ -231,7 +231,7 @@ const CustomTreeItem = React.forwardRef(function CustomTreeItem(props, ref) {
   }
 
   return (
-    <TreeItem2Provider itemId={itemId}>
+    <TreeItemProvider itemId={itemId}>
       <StyledTreeItemRoot {...getRootProps(other)}>
         <CustomTreeItemContent
           {...getContentProps({
@@ -243,18 +243,18 @@ const CustomTreeItem = React.forwardRef(function CustomTreeItem(props, ref) {
             }),
           })}
         >
-          <TreeItem2IconContainer {...getIconContainerProps()}>
-            <TreeItem2Icon status={status} />
-          </TreeItem2IconContainer>
-          <TreeItem2Checkbox {...getCheckboxProps()} />
+          <TreeItemIconContainer {...getIconContainerProps()}>
+            <TreeItemIcon status={status} />
+          </TreeItemIconContainer>
+          <TreeItemCheckbox {...getCheckboxProps()} />
           <CustomLabel
             {...getLabelProps({ icon, expandable: expandable && status.expanded })}
           />
-          <TreeItem2DragAndDropOverlay {...getDragAndDropOverlayProps()} />
+          <TreeItemDragAndDropOverlay {...getDragAndDropOverlayProps()} />
         </CustomTreeItemContent>
         {children && <TransitionComponent {...getGroupTransitionProps()} />}
       </StyledTreeItemRoot>
-    </TreeItem2Provider>
+    </TreeItemProvider>
   );
 });