@mui/x-tree-view 9.10.0 → 9.11.0

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
   });
@@ -250,20 +283,27 @@ function propagateSelection({
     if (selectionPropagation.descendants) {
       const selectDescendants = itemId => {
         if (itemId !== addedItemId) {
-          shouldRegenerateModel = true;
-          newModelLookup[itemId] = true;
+          if (_selectors.selectionSelectors.canItemBeSelected(store.state, itemId)) {
+            shouldRegenerateModel = true;
+            newModelLookup[itemId] = true;
+          }
         }
         _items.itemsSelectors.itemOrderedChildrenIds(store.state, itemId).forEach(selectDescendants);
       };
       selectDescendants(addedItemId);
     }
     if (selectionPropagation.parents) {
-      const checkAllDescendantsSelected = itemId => {
+      const checkAllSelectableDescendantsSelected = itemId => {
+        if (!_selectors.selectionSelectors.canItemBeSelected(store.state, itemId)) {
+          // Non-selectable items don't count; still recurse for isItemSelectionDisabled case
+          const children = _items.itemsSelectors.itemOrderedChildrenIds(store.state, itemId);
+          return children.every(checkAllSelectableDescendantsSelected);
+        }
         if (!newModelLookup[itemId]) {
           return false;
         }
         const children = _items.itemsSelectors.itemOrderedChildrenIds(store.state, itemId);
-        return children.every(checkAllDescendantsSelected);
+        return children.every(checkAllSelectableDescendantsSelected);
       };
       const selectParents = itemId => {
         const parentId = _items.itemsSelectors.itemParentId(store.state, itemId);
@@ -271,9 +311,11 @@ function propagateSelection({
           return;
         }
         const siblings = _items.itemsSelectors.itemOrderedChildrenIds(store.state, parentId);
-        if (siblings.every(checkAllDescendantsSelected)) {
-          shouldRegenerateModel = true;
-          newModelLookup[parentId] = true;
+        if (siblings.every(checkAllSelectableDescendantsSelected)) {
+          if (_selectors.selectionSelectors.canItemBeSelected(store.state, parentId)) {
+            shouldRegenerateModel = true;
+            newModelLookup[parentId] = true;
+          }
           selectParents(parentId);
         }
       };
@@ -304,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
 }) {
@@ -313,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
   });
@@ -242,20 +275,27 @@ function propagateSelection({
     if (selectionPropagation.descendants) {
       const selectDescendants = itemId => {
         if (itemId !== addedItemId) {
-          shouldRegenerateModel = true;
-          newModelLookup[itemId] = true;
+          if (selectionSelectors.canItemBeSelected(store.state, itemId)) {
+            shouldRegenerateModel = true;
+            newModelLookup[itemId] = true;
+          }
         }
         itemsSelectors.itemOrderedChildrenIds(store.state, itemId).forEach(selectDescendants);
       };
       selectDescendants(addedItemId);
     }
     if (selectionPropagation.parents) {
-      const checkAllDescendantsSelected = itemId => {
+      const checkAllSelectableDescendantsSelected = itemId => {
+        if (!selectionSelectors.canItemBeSelected(store.state, itemId)) {
+          // Non-selectable items don't count; still recurse for isItemSelectionDisabled case
+          const children = itemsSelectors.itemOrderedChildrenIds(store.state, itemId);
+          return children.every(checkAllSelectableDescendantsSelected);
+        }
         if (!newModelLookup[itemId]) {
           return false;
         }
         const children = itemsSelectors.itemOrderedChildrenIds(store.state, itemId);
-        return children.every(checkAllDescendantsSelected);
+        return children.every(checkAllSelectableDescendantsSelected);
       };
       const selectParents = itemId => {
         const parentId = itemsSelectors.itemParentId(store.state, itemId);
@@ -263,9 +303,11 @@ function propagateSelection({
           return;
         }
         const siblings = itemsSelectors.itemOrderedChildrenIds(store.state, parentId);
-        if (siblings.every(checkAllDescendantsSelected)) {
-          shouldRegenerateModel = true;
-          newModelLookup[parentId] = true;
+        if (siblings.every(checkAllSelectableDescendantsSelected)) {
+          if (selectionSelectors.canItemBeSelected(store.state, parentId)) {
+            shouldRegenerateModel = true;
+            newModelLookup[parentId] = true;
+          }
           selectParents(parentId);
         }
       };
@@ -296,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
 }) {
@@ -305,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))
   };
 }

package/internals/plugins/selection/itemPlugin.js

@@ -8,38 +8,6 @@ var _store = require("@mui/x-internals/store");
 var _TreeViewProvider = require("../../TreeViewProvider");
 var _selectors = require("../items/selectors");
 var _selectors2 = require("./selectors");
-const selectorCheckboxSelectionStatus = (0, _store.createSelector)((state, itemId) => {
-  if (_selectors2.selectionSelectors.isItemSelected(state, itemId)) {
-    return 'checked';
-  }
-  let hasSelectedDescendant = false;
-  let hasUnSelectedDescendant = false;
-  const traverseDescendants = itemToTraverseId => {
-    if (itemToTraverseId !== itemId) {
-      if (_selectors2.selectionSelectors.isItemSelected(state, itemToTraverseId)) {
-        hasSelectedDescendant = true;
-      } else {
-        hasUnSelectedDescendant = true;
-      }
-    }
-    _selectors.itemsSelectors.itemOrderedChildrenIds(state, itemToTraverseId).forEach(traverseDescendants);
-  };
-  traverseDescendants(itemId);
-  const shouldSelectBasedOnDescendants = _selectors2.selectionSelectors.propagationRules(state).parents;
-  if (shouldSelectBasedOnDescendants) {
-    if (hasSelectedDescendant && hasUnSelectedDescendant) {
-      return 'indeterminate';
-    }
-    if (hasSelectedDescendant && !hasUnSelectedDescendant) {
-      return 'checked';
-    }
-    return 'empty';
-  }
-  if (hasSelectedDescendant) {
-    return 'indeterminate';
-  }
-  return 'empty';
-});
 const useSelectionItemPlugin = ({
   props
 }) => {
@@ -52,19 +20,28 @@ const useSelectionItemPlugin = ({
   const isCheckboxSelectionEnabled = (0, _store.useStore)(store, _selectors2.selectionSelectors.isCheckboxSelectionEnabled);
   const isFeatureEnabledForItem = (0, _store.useStore)(store, _selectors2.selectionSelectors.isFeatureEnabledForItem, itemId);
   const canItemBeSelected = (0, _store.useStore)(store, _selectors2.selectionSelectors.canItemBeSelected, itemId);
-  const selectionStatus = (0, _store.useStore)(store, selectorCheckboxSelectionStatus, itemId);
+  const isItemDisabled = (0, _store.useStore)(store, _selectors.itemsSelectors.isItemDisabled, itemId);
+  const isItemSelectable = (0, _store.useStore)(store, _selectors2.selectionSelectors.isItemSelectable, itemId);
+  const selectionStatus = (0, _store.useStore)(store, _selectors2.selectionSelectors.itemSelectionStatus, itemId);
+
+  // An item is "inherently not selectable" when disabled or excluded via isItemSelectionDisabled,
+  // regardless of the global disableSelection flag. Such items must not have aria-checked.
+  const isItemInherentlyNotSelectable = isItemDisabled || !isItemSelectable;
   return {
     propsEnhancers: {
       root: () => {
         // https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
         let ariaChecked;
-        if (selectionStatus === 'checked') {
+        if (isItemInherentlyNotSelectable) {
+          // - if the tree contains nodes that are not selectable, aria-checked is not present on those nodes.
+          ariaChecked = undefined;
+        } else if (selectionStatus === 'selected') {
           // - each selected node has aria-checked set to true.
           ariaChecked = true;
         } else if (selectionStatus === 'indeterminate') {
           ariaChecked = 'mixed';
         } else if (!canItemBeSelected) {
-          // - if the tree contains nodes that are not selectable, aria-checked is not present on those nodes.
+          // disableSelection=true with an unselected item: aria-checked is not present.
           ariaChecked = undefined;
         } else {
           // - all nodes that are selectable but not selected have aria-checked set to false.
@@ -93,7 +70,7 @@ const useSelectionItemPlugin = ({
           onChange: handleChange,
           visible: isCheckboxSelectionEnabled && isFeatureEnabledForItem,
           disabled: !canItemBeSelected,
-          checked: selectionStatus === 'checked',
+          checked: selectionStatus === 'selected',
           indeterminate: selectionStatus === 'indeterminate'
         };
       }

package/internals/plugins/selection/itemPlugin.mjs

@@ -1,39 +1,7 @@
-import { createSelector, useStore } from '@mui/x-internals/store';
+import { useStore } from '@mui/x-internals/store';
 import { useTreeViewContext } from "../../TreeViewProvider/index.mjs";
 import { itemsSelectors } from "../items/selectors.mjs";
 import { selectionSelectors } from "./selectors.mjs";
-const selectorCheckboxSelectionStatus = createSelector((state, itemId) => {
-  if (selectionSelectors.isItemSelected(state, itemId)) {
-    return 'checked';
-  }
-  let hasSelectedDescendant = false;
-  let hasUnSelectedDescendant = false;
-  const traverseDescendants = itemToTraverseId => {
-    if (itemToTraverseId !== itemId) {
-      if (selectionSelectors.isItemSelected(state, itemToTraverseId)) {
-        hasSelectedDescendant = true;
-      } else {
-        hasUnSelectedDescendant = true;
-      }
-    }
-    itemsSelectors.itemOrderedChildrenIds(state, itemToTraverseId).forEach(traverseDescendants);
-  };
-  traverseDescendants(itemId);
-  const shouldSelectBasedOnDescendants = selectionSelectors.propagationRules(state).parents;
-  if (shouldSelectBasedOnDescendants) {
-    if (hasSelectedDescendant && hasUnSelectedDescendant) {
-      return 'indeterminate';
-    }
-    if (hasSelectedDescendant && !hasUnSelectedDescendant) {
-      return 'checked';
-    }
-    return 'empty';
-  }
-  if (hasSelectedDescendant) {
-    return 'indeterminate';
-  }
-  return 'empty';
-});
 export const useSelectionItemPlugin = ({
   props
 }) => {
@@ -46,19 +14,28 @@ export const useSelectionItemPlugin = ({
   const isCheckboxSelectionEnabled = useStore(store, selectionSelectors.isCheckboxSelectionEnabled);
   const isFeatureEnabledForItem = useStore(store, selectionSelectors.isFeatureEnabledForItem, itemId);
   const canItemBeSelected = useStore(store, selectionSelectors.canItemBeSelected, itemId);
-  const selectionStatus = useStore(store, selectorCheckboxSelectionStatus, itemId);
+  const isItemDisabled = useStore(store, itemsSelectors.isItemDisabled, itemId);
+  const isItemSelectable = useStore(store, selectionSelectors.isItemSelectable, itemId);
+  const selectionStatus = useStore(store, selectionSelectors.itemSelectionStatus, itemId);
+
+  // An item is "inherently not selectable" when disabled or excluded via isItemSelectionDisabled,
+  // regardless of the global disableSelection flag. Such items must not have aria-checked.
+  const isItemInherentlyNotSelectable = isItemDisabled || !isItemSelectable;
   return {
     propsEnhancers: {
       root: () => {
         // https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
         let ariaChecked;
-        if (selectionStatus === 'checked') {
+        if (isItemInherentlyNotSelectable) {
+          // - if the tree contains nodes that are not selectable, aria-checked is not present on those nodes.
+          ariaChecked = undefined;
+        } else if (selectionStatus === 'selected') {
           // - each selected node has aria-checked set to true.
           ariaChecked = true;
         } else if (selectionStatus === 'indeterminate') {
           ariaChecked = 'mixed';
         } else if (!canItemBeSelected) {
-          // - if the tree contains nodes that are not selectable, aria-checked is not present on those nodes.
+          // disableSelection=true with an unselected item: aria-checked is not present.
           ariaChecked = undefined;
         } else {
           // - all nodes that are selectable but not selected have aria-checked set to false.
@@ -87,7 +64,7 @@ export const useSelectionItemPlugin = ({
           onChange: handleChange,
           visible: isCheckboxSelectionEnabled && isFeatureEnabledForItem,
           disabled: !canItemBeSelected,
-          checked: selectionStatus === 'checked',
+          checked: selectionStatus === 'selected',
           indeterminate: selectionStatus === 'indeterminate'
         };
       }

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

@@ -1,3 +1,4 @@
+import type { TreeViewItemSelectionStatus } from "../../../models/index.mjs";
 import type { MinimalTreeViewState } from "../../MinimalTreeViewStore/index.mjs";
 export declare const selectionSelectors: {
   /**
@@ -32,6 +33,16 @@ export declare const selectionSelectors: {
    * Checks whether an item is selected.
    */
   isItemSelected: (args_0: MinimalTreeViewState<any, any>, itemId: string) => boolean;
+  /**
+   * Gets the selection status of an item.
+   * An item that is not selected is `indeterminate` when some of its selectable descendants are selected.
+   * When `selectionPropagation.parents` is enabled, an item whose selectable descendants are all selected is `selected`.
+   */
+  itemSelectionStatus: (state: MinimalTreeViewState<any, any>, itemId: string) => TreeViewItemSelectionStatus;
+  /**
+   * Checks whether an item is indeterminate (it is not selected but some of its selectable descendants are).
+   */
+  isItemIndeterminate: (args_0: MinimalTreeViewState<any, any>, _itemId: string) => boolean;
   /**
    * Checks whether the selection feature is enabled for an item.
    * Returns `true` when selection is enabled on the Tree View and the item is selectable (even if the item is disabled).

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

@@ -1,3 +1,4 @@
+import type { TreeViewItemSelectionStatus } from "../../../models/index.js";
 import type { MinimalTreeViewState } from "../../MinimalTreeViewStore/index.js";
 export declare const selectionSelectors: {
   /**
@@ -32,6 +33,16 @@ export declare const selectionSelectors: {
    * Checks whether an item is selected.
    */
   isItemSelected: (args_0: MinimalTreeViewState<any, any>, itemId: string) => boolean;
+  /**
+   * Gets the selection status of an item.
+   * An item that is not selected is `indeterminate` when some of its selectable descendants are selected.
+   * When `selectionPropagation.parents` is enabled, an item whose selectable descendants are all selected is `selected`.
+   */
+  itemSelectionStatus: (state: MinimalTreeViewState<any, any>, itemId: string) => TreeViewItemSelectionStatus;
+  /**
+   * Checks whether an item is indeterminate (it is not selected but some of its selectable descendants are).
+   */
+  isItemIndeterminate: (args_0: MinimalTreeViewState<any, any>, _itemId: string) => boolean;
   /**
    * Checks whether the selection feature is enabled for an item.
    * Returns `true` when selection is enabled on the Tree View and the item is selectable (even if the item is disabled).

package/internals/plugins/selection/selectors.js

@@ -23,6 +23,49 @@ const selectedItemsMapSelector = (0, _store.createSelectorMemoized)(selectedItem
   return selectedItemsMap;
 });
 const isItemSelectableSelector = (0, _store.createSelector)((state, itemId) => state.itemMetaLookup[itemId]?.selectable ?? true);
+const isItemSelectedSelector = (0, _store.createSelector)(selectedItemsMapSelector, (selectedItemsMap, itemId) => selectedItemsMap.has(itemId));
+const canItemBeSelectedSelector = (0, _store.createSelector)(_selectors.itemsSelectors.isItemDisabled, isItemSelectableSelector, state => !state.disableSelection, (isItemDisabled, isItemSelectable, isSelectionEnabled, _itemId) => isSelectionEnabled && !isItemDisabled && isItemSelectable);
+const propagationRulesSelector = (0, _store.createSelector)(state => state.selectionPropagation);
+const itemSelectionStatusSelector = (0, _store.createSelector)((state, itemId) => {
+  if (isItemSelectedSelector(state, itemId)) {
+    return 'selected';
+  }
+
+  // Only the descendants can make an unselected item `indeterminate`, so leaves can be resolved
+  // without traversing the tree.
+  if (_selectors.itemsSelectors.itemOrderedChildrenIds(state, itemId).length === 0) {
+    return 'unselected';
+  }
+  let hasSelectedDescendant = false;
+  let hasUnSelectedDescendant = false;
+  const traverseDescendants = itemToTraverseId => {
+    if (itemToTraverseId !== itemId) {
+      if (canItemBeSelectedSelector(state, itemToTraverseId)) {
+        if (isItemSelectedSelector(state, itemToTraverseId)) {
+          hasSelectedDescendant = true;
+        } else {
+          hasUnSelectedDescendant = true;
+        }
+      }
+    }
+    _selectors.itemsSelectors.itemOrderedChildrenIds(state, itemToTraverseId).forEach(traverseDescendants);
+  };
+  traverseDescendants(itemId);
+  const shouldSelectBasedOnDescendants = propagationRulesSelector(state).parents;
+  if (shouldSelectBasedOnDescendants) {
+    if (hasSelectedDescendant && hasUnSelectedDescendant) {
+      return 'indeterminate';
+    }
+    if (hasSelectedDescendant && !hasUnSelectedDescendant) {
+      return 'selected';
+    }
+    return 'unselected';
+  }
+  if (hasSelectedDescendant) {
+    return 'indeterminate';
+  }
+  return 'unselected';
+});
 const selectionSelectors = exports.selectionSelectors = {
   /**
    * Gets the selected items as provided to the component.
@@ -51,11 +94,21 @@ const selectionSelectors = exports.selectionSelectors = {
   /**
    * Gets the selection propagation rules.
    */
-  propagationRules: (0, _store.createSelector)(state => state.selectionPropagation),
+  propagationRules: propagationRulesSelector,
   /**
    * Checks whether an item is selected.
    */
-  isItemSelected: (0, _store.createSelector)(selectedItemsMapSelector, (selectedItemsMap, itemId) => selectedItemsMap.has(itemId)),
+  isItemSelected: isItemSelectedSelector,
+  /**
+   * Gets the selection status of an item.
+   * An item that is not selected is `indeterminate` when some of its selectable descendants are selected.
+   * When `selectionPropagation.parents` is enabled, an item whose selectable descendants are all selected is `selected`.
+   */
+  itemSelectionStatus: itemSelectionStatusSelector,
+  /**
+   * Checks whether an item is indeterminate (it is not selected but some of its selectable descendants are).
+   */
+  isItemIndeterminate: (0, _store.createSelector)(itemSelectionStatusSelector, (selectionStatus, _itemId) => selectionStatus === 'indeterminate'),
   /**
    * Checks whether the selection feature is enabled for an item.
    * Returns `true` when selection is enabled on the Tree View and the item is selectable (even if the item is disabled).
@@ -64,7 +117,7 @@ const selectionSelectors = exports.selectionSelectors = {
   /**
    * Checks whether an item can be selected (if selection is enabled, if the item is not disabled, and if the item is selectable).
    */
-  canItemBeSelected: (0, _store.createSelector)(_selectors.itemsSelectors.isItemDisabled, isItemSelectableSelector, state => !state.disableSelection, (isItemDisabled, isItemSelectable, isSelectionEnabled, _itemId) => isSelectionEnabled && !isItemDisabled && isItemSelectable),
+  canItemBeSelected: canItemBeSelectedSelector,
   /**
    * Checks whether an item is selectable based on the `isItemSelectionDisabled` prop.
    */