@mui/x-tree-view 8.23.0 → 8.24.0

package/esm/hooks/useTreeItemUtils/useTreeItemUtils.d.ts

@@ -1,12 +1,7 @@
 import * as React from 'react';
-import type { UseTreeViewLazyLoadingSignature } from "../../internals/plugins/useTreeViewLazyLoading/index.js";
-import type { UseTreeViewSelectionSignature } from "../../internals/plugins/useTreeViewSelection/index.js";
-import type { UseTreeViewExpansionSignature } from "../../internals/plugins/useTreeViewExpansion/index.js";
-import type { UseTreeViewItemsSignature } from "../../internals/plugins/useTreeViewItems/index.js";
-import type { UseTreeViewFocusSignature } from "../../internals/plugins/useTreeViewFocus/index.js";
-import { UseTreeViewLabelSignature } from "../../internals/plugins/useTreeViewLabel/index.js";
 import type { UseTreeItemStatus } from "../../useTreeItem/index.js";
-import { TreeViewPublicAPI } from "../../internals/models/index.js";
+import { TreeViewPublicAPI, TreeViewAnyStore } from "../../internals/models/index.js";
+import { TreeViewLabelEditingPlugin } from "../../internals/plugins/labelEditing/index.js";
 export interface UseTreeItemInteractions {
   handleExpansion: (event: React.MouseEvent) => void;
   handleSelection: (event: React.MouseEvent) => void;
@@ -15,28 +10,23 @@ export interface UseTreeItemInteractions {
   handleSaveItemLabel: (event: React.SyntheticEvent, label: string) => void;
   handleCancelItemLabelEditing: (event: React.SyntheticEvent) => void;
 }
-/**
- * Plugins that need to be present in the Tree View in order for `useTreeItemUtils` to work correctly.
- */
-type UseTreeItemUtilsMinimalPlugins = readonly [UseTreeViewSelectionSignature, UseTreeViewExpansionSignature, UseTreeViewItemsSignature, UseTreeViewFocusSignature];
-/**
- * Plugins that `useTreeItemUtils` can use if they are present, but are not required.
- */
-export type UseTreeItemUtilsOptionalPlugins = readonly [UseTreeViewLabelSignature, UseTreeViewLazyLoadingSignature];
-interface UseTreeItemUtilsReturnValue<TSignatures extends UseTreeItemUtilsMinimalPlugins, TOptionalSignatures extends UseTreeItemUtilsOptionalPlugins> {
+interface UseTreeItemUtilsReturnValue<TStore extends TreeViewAnyStore> {
   interactions: UseTreeItemInteractions;
   status: UseTreeItemStatus;
   /**
    * The object the allows Tree View manipulation.
    */
-  publicAPI: TreeViewPublicAPI<TSignatures, TOptionalSignatures>;
+  publicAPI: TreeViewPublicAPI<TStore>;
 }
+type TreeViewStoreWithLabelEditing = TreeViewAnyStore & {
+  labelEditing?: TreeViewLabelEditingPlugin;
+};
 export declare const itemHasChildren: (reactChildren: React.ReactNode) => boolean;
-export declare const useTreeItemUtils: <TSignatures extends UseTreeItemUtilsMinimalPlugins = UseTreeItemUtilsMinimalPlugins, TOptionalSignatures extends UseTreeItemUtilsOptionalPlugins = UseTreeItemUtilsOptionalPlugins>({
+export declare const useTreeItemUtils: <TStore extends TreeViewStoreWithLabelEditing = TreeViewStoreWithLabelEditing>({
   itemId,
   children
 }: {
   itemId: string;
   children?: React.ReactNode;
-}) => UseTreeItemUtilsReturnValue<TSignatures, TOptionalSignatures>;
+}) => UseTreeItemUtilsReturnValue<TStore>;
 export {};

package/esm/hooks/useTreeItemUtils/useTreeItemUtils.js

@@ -2,23 +2,12 @@
 
 import { useStore } from '@mui/x-internals/store';
 import { useTreeViewContext } from "../../internals/TreeViewProvider/index.js";
-import { useTreeViewLabel } from "../../internals/plugins/useTreeViewLabel/index.js";
-import { hasPlugin } from "../../internals/utils/plugins.js";
-import { expansionSelectors } from "../../internals/plugins/useTreeViewExpansion/useTreeViewExpansion.selectors.js";
-import { focusSelectors } from "../../internals/plugins/useTreeViewFocus/useTreeViewFocus.selectors.js";
-import { itemsSelectors } from "../../internals/plugins/useTreeViewItems/useTreeViewItems.selectors.js";
-import { selectionSelectors } from "../../internals/plugins/useTreeViewSelection/useTreeViewSelection.selectors.js";
-import { lazyLoadingSelectors } from "../../internals/plugins/useTreeViewLazyLoading/useTreeViewLazyLoading.selectors.js";
-import { labelSelectors } from "../../internals/plugins/useTreeViewLabel/useTreeViewLabel.selectors.js";
-
-/**
- * Plugins that need to be present in the Tree View in order for `useTreeItemUtils` to work correctly.
- */
-
-/**
- * Plugins that `useTreeItemUtils` can use if they are present, but are not required.
- */
-
+import { expansionSelectors } from "../../internals/plugins/expansion/selectors.js";
+import { focusSelectors } from "../../internals/plugins/focus/selectors.js";
+import { itemsSelectors } from "../../internals/plugins/items/selectors.js";
+import { selectionSelectors } from "../../internals/plugins/selection/selectors.js";
+import { lazyLoadingSelectors } from "../../internals/plugins/lazyLoading/selectors.js";
+import { labelSelectors } from "../../internals/plugins/labelEditing/selectors.js";
 export const itemHasChildren = reactChildren => {
   if (Array.isArray(reactChildren)) {
     return reactChildren.length > 0 && reactChildren.some(itemHasChildren);
@@ -30,7 +19,6 @@ export const useTreeItemUtils = ({
   children
 }) => {
   const {
-    instance,
     store,
     publicAPI
   } = useTreeViewContext();
@@ -60,14 +48,14 @@ export const useTreeItemUtils = ({
       return;
     }
     if (!status.focused) {
-      instance.focusItem(event, itemId);
+      store.focus.focusItem(event, itemId);
     }
     const multiple = selectionSelectors.isMultiSelectEnabled(store.state) && (event.shiftKey || event.ctrlKey || event.metaKey);
 
     // If already expanded and trying to toggle selection don't close
     if (status.expandable && !(multiple && expansionSelectors.isItemExpanded(store.state, itemId))) {
       // make sure the children selection is propagated again
-      instance.setItemExpansion({
+      store.expansion.setItemExpansion({
         event,
         itemId
       });
@@ -78,21 +66,21 @@ export const useTreeItemUtils = ({
       return;
     }
     if (!status.focused && !status.editing) {
-      instance.focusItem(event, itemId);
+      store.focus.focusItem(event, itemId);
     }
     const multiple = selectionSelectors.isMultiSelectEnabled(store.state) && (event.shiftKey || event.ctrlKey || event.metaKey);
     if (multiple) {
       if (event.shiftKey) {
-        instance.expandSelectionRange(event, itemId);
+        store.selection.expandSelectionRange(event, itemId);
       } else {
-        instance.setItemSelection({
+        store.selection.setItemSelection({
           event,
           itemId,
           keepExistingSelection: true
         });
       }
     } else {
-      instance.setItemSelection({
+      store.selection.setItemSelection({
         event,
         itemId,
         shouldBeSelected: true
@@ -103,9 +91,9 @@ export const useTreeItemUtils = ({
     const hasShift = event.nativeEvent.shiftKey;
     const isMultiSelectEnabled = selectionSelectors.isMultiSelectEnabled(store.state);
     if (isMultiSelectEnabled && hasShift) {
-      instance.expandSelectionRange(event, itemId);
+      store.selection.expandSelectionRange(event, itemId);
     } else {
-      instance.setItemSelection({
+      store.selection.setItemSelection({
         event,
         itemId,
         keepExistingSelection: isMultiSelectEnabled,
@@ -114,17 +102,19 @@ export const useTreeItemUtils = ({
     }
   };
   const toggleItemEditing = () => {
-    if (!hasPlugin(instance, useTreeViewLabel)) {
+    // If the store doesn't support label editing, do nothing
+    if (!store.labelEditing) {
       return;
     }
     if (isEditing) {
-      instance.setEditedItem(null);
+      store.labelEditing.setEditedItem(null);
     } else {
-      instance.setEditedItem(itemId);
+      store.labelEditing.setEditedItem(itemId);
     }
   };
   const handleSaveItemLabel = (event, newLabel) => {
-    if (!hasPlugin(instance, useTreeViewLabel)) {
+    // If the store doesn't support label editing, do nothing
+    if (!store.labelEditing) {
       return;
     }
 
@@ -132,18 +122,19 @@ export const useTreeItemUtils = ({
     // The `onBlur` event is triggered, which calls `handleSaveItemLabel` again.
     // To avoid creating an unwanted behavior we need to check if the item is being edited before calling `updateItemLabel`
     if (labelSelectors.isItemBeingEdited(store.state, itemId)) {
-      instance.updateItemLabel(itemId, newLabel);
+      store.labelEditing.updateItemLabel(itemId, newLabel);
       toggleItemEditing();
-      instance.focusItem(event, itemId);
+      store.focus.focusItem(event, itemId);
     }
   };
   const handleCancelItemLabelEditing = event => {
-    if (!hasPlugin(instance, useTreeViewLabel)) {
+    // If the store doesn't support label editing, do nothing
+    if (!store.labelEditing) {
       return;
     }
     if (labelSelectors.isItemBeingEdited(store.state, itemId)) {
       toggleItemEditing();
-      instance.focusItem(event, itemId);
+      store.focus.focusItem(event, itemId);
     }
   };
   const interactions = {

package/esm/hooks/useTreeViewApiRef.d.ts

@@ -1,8 +1,6 @@
-import * as React from 'react';
-import { TreeViewAnyPluginSignature, TreeViewPublicAPI } from "../internals/models/index.js";
-import { RichTreeViewPluginSignatures } from "../RichTreeView/RichTreeView.plugins.js";
+import { useRichTreeViewApiRef } from "./useRichTreeViewApiRef.js";
 /**
  * Hook that instantiates a [[TreeViewApiRef]].
  * @deprecated Use `useRichTreeViewApiRef()`, `useRichTreeViewProApiRef()` or `useSimpleTreeViewApiRef()` instead.
  */
-export declare const useTreeViewApiRef: <TSignatures extends readonly TreeViewAnyPluginSignature[] = RichTreeViewPluginSignatures>() => React.RefObject<TreeViewPublicAPI<TSignatures> | undefined>;
+export declare const useTreeViewApiRef: typeof useRichTreeViewApiRef;

package/esm/hooks/useTreeViewApiRef.js

@@ -1,8 +1,9 @@
 'use client';
 
-import * as React from 'react';
+import { useRichTreeViewApiRef } from "./useRichTreeViewApiRef.js";
+
 /**
  * Hook that instantiates a [[TreeViewApiRef]].
  * @deprecated Use `useRichTreeViewApiRef()`, `useRichTreeViewProApiRef()` or `useSimpleTreeViewApiRef()` instead.
  */
-export const useTreeViewApiRef = () => React.useRef(undefined);
+export const useTreeViewApiRef = useRichTreeViewApiRef;

package/esm/index.d.ts

@@ -6,7 +6,6 @@ export * from "./TreeItemIcon/index.js";
 export * from "./TreeItemProvider/index.js";
 export * from "./TreeItemDragAndDropOverlay/index.js";
 export * from "./TreeItemLabelInput/index.js";
-export { unstable_resetCleanupTracking } from "./internals/hooks/useInstanceEventHandler.js";
 export * from "./models/index.js";
 export * from "./icons/index.js";
 export * from "./hooks/index.js";

package/esm/index.js

@@ -1,5 +1,5 @@
 /**
- * @mui/x-tree-view v8.23.0
+ * @mui/x-tree-view v8.24.0
  *
  * @license MIT
  * This source code is licensed under the MIT license found in the
@@ -16,7 +16,6 @@ export * from "./TreeItemIcon/index.js";
 export * from "./TreeItemProvider/index.js";
 export * from "./TreeItemDragAndDropOverlay/index.js";
 export * from "./TreeItemLabelInput/index.js";
-export { unstable_resetCleanupTracking } from "./internals/hooks/useInstanceEventHandler.js";
 export * from "./models/index.js";
 export * from "./icons/index.js";
 export * from "./hooks/index.js";

package/esm/internals/MinimalTreeViewStore/MinimalTreeViewStore.d.ts

@@ -0,0 +1,90 @@
+import { Store } from '@mui/x-internals/store';
+import { MinimalTreeViewParameters, TreeViewParametersToStateMapper, MinimalTreeViewState } from "./MinimalTreeViewStore.types.js";
+import { TreeViewValidItem } from "../../models/index.js";
+import { TimeoutManager } from "./TimeoutManager.js";
+import { TreeViewKeyboardNavigationPlugin } from "../plugins/keyboardNavigation/index.js";
+import { TreeViewFocusPlugin } from "../plugins/focus/TreeViewFocusPlugin.js";
+import { TreeViewItemsPlugin } from "../plugins/items/TreeViewItemsPlugin.js";
+import { TreeViewSelectionPlugin } from "../plugins/selection/TreeViewSelectionPlugin.js";
+import { TreeViewExpansionPlugin } from "../plugins/expansion/index.js";
+import { TreeViewItemPluginManager } from "./TreeViewItemPluginManager.js";
+import { TreeViewEventEvent, TreeViewEventListener, TreeViewEventParameters, TreeViewEvents } from "../models/index.js";
+export declare class MinimalTreeViewStore<R extends TreeViewValidItem<R>, Multiple extends boolean | undefined, State extends MinimalTreeViewState<R, Multiple> = MinimalTreeViewState<R, Multiple>, Parameters extends MinimalTreeViewParameters<R, Multiple> = MinimalTreeViewParameters<R, Multiple>> extends Store<State> {
+  private initialParameters;
+  private mapper;
+  private eventManager;
+  instanceName: string;
+  parameters: Parameters;
+  timeoutManager: TimeoutManager;
+  itemPluginManager: TreeViewItemPluginManager<this>;
+  items: TreeViewItemsPlugin<R>;
+  focus: TreeViewFocusPlugin;
+  expansion: TreeViewExpansionPlugin;
+  selection: TreeViewSelectionPlugin<Multiple>;
+  keyboardNavigation: TreeViewKeyboardNavigationPlugin;
+  constructor(parameters: Parameters, instanceName: string, mapper: TreeViewParametersToStateMapper<R, Multiple, State, Parameters>);
+  /**
+   * Builds an object containing the method that should be exposed publicly by the Tree View components.
+   */
+  buildPublicAPI(): {
+    setItemSelection: ({
+      itemId,
+      event,
+      keepExistingSelection,
+      shouldBeSelected
+    }: {
+      itemId: string;
+      event?: React.SyntheticEvent | null;
+      shouldBeSelected?: boolean;
+      keepExistingSelection?: boolean;
+    }) => void;
+    isItemExpanded: (itemId: import("../../index.js").TreeViewItemId) => boolean;
+    setItemExpansion: ({
+      itemId,
+      event,
+      shouldBeExpanded
+    }: {
+      itemId: import("../../index.js").TreeViewItemId;
+      event?: React.SyntheticEvent | null;
+      shouldBeExpanded?: boolean;
+    }) => void;
+    focusItem: (event: React.SyntheticEvent | null, itemId: import("../../index.js").TreeViewItemId) => void;
+    getItem: (itemId: import("../../index.js").TreeViewItemId) => R;
+    getItemDOMElement: (itemId: import("../../index.js").TreeViewItemId) => HTMLElement | null;
+    getItemOrderedChildrenIds: (itemId: import("../../index.js").TreeViewItemId | null) => import("../../index.js").TreeViewItemId[];
+    getItemTree: () => R[];
+    getParentId: (itemId: import("../../index.js").TreeViewItemId) => import("../../index.js").TreeViewItemId | null;
+    setIsItemDisabled: ({
+      itemId,
+      shouldBeDisabled
+    }: {
+      itemId: import("../../index.js").TreeViewItemId;
+      shouldBeDisabled?: boolean;
+    }) => void;
+  };
+  /**
+   * Updates the state of the Tree View based on the new parameters provided to the root component.
+   */
+  updateStateFromParameters(parameters: Parameters): void;
+  /**
+   * Returns a cleanup function that need to be called when the store is destroyed.
+   */
+  disposeEffect: () => () => void;
+  /**
+   * Whether updates based on `props.items` change should be ignored.
+   */
+  shouldIgnoreItemsStateUpdate: () => boolean;
+  /**
+   * Registers an effect to be run when the value returned by the selector changes.
+   */
+  registerStoreEffect: <Value>(selector: (state: State) => Value, effect: (previous: Value, next: Value) => void) => void;
+  /**
+   * Publishes an event to all its subscribers.
+   */
+  publishEvent: <E extends TreeViewEvents>(name: E, params: TreeViewEventParameters<E>, event: TreeViewEventEvent<E>) => void;
+  /**
+   * Subscribe to an event emitted by the store.
+   * For now, the subscription is only removed when the store is destroyed.
+   */
+  subscribeEvent: <E extends TreeViewEvents>(eventName: E, handler: TreeViewEventListener<E>) => void;
+}

package/esm/internals/MinimalTreeViewStore/MinimalTreeViewStore.js

@@ -0,0 +1,126 @@
+import _extends from "@babel/runtime/helpers/esm/extends";
+import { Store } from '@mui/x-internals/store';
+import { warnOnce } from '@mui/x-internals/warning';
+import { EventManager } from '@mui/x-internals/EventManager';
+import { createMinimalInitialState, createTreeViewDefaultId, deriveStateFromParameters } from "./MinimalTreeViewStore.utils.js";
+import { TimeoutManager } from "./TimeoutManager.js";
+import { TreeViewKeyboardNavigationPlugin } from "../plugins/keyboardNavigation/index.js";
+import { TreeViewFocusPlugin } from "../plugins/focus/TreeViewFocusPlugin.js";
+import { TreeViewItemsPlugin } from "../plugins/items/TreeViewItemsPlugin.js";
+import { TreeViewSelectionPlugin } from "../plugins/selection/TreeViewSelectionPlugin.js";
+import { TreeViewExpansionPlugin } from "../plugins/expansion/index.js";
+import { TreeViewItemPluginManager } from "./TreeViewItemPluginManager.js";
+export class MinimalTreeViewStore extends Store {
+  initialParameters = null;
+  eventManager = (() => new EventManager())();
+  timeoutManager = (() => new TimeoutManager())();
+  itemPluginManager = (() => new TreeViewItemPluginManager())();
+  constructor(parameters, instanceName, mapper) {
+    const minimalInitialState = createMinimalInitialState(parameters);
+    const initialState = mapper.getInitialState(minimalInitialState, parameters);
+    super(initialState);
+    this.parameters = parameters;
+    this.instanceName = instanceName;
+    this.mapper = mapper;
+
+    // We mount the plugins in the constructor to make sure all the methods of the store are available to the plugins during their construction.
+    this.items = new TreeViewItemsPlugin(this);
+    this.focus = new TreeViewFocusPlugin(this);
+    this.expansion = new TreeViewExpansionPlugin(this);
+    this.selection = new TreeViewSelectionPlugin(this);
+    this.keyboardNavigation = new TreeViewKeyboardNavigationPlugin(this);
+    if (process.env.NODE_ENV !== 'production') {
+      this.initialParameters = parameters;
+    }
+  }
+
+  /**
+   * Builds an object containing the method that should be exposed publicly by the Tree View components.
+   */
+  buildPublicAPI() {
+    return _extends({}, this.items.buildPublicAPI(), this.focus.buildPublicAPI(), this.expansion.buildPublicAPI(), this.selection.buildPublicAPI());
+  }
+
+  /**
+   * Updates the state of the Tree View based on the new parameters provided to the root component.
+   */
+  updateStateFromParameters(parameters) {
+    const updateModel = (mutableNewState, controlledProp, defaultProp) => {
+      if (parameters[controlledProp] !== undefined) {
+        mutableNewState[controlledProp] = parameters[controlledProp];
+      }
+      if (process.env.NODE_ENV !== 'production') {
+        const defaultValue = parameters[defaultProp];
+        const isControlled = parameters[controlledProp] !== undefined;
+        const initialDefaultValue = this.initialParameters?.[defaultProp];
+        const initialIsControlled = this.initialParameters?.[controlledProp] !== undefined;
+        if (initialIsControlled !== isControlled) {
+          warnOnce([`MUI X Tree View: A component is changing the ${initialIsControlled ? '' : 'un'}controlled ${controlledProp} state of ${this.instanceName} to be ${initialIsControlled ? 'un' : ''}controlled.`, 'Elements should not switch from uncontrolled to controlled (or vice versa).', `Decide between using a controlled or uncontrolled ${controlledProp} element for the lifetime of the component.`, "The nature of the state is determined during the first render. It's considered controlled if the value is not `undefined`.", 'More info: https://fb.me/react-controlled-components'], 'error');
+        } else if (JSON.stringify(initialDefaultValue) !== JSON.stringify(defaultValue)) {
+          warnOnce([`MUI X Tree View: A component is changing the default ${controlledProp} state of an uncontrolled ${this.instanceName} after being initialized. `, `To suppress this warning opt to use a controlled ${this.instanceName}.`], 'error');
+        }
+      }
+    };
+    const newMinimalState = deriveStateFromParameters(parameters);
+    updateModel(newMinimalState, 'expandedItems', 'defaultExpandedItems');
+    updateModel(newMinimalState, 'selectedItems', 'defaultSelectedItems');
+    if (this.state.providedTreeId !== parameters.id || this.state.treeId === undefined) {
+      newMinimalState.treeId = createTreeViewDefaultId();
+    }
+    if (!this.mapper.shouldIgnoreItemsStateUpdate(parameters) && TreeViewItemsPlugin.shouldRebuildItemsState(parameters, this.parameters)) {
+      Object.assign(newMinimalState, TreeViewItemsPlugin.buildItemsStateIfNeeded(parameters));
+    }
+    const newState = this.mapper.updateStateFromParameters(newMinimalState, parameters, updateModel);
+    this.update(newState);
+    this.parameters = parameters;
+  }
+
+  /**
+   * Returns a cleanup function that need to be called when the store is destroyed.
+   */
+  disposeEffect = () => {
+    return this.timeoutManager.clearAll;
+  };
+
+  /**
+   * Whether updates based on `props.items` change should be ignored.
+   */
+  shouldIgnoreItemsStateUpdate = () => {
+    return this.mapper.shouldIgnoreItemsStateUpdate(this.parameters);
+  };
+
+  /**
+   * Registers an effect to be run when the value returned by the selector changes.
+   */
+  registerStoreEffect = (selector, effect) => {
+    let previousValue = selector(this.state);
+    this.subscribe(state => {
+      const nextValue = selector(state);
+      if (nextValue !== previousValue) {
+        effect(previousValue, nextValue);
+        previousValue = nextValue;
+      }
+    });
+  };
+
+  /**
+   * Publishes an event to all its subscribers.
+   */
+  publishEvent = (name, params, event) => {
+    if (isSyntheticEvent(event) && event.isPropagationStopped()) {
+      return;
+    }
+    this.eventManager.emit(name, params, event);
+  };
+
+  /**
+   * Subscribe to an event emitted by the store.
+   * For now, the subscription is only removed when the store is destroyed.
+   */
+  subscribeEvent = (eventName, handler) => {
+    this.eventManager.on(eventName, handler);
+  };
+}
+function isSyntheticEvent(event) {
+  return event.isPropagationStopped !== undefined;
+}