@mui/x-tree-view 9.10.1 → 9.11.0

package/internals/plugins/items/TreeViewItemsPlugin.mjs

@@ -1,7 +1,8 @@
+import _formatErrorMessage from "@mui/x-internals/formatErrorMessage";
 import _extends from "@babel/runtime/helpers/esm/extends";
 import { idSelectors } from "../id/index.mjs";
 import { itemsSelectors } from "./selectors.mjs";
-import { buildItemsLookups, TREE_VIEW_ROOT_PARENT_ID } from "./utils.mjs";
+import { buildItemsLookups, buildItemsLookupsRecursively, buildSiblingIndexes, TREE_VIEW_ROOT_PARENT_ID } from "./utils.mjs";
 export class TreeViewItemsPlugin {
   // We can't type `store`, otherwise we get the following TS error:
   // 'items' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.
@@ -23,41 +24,13 @@ export class TreeViewItemsPlugin {
    * Builds the state properties derived from the `items` prop.
    */
   static buildItemsStateIfNeeded = parameters => {
-    const itemMetaLookup = {};
-    const itemModelLookup = {};
-    const itemOrderedChildrenIdsLookup = {};
-    const itemChildrenIndexesLookup = {};
-    function processSiblings(items, parentId, depth) {
-      const parentIdWithDefault = parentId ?? TREE_VIEW_ROOT_PARENT_ID;
-      const {
-        metaLookup,
-        modelLookup,
-        orderedChildrenIds,
-        childrenIndexes,
-        itemsChildren
-      } = buildItemsLookups({
-        storeParameters: parameters,
-        items,
-        parentId,
-        depth,
-        isItemExpandable: (item, children) => !!children && children.length > 0,
-        otherItemsMetaLookup: itemMetaLookup
-      });
-      Object.assign(itemMetaLookup, metaLookup);
-      Object.assign(itemModelLookup, modelLookup);
-      itemOrderedChildrenIdsLookup[parentIdWithDefault] = orderedChildrenIds;
-      itemChildrenIndexesLookup[parentIdWithDefault] = childrenIndexes;
-      for (const item of itemsChildren) {
-        processSiblings(item.children || [], item.id, depth + 1);
-      }
-    }
-    processSiblings(parameters.items, null, 0);
-    return {
-      itemMetaLookup,
-      itemModelLookup,
-      itemOrderedChildrenIdsLookup,
-      itemChildrenIndexesLookup
-    };
+    return buildItemsLookupsRecursively({
+      storeParameters: parameters,
+      items: parameters.items,
+      parentId: null,
+      depth: 0,
+      isItemExpandable: (item, children) => !!children && children.length > 0
+    });
   };
 
   /**
@@ -124,6 +97,79 @@ export class TreeViewItemsPlugin {
     });
     this.store.set('itemMetaLookup', itemMetaLookup);
   };
+
+  /**
+   * Add items to the tree.
+   * The items are added as children of the item with the given `parentId`, or at the root level if `parentId` is `null` or not defined.
+   * @param {AddItemsParameters<R>} parameters The items to add and their position in the tree.
+   */
+  addItems = ({
+    items,
+    parentId = null,
+    index
+  }) => {
+    if (items.length === 0) {
+      return;
+    }
+    if (parentId != null && itemsSelectors.itemMeta(this.store.state, parentId) == null) {
+      throw new Error(process.env.NODE_ENV !== "production" ? `MUI X Tree View: Unable to add items to the parent with id "${parentId}" because it is not present in the tree. ` + 'Pass the id of an existing item, or `null` to add the items at the root level.' : _formatErrorMessage(295, parentId));
+    }
+    const parentDepth = parentId == null ? -1 : itemsSelectors.itemDepth(this.store.state, parentId);
+
+    // When the items are lazy loaded, an item can be expandable even if its children are not loaded yet.
+    const dataSource = this.store.parameters.dataSource;
+    const isItemExpandable = (item, children) => {
+      if (children != null && children.length > 0) {
+        return true;
+      }
+      return dataSource == null ? false : dataSource.getChildrenCount(item) !== 0;
+    };
+    const {
+      itemMetaLookup: metaLookup,
+      itemModelLookup: modelLookup,
+      itemOrderedChildrenIdsLookup: orderedChildrenIdsLookup,
+      itemChildrenIndexesLookup: childrenIndexesLookup
+    } = buildItemsLookupsRecursively({
+      storeParameters: this.store.parameters,
+      items,
+      parentId,
+      depth: parentDepth + 1,
+      isItemExpandable,
+      existingItemMetaLookup: this.store.state.itemMetaLookup
+    });
+
+    // `buildItemsLookups` allows an id to be re-used by an item with the same parent,
+    // which is only valid when rebuilding the state from the `items` prop.
+    for (const id of Object.keys(metaLookup)) {
+      if (this.store.state.itemMetaLookup[id] != null) {
+        throw new Error(process.env.NODE_ENV !== "production" ? `MUI X Tree View: All items must have a unique \`id\` property. ` + `The id "${id}" is used by multiple items. ` + 'Use the `getItemId` prop to specify a custom id for each item if needed.' : _formatErrorMessage(194, id));
+      }
+    }
+    const parentIdWithDefault = parentId ?? TREE_VIEW_ROOT_PARENT_ID;
+    const existingChildrenIds = itemsSelectors.itemOrderedChildrenIds(this.store.state, parentId);
+    const insertionIndex = index ?? existingChildrenIds.length;
+    if (insertionIndex < 0 || insertionIndex > existingChildrenIds.length) {
+      throw new Error(process.env.NODE_ENV !== "production" ? `MUI X Tree View: Unable to add items at index "${insertionIndex}" because it is out of range. ` + `The index must be between 0 and the amount of children of the parent item (${existingChildrenIds.length}).` : _formatErrorMessage(296, insertionIndex, existingChildrenIds.length));
+    }
+    const newChildrenIds = orderedChildrenIdsLookup[parentIdWithDefault];
+    const mergedChildrenIds = [...existingChildrenIds];
+    mergedChildrenIds.splice(insertionIndex, 0, ...newChildrenIds);
+    orderedChildrenIdsLookup[parentIdWithDefault] = mergedChildrenIds;
+    childrenIndexesLookup[parentIdWithDefault] = buildSiblingIndexes(mergedChildrenIds);
+    const newMetaLookup = _extends({}, this.store.state.itemMetaLookup, metaLookup);
+    if (parentId != null && !newMetaLookup[parentId].expandable) {
+      newMetaLookup[parentId] = _extends({}, newMetaLookup[parentId], {
+        expandable: true
+      });
+    }
+    this.store.update({
+      itemMetaLookup: newMetaLookup,
+      itemModelLookup: _extends({}, this.store.state.itemModelLookup, modelLookup),
+      itemOrderedChildrenIdsLookup: _extends({}, this.store.state.itemOrderedChildrenIdsLookup, orderedChildrenIdsLookup),
+      itemChildrenIndexesLookup: _extends({}, this.store.state.itemChildrenIndexesLookup, childrenIndexesLookup)
+    });
+    this.store.selection.propagateSelectionToNewItems(parentId, newChildrenIds);
+  };
   buildPublicAPI = () => {
     return {
       getItem: this.getItem,

package/internals/plugins/items/utils.d.mts

@@ -30,6 +30,34 @@ export declare function buildItemsLookups<R extends TreeViewValidItem<R>>(parame
     children: R[];
   }[];
 };
+/**
+ * Builds the items lookups for a tree of items, recursing into the children of each item.
+ * The returned lookups only contain the items passed to this method.
+ */
+export declare function buildItemsLookupsRecursively<R extends TreeViewValidItem<R>>(parameters: BuildItemsLookupsRecursivelyParameters<R>): {
+  itemMetaLookup: {
+    [itemId: string]: TreeViewItemMeta;
+  };
+  itemModelLookup: {
+    [itemId: string]: R;
+  };
+  itemOrderedChildrenIdsLookup: {
+    [parentItemId: string]: string[];
+  };
+  itemChildrenIndexesLookup: {
+    [parentItemId: string]: {
+      [itemId: string]: number;
+    };
+  };
+};
+interface BuildItemsLookupsRecursivelyParameters<R extends TreeViewValidItem<R>> extends Omit<BuildItemsLookupsParameters<R>, 'otherItemsMetaLookup'> {
+  /**
+   * The meta of the items already present in the tree, used to detect duplicated ids.
+   */
+  existingItemMetaLookup?: {
+    [itemId: string]: TreeViewItemMeta;
+  };
+}
 interface BuildItemsLookupsParameters<R extends TreeViewValidItem<R>> {
   items: readonly R[];
   storeParameters: Pick<MinimalTreeViewParameters<R, any>, 'getItemId' | 'getItemLabel' | 'getItemChildren' | 'isItemDisabled' | 'isItemSelectionDisabled'>;

package/internals/plugins/items/utils.d.ts

@@ -30,6 +30,34 @@ export declare function buildItemsLookups<R extends TreeViewValidItem<R>>(parame
     children: R[];
   }[];
 };
+/**
+ * Builds the items lookups for a tree of items, recursing into the children of each item.
+ * The returned lookups only contain the items passed to this method.
+ */
+export declare function buildItemsLookupsRecursively<R extends TreeViewValidItem<R>>(parameters: BuildItemsLookupsRecursivelyParameters<R>): {
+  itemMetaLookup: {
+    [itemId: string]: TreeViewItemMeta;
+  };
+  itemModelLookup: {
+    [itemId: string]: R;
+  };
+  itemOrderedChildrenIdsLookup: {
+    [parentItemId: string]: string[];
+  };
+  itemChildrenIndexesLookup: {
+    [parentItemId: string]: {
+      [itemId: string]: number;
+    };
+  };
+};
+interface BuildItemsLookupsRecursivelyParameters<R extends TreeViewValidItem<R>> extends Omit<BuildItemsLookupsParameters<R>, 'otherItemsMetaLookup'> {
+  /**
+   * The meta of the items already present in the tree, used to detect duplicated ids.
+   */
+  existingItemMetaLookup?: {
+    [itemId: string]: TreeViewItemMeta;
+  };
+}
 interface BuildItemsLookupsParameters<R extends TreeViewValidItem<R>> {
   items: readonly R[];
   storeParameters: Pick<MinimalTreeViewParameters<R, any>, 'getItemId' | 'getItemLabel' | 'getItemChildren' | 'isItemDisabled' | 'isItemSelectionDisabled'>;

package/internals/plugins/items/utils.js

@@ -6,7 +6,9 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.TREE_VIEW_ROOT_PARENT_ID = void 0;
 exports.buildItemsLookups = buildItemsLookups;
+exports.buildItemsLookupsRecursively = buildItemsLookupsRecursively;
 exports.isItemDisabled = exports.buildSiblingIndexes = void 0;
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
 var _formatErrorMessage2 = _interopRequireDefault(require("@mui/x-internals/formatErrorMessage"));
 const TREE_VIEW_ROOT_PARENT_ID = exports.TREE_VIEW_ROOT_PARENT_ID = '__TREE_VIEW_ROOT_PARENT_ID__';
 const buildSiblingIndexes = siblings => {
@@ -104,6 +106,53 @@ function buildItemsLookups(parameters) {
     itemsChildren
   };
 }
+
+/**
+ * Builds the items lookups for a tree of items, recursing into the children of each item.
+ * The returned lookups only contain the items passed to this method.
+ */
+function buildItemsLookupsRecursively(parameters) {
+  const {
+    storeParameters,
+    items,
+    parentId,
+    depth,
+    isItemExpandable,
+    existingItemMetaLookup
+  } = parameters;
+  const itemMetaLookup = {};
+  const itemModelLookup = {};
+  const itemOrderedChildrenIdsLookup = {};
+  const itemChildrenIndexesLookup = {};
+
+  // Both the existing items and the ones processed here, to detect duplicated ids.
+  const otherItemsMetaLookup = (0, _extends2.default)({}, existingItemMetaLookup);
+  const processSiblings = (siblings, siblingsParentId, siblingsDepth) => {
+    const lookups = buildItemsLookups({
+      storeParameters,
+      items: siblings,
+      parentId: siblingsParentId,
+      depth: siblingsDepth,
+      isItemExpandable,
+      otherItemsMetaLookup
+    });
+    Object.assign(itemMetaLookup, lookups.metaLookup);
+    Object.assign(otherItemsMetaLookup, lookups.metaLookup);
+    Object.assign(itemModelLookup, lookups.modelLookup);
+    itemOrderedChildrenIdsLookup[siblingsParentId ?? TREE_VIEW_ROOT_PARENT_ID] = lookups.orderedChildrenIds;
+    itemChildrenIndexesLookup[siblingsParentId ?? TREE_VIEW_ROOT_PARENT_ID] = lookups.childrenIndexes;
+    for (const item of lookups.itemsChildren) {
+      processSiblings(item.children, item.id, siblingsDepth + 1);
+    }
+  };
+  processSiblings(items, parentId, depth);
+  return {
+    itemMetaLookup,
+    itemModelLookup,
+    itemOrderedChildrenIdsLookup,
+    itemChildrenIndexesLookup
+  };
+}
 function checkId({
   id,
   parentId,

package/internals/plugins/items/utils.mjs

@@ -1,3 +1,4 @@
+import _extends from "@babel/runtime/helpers/esm/extends";
 import _formatErrorMessage from "@mui/x-internals/formatErrorMessage";
 export const TREE_VIEW_ROOT_PARENT_ID = '__TREE_VIEW_ROOT_PARENT_ID__';
 export const buildSiblingIndexes = siblings => {
@@ -93,6 +94,53 @@ export function buildItemsLookups(parameters) {
     itemsChildren
   };
 }
+
+/**
+ * Builds the items lookups for a tree of items, recursing into the children of each item.
+ * The returned lookups only contain the items passed to this method.
+ */
+export function buildItemsLookupsRecursively(parameters) {
+  const {
+    storeParameters,
+    items,
+    parentId,
+    depth,
+    isItemExpandable,
+    existingItemMetaLookup
+  } = parameters;
+  const itemMetaLookup = {};
+  const itemModelLookup = {};
+  const itemOrderedChildrenIdsLookup = {};
+  const itemChildrenIndexesLookup = {};
+
+  // Both the existing items and the ones processed here, to detect duplicated ids.
+  const otherItemsMetaLookup = _extends({}, existingItemMetaLookup);
+  const processSiblings = (siblings, siblingsParentId, siblingsDepth) => {
+    const lookups = buildItemsLookups({
+      storeParameters,
+      items: siblings,
+      parentId: siblingsParentId,
+      depth: siblingsDepth,
+      isItemExpandable,
+      otherItemsMetaLookup
+    });
+    Object.assign(itemMetaLookup, lookups.metaLookup);
+    Object.assign(otherItemsMetaLookup, lookups.metaLookup);
+    Object.assign(itemModelLookup, lookups.modelLookup);
+    itemOrderedChildrenIdsLookup[siblingsParentId ?? TREE_VIEW_ROOT_PARENT_ID] = lookups.orderedChildrenIds;
+    itemChildrenIndexesLookup[siblingsParentId ?? TREE_VIEW_ROOT_PARENT_ID] = lookups.childrenIndexes;
+    for (const item of lookups.itemsChildren) {
+      processSiblings(item.children, item.id, siblingsDepth + 1);
+    }
+  };
+  processSiblings(items, parentId, depth);
+  return {
+    itemMetaLookup,
+    itemModelLookup,
+    itemOrderedChildrenIdsLookup,
+    itemChildrenIndexesLookup
+  };
+}
 function checkId({
   id,
   parentId,

package/internals/plugins/selection/TreeViewSelectionPlugin.d.mts

@@ -1,3 +1,4 @@
+import type { TreeViewItemId, TreeViewItemSelectionStatus } from "../../../models/index.mjs";
 export declare class TreeViewSelectionPlugin<Multiple extends boolean | undefined> {
   private store;
   private lastSelectedItem;
@@ -5,7 +6,15 @@ export declare class TreeViewSelectionPlugin<Multiple extends boolean | undefine
   constructor(store: any);
   private setSelectedItems;
   private selectRange;
+  /**
+   * Get the selection status of an item.
+   * An item that is not selected is `indeterminate` when some of its selectable descendants are selected.
+   * @param {TreeViewItemId} itemId The id of the item to get the selection status of.
+   * @returns {TreeViewItemSelectionStatus} The selection status of the item.
+   */
+  private getItemSelection;
   buildPublicAPI: () => {
+    getItemSelection: (itemId: TreeViewItemId) => TreeViewItemSelectionStatus;
     setItemSelection: ({
       itemId,
       event,
@@ -18,6 +27,12 @@ export declare class TreeViewSelectionPlugin<Multiple extends boolean | undefine
       keepExistingSelection?: boolean;
     }) => void;
   };
+  /**
+   * Select the items added below a selected parent when the selection propagates to the descendants.
+   * @param {TreeViewItemId | null} parentId The id of the item the new items were added to.
+   * @param {TreeViewItemId[]} newItemIds The ids of the items that were just added.
+   */
+  propagateSelectionToNewItems: (parentId: TreeViewItemId | null, newItemIds: TreeViewItemId[]) => void;
   /**
    * Select or deselect an item.
    * @param {object} parameters The parameters of the method.

package/internals/plugins/selection/TreeViewSelectionPlugin.d.ts

@@ -1,3 +1,4 @@
+import type { TreeViewItemId, TreeViewItemSelectionStatus } from "../../../models/index.js";
 export declare class TreeViewSelectionPlugin<Multiple extends boolean | undefined> {
   private store;
   private lastSelectedItem;
@@ -5,7 +6,15 @@ export declare class TreeViewSelectionPlugin<Multiple extends boolean | undefine
   constructor(store: any);
   private setSelectedItems;
   private selectRange;
+  /**
+   * Get the selection status of an item.
+   * An item that is not selected is `indeterminate` when some of its selectable descendants are selected.
+   * @param {TreeViewItemId} itemId The id of the item to get the selection status of.
+   * @returns {TreeViewItemSelectionStatus} The selection status of the item.
+   */
+  private getItemSelection;
   buildPublicAPI: () => {
+    getItemSelection: (itemId: TreeViewItemId) => TreeViewItemSelectionStatus;
     setItemSelection: ({
       itemId,
       event,
@@ -18,6 +27,12 @@ export declare class TreeViewSelectionPlugin<Multiple extends boolean | undefine
       keepExistingSelection?: boolean;
     }) => void;
   };
+  /**
+   * Select the items added below a selected parent when the selection propagates to the descendants.
+   * @param {TreeViewItemId | null} parentId The id of the item the new items were added to.
+   * @param {TreeViewItemId[]} newItemIds The ids of the items that were just added.
+   */
+  propagateSelectionToNewItems: (parentId: TreeViewItemId | null, newItemIds: TreeViewItemId[]) => void;
   /**
    * Select or deselect an item.
    * @param {object} parameters The parameters of the method.

package/internals/plugins/selection/TreeViewSelectionPlugin.js

@@ -41,10 +41,16 @@ class TreeViewSelectionPlugin {
     } else {
       cleanModel = newModel;
     }
+
+    // The store is updated before the callbacks are fired,
+    // so that the selection selectors and the `getItemSelection` API method
+    // return the new selection status when called from `onItemSelectionToggle` or `onSelectedItemsChange`.
+    if (selectedItems === undefined) {
+      this.store.set('selectedItems', cleanModel);
+    }
     if (onItemSelectionToggle) {
       if (isMultiSelectEnabled) {
         const changes = getAddedAndRemovedItems({
-          store: this.store,
           newModel: cleanModel,
           oldModel: oldModel
         });
@@ -65,9 +71,6 @@ class TreeViewSelectionPlugin {
         }
       }
     }
-    if (selectedItems === undefined) {
-      this.store.set('selectedItems', cleanModel);
-    }
     onSelectedItemsChange?.(event, cleanModel);
   };
   selectRange = (event, [start, end]) => {
@@ -91,12 +94,39 @@ class TreeViewSelectionPlugin {
     this.setSelectedItems(event, newSelectedItems);
     this.lastSelectedRange = getLookupFromArray(range);
   };
+
+  /**
+   * Get the selection status of an item.
+   * An item that is not selected is `indeterminate` when some of its selectable descendants are selected.
+   * @param {TreeViewItemId} itemId The id of the item to get the selection status of.
+   * @returns {TreeViewItemSelectionStatus} The selection status of the item.
+   */
+  getItemSelection = itemId => _selectors.selectionSelectors.itemSelectionStatus(this.store.state, itemId);
   buildPublicAPI = () => {
     return {
+      getItemSelection: this.getItemSelection,
       setItemSelection: this.setItemSelection
     };
   };
 
+  /**
+   * Select the items added below a selected parent when the selection propagates to the descendants.
+   * @param {TreeViewItemId | null} parentId The id of the item the new items were added to.
+   * @param {TreeViewItemId[]} newItemIds The ids of the items that were just added.
+   */
+  propagateSelectionToNewItems = (parentId, newItemIds) => {
+    const {
+      selectionPropagation = _empty.EMPTY_OBJECT
+    } = this.store.parameters;
+    if (parentId == null || newItemIds.length === 0 || !selectionPropagation.descendants || !_selectors.selectionSelectors.isMultiSelectEnabled(this.store.state) || !_selectors.selectionSelectors.isItemSelected(this.store.state, parentId)) {
+      return;
+    }
+
+    // Only propagate to the new items, the rest of the parent's subtree is already up to date.
+    const newModel = _selectors.selectionSelectors.selectedItems(this.store.state).concat(newItemIds);
+    this.setSelectedItems(null, newModel, newItemIds);
+  };
+
   /**
    * Select or deselect an item.
    * @param {object} parameters The parameters of the method.
@@ -116,7 +146,7 @@ class TreeViewSelectionPlugin {
     }
     let newSelected;
     const isMultiSelectEnabled = _selectors.selectionSelectors.isMultiSelectEnabled(this.store.state);
-    if (keepExistingSelection) {
+    if (keepExistingSelection && isMultiSelectEnabled) {
       const oldSelected = _selectors.selectionSelectors.selectedItems(this.store.state);
       const isSelectedBefore = _selectors.selectionSelectors.isItemSelected(this.store.state, itemId);
       if (isSelectedBefore && (shouldBeSelected === false || shouldBeSelected == null)) {
@@ -199,7 +229,9 @@ class TreeViewSelectionPlugin {
     }
     let newSelectedItems = _selectors.selectionSelectors.selectedItems(this.store.state).slice();
     if (Object.keys(this.lastSelectedRange).length === 0) {
-      newSelectedItems.push(nextItem);
+      if (!_selectors.selectionSelectors.isItemSelected(this.store.state, nextItem)) {
+        newSelectedItems.push(nextItem);
+      }
       this.lastSelectedRange = {
         [currentItem]: true,
         [nextItem]: true
@@ -212,7 +244,9 @@ class TreeViewSelectionPlugin {
         newSelectedItems = newSelectedItems.filter(id => id !== currentItem);
         delete this.lastSelectedRange[currentItem];
       } else {
-        newSelectedItems.push(nextItem);
+        if (!_selectors.selectionSelectors.isItemSelected(this.store.state, nextItem)) {
+          newSelectedItems.push(nextItem);
+        }
         this.lastSelectedRange[nextItem] = true;
       }
     }
@@ -233,7 +267,6 @@ function propagateSelection({
   let shouldRegenerateModel = false;
   const newModelLookup = getLookupFromArray(newModel);
   const changes = getAddedAndRemovedItems({
-    store,
     newModel,
     oldModel
   });
@@ -313,8 +346,11 @@ function propagateSelection({
   });
   return shouldRegenerateModel ? Object.keys(newModelLookup) : newModel;
 }
+
+// This method only diffs the two models it receives,
+// it must not read the selection from the store,
+// otherwise the result would depend on whether the store has already been updated or not.
 function getAddedAndRemovedItems({
-  store,
   oldModel,
   newModel
 }) {
@@ -322,8 +358,12 @@ function getAddedAndRemovedItems({
   newModel.forEach(id => {
     newModelMap.set(id, true);
   });
+  const oldModelMap = new Map();
+  oldModel.forEach(id => {
+    oldModelMap.set(id, true);
+  });
   return {
-    added: newModel.filter(itemId => !_selectors.selectionSelectors.isItemSelected(store.state, itemId)),
+    added: newModel.filter(itemId => !oldModelMap.has(itemId)),
     removed: oldModel.filter(itemId => !newModelMap.has(itemId))
   };
 }

package/internals/plugins/selection/TreeViewSelectionPlugin.mjs

@@ -34,10 +34,16 @@ export class TreeViewSelectionPlugin {
     } else {
       cleanModel = newModel;
     }
+
+    // The store is updated before the callbacks are fired,
+    // so that the selection selectors and the `getItemSelection` API method
+    // return the new selection status when called from `onItemSelectionToggle` or `onSelectedItemsChange`.
+    if (selectedItems === undefined) {
+      this.store.set('selectedItems', cleanModel);
+    }
     if (onItemSelectionToggle) {
       if (isMultiSelectEnabled) {
         const changes = getAddedAndRemovedItems({
-          store: this.store,
           newModel: cleanModel,
           oldModel: oldModel
         });
@@ -58,9 +64,6 @@ export class TreeViewSelectionPlugin {
         }
       }
     }
-    if (selectedItems === undefined) {
-      this.store.set('selectedItems', cleanModel);
-    }
     onSelectedItemsChange?.(event, cleanModel);
   };
   selectRange = (event, [start, end]) => {
@@ -84,12 +87,39 @@ export class TreeViewSelectionPlugin {
     this.setSelectedItems(event, newSelectedItems);
     this.lastSelectedRange = getLookupFromArray(range);
   };
+
+  /**
+   * Get the selection status of an item.
+   * An item that is not selected is `indeterminate` when some of its selectable descendants are selected.
+   * @param {TreeViewItemId} itemId The id of the item to get the selection status of.
+   * @returns {TreeViewItemSelectionStatus} The selection status of the item.
+   */
+  getItemSelection = itemId => selectionSelectors.itemSelectionStatus(this.store.state, itemId);
   buildPublicAPI = () => {
     return {
+      getItemSelection: this.getItemSelection,
       setItemSelection: this.setItemSelection
     };
   };
 
+  /**
+   * Select the items added below a selected parent when the selection propagates to the descendants.
+   * @param {TreeViewItemId | null} parentId The id of the item the new items were added to.
+   * @param {TreeViewItemId[]} newItemIds The ids of the items that were just added.
+   */
+  propagateSelectionToNewItems = (parentId, newItemIds) => {
+    const {
+      selectionPropagation = EMPTY_OBJECT
+    } = this.store.parameters;
+    if (parentId == null || newItemIds.length === 0 || !selectionPropagation.descendants || !selectionSelectors.isMultiSelectEnabled(this.store.state) || !selectionSelectors.isItemSelected(this.store.state, parentId)) {
+      return;
+    }
+
+    // Only propagate to the new items, the rest of the parent's subtree is already up to date.
+    const newModel = selectionSelectors.selectedItems(this.store.state).concat(newItemIds);
+    this.setSelectedItems(null, newModel, newItemIds);
+  };
+
   /**
    * Select or deselect an item.
    * @param {object} parameters The parameters of the method.
@@ -109,7 +139,7 @@ export class TreeViewSelectionPlugin {
     }
     let newSelected;
     const isMultiSelectEnabled = selectionSelectors.isMultiSelectEnabled(this.store.state);
-    if (keepExistingSelection) {
+    if (keepExistingSelection && isMultiSelectEnabled) {
       const oldSelected = selectionSelectors.selectedItems(this.store.state);
       const isSelectedBefore = selectionSelectors.isItemSelected(this.store.state, itemId);
       if (isSelectedBefore && (shouldBeSelected === false || shouldBeSelected == null)) {
@@ -192,7 +222,9 @@ export class TreeViewSelectionPlugin {
     }
     let newSelectedItems = selectionSelectors.selectedItems(this.store.state).slice();
     if (Object.keys(this.lastSelectedRange).length === 0) {
-      newSelectedItems.push(nextItem);
+      if (!selectionSelectors.isItemSelected(this.store.state, nextItem)) {
+        newSelectedItems.push(nextItem);
+      }
       this.lastSelectedRange = {
         [currentItem]: true,
         [nextItem]: true
@@ -205,7 +237,9 @@ export class TreeViewSelectionPlugin {
         newSelectedItems = newSelectedItems.filter(id => id !== currentItem);
         delete this.lastSelectedRange[currentItem];
       } else {
-        newSelectedItems.push(nextItem);
+        if (!selectionSelectors.isItemSelected(this.store.state, nextItem)) {
+          newSelectedItems.push(nextItem);
+        }
         this.lastSelectedRange[nextItem] = true;
       }
     }
@@ -225,7 +259,6 @@ function propagateSelection({
   let shouldRegenerateModel = false;
   const newModelLookup = getLookupFromArray(newModel);
   const changes = getAddedAndRemovedItems({
-    store,
     newModel,
     oldModel
   });
@@ -305,8 +338,11 @@ function propagateSelection({
   });
   return shouldRegenerateModel ? Object.keys(newModelLookup) : newModel;
 }
+
+// This method only diffs the two models it receives,
+// it must not read the selection from the store,
+// otherwise the result would depend on whether the store has already been updated or not.
 function getAddedAndRemovedItems({
-  store,
   oldModel,
   newModel
 }) {
@@ -314,8 +350,12 @@ function getAddedAndRemovedItems({
   newModel.forEach(id => {
     newModelMap.set(id, true);
   });
+  const oldModelMap = new Map();
+  oldModel.forEach(id => {
+    oldModelMap.set(id, true);
+  });
   return {
-    added: newModel.filter(itemId => !selectionSelectors.isItemSelected(store.state, itemId)),
+    added: newModel.filter(itemId => !oldModelMap.has(itemId)),
     removed: oldModel.filter(itemId => !newModelMap.has(itemId))
   };
 }