@headless-tree/core 0.0.0-20250820225709 → 0.0.0-20250828222543

package/CHANGELOG.md

@@ -1,10 +1,13 @@
 # @headless-tree/core
 
-## 0.0.0-20250820225709
+## 0.0.0-20250828222543
 
 ### Patch Changes
 
 - 215ab4b: add a new symbol that can be used in hotkey configurations "metaorcontrol" that will trigger if either any windows control key or mac meta key is pressed (#141)
+- cf845d7: Added new state variable `loadingCheckPropagationItems` to indicate if, in async trees with checkboxes and state propagation enabled, data loading operations are currently loading due to a checkbox propagation taking place
+- 597faad: Checkbox propagation is now supported for trees with async data loaders!
+- b0ee382: triggering a data refetch will now always set the loadingItemData/loadingItemChildrens state variable to the associated items if they where not apart of the cache before
 
 ## 1.4.0
 

package/dist/index.d.mts

@@ -312,7 +312,8 @@ type AsyncDataLoaderFeatureDef<T> = {
          * @param optimistic If true, the item will not trigger a state update on `loadingItemChildrens`, and
          * the tree will continue to display the old data until the new data has loaded. */
         invalidateChildrenIds: (optimistic?: boolean) => Promise<void>;
-        updateCachedData: (data: T) => void;
+        /** Set to undefined to clear cache without triggering automatic refetch. Use @invalidateItemData to clear and triggering refetch. */
+        updateCachedData: (data: T | undefined) => void;
         updateCachedChildrenIds: (childrenIds: string[]) => void;
         isLoading: () => boolean;
     };
@@ -448,9 +449,11 @@ declare enum CheckedState {
 type CheckboxesFeatureDef<T> = {
     state: {
         checkedItems: string[];
+        loadingCheckPropagationItems: string[];
     };
     config: {
         setCheckedItems?: SetStateFn<string[]>;
+        setLoadingCheckPropagationItems?: SetStateFn<string[]>;
         canCheckFolders?: boolean;
         propagateCheckedState?: boolean;
     };
@@ -458,11 +461,18 @@ type CheckboxesFeatureDef<T> = {
         setCheckedItems: (checkedItems: string[]) => void;
     };
     itemInstance: {
-        setChecked: () => void;
-        setUnchecked: () => void;
-        toggleCheckedState: () => void;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        setChecked: () => Promise<void>;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        setUnchecked: () => Promise<void>;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        toggleCheckedState: () => Promise<void>;
         getCheckedState: () => CheckedState;
         getCheckboxProps: () => Record<string, any>;
+        isLoadingCheckPropagation: () => boolean;
     };
     hotkeys: never;
 };

package/dist/index.d.ts

@@ -312,7 +312,8 @@ type AsyncDataLoaderFeatureDef<T> = {
          * @param optimistic If true, the item will not trigger a state update on `loadingItemChildrens`, and
          * the tree will continue to display the old data until the new data has loaded. */
         invalidateChildrenIds: (optimistic?: boolean) => Promise<void>;
-        updateCachedData: (data: T) => void;
+        /** Set to undefined to clear cache without triggering automatic refetch. Use @invalidateItemData to clear and triggering refetch. */
+        updateCachedData: (data: T | undefined) => void;
         updateCachedChildrenIds: (childrenIds: string[]) => void;
         isLoading: () => boolean;
     };
@@ -448,9 +449,11 @@ declare enum CheckedState {
 type CheckboxesFeatureDef<T> = {
     state: {
         checkedItems: string[];
+        loadingCheckPropagationItems: string[];
     };
     config: {
         setCheckedItems?: SetStateFn<string[]>;
+        setLoadingCheckPropagationItems?: SetStateFn<string[]>;
         canCheckFolders?: boolean;
         propagateCheckedState?: boolean;
     };
@@ -458,11 +461,18 @@ type CheckboxesFeatureDef<T> = {
         setCheckedItems: (checkedItems: string[]) => void;
     };
     itemInstance: {
-        setChecked: () => void;
-        setUnchecked: () => void;
-        toggleCheckedState: () => void;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        setChecked: () => Promise<void>;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        setUnchecked: () => Promise<void>;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        toggleCheckedState: () => Promise<void>;
         getCheckedState: () => CheckedState;
         getCheckboxProps: () => Record<string, any>;
+        isLoadingCheckPropagation: () => boolean;
     };
     hotkeys: never;
 };

package/dist/index.js

@@ -817,33 +817,60 @@ var getAllLoadedDescendants = (tree, itemId, includeFolders = false) => {
   if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
     return [itemId];
   }
-  const descendants = tree.retrieveChildrenIds(itemId).map((child) => getAllLoadedDescendants(tree, child, includeFolders)).flat();
+  const descendants = tree.retrieveChildrenIds(itemId, true).map((child) => getAllLoadedDescendants(tree, child, includeFolders)).flat();
   return includeFolders ? [itemId, ...descendants] : descendants;
 };
+var getAllDescendants = (tree, itemId, includeFolders = false) => __async(null, null, function* () {
+  yield tree.loadItemData(itemId);
+  if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
+    return [itemId];
+  }
+  const childrenIds = yield tree.loadChildrenIds(itemId);
+  const descendants = (yield Promise.all(
+    childrenIds.map(
+      (child) => getAllDescendants(tree, child, includeFolders)
+    )
+  )).flat();
+  return includeFolders ? [itemId, ...descendants] : descendants;
+});
+var withLoadingState = (tree, itemId, callback) => __async(null, null, function* () {
+  tree.applySubStateUpdate("loadingCheckPropagationItems", (items) => [
+    ...items,
+    itemId
+  ]);
+  try {
+    yield callback();
+  } finally {
+    tree.applySubStateUpdate(
+      "loadingCheckPropagationItems",
+      (items) => items.filter((id) => id !== itemId)
+    );
+  }
+});
 var checkboxesFeature = {
   key: "checkboxes",
   overwrites: ["selection"],
   getInitialState: (initialState) => __spreadValues({
-    checkedItems: []
+    checkedItems: [],
+    loadingCheckPropagationItems: []
   }, initialState),
   getDefaultConfig: (defaultConfig, tree) => {
-    var _a, _b, _c;
-    const hasAsyncLoader = (_a = defaultConfig.features) == null ? void 0 : _a.some(
-      (f) => f.key === "async-data-loader"
-    );
-    if (hasAsyncLoader && defaultConfig.propagateCheckedState) {
-      throwError(`propagateCheckedState not supported with async trees`);
-    }
-    const propagateCheckedState = (_b = defaultConfig.propagateCheckedState) != null ? _b : !hasAsyncLoader;
-    const canCheckFolders = (_c = defaultConfig.canCheckFolders) != null ? _c : !propagateCheckedState;
+    var _a, _b;
+    const propagateCheckedState = (_a = defaultConfig.propagateCheckedState) != null ? _a : true;
+    const canCheckFolders = (_b = defaultConfig.canCheckFolders) != null ? _b : !propagateCheckedState;
     return __spreadValues({
       setCheckedItems: makeStateUpdater("checkedItems", tree),
+      setLoadingCheckPropagationItems: makeStateUpdater(
+        "loadingCheckPropagationItems",
+        tree
+      ),
       propagateCheckedState,
       canCheckFolders
     }, defaultConfig);
   },
   stateHandlerNames: {
-    checkedItems: "setCheckedItems"
+    checkedItems: "setCheckedItems",
+    loadingCheckPropagationItems: "setLoadingCheckPropagationItems"
   },
   treeInstance: {
     setCheckedItems: ({ tree }, checkedItems) => {
@@ -863,13 +890,13 @@ var checkboxesFeature = {
         }
       };
     },
-    toggleCheckedState: ({ item }) => {
+    toggleCheckedState: (_0) => __async(null, [_0], function* ({ item }) {
       if (item.getCheckedState() === "checked" /* Checked */) {
-        item.setUnchecked();
+        yield item.setUnchecked();
       } else {
-        item.setChecked();
+        yield item.setChecked();
       }
-    },
+    }),
     getCheckedState: ({ item, tree }) => {
       const { checkedItems } = tree.getState();
       const { propagateCheckedState } = tree.getConfig();
@@ -879,6 +906,7 @@ var checkboxesFeature = {
       }
       if (item.isFolder() && propagateCheckedState) {
         const descendants = getAllLoadedDescendants(tree, itemId);
+        if (descendants.length === 0) return "unchecked" /* Unchecked */;
         if (descendants.every((d) => checkedItems.includes(d))) {
           return "checked" /* Checked */;
         }
@@ -888,36 +916,48 @@ var checkboxesFeature = {
       }
       return "unchecked" /* Unchecked */;
     },
-    setChecked: ({ item, tree, itemId }) => {
-      const { propagateCheckedState, canCheckFolders } = tree.getConfig();
-      if (item.isFolder() && propagateCheckedState) {
-        tree.applySubStateUpdate("checkedItems", (items) => [
-          ...items,
-          ...getAllLoadedDescendants(tree, itemId, canCheckFolders)
-        ]);
-      } else if (!item.isFolder() || canCheckFolders) {
-        tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
-      }
-    },
-    setUnchecked: ({ item, tree, itemId }) => {
-      const { propagateCheckedState, canCheckFolders } = tree.getConfig();
-      if (item.isFolder() && propagateCheckedState) {
-        const descendants = getAllLoadedDescendants(
-          tree,
-          itemId,
-          canCheckFolders
-        );
-        tree.applySubStateUpdate(
-          "checkedItems",
-          (items) => items.filter((id) => !descendants.includes(id) && id !== itemId)
-        );
-      } else {
-        tree.applySubStateUpdate(
-          "checkedItems",
-          (items) => items.filter((id) => id !== itemId)
-        );
-      }
-    }
+    setChecked: (_0) => __async(null, [_0], function* ({ item, tree, itemId }) {
+      yield withLoadingState(tree, itemId, () => __async(null, null, function* () {
+        const { propagateCheckedState, canCheckFolders } = tree.getConfig();
+        if (item.isFolder() && propagateCheckedState) {
+          const descendants = yield getAllDescendants(
+            tree,
+            itemId,
+            canCheckFolders
+          );
+          tree.applySubStateUpdate("checkedItems", (items) => [
+            ...items,
+            ...descendants
+          ]);
+        } else if (!item.isFolder() || canCheckFolders) {
+          tree.applySubStateUpdate("checkedItems", (items) => [
+            ...items,
+            itemId
+          ]);
+        }
+      }));
+    }),
+    setUnchecked: (_0) => __async(null, [_0], function* ({ item, tree, itemId }) {
+      yield withLoadingState(tree, itemId, () => __async(null, null, function* () {
+        const { propagateCheckedState, canCheckFolders } = tree.getConfig();
+        if (item.isFolder() && propagateCheckedState) {
+          const descendants = yield getAllDescendants(
+            tree,
+            itemId,
+            canCheckFolders
+          );
+          tree.applySubStateUpdate(
+            "checkedItems",
+            (items) => items.filter((id) => !descendants.includes(id) && id !== itemId)
+          );
+        } else {
+          tree.applySubStateUpdate(
+            "checkedItems",
+            (items) => items.filter((id) => id !== itemId)
+          );
+        }
+      }));
+    })
   }
 };
 
@@ -1035,6 +1075,12 @@ var loadItemData = (tree, itemId) => __async(null, null, function* () {
   var _a;
   const config = tree.getConfig();
   const dataRef = getDataRef(tree);
+  if (!dataRef.current.itemData[itemId]) {
+    tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
+      ...loadingItemData,
+      itemId
+    ]);
+  }
   const item = yield config.dataLoader.getItem(itemId);
   dataRef.current.itemData[itemId] = item;
   (_a = config.onLoadedItem) == null ? void 0 : _a.call(config, itemId, item);
@@ -1049,6 +1095,12 @@ var loadChildrenIds = (tree, itemId) => __async(null, null, function* () {
   const config = tree.getConfig();
   const dataRef = getDataRef(tree);
   let childrenIds;
+  if (!dataRef.current.childrenIds[itemId]) {
+    tree.applySubStateUpdate("loadingItemChildrens", (loadingItemChildrens) => [
+      ...loadingItemChildrens,
+      itemId
+    ]);
+  }
   if ("getChildrenWithData" in config.dataLoader) {
     const children = yield config.dataLoader.getChildrenWithData(itemId);
     childrenIds = children.map((c) => c.id);
@@ -1109,10 +1161,6 @@ var asyncDataLoaderFeature = {
         return dataRef.current.itemData[itemId];
       }
       if (!tree.getState().loadingItemData.includes(itemId) && !skipFetch) {
-        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
-          ...loadingItemData,
-          itemId
-        ]);
         loadItemData(tree, itemId);
       }
       return (_b = (_a = config.createLoadingItemData) == null ? void 0 : _a.call(config)) != null ? _b : null;
@@ -1125,10 +1173,6 @@ var asyncDataLoaderFeature = {
       if (tree.getState().loadingItemChildrens.includes(itemId) || skipFetch) {
         return [];
       }
-      tree.applySubStateUpdate(
-        "loadingItemChildrens",
-        (loadingItemChildrens) => [...loadingItemChildrens, itemId]
-      );
       loadChildrenIds(tree, itemId);
       return [];
     }
@@ -1139,10 +1183,6 @@ var asyncDataLoaderFeature = {
       var _a;
       if (!optimistic) {
         (_a = getDataRef(tree).current.itemData) == null ? true : delete _a[itemId];
-        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
-          ...loadingItemData,
-          itemId
-        ]);
       }
       yield loadItemData(tree, itemId);
     }),
