@mui/x-tree-view 7.5.1 → 7.6.0

package/internals/models/treeView.d.ts

@@ -7,7 +7,11 @@ export interface TreeViewItemMeta {
     expandable: boolean;
     disabled: boolean;
     /**
-     * Only defined for `RichTreeView`.
+     * Only defined for `RichTreeView` and `RichTreeViewPro`.
+     */
+    depth?: number;
+    /**
+     * Only defined for `RichTreeView` and `RichTreeViewPro`.
      */
     label?: string;
 }
@@ -18,3 +22,6 @@ export interface TreeViewModel<TValue> {
 }
 export type TreeViewInstance<TSignatures extends readonly TreeViewAnyPluginSignature[]> = MergePluginsProperty<TSignatures, 'instance'>;
 export type TreeViewPublicAPI<TSignatures extends readonly TreeViewAnyPluginSignature[]> = MergePluginsProperty<TSignatures, 'publicAPI'>;
+export type TreeViewExperimentalFeatures<TSignatures extends readonly TreeViewAnyPluginSignature[]> = {
+    [key in MergePluginsProperty<TSignatures, 'experimentalFeatures'>]?: boolean;
+};

package/internals/plugins/useTreeViewExpansion/useTreeViewExpansion.types.d.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { DefaultizedProps, TreeViewPluginSignature } from '../../models';
 import { UseTreeViewItemsSignature } from '../useTreeViewItems';
