@mui/x-tree-view 7.0.0-beta.7 → 7.1.0

package/{modern/internals/plugins/useTreeViewNodes/useTreeViewNodes.js → internals/plugins/useTreeViewItems/useTreeViewItems.js}

@@ -1,9 +1,8 @@
 import _extends from "@babel/runtime/helpers/esm/extends";
 import * as React from 'react';
-import useEventCallback from '@mui/utils/useEventCallback';
 import { populateInstance, populatePublicAPI } from '../../useTreeView/useTreeView.utils';
 import { publishTreeViewEvent } from '../../utils/publishTreeViewEvent';
-const updateNodesState = ({
+const updateItemsState = ({
   items,
   isItemDisabled,
   getItemLabel,
@@ -45,22 +44,22 @@ const updateNodesState = ({
     itemMap
   };
 };
-export const useTreeViewNodes = ({
+export const useTreeViewItems = ({
   instance,
   publicAPI,
   params,
   state,
   setState
 }) => {
-  const getNode = React.useCallback(nodeId => state.nodes.nodeMap[nodeId], [state.nodes.nodeMap]);
-  const getItem = React.useCallback(nodeId => state.nodes.itemMap[nodeId], [state.nodes.itemMap]);
-  const isNodeDisabled = React.useCallback(nodeId => {
-    if (nodeId == null) {
+  const getNode = React.useCallback(itemId => state.items.nodeMap[itemId], [state.items.nodeMap]);
+  const getItem = React.useCallback(itemId => state.items.itemMap[itemId], [state.items.itemMap]);
+  const isItemDisabled = React.useCallback(itemId => {
+    if (itemId == null) {
       return false;
     }
-    let node = instance.getNode(nodeId);
+    let node = instance.getNode(itemId);
 
-    // This can be called before the node has been added to the node map.
+    // This can be called before the item has been added to the item map.
     if (!node) {
       return false;
     }
@@ -75,56 +74,66 @@ export const useTreeViewNodes = ({
     }
     return false;
   }, [instance]);
-  const getChildrenIds = useEventCallback(nodeId => Object.values(state.nodes.nodeMap).filter(node => node.parentId === nodeId).sort((a, b) => a.index - b.index).map(child => child.id));
-  const getNavigableChildrenIds = nodeId => {
-    let childrenIds = instance.getChildrenIds(nodeId);
+  const getChildrenIds = React.useCallback(itemId => Object.values(state.items.nodeMap).filter(item => item.parentId === itemId).sort((a, b) => a.index - b.index).map(child => child.id), [state.items.nodeMap]);
+  const getNavigableChildrenIds = itemId => {
+    let childrenIds = instance.getChildrenIds(itemId);
     if (!params.disabledItemsFocusable) {
-      childrenIds = childrenIds.filter(node => !instance.isNodeDisabled(node));
+      childrenIds = childrenIds.filter(item => !instance.isItemDisabled(item));
     }
     return childrenIds;
   };
+  const areItemUpdatesPreventedRef = React.useRef(false);
+  const preventItemUpdates = React.useCallback(() => {
+    areItemUpdatesPreventedRef.current = true;
+  }, []);
+  const areItemUpdatesPrevented = React.useCallback(() => areItemUpdatesPreventedRef.current, []);
   React.useEffect(() => {
+    if (instance.areItemUpdatesPrevented()) {
+      return;
+    }
     setState(prevState => {
-      const newState = updateNodesState({
+      const newState = updateItemsState({
         items: params.items,
         isItemDisabled: params.isItemDisabled,
         getItemId: params.getItemId,
         getItemLabel: params.getItemLabel
       });
-      Object.values(prevState.nodes.nodeMap).forEach(node => {
-        if (!newState.nodeMap[node.id]) {
-          publishTreeViewEvent(instance, 'removeNode', {
-            id: node.id
+      Object.values(prevState.items.nodeMap).forEach(item => {
+        if (!newState.nodeMap[item.id]) {
+          publishTreeViewEvent(instance, 'removeItem', {
+            id: item.id
           });
         }
       });
       return _extends({}, prevState, {
-        nodes: newState
+        items: newState
       });
     });
   }, [instance, setState, params.items, params.isItemDisabled, params.getItemId, params.getItemLabel]);
-  const getNodesToRender = () => {
-    const getPropsFromNodeId = ({
+  const getItemsToRender = () => {
+    const getPropsFromItemId = ({
       id,
       children
     }) => {
-      const node = state.nodes.nodeMap[id];
+      const item = state.items.nodeMap[id];
       return {
-        label: node.label,
-        nodeId: node.id,
-        id: node.idAttribute,
-        children: children?.map(getPropsFromNodeId)
+        label: item.label,
+        itemId: item.id,
+        id: item.idAttribute,
+        children: children?.map(getPropsFromItemId)
       };
     };
-    return state.nodes.nodeTree.map(getPropsFromNodeId);
+    return state.items.nodeTree.map(getPropsFromItemId);
   };
   populateInstance(instance, {
     getNode,
     getItem,
-    getNodesToRender,
+    getItemsToRender,
     getChildrenIds,
     getNavigableChildrenIds,
-    isNodeDisabled
+    isItemDisabled,
+    preventItemUpdates,
+    areItemUpdatesPrevented
   });
   populatePublicAPI(publicAPI, {
     getItem
@@ -135,18 +144,18 @@ export const useTreeViewNodes = ({
     }
   };
 };
-useTreeViewNodes.getInitialState = params => ({
-  nodes: updateNodesState({
+useTreeViewItems.getInitialState = params => ({
+  items: updateItemsState({
     items: params.items,
     isItemDisabled: params.isItemDisabled,
     getItemId: params.getItemId,
     getItemLabel: params.getItemLabel
   })
 });
-useTreeViewNodes.getDefaultizedParams = params => _extends({}, params, {
+useTreeViewItems.getDefaultizedParams = params => _extends({}, params, {
   disabledItemsFocusable: params.disabledItemsFocusable ?? false
 });
-useTreeViewNodes.params = {
+useTreeViewItems.params = {
   disabledItemsFocusable: true,
   items: true,
   isItemDisabled: true,

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

@@ -0,0 +1,99 @@
+import { TreeViewNode, DefaultizedProps, TreeViewPluginSignature } from '../../models';
+import { TreeViewItemId } from '../../../models';
+interface TreeViewItemProps {
+    label: string;
+    itemId: string;
+    id: string | undefined;
+    children?: TreeViewItemProps[];
+}
+export interface UseTreeViewItemsInstance<R extends {}> {
+    getNode: (itemId: string) => TreeViewNode;
+    getItem: (itemId: string) => R;
+    getItemsToRender: () => TreeViewItemProps[];
+    getChildrenIds: (itemId: string | null) => string[];
+    getNavigableChildrenIds: (itemId: string | null) => string[];
+    isItemDisabled: (itemId: string | null) => itemId is string;
+    /**
+     * Freeze any future update to the state based on the `items` prop.
+     * This is useful when `useTreeViewJSXNodes` is used to avoid having conflicting sources of truth.
+     */
+    preventItemUpdates: () => void;
+    /**
+     * Check if the updates to the state based on the `items` prop are prevented.
+     * This is useful when `useTreeViewJSXNodes` is used to avoid having conflicting sources of truth.
+     * @returns {boolean} `true` if the updates to the state based on the `items` prop are prevented.
+     */
+    areItemUpdatesPrevented: () => boolean;
+}
+export interface UseTreeViewItemsPublicAPI<R extends {}> extends Pick<UseTreeViewItemsInstance<R>, 'getItem'> {
+}
+export interface UseTreeViewItemsParameters<R extends {}> {
+    /**
+     * If `true`, will allow focus on disabled items.
+     * @default false
+     */
+    disabledItemsFocusable?: boolean;
+    items: readonly R[];
+    /**
+     * Used to determine if a given item should be disabled.
+     * @template R
+     * @param {R} item The item to check.
+     * @returns {boolean} `true` if the item should be disabled.
+     */
+    isItemDisabled?: (item: R) => boolean;
+    /**
+     * Used to determine the string label for a given item.
+     *
+     * @template R
+     * @param {R} item The item to check.
+     * @returns {string} The label of the item.
+     * @default `(item) => item.label`
+     */
+    getItemLabel?: (item: R) => string;
+    /**
+     * Used to determine the string label for a given item.
+     *
+     * @template R
+     * @param {R} item The item to check.
+     * @returns {string} The id of the item.
+     * @default `(item) => item.id`
+     */
+    getItemId?: (item: R) => TreeViewItemId;
+}
+export type UseTreeViewItemsDefaultizedParameters<R extends {}> = DefaultizedProps<UseTreeViewItemsParameters<R>, 'disabledItemsFocusable'>;
+interface UseTreeViewItemsEventLookup {
+    removeItem: {
+        params: {
+            id: string;
+        };
+    };
+}
+export interface TreeViewItemIdAndChildren {
+    id: TreeViewItemId;
+    children?: TreeViewItemIdAndChildren[];
+}
+export interface UseTreeViewItemsState<R extends {}> {
+    items: {
+        nodeTree: TreeViewItemIdAndChildren[];
+        nodeMap: TreeViewNodeMap;
+        itemMap: TreeViewItemMap<R>;
+    };
+}
+interface UseTreeViewItemsContextValue extends Pick<UseTreeViewItemsDefaultizedParameters<any>, 'disabledItemsFocusable'> {
+}
+export type UseTreeViewItemsSignature = TreeViewPluginSignature<{
+    params: UseTreeViewItemsParameters<any>;
+    defaultizedParams: UseTreeViewItemsDefaultizedParameters<any>;
+    instance: UseTreeViewItemsInstance<any>;
+    publicAPI: UseTreeViewItemsPublicAPI<any>;
+    events: UseTreeViewItemsEventLookup;
+    state: UseTreeViewItemsState<any>;
+    contextValue: UseTreeViewItemsContextValue;
+}>;
+export type TreeViewNodeMap = {
+    [itemId: string]: TreeViewNode;
+};
+export type TreeViewItemMap<R extends {}> = {
+    [itemId: string]: R;
+};
+export {};

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

@@ -0,0 +1,2 @@
+export { useTreeViewJSXItems } from './useTreeViewJSXItems';
+export type { UseTreeViewJSXItemsSignature, UseTreeViewItemsParameters, UseTreeViewItemsDefaultizedParameters, } from './useTreeViewJSXItems.types';

package/internals/plugins/useTreeViewJSXItems/index.js

@@ -0,0 +1 @@
+export { useTreeViewJSXItems } from './useTreeViewJSXItems';

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

@@ -0,0 +1,3 @@
+import { TreeViewPlugin } from '../../models';
+import { UseTreeViewJSXItemsSignature } from './useTreeViewJSXItems.types';
+export declare const useTreeViewJSXItems: TreeViewPlugin<UseTreeViewJSXItemsSignature>;

package/{modern/internals/plugins/useTreeViewJSXNodes/useTreeViewJSXNodes.js → internals/plugins/useTreeViewJSXItems/useTreeViewJSXItems.js}

@@ -7,68 +7,69 @@ import { publishTreeViewEvent } from '../../utils/publishTreeViewEvent';
 import { useTreeViewContext } from '../../TreeViewProvider/useTreeViewContext';
 import { DescendantProvider, useDescendant } from '../../TreeViewProvider/DescendantProvider';
 import { jsx as _jsx } from "react/jsx-runtime";
-export const useTreeViewJSXNodes = ({
+export const useTreeViewJSXItems = ({
   instance,
   setState
 }) => {
-  const insertJSXNode = useEventCallback(node => {
+  instance.preventItemUpdates();
+  const insertJSXItem = useEventCallback(item => {
     setState(prevState => {
-      if (prevState.nodes.nodeMap[node.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.', `Tow items were provided with the same id in the \`items\` prop: "${node.id}"`].join('\n'));
+      if (prevState.items.nodeMap[item.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.', `Tow items were provided with the same id in the \`items\` prop: "${item.id}"`].join('\n'));
       }
       return _extends({}, prevState, {
-        nodes: _extends({}, prevState.nodes, {
-          nodeMap: _extends({}, prevState.nodes.nodeMap, {
-            [node.id]: node
+        items: _extends({}, prevState.items, {
+          nodeMap: _extends({}, prevState.items.nodeMap, {
+            [item.id]: item
           }),
           // For `SimpleTreeView`, we don't have a proper `item` object, so we create a very basic one.
-          itemMap: _extends({}, prevState.nodes.itemMap, {
-            [node.id]: {
-              id: node.id,
-              label: node.label
+          itemMap: _extends({}, prevState.items.itemMap, {
+            [item.id]: {
+              id: item.id,
+              label: item.label
             }
           })
         })
       });
     });
   });
-  const removeJSXNode = useEventCallback(nodeId => {
+  const removeJSXItem = useEventCallback(itemId => {
     setState(prevState => {
-      const newNodeMap = _extends({}, prevState.nodes.nodeMap);
-      const newItemMap = _extends({}, prevState.nodes.itemMap);
-      delete newNodeMap[nodeId];
-      delete newItemMap[nodeId];
+      const newNodeMap = _extends({}, prevState.items.nodeMap);
+      const newItemMap = _extends({}, prevState.items.itemMap);
+      delete newNodeMap[itemId];
+      delete newItemMap[itemId];
       return _extends({}, prevState, {
-        nodes: _extends({}, prevState.nodes, {
+        items: _extends({}, prevState.items, {
           nodeMap: newNodeMap,
           itemMap: newItemMap
         })
       });
     });
-    publishTreeViewEvent(instance, 'removeNode', {
-      id: nodeId
+    publishTreeViewEvent(instance, 'removeItem', {
+      id: itemId
     });
   });
-  const mapFirstCharFromJSX = useEventCallback((nodeId, firstChar) => {
+  const mapFirstCharFromJSX = useEventCallback((itemId, firstChar) => {
     instance.updateFirstCharMap(firstCharMap => {
-      firstCharMap[nodeId] = firstChar;
+      firstCharMap[itemId] = firstChar;
       return firstCharMap;
     });
     return () => {
       instance.updateFirstCharMap(firstCharMap => {
         const newMap = _extends({}, firstCharMap);
-        delete newMap[nodeId];
+        delete newMap[itemId];
         return newMap;
       });
     };
   });
   populateInstance(instance, {
-    insertJSXNode,
-    removeJSXNode,
+    insertJSXItem,
+    removeJSXItem,
     mapFirstCharFromJSX
   });
 };
-const useTreeViewJSXNodesItemPlugin = ({
+const useTreeViewJSXItemsItemPlugin = ({
   props,
   rootRef,
   contentRef
@@ -77,7 +78,7 @@ const useTreeViewJSXNodesItemPlugin = ({
     children,
     disabled = false,
     label,
-    nodeId,
+    itemId,
     id
   } = props;
   const {
@@ -96,44 +97,44 @@ const useTreeViewJSXNodesItemPlugin = ({
   const handleContentRef = useForkRef(pluginContentRef, contentRef);
   const descendant = React.useMemo(() => ({
     element: treeItemElement,
-    id: nodeId
-  }), [nodeId, treeItemElement]);
+    id: itemId
+  }), [itemId, treeItemElement]);
   const {
     index,
     parentId
   } = useDescendant(descendant);
   React.useEffect(() => {
-    // On the first render a node's index will be -1. We want to wait for the real index.
+    // On the first render a item's index will be -1. We want to wait for the real index.
     if (index !== -1) {
-      instance.insertJSXNode({
-        id: nodeId,
+      instance.insertJSXItem({
+        id: itemId,
         idAttribute: id,
         index,
         parentId,
         expandable,
         disabled
       });
-      return () => instance.removeJSXNode(nodeId);
+      return () => instance.removeJSXItem(itemId);
     }
     return undefined;
-  }, [instance, parentId, index, nodeId, expandable, disabled, id]);
+  }, [instance, parentId, index, itemId, expandable, disabled, id]);
   React.useEffect(() => {
     if (label) {
-      return instance.mapFirstCharFromJSX(nodeId, (pluginContentRef.current?.textContent ?? '').substring(0, 1).toLowerCase());
+      return instance.mapFirstCharFromJSX(itemId, (pluginContentRef.current?.textContent ?? '').substring(0, 1).toLowerCase());
     }
     return undefined;
-  }, [instance, nodeId, label]);
+  }, [instance, itemId, label]);
   return {
     contentRef: handleContentRef,
     rootRef: handleRootRef
   };
 };
-useTreeViewJSXNodes.itemPlugin = useTreeViewJSXNodesItemPlugin;
-useTreeViewJSXNodes.wrapItem = ({
+useTreeViewJSXItems.itemPlugin = useTreeViewJSXItemsItemPlugin;
+useTreeViewJSXItems.wrapItem = ({
   children,
-  nodeId
+  itemId
 }) => /*#__PURE__*/_jsx(DescendantProvider, {
-  id: nodeId,
+  id: itemId,
   children: children
 });
-useTreeViewJSXNodes.params = {};
+useTreeViewJSXItems.params = {};

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

@@ -0,0 +1,18 @@
+import { TreeViewNode, TreeViewPluginSignature } from '../../models';
+import { UseTreeViewItemsSignature } from '../useTreeViewItems';
+import { UseTreeViewKeyboardNavigationSignature } from '../useTreeViewKeyboardNavigation';
+export interface UseTreeViewItemsInstance {
+    insertJSXItem: (item: TreeViewNode) => void;
+    removeJSXItem: (itemId: string) => void;
+    mapFirstCharFromJSX: (itemId: string, firstChar: string) => () => void;
+}
+export interface UseTreeViewItemsParameters {
+}
+export interface UseTreeViewItemsDefaultizedParameters {
+}
+export type UseTreeViewJSXItemsSignature = TreeViewPluginSignature<{
+    params: UseTreeViewItemsParameters;
+    defaultizedParams: UseTreeViewItemsDefaultizedParameters;
+    instance: UseTreeViewItemsInstance;
+    dependantPlugins: [UseTreeViewItemsSignature, UseTreeViewKeyboardNavigationSignature];
+}>;