@@ -1150,10 +1190,6 @@ var asyncDataLoaderFeature = {
       var _a;
       if (!optimistic) {
         (_a = getDataRef(tree).current.childrenIds) == null ? true : delete _a[itemId];
-        tree.applySubStateUpdate(
-          "loadingItemChildrens",
-          (loadingItemChildrens) => [...loadingItemChildrens, itemId]
-        );
       }
       yield loadChildrenIds(tree, itemId);
     }),

package/dist/index.mjs

@@ -773,33 +773,60 @@ var getAllLoadedDescendants = (tree, itemId, includeFolders = false) => {
   if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
     return [itemId];
   }
-  const descendants = tree.retrieveChildrenIds(itemId).map((child) => getAllLoadedDescendants(tree, child, includeFolders)).flat();
+  const descendants = tree.retrieveChildrenIds(itemId, true).map((child) => getAllLoadedDescendants(tree, child, includeFolders)).flat();
   return includeFolders ? [itemId, ...descendants] : descendants;
 };
+var getAllDescendants = (tree, itemId, includeFolders = false) => __async(null, null, function* () {
+  yield tree.loadItemData(itemId);
+  if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
+    return [itemId];
+  }
+  const childrenIds = yield tree.loadChildrenIds(itemId);
+  const descendants = (yield Promise.all(
+    childrenIds.map(
+      (child) => getAllDescendants(tree, child, includeFolders)
+    )
+  )).flat();
+  return includeFolders ? [itemId, ...descendants] : descendants;
+});
+var withLoadingState = (tree, itemId, callback) => __async(null, null, function* () {
+  tree.applySubStateUpdate("loadingCheckPropagationItems", (items) => [
+    ...items,
+    itemId
+  ]);
+  try {
+    yield callback();
+  } finally {
+    tree.applySubStateUpdate(
+      "loadingCheckPropagationItems",
+      (items) => items.filter((id) => id !== itemId)
+    );
+  }
+});
 var checkboxesFeature = {
   key: "checkboxes",
   overwrites: ["selection"],
   getInitialState: (initialState) => __spreadValues({
-    checkedItems: []
+    checkedItems: [],
+    loadingCheckPropagationItems: []
   }, initialState),
   getDefaultConfig: (defaultConfig, tree) => {
-    var _a, _b, _c;
-    const hasAsyncLoader = (_a = defaultConfig.features) == null ? void 0 : _a.some(
-      (f) => f.key === "async-data-loader"
-    );
-    if (hasAsyncLoader && defaultConfig.propagateCheckedState) {
-      throwError(`propagateCheckedState not supported with async trees`);
-    }
-    const propagateCheckedState = (_b = defaultConfig.propagateCheckedState) != null ? _b : !hasAsyncLoader;
-    const canCheckFolders = (_c = defaultConfig.canCheckFolders) != null ? _c : !propagateCheckedState;
+    var _a, _b;
+    const propagateCheckedState = (_a = defaultConfig.propagateCheckedState) != null ? _a : true;
+    const canCheckFolders = (_b = defaultConfig.canCheckFolders) != null ? _b : !propagateCheckedState;
     return __spreadValues({
       setCheckedItems: makeStateUpdater("checkedItems", tree),
+      setLoadingCheckPropagationItems: makeStateUpdater(
+        "loadingCheckPropagationItems",
+        tree
+      ),
       propagateCheckedState,
       canCheckFolders
     }, defaultConfig);
   },
   stateHandlerNames: {
-    checkedItems: "setCheckedItems"
+    checkedItems: "setCheckedItems",
+    loadingCheckPropagationItems: "setLoadingCheckPropagationItems"
   },
   treeInstance: {
     setCheckedItems: ({ tree }, checkedItems) => {
@@ -819,13 +846,13 @@ var checkboxesFeature = {
         }
       };
     },
-    toggleCheckedState: ({ item }) => {
+    toggleCheckedState: (_0) => __async(null, [_0], function* ({ item }) {
       if (item.getCheckedState() === "checked" /* Checked */) {
-        item.setUnchecked();
+        yield item.setUnchecked();
       } else {
-        item.setChecked();
+        yield item.setChecked();
       }
-    },
+    }),
     getCheckedState: ({ item, tree }) => {
       const { checkedItems } = tree.getState();
       const { propagateCheckedState } = tree.getConfig();
@@ -835,6 +862,7 @@ var checkboxesFeature = {
       }
       if (item.isFolder() && propagateCheckedState) {
         const descendants = getAllLoadedDescendants(tree, itemId);
+        if (descendants.length === 0) return "unchecked" /* Unchecked */;
         if (descendants.every((d) => checkedItems.includes(d))) {
           return "checked" /* Checked */;
         }
@@ -844,36 +872,48 @@ var checkboxesFeature = {
       }
       return "unchecked" /* Unchecked */;
     },
-    setChecked: ({ item, tree, itemId }) => {
-      const { propagateCheckedState, canCheckFolders } = tree.getConfig();
-      if (item.isFolder() && propagateCheckedState) {
-        tree.applySubStateUpdate("checkedItems", (items) => [
-          ...items,
-          ...getAllLoadedDescendants(tree, itemId, canCheckFolders)
-        ]);
-      } else if (!item.isFolder() || canCheckFolders) {
-        tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
-      }
-    },
-    setUnchecked: ({ item, tree, itemId }) => {
-      const { propagateCheckedState, canCheckFolders } = tree.getConfig();
-      if (item.isFolder() && propagateCheckedState) {
-        const descendants = getAllLoadedDescendants(
-          tree,
-          itemId,
-          canCheckFolders
-        );
-        tree.applySubStateUpdate(
-          "checkedItems",
-          (items) => items.filter((id) => !descendants.includes(id) && id !== itemId)
-        );
-      } else {
-        tree.applySubStateUpdate(
-          "checkedItems",
-          (items) => items.filter((id) => id !== itemId)
-        );
-      }
-    }
+    setChecked: (_0) => __async(null, [_0], function* ({ item, tree, itemId }) {
+      yield withLoadingState(tree, itemId, () => __async(null, null, function* () {
+        const { propagateCheckedState, canCheckFolders } = tree.getConfig();
+        if (item.isFolder() && propagateCheckedState) {
+          const descendants = yield getAllDescendants(
+            tree,
+            itemId,
+            canCheckFolders
+          );
+          tree.applySubStateUpdate("checkedItems", (items) => [
+            ...items,
+            ...descendants
+          ]);
+        } else if (!item.isFolder() || canCheckFolders) {
+          tree.applySubStateUpdate("checkedItems", (items) => [
+            ...items,
+            itemId
+          ]);
+        }
+      }));
+    }),
+    setUnchecked: (_0) => __async(null, [_0], function* ({ item, tree, itemId }) {
+      yield withLoadingState(tree, itemId, () => __async(null, null, function* () {
+        const { propagateCheckedState, canCheckFolders } = tree.getConfig();
+        if (item.isFolder() && propagateCheckedState) {
+          const descendants = yield getAllDescendants(
+            tree,
+            itemId,
+            canCheckFolders
+          );
+          tree.applySubStateUpdate(
+            "checkedItems",
+            (items) => items.filter((id) => !descendants.includes(id) && id !== itemId)
+          );
+        } else {
+          tree.applySubStateUpdate(
+            "checkedItems",
+            (items) => items.filter((id) => id !== itemId)
+          );
+        }
+      }));
+    })
   }
 };
 