+import { TreeViewItemId } from '../../../models';
 export interface UseTreeViewExpansionPublicAPI {
     /**
      * Change the expansion status of a given item.
@@ -11,10 +12,33 @@ export interface UseTreeViewExpansionPublicAPI {
     setItemExpansion: (event: React.SyntheticEvent, itemId: string, isExpanded: boolean) => void;
 }
 export interface UseTreeViewExpansionInstance extends UseTreeViewExpansionPublicAPI {
-    isItemExpanded: (itemId: string) => boolean;
-    isItemExpandable: (itemId: string) => boolean;
-    toggleItemExpansion: (event: React.SyntheticEvent, itemId: string) => void;
-    expandAllSiblings: (event: React.KeyboardEvent, itemId: string) => void;
+    /**
+     * Check if an item is expanded.
+     * @param {TreeViewItemId} itemId The id of the item to check.
+     * @returns {boolean} `true` if the item is expanded, `false` otherwise.
+     */
+    isItemExpanded: (itemId: TreeViewItemId) => boolean;
+    /**
+     * Check if an item is expandable.
+     * Currently, an item is expandable if it has children.
+     * In the future, the user should be able to flag an item as expandable even if it has no loaded children to support children lazy loading.
+     * @param {TreeViewItemId} itemId The id of the item to check.
+     * @returns {boolean} `true` if the item can be expanded, `false` otherwise.
+     */
+    isItemExpandable: (itemId: TreeViewItemId) => boolean;
+    /**
+     * Toggle the current expansion of an item.
+     * If it is expanded, it will be collapsed, and vice versa.
+     * @param {React.SyntheticEvent} event The UI event that triggered the change.
+     * @param {TreeViewItemId} itemId The id of the item to toggle.
+     */
+    toggleItemExpansion: (event: React.SyntheticEvent, itemId: TreeViewItemId) => void;
+    /**
+     * Expand all the siblings (i.e.: the items that have the same parent) of a given item.
+     * @param {React.SyntheticEvent} event The UI event that triggered the change.
+     * @param {TreeViewItemId} itemId The id of the item whose siblings will be expanded.
+     */
+    expandAllSiblings: (event: React.KeyboardEvent, itemId: TreeViewItemId) => void;
 }
 export interface UseTreeViewExpansionParameters {
     /**

package/internals/plugins/useTreeViewFocus/useTreeViewFocus.js

@@ -5,17 +5,15 @@ import ownerDocument from '@mui/utils/ownerDocument';
 import { useInstanceEventHandler } from '../../hooks/useInstanceEventHandler';
 import { getActiveElement } from '../../utils/utils';
 import { getFirstNavigableItem } from '../../utils/tree';
-const useTabbableItemId = (instance, selectedItems) => {
-  const isItemVisible = itemId => {
+import { convertSelectedItemsToArray } from '../useTreeViewSelection/useTreeViewSelection.utils';
+const useDefaultFocusableItemId = (instance, selectedItems) => {
+  let tabbableItemId = convertSelectedItemsToArray(selectedItems).find(itemId => {
+    if (!instance.isItemNavigable(itemId)) {
+      return false;
+    }
     const itemMeta = instance.getItemMeta(itemId);
     return itemMeta && (itemMeta.parentId == null || instance.isItemExpanded(itemMeta.parentId));
-  };
-  let tabbableItemId;
-  if (Array.isArray(selectedItems)) {
-    tabbableItemId = selectedItems.find(isItemVisible);
-  } else if (selectedItems != null && isItemVisible(selectedItems)) {
-    tabbableItemId = selectedItems;
-  }
+  });
   if (tabbableItemId == null) {
     tabbableItemId = getFirstNavigableItem(instance);
   }
@@ -29,7 +27,7 @@ export const useTreeViewFocus = ({
   models,
   rootRef
 }) => {
-  const tabbableItemId = useTabbableItemId(instance, models.selectedItems.value);
+  const defaultFocusableItemId = useDefaultFocusableItemId(instance, models.selectedItems.value);
   const setFocusedItemId = useEventCallback(itemId => {
     const cleanItemId = typeof itemId === 'function' ? itemId(state.focusedItemId) : itemId;
     if (state.focusedItemId !== cleanItemId) {
@@ -61,18 +59,6 @@ export const useTreeViewFocus = ({
       innerFocusItem(event, itemId);
     }
   });
-  const focusDefaultItem = useEventCallback(event => {
-    let itemToFocusId;
-    if (Array.isArray(models.selectedItems.value)) {
-      itemToFocusId = models.selectedItems.value.find(isItemVisible);
-    } else if (models.selectedItems.value != null && isItemVisible(models.selectedItems.value)) {
-      itemToFocusId = models.selectedItems.value;
-    }
-    if (itemToFocusId == null) {
-      itemToFocusId = getFirstNavigableItem(instance);
-    }
-    innerFocusItem(event, itemToFocusId);
-  });
   const removeFocusedItem = useEventCallback(() => {
     if (state.focusedItemId == null) {
       return;
@@ -86,12 +72,12 @@ export const useTreeViewFocus = ({
     }
     setFocusedItemId(null);
   });
-  const canItemBeTabbed = itemId => itemId === tabbableItemId;
+  const canItemBeTabbed = itemId => itemId === defaultFocusableItemId;
   useInstanceEventHandler(instance, 'removeItem', ({
     id
   }) => {
     if (state.focusedItemId === id) {
-      instance.focusDefaultItem(null);
+      innerFocusItem(null, defaultFocusableItemId);
     }
   });
   const createRootHandleFocus = otherHandlers => event => {
@@ -102,7 +88,7 @@ export const useTreeViewFocus = ({
 
     // if the event bubbled (which is React specific) we don't want to steal focus
     if (event.target === event.currentTarget) {
-      instance.focusDefaultItem(event);
+      innerFocusItem(event, defaultFocusableItemId);
     }
   };
   return {
@@ -116,7 +102,6 @@ export const useTreeViewFocus = ({
       isItemFocused,
       canItemBeTabbed,
       focusItem,
-      focusDefaultItem,
       removeFocusedItem
     }
   };

package/internals/plugins/useTreeViewFocus/useTreeViewFocus.types.d.ts

@@ -4,21 +4,36 @@ import { UseTreeViewIdSignature } from '../useTreeViewId/useTreeViewId.types';
 import type { UseTreeViewItemsSignature } from '../useTreeViewItems';
 import type { UseTreeViewSelectionSignature } from '../useTreeViewSelection';
 import { UseTreeViewExpansionSignature } from '../useTreeViewExpansion';
+import { TreeViewItemId } from '../../../models';
 export interface UseTreeViewFocusPublicAPI {
     /**
-     * Focuses the item with the given id.
+     * Focus the item with the given id.
      *
      * If the item is the child of a collapsed item, then this method will do nothing.
      * Make sure to expand the ancestors of the item before calling this method if needed.
      * @param {React.SyntheticEvent} event The event source of the action.
-     * @param {string} itemId The id of the item to focus.
+     * @param {TreeViewItemId} itemId The id of the item to focus.
      */
     focusItem: (event: React.SyntheticEvent, itemId: string) => void;
 }
 export interface UseTreeViewFocusInstance extends UseTreeViewFocusPublicAPI {
-    isItemFocused: (itemId: string) => boolean;
-    canItemBeTabbed: (itemId: string) => boolean;
-    focusDefaultItem: (event: React.SyntheticEvent | null) => void;
+    /**
+     * Check if an item is the currently focused item.
+     * @param {TreeViewItemId} itemId The id of the item to check.
+     * @returns {boolean} `true` if the item is focused, `false` otherwise.
+     */
+    isItemFocused: (itemId: TreeViewItemId) => boolean;
+    /**
+     * Check if an item should be sequentially focusable (usually with the Tab key).
+     * At any point in time, there is a single item that can be sequentially focused in the Tree View.
+     * This item is the first selected item (that is both visible and navigable), if any, or the first navigable item if no item is selected.
+     * @param {TreeViewItemId} itemId The id of the item to check.
+     * @returns {boolean} `true` if the item can be sequentially focusable, `false` otherwise.
+     */
+    canItemBeTabbed: (itemId: TreeViewItemId) => boolean;
+    /**
+     * Remove the focus from the currently focused item (both from the internal state and the DOM).
+     */
     removeFocusedItem: () => void;
 }
 export interface UseTreeViewFocusParameters {

package/internals/plugins/useTreeViewId/useTreeViewId.types.d.ts

@@ -1,6 +1,15 @@
 import { TreeViewPluginSignature } from '../../models';
+import { TreeViewItemId } from '../../../models';
 export interface UseTreeViewIdInstance {
-    getTreeItemIdAttribute: (itemId: string, idAttribute: string | undefined) => string;
+    /**
+     * Get the id attribute (i.e.: the `id` attribute passed to the DOM element) of a tree item.
+     * If the user explicitly defined an id attribute, it will be returned.
+     * Otherwise, the method created a unique id for the item based on the Tree View id attribute and the item `itemId`
+     * @param {TreeViewItemId} itemId The id of the item to get the id attribute of.
+     * @param {string | undefined} idAttribute The id attribute of the item if explicitly defined by the user.
+     * @returns {string} The id attribute of the item.
+     */
+    getTreeItemIdAttribute: (itemId: TreeViewItemId, idAttribute: string | undefined) => string;
 }
 export interface UseTreeViewIdParameters {
     /**

package/internals/plugins/useTreeViewItems/useTreeViewItems.js

@@ -2,6 +2,8 @@ import _extends from "@babel/runtime/helpers/esm/extends";
 import * as React from 'react';
 import { publishTreeViewEvent } from '../../utils/publishTreeViewEvent';
 import { buildSiblingIndexes, TREE_VIEW_ROOT_PARENT_ID } from './useTreeViewItems.utils';
+import { TreeViewItemDepthContext } from '../../TreeViewItemDepthContext';
+import { jsx as _jsx } from "react/jsx-runtime";
 const updateItemsState = ({
   items,
   isItemDisabled,
@@ -13,7 +15,7 @@ const updateItemsState = ({
   const itemOrderedChildrenIds = {
     [TREE_VIEW_ROOT_PARENT_ID]: []
   };
-  const processItem = (item, parentId) => {
+  const processItem = (item, depth, parentId) => {
     const id = getItemId ? getItemId(item) : item.id;
     if (id == null) {
       throw new Error(['MUI X: The Tree View component requires all items to have a unique `id` property.', 'Alternatively, you can use the `getItemId` prop to specify a custom id for each item.', 'An item was provided without id in the `items` prop:', JSON.stringify(item)].join('\n'));
@@ -31,7 +33,8 @@ const updateItemsState = ({
       parentId,
       idAttribute: undefined,
       expandable: !!item.children?.length,
-      disabled: isItemDisabled ? isItemDisabled(item) : false
+      disabled: isItemDisabled ? isItemDisabled(item) : false,
+      depth
     };
     itemMap[id] = item;
     itemOrderedChildrenIds[id] = [];
@@ -40,9 +43,9 @@ const updateItemsState = ({
       itemOrderedChildrenIds[parentIdWithDefault] = [];
     }
     itemOrderedChildrenIds[parentIdWithDefault].push(id);
-    item.children?.forEach(child => processItem(child, id));
+    item.children?.forEach(child => processItem(child, depth + 1, id));
   };
-  items.forEach(item => processItem(item, null));
+  items.forEach(item => processItem(item, 0, null));
   const itemChildrenIndexes = {};
   Object.keys(itemOrderedChildrenIds).forEach(parentId => {
     itemChildrenIndexes[parentId] = buildSiblingIndexes(itemOrderedChildrenIds[parentId]);
@@ -58,7 +61,8 @@ export const useTreeViewItems = ({
   instance,
   params,
   state,
-  setState
+  setState,
+  experimentalFeatures
 }) => {
   const getItemMeta = React.useCallback(itemId => state.items.itemMetaMap[itemId], [state.items.itemMetaMap]);
   const getItem = React.useCallback(itemId => state.items.itemMap[itemId], [state.items.itemMap]);
@@ -135,6 +139,11 @@ export const useTreeViewItems = ({
     return state.items.itemOrderedChildrenIds[TREE_VIEW_ROOT_PARENT_ID].map(getPropsFromItemId);
   };
   return {
+    getRootProps: () => ({
+      style: {
+        '--TreeView-itemChildrenIndentation': typeof params.itemChildrenIndentation === 'number' ? `${params.itemChildrenIndentation}px` : params.itemChildrenIndentation
+      }
+    }),
     publicAPI: {
       getItem
     },
@@ -150,7 +159,8 @@ export const useTreeViewItems = ({
       areItemUpdatesPrevented
     },
     contextValue: {
-      disabledItemsFocusable: params.disabledItemsFocusable
+      disabledItemsFocusable: params.disabledItemsFocusable,
+      indentationAtItemLevel: experimentalFeatures.indentationAtItemLevel ?? false
     }
   };
 };
@@ -163,12 +173,23 @@ useTreeViewItems.getInitialState = params => ({
   })
 });
 useTreeViewItems.getDefaultizedParams = params => _extends({}, params, {
-  disabledItemsFocusable: params.disabledItemsFocusable ?? false
+  disabledItemsFocusable: params.disabledItemsFocusable ?? false,
+  itemChildrenIndentation: params.itemChildrenIndentation ?? '12px'
 });
+useTreeViewItems.wrapRoot = ({
+  children,
+  instance
+}) => {
+  return /*#__PURE__*/_jsx(TreeViewItemDepthContext.Provider, {
+    value: itemId => instance.getItemMeta(itemId)?.depth ?? 0,
+    children: children
+  });
+};
 useTreeViewItems.params = {
   disabledItemsFocusable: true,
   items: true,
   isItemDisabled: true,
   getItemLabel: true,
-  getItemId: true
+  getItemId: true,
+  itemChildrenIndentation: true
 };

package/internals/plugins/useTreeViewItems/useTreeViewItems.types.d.ts

@@ -13,15 +13,50 @@ export interface UseTreeViewItemsPublicAPI<R extends {}> {
      * @param {string} itemId The id of the item to return.
      * @returns {R} The item with the given id.
      */
-    getItem: (itemId: string) => R;
+    getItem: (itemId: TreeViewItemId) => R;
 }
 export interface UseTreeViewItemsInstance<R extends {}> extends UseTreeViewItemsPublicAPI<R> {
-    getItemMeta: (itemId: string) => TreeViewItemMeta;
+    /**
+     * Get the meta-information of an item.
+     * Check the `TreeViewItemMeta` type for more information.
+     * @param {TreeViewItemId} itemId The id of the item to get the meta-information of.
+     * @returns {TreeViewItemMeta} The meta-information of the item.
+     */
+    getItemMeta: (itemId: TreeViewItemId) => TreeViewItemMeta;
+    /**
+     * Get the item that should be rendered.
+     * This method is only used on Rich Tree View components.
+     * Check the `TreeViewItemProps` type for more information.
+     * @returns {TreeViewItemProps[]} The items to render.
+     */
     getItemsToRender: () => TreeViewItemProps[];
-    getItemOrderedChildrenIds: (parentId: string | null) => string[];
-    isItemDisabled: (itemId: string) => itemId is string;
-    isItemNavigable: (itemId: string) => boolean;
-    getItemIndex: (itemId: string) => number;
+    /**
+     * Get the ids of a given item's children.
+     * Those ids are returned in the order they should be rendered.
+     * @param {TreeViewItemId | null} itemId The id of the item to get the children of.
+     * @returns {TreeViewItemId[]} The ids of the item's children.
+     */
+    getItemOrderedChildrenIds: (itemId: TreeViewItemId | null) => TreeViewItemId[];
+    /**
+     * Check if a given item is disabled.
+     * An item is disabled if it was marked as disabled or if one of its ancestors is disabled.
+     * @param {TreeViewItemId} itemId The id of the item to check.
+     * @returns {boolean} `true` if the item is disabled, `false` otherwise.
+     */
+    isItemDisabled: (itemId: TreeViewItemId) => boolean;
+    /**
+     * Check if a given item is navigable (i.e.: if it can be accessed through keyboard navigation).
+     * An item is navigable if it is not disabled or if the `disabledItemsFocusable` prop is `true`.
+     * @param {TreeViewItemId} itemId The id of the item to check.
+     * @returns {boolean} `true` if the item is navigable, `false` otherwise.
+     */
+    isItemNavigable: (itemId: TreeViewItemId) => boolean;
+    /**
+     * Get the index of a given item in its parent's children list.
+     * @param {TreeViewItemId} itemId The id of the item to get the index of.
+     * @returns {number} The index of the item in its parent's children list.
+     */
+    getItemIndex: (itemId: TreeViewItemId) => number;
     /**
      * Freeze any future update to the state based on the `items` prop.
      * This is useful when `useTreeViewJSXItems` is used to avoid having conflicting sources of truth.
@@ -66,8 +101,14 @@ export interface UseTreeViewItemsParameters<R extends {}> {
      * @default (item) => item.id
      */
     getItemId?: (item: R) => TreeViewItemId;
+    /**
+     * Horizontal indentation between an item and its children.
+     * Examples: 24, "24px", "2rem", "2em".
+     * @default 12px
+     */
+    itemChildrenIndentation?: string | number;
 }
-export type UseTreeViewItemsDefaultizedParameters<R extends {}> = DefaultizedProps<UseTreeViewItemsParameters<R>, 'disabledItemsFocusable'>;
+export type UseTreeViewItemsDefaultizedParameters<R extends {}> = DefaultizedProps<UseTreeViewItemsParameters<R>, 'disabledItemsFocusable' | 'itemChildrenIndentation'>;
 interface UseTreeViewItemsEventLookup {
     removeItem: {
         params: {
@@ -90,6 +131,7 @@ export interface UseTreeViewItemsState<R extends {}> {
     };
 }
 interface UseTreeViewItemsContextValue extends Pick<UseTreeViewItemsDefaultizedParameters<any>, 'disabledItemsFocusable'> {
+    indentationAtItemLevel: boolean;
 }
 export type UseTreeViewItemsSignature = TreeViewPluginSignature<{
     params: UseTreeViewItemsParameters<any>;
@@ -99,6 +141,7 @@ export type UseTreeViewItemsSignature = TreeViewPluginSignature<{
     events: UseTreeViewItemsEventLookup;
     state: UseTreeViewItemsState<any>;
     contextValue: UseTreeViewItemsContextValue;
+    experimentalFeatures: 'indentationAtItemLevel';
 }>;
 export type TreeViewItemMetaMap = {
     [itemId: string]: TreeViewItemMeta;

package/internals/plugins/useTreeViewJSXItems/useTreeViewJSXItems.js

@@ -7,6 +7,7 @@ import { publishTreeViewEvent } from '../../utils/publishTreeViewEvent';
 import { useTreeViewContext } from '../../TreeViewProvider/useTreeViewContext';
 import { TreeViewChildrenItemContext, TreeViewChildrenItemProvider } from '../../TreeViewProvider/TreeViewChildrenItemProvider';
 import { buildSiblingIndexes, TREE_VIEW_ROOT_PARENT_ID } from '../useTreeViewItems/useTreeViewItems.utils';
+import { TreeViewItemDepthContext } from '../../TreeViewItemDepthContext';
 import { jsx as _jsx } from "react/jsx-runtime";
 export const useTreeViewJSXItems = ({
   instance,
@@ -33,6 +34,23 @@ export const useTreeViewJSXItems = ({
         })
       });
     });
+    return () => {
+      setState(prevState => {
+        const newItemMetaMap = _extends({}, prevState.items.itemMetaMap);
+        const newItemMap = _extends({}, prevState.items.itemMap);
+        delete newItemMetaMap[item.id];
+        delete newItemMap[item.id];
+        return _extends({}, prevState, {
+          items: _extends({}, prevState.items, {
+            itemMetaMap: newItemMetaMap,
+            itemMap: newItemMap
+          })
+        });
+      });
+      publishTreeViewEvent(instance, 'removeItem', {
+        id: item.id
+      });
+    };
   });
   const setJSXItemsOrderedChildrenIds = (parentId, orderedChildrenIds) => {
     const parentIdWithDefault = parentId ?? TREE_VIEW_ROOT_PARENT_ID;
@@ -47,23 +65,6 @@ export const useTreeViewJSXItems = ({
       })
     }));
   };
