[TreeView] Add getItemTree and getItemOrderedChildrenIds methods …

…to the public API (mui#13804)

docs/data/tree-view/rich-tree-view/items/ApiMethodGetItemOrderedChildrenIds.js

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { RichTreeView } from '@mui/x-tree-view/RichTreeView';
+
+import { useTreeViewApiRef } from '@mui/x-tree-view/hooks';
+
+const MUI_X_PRODUCTS = [
+  {
+    id: 'grid',
+    label: 'Data Grid',
+    children: [
+      { id: 'grid-community', label: '@mui/x-data-grid' },
+      { id: 'grid-pro', label: '@mui/x-data-grid-pro' },
+      { id: 'grid-premium', label: '@mui/x-data-grid-premium' },
+    ],
+  },
+  {
+    id: 'pickers',
+    label: 'Date and Time Pickers',
+    children: [
+      { id: 'pickers-community', label: '@mui/x-date-pickers' },
+      { id: 'pickers-pro', label: '@mui/x-date-pickers-pro' },
+    ],
+  },
+  {
+    id: 'charts',
+    label: 'Charts',
+    children: [{ id: 'charts-community', label: '@mui/x-charts' }],
+  },
+  {
+    id: 'tree-view',
+    label: 'Tree View',
+    children: [{ id: 'tree-view-community', label: '@mui/x-tree-view' }],
+  },
+];
+
+export default function ApiMethodGetItemOrderedChildrenIds() {
+  const apiRef = useTreeViewApiRef();
+  const [isSelectedItemLeaf, setIsSelectedItemLeaf] = React.useState(null);
+
+  const handleSelectedItemsChange = (event, itemId) => {
+    if (itemId == null) {
+      setIsSelectedItemLeaf(null);
+    } else {
+      const children = apiRef.current.getItemOrderedChildrenIds(itemId);
+      setIsSelectedItemLeaf(children.length === 0);
+    }
+  };
+
+  return (
+    <Stack spacing={2}>
+      <Typography>
+        {isSelectedItemLeaf == null && 'No item selected'}
+        {isSelectedItemLeaf === true && 'The selected item is a leaf'}
+        {isSelectedItemLeaf === false && 'The selected item is a node with children'}
+      </Typography>
+      <Box sx={{ minHeight: 352, minWidth: 300 }}>
+        <RichTreeView
+          items={MUI_X_PRODUCTS}
+          apiRef={apiRef}
+          onSelectedItemsChange={handleSelectedItemsChange}
+        />
+      </Box>
+    </Stack>
+  );
+}

docs/data/tree-view/rich-tree-view/items/ApiMethodGetItemOrderedChildrenIds.tsx

@@ -0,0 +1,73 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { RichTreeView } from '@mui/x-tree-view/RichTreeView';
+import { TreeViewBaseItem } from '@mui/x-tree-view/models';
+import { useTreeViewApiRef } from '@mui/x-tree-view/hooks';
+
+const MUI_X_PRODUCTS: TreeViewBaseItem[] = [
+  {
+    id: 'grid',
+    label: 'Data Grid',
+    children: [
+      { id: 'grid-community', label: '@mui/x-data-grid' },
+      { id: 'grid-pro', label: '@mui/x-data-grid-pro' },
+      { id: 'grid-premium', label: '@mui/x-data-grid-premium' },
+    ],
+  },
+  {
+    id: 'pickers',
+    label: 'Date and Time Pickers',
+    children: [
+      { id: 'pickers-community', label: '@mui/x-date-pickers' },
+      { id: 'pickers-pro', label: '@mui/x-date-pickers-pro' },
+    ],
+  },
+  {
+    id: 'charts',
+    label: 'Charts',
+    children: [{ id: 'charts-community', label: '@mui/x-charts' }],
+  },
+  {
+    id: 'tree-view',
+    label: 'Tree View',
+    children: [{ id: 'tree-view-community', label: '@mui/x-tree-view' }],
+  },
+];
+
+export default function ApiMethodGetItemOrderedChildrenIds() {
+  const apiRef = useTreeViewApiRef();
+  const [isSelectedItemLeaf, setIsSelectedItemLeaf] = React.useState<boolean | null>(
+    null,
+  );
+
+  const handleSelectedItemsChange = (
+    event: React.SyntheticEvent,
+    itemId: string | null,
+  ) => {
+    if (itemId == null) {
+      setIsSelectedItemLeaf(null);
+    } else {
+      const children = apiRef.current!.getItemOrderedChildrenIds(itemId);
+      setIsSelectedItemLeaf(children.length === 0);
+    }
+  };
+
+  return (
+    <Stack spacing={2}>
+      <Typography>
+        {isSelectedItemLeaf == null && 'No item selected'}
+        {isSelectedItemLeaf === true && 'The selected item is a leaf'}
+        {isSelectedItemLeaf === false && 'The selected item is a node with children'}
+      </Typography>
+      <Box sx={{ minHeight: 352, minWidth: 300 }}>
+        <RichTreeView
+          items={MUI_X_PRODUCTS}
+          apiRef={apiRef}
+          onSelectedItemsChange={handleSelectedItemsChange}
+        />
+      </Box>
+    </Stack>
+  );
+}

docs/data/tree-view/rich-tree-view/items/ApiMethodGetItemOrderedChildrenIds.tsx.preview

@@ -0,0 +1,12 @@
+<Typography>
+  {isSelectedItemLeaf == null && 'No item selected'}
+  {isSelectedItemLeaf === true && 'The selected item is a leaf'}
+  {isSelectedItemLeaf === false && 'The selected item is a node with children'}
+</Typography>
+<Box sx={{ minHeight: 352, minWidth: 300 }}>
+  <RichTreeView
+    items={MUI_X_PRODUCTS}
+    apiRef={apiRef}
+    onSelectedItemsChange={handleSelectedItemsChange}
+  />
+</Box>

docs/data/tree-view/rich-tree-view/items/ApiMethodGetItemTree.js

@@ -0,0 +1,66 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Stack from '@mui/material/Stack';
+import Button from '@mui/material/Button';
+import Typography from '@mui/material/Typography';
+import { RichTreeView } from '@mui/x-tree-view/RichTreeView';
+
+import { useTreeViewApiRef } from '@mui/x-tree-view/hooks';
+
+const MUI_X_PRODUCTS = [
+  {
+    id: 'grid',
+    label: 'Data Grid',
+    children: [
+      { id: 'grid-community', label: '@mui/x-data-grid' },
+      { id: 'grid-pro', label: '@mui/x-data-grid-pro' },
+      { id: 'grid-premium', label: '@mui/x-data-grid-premium' },
+    ],
+  },
+  {
+    id: 'pickers',
+    label: 'Date and Time Pickers',
+    children: [
+      { id: 'pickers-community', label: '@mui/x-date-pickers' },
+      { id: 'pickers-pro', label: '@mui/x-date-pickers-pro' },
+    ],
+  },
+  {
+    id: 'charts',
+    label: 'Charts',
+    children: [{ id: 'charts-community', label: '@mui/x-charts' }],
+  },
+  {
+    id: 'tree-view',
+    label: 'Tree View',
+    children: [{ id: 'tree-view-community', label: '@mui/x-tree-view' }],
+  },
+];
+
+export default function ApiMethodGetItemTree() {
+  const apiRef = useTreeViewApiRef();
+
+  const [items, setItems] = React.useState(MUI_X_PRODUCTS);
+  const [itemOnTop, setItemOnTop] = React.useState(items[0].label);
+
+  const handleInvertItems = () => {
+    setItems((prevItems) => [...prevItems].reverse());
+  };
+
+  const handleUpdateItemOnTop = () => {
+    setItemOnTop(apiRef.current.getItemTree()[0].label);
+  };
+
+  return (
+    <Stack spacing={2}>
+      <Stack direction="row" spacing={2}>
+        <Button onClick={handleInvertItems}>Invert first tree</Button>
+        <Button onClick={handleUpdateItemOnTop}>Update item on top</Button>
+      </Stack>
+      <Typography>Item on top: {itemOnTop}</Typography>
+      <Box sx={{ minHeight: 352, minWidth: 300 }}>
+        <RichTreeView apiRef={apiRef} items={items} />
+      </Box>
+    </Stack>
+  );
+}

docs/data/tree-view/rich-tree-view/items/ApiMethodGetItemTree.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Stack from '@mui/material/Stack';
+import Button from '@mui/material/Button';
+import Typography from '@mui/material/Typography';
+import { RichTreeView } from '@mui/x-tree-view/RichTreeView';
+import { TreeViewBaseItem } from '@mui/x-tree-view/models';
+import { useTreeViewApiRef } from '@mui/x-tree-view/hooks';
+
+const MUI_X_PRODUCTS: TreeViewBaseItem[] = [
+  {
+    id: 'grid',
+    label: 'Data Grid',
+    children: [
+      { id: 'grid-community', label: '@mui/x-data-grid' },
+      { id: 'grid-pro', label: '@mui/x-data-grid-pro' },
+      { id: 'grid-premium', label: '@mui/x-data-grid-premium' },
+    ],
+  },
+  {
+    id: 'pickers',
+    label: 'Date and Time Pickers',
+    children: [
+      { id: 'pickers-community', label: '@mui/x-date-pickers' },
+      { id: 'pickers-pro', label: '@mui/x-date-pickers-pro' },
+    ],
+  },
+  {
+    id: 'charts',
+    label: 'Charts',
+    children: [{ id: 'charts-community', label: '@mui/x-charts' }],
+  },
+  {
+    id: 'tree-view',
+    label: 'Tree View',
+    children: [{ id: 'tree-view-community', label: '@mui/x-tree-view' }],
+  },
+];
+
+export default function ApiMethodGetItemTree() {
+  const apiRef = useTreeViewApiRef();
+
+  const [items, setItems] = React.useState(MUI_X_PRODUCTS);
+  const [itemOnTop, setItemOnTop] = React.useState(items[0].label);
+
+  const handleInvertItems = () => {
+    setItems((prevItems) => [...prevItems].reverse());
+  };
+
+  const handleUpdateItemOnTop = () => {
+    setItemOnTop(apiRef.current!.getItemTree()[0].label);
+  };
+
+  return (
+    <Stack spacing={2}>
+      <Stack direction="row" spacing={2}>
+        <Button onClick={handleInvertItems}>Invert first tree</Button>
+        <Button onClick={handleUpdateItemOnTop}>Update item on top</Button>
+      </Stack>
+      <Typography>Item on top: {itemOnTop}</Typography>
+      <Box sx={{ minHeight: 352, minWidth: 300 }}>
+        <RichTreeView apiRef={apiRef} items={items} />
+      </Box>
+    </Stack>
+  );
+}

docs/data/tree-view/rich-tree-view/items/ApiMethodGetItemTree.tsx.preview

@@ -0,0 +1,8 @@
+<Stack direction="row" spacing={2}>
+  <Button onClick={handleInvertItems}>Invert first tree</Button>
+  <Button onClick={handleUpdateItemOnTop}>Update item on top</Button>
+</Stack>
+<Typography>Item on top: {itemOnTop}</Typography>
+<Box sx={{ minHeight: 352, minWidth: 300 }}>
+  <RichTreeView apiRef={apiRef} items={items} />
+</Box>

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

@@ -170,3 +170,26 @@ const itemElement = apiRef.current.getItemDOMElement(
 ```
 
 {{"demo": "ApiMethodGetItemDOMElement.js", "defaultCodeOpen": false}}
+
+### Get the current item tree
+
+Use the `getItemTree` API method to get the current item tree.
+
+```ts
+const itemTree = apiRef.current.getItemTree();
+```
+
+{{"demo": "ApiMethodGetItemTree.js", "defaultCodeOpen": false}}
+
+### Get an item's children by ID
+
+Use the `getItemOrderedChildrenIds` API method to get an item's children by its ID.
+
+```ts
+const childrenIds = apiRef.current.getItemOrderedChildrenIds(
+  // The id of the item to retrieve the children from
+  itemId,
+);
+```
+
+{{"demo": "ApiMethodGetItemOrderedChildrenIds.js", "defaultCodeOpen": false}}

docs/pages/x/api/tree-view/rich-tree-view.json

@@ -3,7 +3,7 @@
     "apiRef": {
       "type": {
         "name": "shape",
-        "description": "{ current?: { focusItem: func, getItem: func, getItemDOMElement: func, selectItem: func, setItemExpansion: func } }"
+        "description": "{ current?: { focusItem: func, getItem: func, getItemDOMElement: func, getItemOrderedChildrenIds: func, getItemTree: func, selectItem: func, setItemExpansion: func } }"
       }
     },
     "checkboxSelection": { "type": { "name": "bool" }, "default": "false" },

docs/pages/x/api/tree-view/simple-tree-view.json

@@ -3,7 +3,7 @@
     "apiRef": {
       "type": {
         "name": "shape",
-        "description": "{ current?: { focusItem: func, getItem: func, getItemDOMElement: func, selectItem: func, setItemExpansion: func } }"
+        "description": "{ current?: { focusItem: func, getItem: func, getItemDOMElement: func, getItemOrderedChildrenIds: func, getItemTree: func, selectItem: func, setItemExpansion: func } }"
       }
     },
     "checkboxSelection": { "type": { "name": "bool" }, "default": "false" },

docs/pages/x/api/tree-view/tree-view.json

@@ -3,7 +3,7 @@
     "apiRef": {
       "type": {
         "name": "shape",
-        "description": "{ current?: { focusItem: func, getItem: func, getItemDOMElement: func, selectItem: func, setItemExpansion: func } }"
+        "description": "{ current?: { focusItem: func, getItem: func, getItemDOMElement: func, getItemOrderedChildrenIds: func, getItemTree: func, selectItem: func, setItemExpansion: func } }"
       }
     },
     "checkboxSelection": { "type": { "name": "bool" }, "default": "false" },

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

@@ -152,6 +152,8 @@ RichTreeView.propTypes = {
       focusItem: PropTypes.func.isRequired,
       getItem: PropTypes.func.isRequired,
       getItemDOMElement: PropTypes.func.isRequired,
+      getItemOrderedChildrenIds: PropTypes.func.isRequired,
+      getItemTree: PropTypes.func.isRequired,
       selectItem: PropTypes.func.isRequired,
       setItemExpansion: PropTypes.func.isRequired,
     }),

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

@@ -111,6 +111,8 @@ SimpleTreeView.propTypes = {
       focusItem: PropTypes.func.isRequired,
       getItem: PropTypes.func.isRequired,
       getItemDOMElement: PropTypes.func.isRequired,
+      getItemOrderedChildrenIds: PropTypes.func.isRequired,
+      getItemTree: PropTypes.func.isRequired,
       selectItem: PropTypes.func.isRequired,
       setItemExpansion: PropTypes.func.isRequired,
     }),

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

@@ -96,6 +96,8 @@ TreeView.propTypes = {
       focusItem: PropTypes.func.isRequired,
       getItem: PropTypes.func.isRequired,
       getItemDOMElement: PropTypes.func.isRequired,
+      getItemOrderedChildrenIds: PropTypes.func.isRequired,
+      getItemTree: PropTypes.func.isRequired,
       selectItem: PropTypes.func.isRequired,
       setItemExpansion: PropTypes.func.isRequired,
     }),