@@ -991,6 +1031,12 @@ var loadItemData = (tree, itemId) => __async(null, null, function* () {
   var _a;
   const config = tree.getConfig();
   const dataRef = getDataRef(tree);
+  if (!dataRef.current.itemData[itemId]) {
+    tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
+      ...loadingItemData,
+      itemId
+    ]);
+  }
   const item = yield config.dataLoader.getItem(itemId);
   dataRef.current.itemData[itemId] = item;
   (_a = config.onLoadedItem) == null ? void 0 : _a.call(config, itemId, item);
@@ -1005,6 +1051,12 @@ var loadChildrenIds = (tree, itemId) => __async(null, null, function* () {
   const config = tree.getConfig();
   const dataRef = getDataRef(tree);
   let childrenIds;
+  if (!dataRef.current.childrenIds[itemId]) {
+    tree.applySubStateUpdate("loadingItemChildrens", (loadingItemChildrens) => [
+      ...loadingItemChildrens,
+      itemId
+    ]);
+  }
   if ("getChildrenWithData" in config.dataLoader) {
     const children = yield config.dataLoader.getChildrenWithData(itemId);
     childrenIds = children.map((c) => c.id);
@@ -1065,10 +1117,6 @@ var asyncDataLoaderFeature = {
         return dataRef.current.itemData[itemId];
       }
       if (!tree.getState().loadingItemData.includes(itemId) && !skipFetch) {
-        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
-          ...loadingItemData,
-          itemId
-        ]);
         loadItemData(tree, itemId);
       }
       return (_b = (_a = config.createLoadingItemData) == null ? void 0 : _a.call(config)) != null ? _b : null;
@@ -1081,10 +1129,6 @@ var asyncDataLoaderFeature = {
       if (tree.getState().loadingItemChildrens.includes(itemId) || skipFetch) {
         return [];
       }
-      tree.applySubStateUpdate(
-        "loadingItemChildrens",
-        (loadingItemChildrens) => [...loadingItemChildrens, itemId]
-      );
       loadChildrenIds(tree, itemId);
       return [];
     }
@@ -1095,10 +1139,6 @@ var asyncDataLoaderFeature = {
       var _a;
       if (!optimistic) {
         (_a = getDataRef(tree).current.itemData) == null ? true : delete _a[itemId];
-        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
-          ...loadingItemData,
-          itemId
-        ]);
       }
       yield loadItemData(tree, itemId);
     }),
