From 5842abf5a7b22c81335498b3477fbd4016ff0e8c Mon Sep 17 00:00:00 2001 From: delangle Date: Tue, 21 May 2024 11:10:58 +0200 Subject: [PATCH 1/8] [docs] Unify Tree View apiRef methods doc examples --- ...ansion.js => ApiMethodSetItemExpansion.js} | 2 +- ...sion.tsx => ApiMethodSetItemExpansion.tsx} | 2 +- ... => ApiMethodSetItemExpansion.tsx.preview} | 0 .../rich-tree-view/expansion/expansion.md | 31 +++++++++- ...dRichTreeView.js => ApiMethodFocusItem.js} | 2 +- ...ichTreeView.tsx => ApiMethodFocusItem.tsx} | 2 +- .../focus/FocusedRichTreeView.tsx.preview | 6 -- .../tree-view/rich-tree-view/focus/focus.md | 20 ++++-- .../rich-tree-view/headless/headless.md | 6 +- .../rich-tree-view/items/ApiMethodGetItem.js | 56 +++++++++++++++++ .../rich-tree-view/items/ApiMethodGetItem.tsx | 61 +++++++++++++++++++ .../items/ApiMethodGetItem.tsx.preview | 11 ++++ .../tree-view/rich-tree-view/items/items.md | 19 +++++- ...ansion.js => ApiMethodSetItemExpansion.js} | 2 +- ...sion.tsx => ApiMethodSetItemExpansion.tsx} | 2 +- .../simple-tree-view/expansion/expansion.md | 31 +++++++++- ...impleTreeView.js => ApiMethodFocusItem.js} | 2 +- ...pleTreeView.tsx => ApiMethodFocusItem.tsx} | 2 +- .../tree-view/simple-tree-view/focus/focus.md | 20 ++++-- .../useTreeViewItems.types.ts | 1 + 20 files changed, 243 insertions(+), 35 deletions(-) rename docs/data/tree-view/rich-tree-view/expansion/{ChangeItemExpansion.js => ApiMethodSetItemExpansion.js} (96%) rename docs/data/tree-view/rich-tree-view/expansion/{ChangeItemExpansion.tsx => ApiMethodSetItemExpansion.tsx} (96%) rename docs/data/tree-view/rich-tree-view/expansion/{ChangeItemExpansion.tsx.preview => ApiMethodSetItemExpansion.tsx.preview} (100%) rename docs/data/tree-view/rich-tree-view/focus/{FocusedRichTreeView.js => ApiMethodFocusItem.js} (96%) rename docs/data/tree-view/rich-tree-view/focus/{FocusedRichTreeView.tsx => ApiMethodFocusItem.tsx} (96%) delete mode 100644 docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx.preview create mode 100644 docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.js create mode 100644 docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx create mode 100644 docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx.preview rename docs/data/tree-view/simple-tree-view/expansion/{ChangeItemExpansion.js => ApiMethodSetItemExpansion.js} (96%) rename docs/data/tree-view/simple-tree-view/expansion/{ChangeItemExpansion.tsx => ApiMethodSetItemExpansion.tsx} (96%) rename docs/data/tree-view/simple-tree-view/focus/{FocusedSimpleTreeView.js => ApiMethodFocusItem.js} (96%) rename docs/data/tree-view/simple-tree-view/focus/{FocusedSimpleTreeView.tsx => ApiMethodFocusItem.tsx} (97%) diff --git a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.js b/docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.js similarity index 96% rename from docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.js rename to docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.js index 044944e3dadcb..54ef0fe7b1732 100644 --- a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.js +++ b/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) => { diff --git a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx b/docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx similarity index 96% rename from docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx rename to docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx index 91587ed8df718..051424e259509 100644 --- a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx +++ b/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) => { diff --git a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx.preview b/docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx.preview similarity index 100% rename from docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx.preview rename to docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx.preview diff --git a/docs/data/tree-view/rich-tree-view/expansion/expansion.md b/docs/data/tree-view/rich-tree-view/expansion/expansion.md index a44e1e07bdfb8..220b31cb9559f 100644 --- a/docs/data/tree-view/rich-tree-view/expansion/expansion.md +++ b/docs/data/tree-view/rich-tree-view/expansion/expansion.md @@ -33,8 +33,33 @@ 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 ; +``` + +`apiRef` will be undefined during the first render and will then contain methods allowing you to imperatively interact 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"}} diff --git a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.js b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.js similarity index 96% rename from docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.js rename to docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.js index c2a96bffdf47e..4dc583c1c6a8f 100644 --- a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.js +++ b/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'); diff --git a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx similarity index 96% rename from docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx rename to docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx index 04b1aad4d11cf..364a83f58a5c3 100644 --- a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx +++ b/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'); diff --git a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx.preview b/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx.preview deleted file mode 100644 index 144d8e4e8dd5d..0000000000000 --- a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx.preview +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file diff --git a/docs/data/tree-view/rich-tree-view/focus/focus.md b/docs/data/tree-view/rich-tree-view/focus/focus.md index 4fa127cea557e..34a128eee4571 100644 --- a/docs/data/tree-view/rich-tree-view/focus/focus.md +++ b/docs/data/tree-view/rich-tree-view/focus/focus.md @@ -11,10 +11,7 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/

Learn how to focus Tree View items.

-## 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: @@ -28,9 +25,22 @@ return ; `apiRef` will be undefined during the first render and will then contain methods allowing you to imperatively interact with the Tree View. ::: +### Focus a specific item + +Use the `apiRef.focusItem` method to focus a specific item. + +```ts +apiRef.current.focusedItem( + // 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"}} diff --git a/docs/data/tree-view/rich-tree-view/headless/headless.md b/docs/data/tree-view/rich-tree-view/headless/headless.md index a258a6e6b524f..99955f9962855 100644 --- a/docs/data/tree-view/rich-tree-view/headless/headless.md +++ b/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. diff --git a/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.js b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.js new file mode 100644 index 0000000000000..84b3d54baaccc --- /dev/null +++ b/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 ( + + + Selected item: {selectedItem == null ? 'none' : selectedItem.label} + + + + + + ); +} diff --git a/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx new file mode 100644 index 0000000000000..b21fbbc7f888b --- /dev/null +++ b/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( + null, + ); + + const handleSelectedItemsChange = ( + event: React.SyntheticEvent, + itemId: string | null, + ) => { + if (itemId == null) { + setSelectedItem(null); + } else { + setSelectedItem(apiRef.current!.getItem(itemId)); + } + }; + + return ( + + + Selected item: {selectedItem == null ? 'none' : selectedItem.label} + + + + + + ); +} diff --git a/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx.preview b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx.preview new file mode 100644 index 0000000000000..640e65a388c39 --- /dev/null +++ b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx.preview @@ -0,0 +1,11 @@ + + Selected item: {selectedItem == null ? 'none' : selectedItem.label} + + + + \ No newline at end of file diff --git a/docs/data/tree-view/rich-tree-view/items/items.md b/docs/data/tree-view/rich-tree-view/items/items.md index e85d35328c698..d9d97dd9ddf5b 100644 --- a/docs/data/tree-view/rich-tree-view/items/items.md +++ b/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. - Shift + 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` 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}} diff --git a/docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.js b/docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.js similarity index 96% rename from docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.js rename to docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.js index 7af3290f9f7ed..4015d5b926f4a 100644 --- a/docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.js +++ b/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) => { diff --git a/docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.tsx b/docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.tsx similarity index 96% rename from docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.tsx rename to docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.tsx index ceddc17a3a266..ea0bfb3d3cab5 100644 --- a/docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.tsx +++ b/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) => { diff --git a/docs/data/tree-view/simple-tree-view/expansion/expansion.md b/docs/data/tree-view/simple-tree-view/expansion/expansion.md index d984b1bfb8137..771f50b764087 100644 --- a/docs/data/tree-view/simple-tree-view/expansion/expansion.md +++ b/docs/data/tree-view/simple-tree-view/expansion/expansion.md @@ -32,8 +32,33 @@ 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 {children}; +``` + +`apiRef` will be undefined during the first render and will then contain methods allowing you to imperatively interact 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"}} diff --git a/docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.js b/docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.js similarity index 96% rename from docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.js rename to docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.js index 9e12cc3ce0609..97950e48843af 100644 --- a/docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.js +++ b/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'); diff --git a/docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.tsx b/docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.tsx similarity index 97% rename from docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.tsx rename to docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.tsx index bc98ac6e25a9b..919cd401fb6f4 100644 --- a/docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.tsx +++ b/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'); diff --git a/docs/data/tree-view/simple-tree-view/focus/focus.md b/docs/data/tree-view/simple-tree-view/focus/focus.md index b408b02c9f35d..d9734ecf58576 100644 --- a/docs/data/tree-view/simple-tree-view/focus/focus.md +++ b/docs/data/tree-view/simple-tree-view/focus/focus.md @@ -11,10 +11,7 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/

Learn how to focus Tree View items.

-## 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: @@ -28,9 +25,22 @@ return {children}; `apiRef` will be undefined during the first render and will then contain methods allowing you to imperatively interact with the Tree View. ::: +### Focus a specific item + +Use the `apiRef.focusItem` method to focus a specific item. + +```ts +apiRef.current.focusedItem( + // 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": "FocusedSimpleTreeView.js"}} +{{"demo": "ApiMethodFocusItem.js"}} diff --git a/packages/x-tree-view/src/internals/plugins/useTreeViewItems/useTreeViewItems.types.ts b/packages/x-tree-view/src/internals/plugins/useTreeViewItems/useTreeViewItems.types.ts index 3862f2d5d51df..327907342d612 100644 --- a/packages/x-tree-view/src/internals/plugins/useTreeViewItems/useTreeViewItems.types.ts +++ b/packages/x-tree-view/src/internals/plugins/useTreeViewItems/useTreeViewItems.types.ts @@ -11,6 +11,7 @@ interface TreeViewItemProps { export interface UseTreeViewItemsPublicAPI { /** * Get the item with the given id. + * When used in the `SimpleTreeView`, it returns an object with the `id` and `label` properties. * @param {string} itemId The id of the item to return. * @returns {R} The item with the given id. */ From d549703a53d25e435d02788b3333a51cc3547d35 Mon Sep 17 00:00:00 2001 From: delangle Date: Tue, 21 May 2024 11:15:28 +0200 Subject: [PATCH 2/8] Fix --- .../rich-tree-view/focus/ApiMethodFocusItem.tsx.preview | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx.preview diff --git a/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx.preview b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx.preview new file mode 100644 index 0000000000000..144d8e4e8dd5d --- /dev/null +++ b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx.preview @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file From b8d25cf36b24105402ad3d5bcfab6f73aafa8690 Mon Sep 17 00:00:00 2001 From: Flavien DELANGLE Date: Tue, 21 May 2024 11:26:33 +0200 Subject: [PATCH 3/8] Update docs/data/tree-view/rich-tree-view/focus/focus.md Co-authored-by: Michel Engelen <32863416+michelengelen@users.noreply.github.com> Signed-off-by: Flavien DELANGLE --- docs/data/tree-view/rich-tree-view/focus/focus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/tree-view/rich-tree-view/focus/focus.md b/docs/data/tree-view/rich-tree-view/focus/focus.md index 34a128eee4571..56123cf385cb4 100644 --- a/docs/data/tree-view/rich-tree-view/focus/focus.md +++ b/docs/data/tree-view/rich-tree-view/focus/focus.md @@ -27,7 +27,7 @@ return ; ### Focus a specific item -Use the `apiRef.focusItem` method to focus a specific item. +Use the `focusItem` API method to focus a specific item. ```ts apiRef.current.focusedItem( From a4dbe47b51f82611cb99181df2cbeac756deed0f Mon Sep 17 00:00:00 2001 From: Flavien DELANGLE Date: Tue, 21 May 2024 11:26:37 +0200 Subject: [PATCH 4/8] Update docs/data/tree-view/rich-tree-view/focus/focus.md Co-authored-by: Michel Engelen <32863416+michelengelen@users.noreply.github.com> Signed-off-by: Flavien DELANGLE --- docs/data/tree-view/rich-tree-view/focus/focus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/tree-view/rich-tree-view/focus/focus.md b/docs/data/tree-view/rich-tree-view/focus/focus.md index 56123cf385cb4..16ce1bd94ce4b 100644 --- a/docs/data/tree-view/rich-tree-view/focus/focus.md +++ b/docs/data/tree-view/rich-tree-view/focus/focus.md @@ -30,7 +30,7 @@ return ; Use the `focusItem` API method to focus a specific item. ```ts -apiRef.current.focusedItem( +apiRef.current.focusItem( // The DOM event that triggered the change event, // The ID of the item to focus From 3541890a02c3d2315db244d7856fba03696ffb3a Mon Sep 17 00:00:00 2001 From: Flavien DELANGLE Date: Tue, 21 May 2024 11:26:44 +0200 Subject: [PATCH 5/8] Update docs/data/tree-view/rich-tree-view/items/items.md Co-authored-by: Michel Engelen <32863416+michelengelen@users.noreply.github.com> Signed-off-by: Flavien DELANGLE --- docs/data/tree-view/rich-tree-view/items/items.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/tree-view/rich-tree-view/items/items.md b/docs/data/tree-view/rich-tree-view/items/items.md index d9d97dd9ddf5b..053934eabefae 100644 --- a/docs/data/tree-view/rich-tree-view/items/items.md +++ b/docs/data/tree-view/rich-tree-view/items/items.md @@ -145,7 +145,7 @@ When it's set to true: ### Get an item by ID -Use the `getItem` method to get an item by its ID. +Use the `getItem` API method to get an item by its ID. ```ts const item = apiRef.current.getItem( From 309a4e80d2f51a6bb7c21ec001b9f160786cf9e6 Mon Sep 17 00:00:00 2001 From: Flavien DELANGLE Date: Tue, 21 May 2024 11:26:50 +0200 Subject: [PATCH 6/8] Update docs/data/tree-view/simple-tree-view/focus/focus.md Co-authored-by: Michel Engelen <32863416+michelengelen@users.noreply.github.com> Signed-off-by: Flavien DELANGLE --- docs/data/tree-view/simple-tree-view/focus/focus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/tree-view/simple-tree-view/focus/focus.md b/docs/data/tree-view/simple-tree-view/focus/focus.md index d9734ecf58576..41e376096a90f 100644 --- a/docs/data/tree-view/simple-tree-view/focus/focus.md +++ b/docs/data/tree-view/simple-tree-view/focus/focus.md @@ -27,7 +27,7 @@ return {children}; ### Focus a specific item -Use the `apiRef.focusItem` method to focus a specific item. +Use the `focusItem` API method to focus a specific item. ```ts apiRef.current.focusedItem( From f5c65f0a90d95769609997ebab044f1ece127090 Mon Sep 17 00:00:00 2001 From: delangle Date: Tue, 21 May 2024 11:27:32 +0200 Subject: [PATCH 7/8] Fix --- docs/data/tree-view/simple-tree-view/focus/focus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/tree-view/simple-tree-view/focus/focus.md b/docs/data/tree-view/simple-tree-view/focus/focus.md index 41e376096a90f..9e49e777dd532 100644 --- a/docs/data/tree-view/simple-tree-view/focus/focus.md +++ b/docs/data/tree-view/simple-tree-view/focus/focus.md @@ -30,7 +30,7 @@ return {children}; Use the `focusItem` API method to focus a specific item. ```ts -apiRef.current.focusedItem( +apiRef.current.focusItem( // The DOM event that triggered the change event, // The ID of the item to focus From f325b2a5c7eb91a427a3660d8b37d2f3507592ae Mon Sep 17 00:00:00 2001 From: delangle Date: Tue, 21 May 2024 13:39:18 +0200 Subject: [PATCH 8/8] Review --- docs/data/tree-view/rich-tree-view/expansion/expansion.md | 3 ++- docs/data/tree-view/rich-tree-view/focus/focus.md | 3 ++- docs/data/tree-view/simple-tree-view/expansion/expansion.md | 3 ++- docs/data/tree-view/simple-tree-view/focus/focus.md | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/data/tree-view/rich-tree-view/expansion/expansion.md b/docs/data/tree-view/rich-tree-view/expansion/expansion.md index 220b31cb9559f..e36fe65d20c1e 100644 --- a/docs/data/tree-view/rich-tree-view/expansion/expansion.md +++ b/docs/data/tree-view/rich-tree-view/expansion/expansion.md @@ -44,7 +44,8 @@ const apiRef = useTreeViewApiRef(); return ; ``` -`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. ::: ### Change an item expansion diff --git a/docs/data/tree-view/rich-tree-view/focus/focus.md b/docs/data/tree-view/rich-tree-view/focus/focus.md index 16ce1bd94ce4b..7451953dac480 100644 --- a/docs/data/tree-view/rich-tree-view/focus/focus.md +++ b/docs/data/tree-view/rich-tree-view/focus/focus.md @@ -22,7 +22,8 @@ const apiRef = useTreeViewApiRef(); return ; ``` -`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 diff --git a/docs/data/tree-view/simple-tree-view/expansion/expansion.md b/docs/data/tree-view/simple-tree-view/expansion/expansion.md index 771f50b764087..a6b0a3f4e46ac 100644 --- a/docs/data/tree-view/simple-tree-view/expansion/expansion.md +++ b/docs/data/tree-view/simple-tree-view/expansion/expansion.md @@ -43,7 +43,8 @@ const apiRef = useTreeViewApiRef(); return {children}; ``` -`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. ::: ### Change an item expansion diff --git a/docs/data/tree-view/simple-tree-view/focus/focus.md b/docs/data/tree-view/simple-tree-view/focus/focus.md index 9e49e777dd532..d1596614823c5 100644 --- a/docs/data/tree-view/simple-tree-view/focus/focus.md +++ b/docs/data/tree-view/simple-tree-view/focus/focus.md @@ -22,7 +22,8 @@ const apiRef = useTreeViewApiRef(); return {children}; ``` -`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