@headless-tree/core 1.3.0 → 1.5.0

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,12 +118,7 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
       }
 
       if (!tree.getState().loadingItemData.includes(itemId) && !skipFetch) {
-        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
-          ...loadingItemData,
-          itemId,
-        ]);
-
-        loadItemData(tree, itemId);
+        setTimeout(() => loadItemData(tree, itemId));
       }
 
       return config.createLoadingItemData?.() ?? null;
@@ -125,12 +134,7 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
         return [];
       }
 
-      tree.applySubStateUpdate(
-        "loadingItemChildrens",
-        (loadingItemChildrens) => [...loadingItemChildrens, itemId],
-      );
-
-      loadChildrenIds(tree, itemId);
+      setTimeout(() => 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;
 };