@@ -1106,10 +1146,6 @@ var asyncDataLoaderFeature = {
       var _a;
       if (!optimistic) {
         (_a = getDataRef(tree).current.childrenIds) == null ? true : delete _a[itemId];
-        tree.applySubStateUpdate(
-          "loadingItemChildrens",
-          (loadingItemChildrens) => [...loadingItemChildrens, itemId]
-        );
       }
       yield loadChildrenIds(tree, itemId);
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-tree/core",
-  "version": "0.0.0-20250820225709",
+  "version": "0.0.0-20250828222543",
   "main": "dist/index.d.ts",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",

package/src/features/async-data-loader/feature.ts

@@ -13,6 +13,13 @@ const loadItemData = async <T>(tree: TreeInstance<T>, itemId: string) => {
   const config = tree.getConfig();
   const dataRef = getDataRef(tree);
 
+  if (!dataRef.current.itemData[itemId]) {
+    tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
+      ...loadingItemData,
+      itemId,
+    ]);
+  }
+
   const item = await config.dataLoader.getItem(itemId);
   dataRef.current.itemData[itemId] = item;
   config.onLoadedItem?.(itemId, item);
@@ -28,6 +35,13 @@ const loadChildrenIds = async <T>(tree: TreeInstance<T>, itemId: string) => {
   const dataRef = getDataRef(tree);
   let childrenIds: string[];
 
+  if (!dataRef.current.childrenIds[itemId]) {
+    tree.applySubStateUpdate("loadingItemChildrens", (loadingItemChildrens) => [
+      ...loadingItemChildrens,
+      itemId,
+    ]);
+  }
+
   if ("getChildrenWithData" in config.dataLoader) {
     const children = await config.dataLoader.getChildrenWithData(itemId);
     childrenIds = children.map((c) => c.id);
@@ -104,11 +118,6 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
       }
 
       if (!tree.getState().loadingItemData.includes(itemId) && !skipFetch) {
-        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
-          ...loadingItemData,
-          itemId,
-        ]);
-
         loadItemData(tree, itemId);
       }
 
