[docs] Unify Tree View apiRef methods doc examples (mui#13193)

Signed-off-by: Flavien DELANGLE <[email protected]>
Co-authored-by: Michel Engelen <[email protected]>

docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.js → docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.js

@@ -26,7 +26,7 @@ const MUI_X_PRODUCTS = [
   },
 ];
 
-export default function ChangeItemExpansion() {
+export default function ApiMethodSetItemExpansion() {
   const apiRef = useTreeViewApiRef();
 
   const handleExpandClick = (event) => {

docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx → docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx

@@ -26,7 +26,7 @@ const MUI_X_PRODUCTS: TreeViewBaseItem[] = [
   },
 ];
 
-export default function ChangeItemExpansion() {
+export default function ApiMethodSetItemExpansion() {
   const apiRef = useTreeViewApiRef();
 
   const handleExpandClick = (event: React.MouseEvent) => {

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

@@ -33,8 +33,34 @@ Use the `onItemExpansionToggle` prop if you want to react to an item expansion c
 
 {{"demo": "TrackItemExpansionToggle.js"}}
 
-## Change item expansion
+## Imperative API
 
-You can use the `setItemExpansion` API method to imperatively change the expansion of an item:
+:::success
+To use the `apiRef` object, you need to initialize it using the `useTreeViewApiRef` hook as follows:
 
-{{"demo": "ChangeItemExpansion.js"}}
+```tsx
+const apiRef = useTreeViewApiRef();
+
+return <RichTreeView apiRef={apiRef} items={ITEMS}>;
+```
+
+When your component first renders, `apiRef` will be `undefined`.
+After this initial render, `apiRef` holds methods to interact imperatively with the Tree View.
+:::
+
+### Change an item expansion
+
+Use the `setItemExpansion` API method to change the expansion of an item.
+
+```ts
+apiRef.current.setItemExpansion(
+  // The DOM event that triggered the change
+  event,
+  // The ID of the item to expand or collapse
+  itemId,
+  // `true` if the item should be expanded, `false` if it should be collapsed
+  isExpanded,
+);
+```
+
+{{"demo": "ApiMethodSetItemExpansion.js"}}

docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.js → docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.js

@@ -35,7 +35,7 @@ const MUI_X_PRODUCTS = [
   },
 ];
 
-export default function FocusedRichTreeView() {
+export default function ApiMethodFocusItem() {
   const apiRef = useTreeViewApiRef();
   const handleButtonClick = (event) => {
     apiRef.current?.focusItem(event, 'pickers');

docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx → docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx

@@ -35,7 +35,7 @@ const MUI_X_PRODUCTS: TreeViewBaseItem[] = [
   },
 ];
 
-export default function FocusedRichTreeView() {
+export default function ApiMethodFocusItem() {
   const apiRef = useTreeViewApiRef();
   const handleButtonClick = (event: React.SyntheticEvent) => {
     apiRef.current?.focusItem(event, 'pickers');

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

@@ -11,10 +11,7 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
 
 <p class="description">Learn how to focus Tree View items.</p>
 
-## Focus a specific item
-
-You can use the the `apiRef.focusItem` method to focus a specific item.
-This methods receives two parameters: `event` and `itemId`.
+## Imperative API
 
 :::success
 To use the `apiRef` object, you need to initialize it using the `useTreeViewApiRef` hook as follows:
@@ -25,12 +22,26 @@ const apiRef = useTreeViewApiRef();
 return <RichTreeView apiRef={apiRef} items={ITEMS}>;
 ```
 
-`apiRef` will be undefined during the first render and will then contain methods allowing you to imperatively interact with the Tree View.
+When your component first renders, `apiRef` will be `undefined`.
+After this initial render, `apiRef` holds methods to interact imperatively with the Tree View.
 :::
 
+### Focus a specific item
+
+Use the `focusItem` API method to focus a specific item.
+
+```ts
+apiRef.current.focusItem(
+  // The DOM event that triggered the change
+  event,
+  // The ID of the item to focus
+  itemId,
+);
+```
+
 :::info
 This method only works with items that are currently visible.
 Calling `apiRef.focusItem` on an item whose parent is collapsed will do nothing.
 :::
 
-{{"demo": "FocusedRichTreeView.js"}}
+{{"demo": "ApiMethodFocusItem.js"}}

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

@@ -43,7 +43,7 @@ A custom plugins contains 2 required elements:
 
 ### Params default value
 
-You can use the `getDefaultizedParams` property to set a default value to your plugin params:
+Use the `getDefaultizedParams` property to set a default value to your plugin params:
 
 ```ts
 const useCustomPlugin = ({ params }) => {
@@ -203,7 +203,7 @@ If you are using TypeScript, you need to define your dependencies in your plugin
 
 ### Pass props to your root element
 
-You can use the `getRootProps` property of your returned value to pass props to your root element:
+Use the `getRootProps` property of your returned value to pass props to your root element:
 
 ```ts
 const useCustomPlugin = ({ params }) => {
@@ -217,7 +217,7 @@ const useCustomPlugin = ({ params }) => {
 
 ### Pass elements to the Tree Item
 
-You can use the `contextValue` property in the returned object to pass elements to the Tree Item:
+Use the `contextValue` property in the returned object to pass elements to the Tree Item:
 
 :::warning
 The context is private for now and cannot be accessed outside the provided plugins.

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

@@ -0,0 +1,56 @@
+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' },
+    ],
+  },
+];
+
+export default function ApiMethodGetItem() {
+  const apiRef = useTreeViewApiRef();
+  const [selectedItem, setSelectedItem] = React.useState(null);
+
+  const handleSelectedItemsChange = (event, itemId) => {
+    if (itemId == null) {
+      setSelectedItem(null);
+    } else {
+      setSelectedItem(apiRef.current.getItem(itemId));
+    }
+  };
+
+  return (
+    <Stack spacing={2}>
+      <Typography>
+        Selected item: {selectedItem == null ? 'none' : selectedItem.label}
+      </Typography>
+      <Box sx={{ minHeight: 220, minWidth: 320, flexGrow: 1 }}>
+        <RichTreeView
+          items={MUI_X_PRODUCTS}
+          apiRef={apiRef}
+          selectedItems={selectedItem?.id ?? null}
+          onSelectedItemsChange={handleSelectedItemsChange}
+        />
+      </Box>
+    </Stack>
+  );
+}

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

@@ -0,0 +1,61 @@
+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' },
+    ],
+  },
+];
+
+export default function ApiMethodGetItem() {
+  const apiRef = useTreeViewApiRef();
+  const [selectedItem, setSelectedItem] = React.useState<TreeViewBaseItem | null>(
+    null,
+  );
+
+  const handleSelectedItemsChange = (
+    event: React.SyntheticEvent,
+    itemId: string | null,
+  ) => {
+    if (itemId == null) {
+      setSelectedItem(null);
+    } else {
+      setSelectedItem(apiRef.current!.getItem(itemId));
+    }
+  };
+
+  return (
+    <Stack spacing={2}>
+      <Typography>
+        Selected item: {selectedItem == null ? 'none' : selectedItem.label}
+      </Typography>
+      <Box sx={{ minHeight: 220, minWidth: 320, flexGrow: 1 }}>
+        <RichTreeView
+          items={MUI_X_PRODUCTS}
+          apiRef={apiRef}
+          selectedItems={selectedItem?.id ?? null}
+          onSelectedItemsChange={handleSelectedItemsChange}
+        />
+      </Box>
+    </Stack>
+  );
+}

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

@@ -0,0 +1,11 @@
+<Typography>
+  Selected item: {selectedItem == null ? 'none' : selectedItem.label}
+</Typography>
+<Box sx={{ minHeight: 220, minWidth: 320, flexGrow: 1 }}>
+  <RichTreeView
+    items={MUI_X_PRODUCTS}
+    apiRef={apiRef}
+    selectedItems={selectedItem?.id ?? null}
+    onSelectedItemsChange={handleSelectedItemsChange}
+  />
+</Box>

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

@@ -119,9 +119,9 @@ Otherwise, the Tree View will re-generate its entire structure.
 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.
 :::
 
-### The disabledItemsFocusable prop
+### Focus disabled items
 
-Use the `disabledItemsFocusable` prop to control whether or not a disabled Tree Item can be focused.
+Use the `disabledItemsFocusable` prop to control if disabled Tree Items can be focused.
 
 When this prop is set to false:
 
@@ -140,3 +140,18 @@ When it's set to true:
 - Mouse or keyboard interaction will not select disabled items.
 - <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.
+
+## Imperative API
+
+### Get an item by ID
+
+Use the `getItem` API method to get an item by its ID.
+
+```ts
+const item = apiRef.current.getItem(
+  // The ID of the item to retrieve
+  itemId,
+);
+```
+
+{{"demo": "ApiMethodGetItem.js", "defaultCodeOpen": false}}

docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.js → docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.js

@@ -6,7 +6,7 @@ import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
 import { TreeItem } from '@mui/x-tree-view/TreeItem';
 import { useTreeViewApiRef } from '@mui/x-tree-view/hooks';
 
-export default function ChangeItemExpansion() {
+export default function ApiMethodSetItemExpansion() {
   const apiRef = useTreeViewApiRef();
 
   const handleExpandClick = (event) => {

docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.tsx → docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.tsx

@@ -6,7 +6,7 @@ import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
 import { TreeItem } from '@mui/x-tree-view/TreeItem';
 import { useTreeViewApiRef } from '@mui/x-tree-view/hooks';
 
-export default function ChangeItemExpansion() {
+export default function ApiMethodSetItemExpansion() {
   const apiRef = useTreeViewApiRef();
 
   const handleExpandClick = (event: React.MouseEvent) => {

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

@@ -32,8 +32,34 @@ Use the `onItemExpansionToggle` prop to trigger an action upon an item being exp
 
 {{"demo": "TrackItemExpansionToggle.js"}}
 
-## Change item expansion
+## Imperative API
 
-You can use the `setItemExpansion` API method to imperatively change the expansion of an item:
+:::success
+To use the `apiRef` object, you need to initialize it using the `useTreeViewApiRef` hook as follows:
 
-{{"demo": "ChangeItemExpansion.js"}}
+```tsx
+const apiRef = useTreeViewApiRef();
+
+return <SimpleTreeView apiRef={apiRef}>{children}</SimpleTreeView>;
+```
+
+When your component first renders, `apiRef` will be `undefined`.
+After this initial render, `apiRef` holds methods to interact imperatively with the Tree View.
+:::
+
+### Change an item expansion
+
+Use the `setItemExpansion` API method to change the expansion of an item.
+
+```ts
+apiRef.current.setItemExpansion(
+  // The DOM event that triggered the change
+  event,
+  // The ID of the item to expand or collapse
+  itemId,
+  // `true` if the item should be expanded, `false` if it should be collapsed
+  isExpanded,
+);
+```
+
+{{"demo": "ApiMethodSetItemExpansion.js"}}

docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.js → docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.js

@@ -5,7 +5,7 @@ import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
 import { TreeItem } from '@mui/x-tree-view/TreeItem';
 import { useTreeViewApiRef } from '@mui/x-tree-view/hooks/useTreeViewApiRef';
 
-export default function FocusedSimpleTreeView() {
+export default function ApiMethodFocusItem() {
   const apiRef = useTreeViewApiRef();
   const handleButtonClick = (event) => {
     apiRef.current?.focusItem(event, 'pickers');

docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.tsx → docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.tsx

@@ -5,7 +5,7 @@ import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView';
 import { TreeItem } from '@mui/x-tree-view/TreeItem';
 import { useTreeViewApiRef } from '@mui/x-tree-view/hooks/useTreeViewApiRef';
 
-export default function FocusedSimpleTreeView() {
+export default function ApiMethodFocusItem() {
   const apiRef = useTreeViewApiRef();
   const handleButtonClick = (event: React.SyntheticEvent) => {
     apiRef.current?.focusItem(event, 'pickers');