-  const removeJSXItem = useEventCallback(itemId => {
-    setState(prevState => {
-      const newItemMetaMap = _extends({}, prevState.items.itemMetaMap);
-      const newItemMap = _extends({}, prevState.items.itemMap);
-      delete newItemMetaMap[itemId];
-      delete newItemMap[itemId];
-      return _extends({}, prevState, {
-        items: _extends({}, prevState.items, {
-          itemMetaMap: newItemMetaMap,
-          itemMap: newItemMap
-        })
-      });
-    });
-    publishTreeViewEvent(instance, 'removeItem', {
-      id: itemId
-    });
-  });
   const mapFirstCharFromJSX = useEventCallback((itemId, firstChar) => {
     instance.updateFirstCharMap(firstCharMap => {
       firstCharMap[itemId] = firstChar;
@@ -80,7 +81,6 @@ export const useTreeViewJSXItems = ({
   return {
     instance: {
       insertJSXItem,
-      removeJSXItem,
       setJSXItemsOrderedChildrenIds,
       mapFirstCharFromJSX
     }
@@ -129,14 +129,13 @@ const useTreeViewJSXItemsItemPlugin = ({
     };
   }, [instance, registerChild, unregisterChild, itemId, id]);
   React.useEffect(() => {
-    instance.insertJSXItem({
+    return instance.insertJSXItem({
       id: itemId,
       idAttribute: id,
       parentId,
       expandable,
       disabled
     });
-    return () => instance.removeJSXItem(itemId);
   }, [instance, parentId, itemId, expandable, disabled, id]);
   React.useEffect(() => {
     if (label) {
@@ -153,13 +152,23 @@ useTreeViewJSXItems.itemPlugin = useTreeViewJSXItemsItemPlugin;
 useTreeViewJSXItems.wrapItem = ({
   children,
   itemId
-}) => /*#__PURE__*/_jsx(TreeViewChildrenItemProvider, {
-  itemId: itemId,
-  children: children
-});
+}) => {
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const depthContext = React.useContext(TreeViewItemDepthContext);
+  return /*#__PURE__*/_jsx(TreeViewChildrenItemProvider, {
+    itemId: itemId,
+    children: /*#__PURE__*/_jsx(TreeViewItemDepthContext.Provider, {
+      value: depthContext + 1,
+      children: children
+    })
+  });
+};
 useTreeViewJSXItems.wrapRoot = ({
   children
 }) => /*#__PURE__*/_jsx(TreeViewChildrenItemProvider, {
-  children: children
+  children: /*#__PURE__*/_jsx(TreeViewItemDepthContext.Provider, {
+    value: 0,
+    children: children
+  })
 });
 useTreeViewJSXItems.params = {};

package/internals/plugins/useTreeViewJSXItems/useTreeViewJSXItems.types.d.ts

@@ -1,11 +1,29 @@
 import { TreeViewItemMeta, TreeViewPluginSignature } from '../../models';
 import { UseTreeViewItemsSignature } from '../useTreeViewItems';
 import { UseTreeViewKeyboardNavigationSignature } from '../useTreeViewKeyboardNavigation';
+import { TreeViewItemId } from '../../../models';
 export interface UseTreeViewItemsInstance {
-    insertJSXItem: (item: TreeViewItemMeta) => void;
-    removeJSXItem: (itemId: string) => void;
-    mapFirstCharFromJSX: (itemId: string, firstChar: string) => () => void;
-    setJSXItemsOrderedChildrenIds: (parentId: string | null, orderedChildrenIds: string[]) => void;
+    /**
+     * Insert a new item in the state from a Tree Item component.
+     * @param {TreeViewItemMeta} item The meta-information of the item to insert.
+     * @returns {() => void} A function to remove the item from the state.
+     */
+    insertJSXItem: (item: TreeViewItemMeta) => () => void;
+    /**
+     * Updates the `firstCharMap` to register the first character of the given item's label.
+     * This map is used to navigate the tree using type-ahead search.
+     * @param {TreeViewItemId} itemId The id of the item to map the first character of.
+     * @param {string} firstChar The first character of the item's label.
+     * @returns {() => void} A function to remove the item from the `firstCharMap`.
+     */
+    mapFirstCharFromJSX: (itemId: TreeViewItemId, firstChar: string) => () => void;
+    /**
+     * Store the ids of a given item's children in the state.
+     * Those ids must be passed in the order they should be rendered.
+     * @param {TreeViewItemId | null} parentId The id of the item to store the children of.
+     * @param {TreeViewItemId[]} orderedChildrenIds The ids of the item's children.
+     */
+    setJSXItemsOrderedChildrenIds: (parentId: TreeViewItemId | null, orderedChildrenIds: TreeViewItemId[]) => void;
 }
 export interface UseTreeViewJSXItemsParameters {
 }

package/internals/plugins/useTreeViewKeyboardNavigation/useTreeViewKeyboardNavigation.types.d.ts

@@ -5,9 +5,22 @@ import { UseTreeViewSelectionSignature } from '../useTreeViewSelection';
 import { UseTreeViewFocusSignature } from '../useTreeViewFocus';
 import { UseTreeViewExpansionSignature } from '../useTreeViewExpansion';
 import { MuiCancellableEvent } from '../../models/MuiCancellableEvent';
+import { TreeViewItemId } from '../../../models';
 export interface UseTreeViewKeyboardNavigationInstance {
+    /**
+     * Updates the `firstCharMap` to add/remove the first character of some item's labels.
+     * This map is used to navigate the tree using type-ahead search.
+     * This method is only used by the `useTreeViewJSXItems` plugin, otherwise the updates are handled internally.
+     * @param {(map: TreeViewFirstCharMap) => TreeViewFirstCharMap} updater The function to update the map.
+     */
     updateFirstCharMap: (updater: (map: TreeViewFirstCharMap) => TreeViewFirstCharMap) => void;
-    handleItemKeyDown: (event: React.KeyboardEvent<HTMLElement> & MuiCancellableEvent, itemId: string) => void;
+    /**
+     * Callback fired when a key is pressed on an item.
+     * Handles all the keyboard navigation logic.
+     * @param {React.KeyboardEvent<HTMLElement> & MuiCancellableEvent} event The keyboard event that triggered the callback.
+     * @param {TreeViewItemId} itemId The id of the item that the event was triggered on.
+     */
+    handleItemKeyDown: (event: React.KeyboardEvent<HTMLElement> & MuiCancellableEvent, itemId: TreeViewItemId) => void;
 }
 export type UseTreeViewKeyboardNavigationSignature = TreeViewPluginSignature<{
     instance: UseTreeViewKeyboardNavigationInstance;

package/internals/plugins/useTreeViewSelection/useTreeViewSelection.types.d.ts

@@ -3,6 +3,11 @@ import type { DefaultizedProps, TreeViewPluginSignature } from '../../models';
 import { UseTreeViewItemsSignature } from '../useTreeViewItems';
 import { UseTreeViewExpansionSignature } from '../useTreeViewExpansion';
 export interface UseTreeViewSelectionInstance {
+    /**
+     * Check if an item is selected.
+     * @param {TreeViewItemId} itemId The id of the item to check.
+     * @returns {boolean} `true` if the item is selected, `false` otherwise.
+     */
     isItemSelected: (itemId: string) => boolean;
     /**
      * Select or deselect an item.

package/internals/useTreeView/useTreeView.js

@@ -48,6 +48,7 @@ export const useTreeView = inParams => {
       params,
       slots: params.slots,
       slotProps: params.slotProps,
+      experimentalFeatures: params.experimentalFeatures,
       state,
       setState,
       rootRef: innerRootRef,
@@ -100,19 +101,23 @@ export const useTreeView = inParams => {
     itemWrappers.forEach(itemWrapper => {
       finalChildren = itemWrapper({
         itemId,
-        children: finalChildren
+        children: finalChildren,
+        instance
       });
     });
     return finalChildren;
   };
-  const rootWrappers = plugins.map(plugin => plugin.wrapRoot).filter(wrapRoot => !!wrapRoot);
+  const rootWrappers = plugins.map(plugin => plugin.wrapRoot).filter(wrapRoot => !!wrapRoot)
+  // The wrappers are reversed to ensure that the first wrapper is the outermost one.
+  .reverse();
   contextValue.wrapRoot = ({
     children
   }) => {
     let finalChildren = children;
     rootWrappers.forEach(rootWrapper => {
       finalChildren = rootWrapper({
-        children: finalChildren
+        children: finalChildren,
+        instance
       });
     });
     return finalChildren;

package/internals/useTreeView/useTreeView.types.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { EventHandlers } from '@mui/base/utils';
 import type { TreeViewContextValue } from '../TreeViewProvider';
-import { TreeViewAnyPluginSignature, TreeViewPlugin, ConvertPluginsIntoSignatures, MergePluginsProperty, TreeViewInstance, TreeViewPublicAPI } from '../models';
+import { TreeViewAnyPluginSignature, TreeViewPlugin, ConvertPluginsIntoSignatures, MergePluginsProperty, TreeViewInstance, TreeViewPublicAPI, TreeViewExperimentalFeatures } from '../models';
 export type UseTreeViewParameters<TPlugins extends readonly TreeViewPlugin<TreeViewAnyPluginSignature>[]> = UseTreeViewBaseParameters<TPlugins> & MergePluginsProperty<ConvertPluginsIntoSignatures<TPlugins>, 'params'>;
 export interface UseTreeViewBaseParameters<TPlugins extends readonly TreeViewPlugin<TreeViewAnyPluginSignature>[]> {
     apiRef: React.MutableRefObject<TreeViewPublicAPI<ConvertPluginsIntoSignatures<TPlugins>>> | undefined;
@@ -9,6 +9,7 @@ export interface UseTreeViewBaseParameters<TPlugins extends readonly TreeViewPlu
     plugins: TPlugins;
     slots: MergePluginsProperty<ConvertPluginsIntoSignatures<TPlugins>, 'slots'>;
     slotProps: MergePluginsProperty<ConvertPluginsIntoSignatures<TPlugins>, 'slotProps'>;
+    experimentalFeatures: TreeViewExperimentalFeatures<ConvertPluginsIntoSignatures<TPlugins>>;
 }
 export type UseTreeViewDefaultizedParameters<TPlugins extends readonly TreeViewPlugin<TreeViewAnyPluginSignature>[]> = UseTreeViewBaseParameters<TPlugins> & MergePluginsProperty<ConvertPluginsIntoSignatures<TPlugins>, 'defaultizedParams'>;
 export interface UseTreeViewRootSlotProps extends Pick<React.HTMLAttributes<HTMLUListElement>, 'onFocus' | 'onBlur' | 'onKeyDown' | 'id' | 'aria-multiselectable' | 'role' | 'tabIndex'> {

package/internals/utils/extractPluginParamsFromProps.d.ts

@@ -1,11 +1,12 @@
 import * as React from 'react';
-import { ConvertPluginsIntoSignatures, MergePluginsProperty, TreeViewPlugin, TreeViewPublicAPI } from '../models';
+import { ConvertPluginsIntoSignatures, MergePluginsProperty, TreeViewExperimentalFeatures, TreeViewPlugin, TreeViewPublicAPI } from '../models';
 import { UseTreeViewBaseParameters } from '../useTreeView/useTreeView.types';
 export declare const extractPluginParamsFromProps: <TPlugins extends readonly TreeViewPlugin<any>[], TSlots extends MergePluginsProperty<TPlugins, "slots">, TSlotProps extends MergePluginsProperty<TPlugins, "slotProps">, TProps extends {
     slots?: TSlots | undefined;
     slotProps?: TSlotProps | undefined;
     apiRef?: React.MutableRefObject<TreeViewPublicAPI<ConvertPluginsIntoSignatures<TPlugins>> | undefined> | undefined;
-}>({ props: { slots, slotProps, apiRef, ...props }, plugins, rootRef, }: {
+    experimentalFeatures?: TreeViewExperimentalFeatures<ConvertPluginsIntoSignatures<TPlugins>> | undefined;
+}>({ props: { slots, slotProps, apiRef, experimentalFeatures, ...props }, plugins, rootRef, }: {
     props: TProps;
     plugins: TPlugins;
     rootRef?: React.Ref<HTMLUListElement>;