@@ -125,11 +134,6 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
         return [];
       }
 
-      tree.applySubStateUpdate(
-        "loadingItemChildrens",
-        (loadingItemChildrens) => [...loadingItemChildrens, itemId],
-      );
-
       loadChildrenIds(tree, itemId);
 
       return [];
@@ -143,20 +147,12 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
     invalidateItemData: async ({ tree, itemId }, optimistic) => {
       if (!optimistic) {
         delete getDataRef(tree).current.itemData?.[itemId];
-        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
-          ...loadingItemData,
-          itemId,
-        ]);
       }
       await loadItemData(tree, itemId);
     },
     invalidateChildrenIds: async ({ tree, itemId }, optimistic) => {
       if (!optimistic) {
         delete getDataRef(tree).current.childrenIds?.[itemId];
-        tree.applySubStateUpdate(
-          "loadingItemChildrens",
-          (loadingItemChildrens) => [...loadingItemChildrens, itemId],
-        );
       }
       await loadChildrenIds(tree, itemId);
     },

package/src/features/async-data-loader/types.ts

@@ -47,7 +47,8 @@ export type AsyncDataLoaderFeatureDef<T> = {
      * the tree will continue to display the old data until the new data has loaded. */
     invalidateChildrenIds: (optimistic?: boolean) => Promise<void>;
 
-    updateCachedData: (data: T) => void;
+    /** Set to undefined to clear cache without triggering automatic refetch. Use @invalidateItemData to clear and triggering refetch. */
+    updateCachedData: (data: T | undefined) => void;
     updateCachedChildrenIds: (childrenIds: string[]) => void;
     isLoading: () => boolean;
   };

package/src/features/checkboxes/checkboxes.spec.ts

@@ -3,147 +3,136 @@ import { TestTree } from "../../test-utils/test-tree";
 import { checkboxesFeature } from "./feature";
 import { CheckedState } from "./types";
 
-const factory = TestTree.default({})
-  .withFeatures(checkboxesFeature)
-  .suits.sync().tree;
+const factory = TestTree.default({
+  propagateCheckedState: true,
+  canCheckFolders: false,
+}).withFeatures(checkboxesFeature);
 
 describe("core-feature/checkboxes", () => {
-  it("should initialize with no checked items", async () => {
-    const tree = await factory.createTestCaseTree();
-    expect(tree.instance.getState().checkedItems).toEqual([]);
-  });
-
-  it("should check items", async () => {
-    const tree = await factory.createTestCaseTree();
-    tree.item("x111").setChecked();
-    tree.item("x112").setChecked();
-    expect(tree.instance.getState().checkedItems).toEqual(["x111", "x112"]);
-  });
-
-  it("should uncheck an item", async () => {
-    const tree = await factory
-      .with({ state: { checkedItems: ["x111"] } })
-      .createTestCaseTree();
-    tree.item("x111").setUnchecked();
-    expect(tree.instance.getState().checkedItems).not.toContain("x111");
-  });
-
-  it("should toggle checked state", async () => {
-    const tree = await factory.createTestCaseTree();
-    const item = tree.item("x111");
+  factory.forSuits((tree) => {
+    it("should initialize with no checked items", async () => {
+      expect(tree.instance.getState().checkedItems).toEqual([]);
+    });
 
-    item.toggleCheckedState();
-    expect(tree.instance.getState().checkedItems).toContain("x111");
+    it("should check items", async () => {
+      await tree.item("x111").setChecked();
+      await tree.item("x112").setChecked();
+      expect(tree.instance.getState().checkedItems).toEqual(["x111", "x112"]);
+    });
 
-    item.toggleCheckedState();
-    expect(tree.instance.getState().checkedItems).not.toContain("x111");
-  });
+    it("should uncheck an item", async () => {
+      await tree.item("x111").setChecked();
+      await tree.item("x111").setUnchecked();
+      expect(tree.instance.getState().checkedItems).not.toContain("x111");
+    });
 
-  describe("props", () => {
     it("should toggle checked state", async () => {
-      const tree = await factory.createTestCaseTree();
       const item = tree.item("x111");
-
-      item.getCheckboxProps().onChange();
+      await item.toggleCheckedState();
       expect(tree.instance.getState().checkedItems).toContain("x111");
-
-      item.getCheckboxProps().onChange();
+      await item.toggleCheckedState();
       expect(tree.instance.getState().checkedItems).not.toContain("x111");
     });
 
-    it("should return checked state in props", async () => {
-      const tree = await factory.createTestCaseTree();
-      tree.item("x111").setChecked();
-      expect(tree.item("x111").getCheckboxProps().checked).toBe(true);
-      expect(tree.item("x112").getCheckboxProps().checked).toBe(false);
+    describe("props", () => {
+      it("should toggle checked state", async () => {
+        const item = tree.item("x111");
+        item.getCheckboxProps().onChange();
+        expect(tree.instance.getState().checkedItems).toContain("x111");
+        item.getCheckboxProps().onChange();
+        expect(tree.instance.getState().checkedItems).not.toContain("x111");
+      });
+
+      it("should return checked state in props", async () => {
+        tree.item("x111").setChecked();
+        expect(tree.item("x111").getCheckboxProps().checked).toBe(true);
+        expect(tree.item("x112").getCheckboxProps().checked).toBe(false);
+      });
+
+      it("should create indeterminate state", async () => {
+        await tree.item("x111").setChecked();
+        const refObject = { indeterminate: undefined };
+        tree.item("x11").getCheckboxProps().ref(refObject);
+        expect(refObject.indeterminate).toBe(true);
+      });
+
+      it("should not create indeterminate state", async () => {
+        const refObject = { indeterminate: undefined };
+        tree.item("x11").getCheckboxProps().ref(refObject);
+        expect(refObject.indeterminate).toBe(false);
+      });
     });
 
-    it("should create indeterminate state", async () => {
-      const tree = await factory.createTestCaseTree();
-      tree.item("x111").setChecked();
-      const refObject = { indeterminate: undefined };
-      tree.item("x11").getCheckboxProps().ref(refObject);
-      expect(refObject.indeterminate).toBe(true);
+    it("should handle folder checking", async () => {
+      const testTree = await tree
+        .with({ canCheckFolders: true, propagateCheckedState: false })
+        .createTestCaseTree();
+      testTree.item("x11").setChecked();
+      expect(testTree.instance.getState().checkedItems).toContain("x11");
     });
 
-    it("should not create indeterminate state", async () => {
-      const tree = await factory.createTestCaseTree();
-      const refObject = { indeterminate: undefined };
-      tree.item("x11").getCheckboxProps().ref(refObject);
-      expect(refObject.indeterminate).toBe(false);
+    it("should not check folders if disabled", async () => {
+      const testTree = await tree
+        .with({ canCheckFolders: false, propagateCheckedState: false })
+        .createTestCaseTree();
+      testTree.item("x11").setChecked();
+      expect(testTree.instance.getState().checkedItems.length).toBe(0);
     });
-  });
-
-  it("should handle folder checking", async () => {
-    const tree = await factory
-      .with({ canCheckFolders: true, propagateCheckedState: false })
-      .createTestCaseTree();
-
-    tree.item("x11").setChecked();
-    expect(tree.instance.getState().checkedItems).toContain("x11");
-  });
 
-  it("should not check folders if disabled", async () => {
-    const tree = await factory
-      .with({ canCheckFolders: false, propagateCheckedState: false })
-      .createTestCaseTree();
-
-    tree.item("x11").setChecked();
-    expect(tree.instance.getState().checkedItems.length).toBe(0);
-  });
-
-  it("should propagate checked state", async () => {
-    const tree = await factory
-      .with({ propagateCheckedState: true })
-      .createTestCaseTree();
-
-    tree.item("x11").setChecked();
-    expect(tree.instance.getState().checkedItems).toEqual(
-      expect.arrayContaining(["x111", "x112", "x113", "x114"]),
-    );
-  });
-
-  it("should turn folder indeterminate", async () => {
-    const tree = await factory
-      .with({ propagateCheckedState: true })
-      .createTestCaseTree();
-
-    tree.item("x111").setChecked();
-    expect(tree.item("x11").getCheckedState()).toBe(CheckedState.Indeterminate);
-  });
-
-  it("should turn folder checked if all children are checked", async () => {
-    const tree = await factory
-      .with({
-        isItemFolder: (item) => item.getItemData().length < 4,
-        propagateCheckedState: true,
-        canCheckFolders: false,
-      })
-      .createTestCaseTree();
-
-    tree.item("x11").setChecked();
-    tree.item("x12").setChecked();
-    tree.item("x13").setChecked();
-    expect(tree.item("x1").getCheckedState()).toBe(CheckedState.Indeterminate);
-    tree.do.selectItem("x14");
-    tree.item("x141").setChecked();
-    tree.item("x142").setChecked();
-    tree.item("x143").setChecked();
-    expect(tree.item("x1").getCheckedState()).toBe(CheckedState.Indeterminate);
-    tree.item("x144").setChecked();
-    expect(tree.item("x1").getCheckedState()).toBe(CheckedState.Checked);
-  });
-
-  it("should return correct checked state for items", async () => {
-    const tree = await factory.createTestCaseTree();
-    const item = tree.instance.getItemInstance("x111");
+    it("should propagate checked state", async () => {
+      const testTree = await tree
+        .with({ propagateCheckedState: true })
+        .createTestCaseTree();
+      await testTree.item("x11").setChecked();
+      expect(testTree.instance.getState().checkedItems).toEqual(
+        expect.arrayContaining(["x111", "x112", "x113", "x114"]),
+      );
+    });
 
-    expect(item.getCheckedState()).toBe(CheckedState.Unchecked);
+    it("should turn folder indeterminate", async () => {
+      const testTree = await tree
+        .with({ propagateCheckedState: true })
+        .createTestCaseTree();
+      testTree.item("x111").setChecked();
+      expect(testTree.item("x11").getCheckedState()).toBe(
+        CheckedState.Indeterminate,
+      );
+    });
 
-    item.setChecked();
-    expect(item.getCheckedState()).toBe(CheckedState.Checked);
+    it("should turn folder checked if all children are checked", async () => {
+      const testTree = await tree
+        .with({
+          isItemFolder: (item: any) => item.getItemData().length < 4,
+          propagateCheckedState: true,
+          canCheckFolders: false,
+        })
+        .createTestCaseTree();
+      testTree.do.selectItem("x14"); // all leafs must be loaded initially, checkpropagation check only respects visibly loaded items
+      // TODO ^ might be a restriction we want to avoid
+      await testTree.resolveAsyncVisibleItems();
+      await testTree.runWhileResolvingItems(testTree.item("x11").setChecked);
+      await testTree.runWhileResolvingItems(testTree.item("x12").setChecked);
+      await testTree.runWhileResolvingItems(testTree.item("x13").setChecked);
+      expect(testTree.item("x1").getCheckedState()).toBe(
+        CheckedState.Indeterminate,
+      );
+      await testTree.runWhileResolvingItems(testTree.item("x141").setChecked);
+      await testTree.runWhileResolvingItems(testTree.item("x142").setChecked);
+      await testTree.runWhileResolvingItems(testTree.item("x143").setChecked);
+      expect(testTree.item("x1").getCheckedState()).toBe(
+        CheckedState.Indeterminate,
+      );
+      await testTree.runWhileResolvingItems(testTree.item("x144").setChecked);
+      expect(testTree.item("x1").getCheckedState()).toBe(CheckedState.Checked);
+    });
 
-    item.setUnchecked();
-    expect(item.getCheckedState()).toBe(CheckedState.Unchecked);
+    it("should return correct checked state for items", async () => {
+      const item = tree.instance.getItemInstance("x111");
+      expect(item.getCheckedState()).toBe(CheckedState.Unchecked);
+      item.setChecked();
+      expect(item.getCheckedState()).toBe(CheckedState.Checked);
+      item.setUnchecked();
+      expect(item.getCheckedState()).toBe(CheckedState.Unchecked);
+    });
   });
 });

package/src/features/checkboxes/feature.ts

@@ -1,7 +1,6 @@
-import { FeatureImplementation, TreeInstance } from "../../types/core";
+import { type FeatureImplementation, TreeInstance } from "../../types/core";
 import { makeStateUpdater } from "../../utils";
 import { CheckedState } from "./types";
-import { throwError } from "../../utilities/errors";
 
 const getAllLoadedDescendants = <T>(
   tree: TreeInstance<T>,
@@ -12,12 +11,50 @@ const getAllLoadedDescendants = <T>(
     return [itemId];
   }
   const descendants = tree
-    .retrieveChildrenIds(itemId)
+    .retrieveChildrenIds(itemId, true)
     .map((child) => getAllLoadedDescendants(tree, child, includeFolders))
     .flat();
   return includeFolders ? [itemId, ...descendants] : descendants;
 };
 
+const getAllDescendants = async <T>(
+  tree: TreeInstance<T>,
+  itemId: string,
+  includeFolders = false,
+): Promise<string[]> => {
+  await tree.loadItemData(itemId);
+  if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
+    return [itemId];
+  }
+  const childrenIds = await tree.loadChildrenIds(itemId);
+  const descendants = (
+    await Promise.all(
+      childrenIds.map((child) =>
+        getAllDescendants(tree, child, includeFolders),
+      ),
+    )
+  ).flat();
+  return includeFolders ? [itemId, ...descendants] : descendants;
+};
+
+const withLoadingState = async <T>(
+  tree: TreeInstance<T>,
+  itemId: string,
+  callback: () => Promise<void>,
+) => {
+  tree.applySubStateUpdate("loadingCheckPropagationItems", (items) => [
+    ...items,
+    itemId,
+  ]);
+  try {
+    await callback();
+  } finally {
+    tree.applySubStateUpdate("loadingCheckPropagationItems", (items) =>
+      items.filter((id) => id !== itemId),
+    );
+  }
+};
+
 export const checkboxesFeature: FeatureImplementation = {
   key: "checkboxes",
 
@@ -25,22 +62,20 @@ export const checkboxesFeature: FeatureImplementation = {
 
   getInitialState: (initialState) => ({
     checkedItems: [],
+    loadingCheckPropagationItems: [],
     ...initialState,
   }),
 
   getDefaultConfig: (defaultConfig, tree) => {
-    const hasAsyncLoader = defaultConfig.features?.some(
-      (f) => f.key === "async-data-loader",
-    );
-    if (hasAsyncLoader && defaultConfig.propagateCheckedState) {
-      throwError(`propagateCheckedState not supported with async trees`);
-    }
-    const propagateCheckedState =
-      defaultConfig.propagateCheckedState ?? !hasAsyncLoader;
+    const propagateCheckedState = defaultConfig.propagateCheckedState ?? true;
     const canCheckFolders =
       defaultConfig.canCheckFolders ?? !propagateCheckedState;
     return {
       setCheckedItems: makeStateUpdater("checkedItems", tree),
+      setLoadingCheckPropagationItems: makeStateUpdater(
+        "loadingCheckPropagationItems",
+        tree,
+      ),
       propagateCheckedState,
       canCheckFolders,
       ...defaultConfig,
@@ -49,6 +84,7 @@ export const checkboxesFeature: FeatureImplementation = {
 
   stateHandlerNames: {
     checkedItems: "setCheckedItems",
+    loadingCheckPropagationItems: "setLoadingCheckPropagationItems",
   },
 
   treeInstance: {
@@ -71,11 +107,11 @@ export const checkboxesFeature: FeatureImplementation = {
       };
     },
 
-    toggleCheckedState: ({ item }) => {
+    toggleCheckedState: async ({ item }) => {
       if (item.getCheckedState() === CheckedState.Checked) {
-        item.setUnchecked();
+        await item.setUnchecked();
       } else {
-        item.setChecked();
+        await item.setChecked();
       }
     },
 
@@ -90,6 +126,7 @@ export const checkboxesFeature: FeatureImplementation = {
 
       if (item.isFolder() && propagateCheckedState) {
         const descendants = getAllLoadedDescendants(tree, itemId);
+        if (descendants.length === 0) return CheckedState.Unchecked;
         if (descendants.every((d) => checkedItems.includes(d))) {
           return CheckedState.Checked;
         }
@@ -101,34 +138,46 @@ export const checkboxesFeature: FeatureImplementation = {
       return CheckedState.Unchecked;
     },
 
-    setChecked: ({ item, tree, itemId }) => {
-      const { propagateCheckedState, canCheckFolders } = tree.getConfig();
-      if (item.isFolder() && propagateCheckedState) {
-        tree.applySubStateUpdate("checkedItems", (items) => [
-          ...items,
-          ...getAllLoadedDescendants(tree, itemId, canCheckFolders),
-        ]);
-      } else if (!item.isFolder() || canCheckFolders) {
-        tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
-      }
+    setChecked: async ({ item, tree, itemId }) => {
+      await withLoadingState(tree, itemId, async () => {
+        const { propagateCheckedState, canCheckFolders } = tree.getConfig();
+        if (item.isFolder() && propagateCheckedState) {
+          const descendants = await getAllDescendants(
+            tree,
+            itemId,
+            canCheckFolders,
+          );
+          tree.applySubStateUpdate("checkedItems", (items) => [
+            ...items,
+            ...descendants,
+          ]);
+        } else if (!item.isFolder() || canCheckFolders) {
+          tree.applySubStateUpdate("checkedItems", (items) => [
+            ...items,
+            itemId,
+          ]);
+        }
+      });
     },
 
-    setUnchecked: ({ item, tree, itemId }) => {
-      const { propagateCheckedState, canCheckFolders } = tree.getConfig();
-      if (item.isFolder() && propagateCheckedState) {
-        const descendants = getAllLoadedDescendants(
-          tree,
-          itemId,
-          canCheckFolders,
-        );
-        tree.applySubStateUpdate("checkedItems", (items) =>
-          items.filter((id) => !descendants.includes(id) && id !== itemId),
-        );
-      } else {
-        tree.applySubStateUpdate("checkedItems", (items) =>
-          items.filter((id) => id !== itemId),
-        );
-      }
+    setUnchecked: async ({ item, tree, itemId }) => {
+      await withLoadingState(tree, itemId, async () => {
+        const { propagateCheckedState, canCheckFolders } = tree.getConfig();
+        if (item.isFolder() && propagateCheckedState) {
+          const descendants = await getAllDescendants(
+            tree,
+            itemId,
+            canCheckFolders,
+          );
+          tree.applySubStateUpdate("checkedItems", (items) =>
+            items.filter((id) => !descendants.includes(id) && id !== itemId),
+          );
+        } else {
+          tree.applySubStateUpdate("checkedItems", (items) =>
+            items.filter((id) => id !== itemId),
+          );
+        }
+      });
     },
   },
 };

package/src/features/checkboxes/types.ts

@@ -9,9 +9,11 @@ export enum CheckedState {
 export type CheckboxesFeatureDef<T> = {
   state: {
     checkedItems: string[];
+    loadingCheckPropagationItems: string[];
   };
   config: {
     setCheckedItems?: SetStateFn<string[]>;
+    setLoadingCheckPropagationItems?: SetStateFn<string[]>;
     canCheckFolders?: boolean;
     propagateCheckedState?: boolean;
   };
@@ -19,11 +21,22 @@ export type CheckboxesFeatureDef<T> = {
     setCheckedItems: (checkedItems: string[]) => void;
   };
   itemInstance: {
-    setChecked: () => void;
-    setUnchecked: () => void;
-    toggleCheckedState: () => void;
+    /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+     * this will return immediately. */
+    setChecked: () => Promise<void>;
+
+    /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+     * this will return immediately. */
+    setUnchecked: () => Promise<void>;
+
+    /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+     * this will return immediately. */
+    toggleCheckedState: () => Promise<void>;
+
     getCheckedState: () => CheckedState;
     getCheckboxProps: () => Record<string, any>;
+
+    isLoadingCheckPropagation: () => boolean;
   };
   hotkeys: never;
 };

package/src/test-utils/test-tree.ts

@@ -101,6 +101,17 @@ export class TestTree<T = string> {
     await TestTree.resolveAsyncLoaders();
   }
 
+  async runWhileResolvingItems(cb: () => Promise<void>) {
+    const interval = setInterval(() => {
+      TestTree.resolveAsyncLoaders();
+    }, 5);
+    try {
+      await cb();
+    } finally {
+      clearInterval(interval);
+    }
+  }
+
   static default(config: Partial<TreeConfig<string>>) {
     return new TestTree({
       rootItemId: "x",