@headless-tree/core 1.2.0 → 1.3.0

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "@headless-tree/core",
-  "version": "1.2.0",
-  "main": "lib/cjs/index.js",
-  "module": "lib/esm/index.js",
-  "types": "lib/esm/index.d.ts",
+  "version": "1.3.0",
+  "main": "dist/index.d.ts",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
   "exports": {
-    "types": "./lib/esm/index.d.ts",
-    "import": "./lib/esm/index.js",
-    "default": "./lib/cjs/index.js"
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.js",
+        "default": "./dist/index.d.ts"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "sideEffects": false,
   "scripts": {
-    "build:cjs": "tsc -m commonjs --outDir lib/cjs",
-    "build:esm": "tsc",
-    "start": "tsc -w",
+    "build": "tsup ./src/index.ts --format esm,cjs --dts",
+    "start": "tsup ./src/index.ts --format esm,cjs --dts --watch",
     "test": "vitest run"
   },
   "repository": {
@@ -26,6 +33,7 @@
   "license": "MIT",
   "devDependencies": {
     "jsdom": "^26.0.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.7.2",
     "vitest": "^3.0.3"
   }

package/src/core/create-tree.ts

@@ -193,7 +193,23 @@ export const createTree = <T>(
           config.setState?.(state);
         }
       },
-      getItemInstance: ({}, itemId) => itemInstancesMap[itemId],
+      getItemInstance: ({}, itemId) => {
+        const existingInstance = itemInstancesMap[itemId];
+        if (!existingInstance) {
+          const [instance, finalizeInstance] = buildInstance(
+            features,
+            "itemInstance",
+            (instance) => ({
+              item: instance,
+              tree: treeInstance,
+              itemId,
+            }),
+          );
+          finalizeInstance();
+          return instance;
+        }
+        return existingInstance;
+      },
       getItems: () => itemInstances,
       registerElement: ({}, element) => {
         if (treeElement === element) {
@@ -236,7 +252,15 @@ export const createTree = <T>(
       getElement: ({ itemId }) => itemElementsMap[itemId],
       // eslint-disable-next-line no-return-assign
       getDataRef: ({ itemId }) => (itemDataRefs[itemId] ??= { current: {} }),
-      getItemMeta: ({ itemId }) => itemMetaMap[itemId],
+      getItemMeta: ({ itemId }) =>
+        itemMetaMap[itemId] ?? {
+          itemId,
+          parentId: null,
+          level: -1,
+          index: -1,
+          posInSet: 0,
+          setSize: 1,
+        },
     },
   };
 

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

@@ -95,7 +95,7 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
       );
     },
 
-    retrieveItemData: ({ tree }, itemId) => {
+    retrieveItemData: ({ tree }, itemId, skipFetch = false) => {
       const config = tree.getConfig();
       const dataRef = getDataRef(tree);
 
@@ -103,7 +103,7 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
         return dataRef.current.itemData[itemId];
       }
 
-      if (!tree.getState().loadingItemData.includes(itemId)) {
+      if (!tree.getState().loadingItemData.includes(itemId) && !skipFetch) {
         tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
           ...loadingItemData,
           itemId,
@@ -115,13 +115,13 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
       return config.createLoadingItemData?.() ?? null;
     },
 
-    retrieveChildrenIds: ({ tree }, itemId) => {
+    retrieveChildrenIds: ({ tree }, itemId, skipFetch = false) => {
       const dataRef = getDataRef(tree);
       if (dataRef.current.childrenIds[itemId]) {
         return dataRef.current.childrenIds[itemId];
       }
 
-      if (tree.getState().loadingItemChildrens.includes(itemId)) {
+      if (tree.getState().loadingItemChildrens.includes(itemId) || skipFetch) {
         return [];
       }
 
@@ -165,5 +165,10 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
       dataRef.current.childrenIds[itemId] = childrenIds;
       tree.rebuildTree();
     },
+    updateCachedData: ({ tree, itemId }, data) => {
+      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
+      dataRef.current.itemData[itemId] = data;
+      tree.rebuildTree();
+    },
   },
 };

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

@@ -34,6 +34,7 @@ export type AsyncDataLoaderFeatureDef<T> = {
     waitForItemChildrenLoaded: (itemId: string) => Promise<void>;
     loadItemData: (itemId: string) => Promise<T>;
     loadChildrenIds: (itemId: string) => Promise<string[]>;
+    /* idea: recursiveLoadItems: (itemId: string, cancelToken?: { current: boolean }, onLoad: (itemIds: string[]) => void) => Promise<T[]> */
   };
   itemInstance: SyncDataLoaderFeatureDef<T>["itemInstance"] & {
     /** Invalidate fetched data for item, and triggers a refetch and subsequent rerender if the item is visible
@@ -46,6 +47,7 @@ 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;
     updateCachedChildrenIds: (childrenIds: string[]) => void;
     isLoading: () => boolean;
   };

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

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+import { TestTree } from "../../test-utils/test-tree";
+import { checkboxesFeature } from "./feature";
+import { CheckedState } from "./types";
+
+const factory = TestTree.default({})
+  .withFeatures(checkboxesFeature)
+  .suits.sync().tree;
+
+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");
+
+    item.toggleCheckedState();
+    expect(tree.instance.getState().checkedItems).toContain("x111");
+
+    item.toggleCheckedState();
+    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();
+      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 () => {
+      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);
+    });
+
+    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 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 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");
+
+    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

@@ -0,0 +1,134 @@
+import { FeatureImplementation, TreeInstance } from "../../types/core";
+import { makeStateUpdater } from "../../utils";
+import { CheckedState } from "./types";
+import { throwError } from "../../utilities/errors";
+
+const getAllLoadedDescendants = <T>(
+  tree: TreeInstance<T>,
+  itemId: string,
+  includeFolders = false,
+): string[] => {
+  if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
+    return [itemId];
+  }
+  const descendants = tree
+    .retrieveChildrenIds(itemId)
+    .map((child) => getAllLoadedDescendants(tree, child, includeFolders))
+    .flat();
+  return includeFolders ? [itemId, ...descendants] : descendants;
+};
+
+export const checkboxesFeature: FeatureImplementation = {
+  key: "checkboxes",
+
+  overwrites: ["selection"],
+
+  getInitialState: (initialState) => ({
+    checkedItems: [],
+    ...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 canCheckFolders =
+      defaultConfig.canCheckFolders ?? !propagateCheckedState;
+    return {
+      setCheckedItems: makeStateUpdater("checkedItems", tree),
+      propagateCheckedState,
+      canCheckFolders,
+      ...defaultConfig,
+    };
+  },
+
+  stateHandlerNames: {
+    checkedItems: "setCheckedItems",
+  },
+
+  treeInstance: {
+    setCheckedItems: ({ tree }, checkedItems) => {
+      tree.applySubStateUpdate("checkedItems", checkedItems);
+    },
+  },
+
+  itemInstance: {
+    getCheckboxProps: ({ item }) => {
+      const checkedState = item.getCheckedState();
+      return {
+        onChange: item.toggleCheckedState,
+        checked: checkedState === CheckedState.Checked,
+        ref: (r: any) => {
+          if (r) {
+            r.indeterminate = checkedState === CheckedState.Indeterminate;
+          }
+        },
+      };
+    },
+
+    toggleCheckedState: ({ item }) => {
+      if (item.getCheckedState() === CheckedState.Checked) {
+        item.setUnchecked();
+      } else {
+        item.setChecked();
+      }
+    },
+
+    getCheckedState: ({ item, tree }) => {
+      const { checkedItems } = tree.getState();
+      const { propagateCheckedState } = tree.getConfig();
+      const itemId = item.getId();
+
+      if (checkedItems.includes(itemId)) {
+        return CheckedState.Checked;
+      }
+
+      if (item.isFolder() && propagateCheckedState) {
+        const descendants = getAllLoadedDescendants(tree, itemId);
+        if (descendants.every((d) => checkedItems.includes(d))) {
+          return CheckedState.Checked;
+        }
+        if (descendants.some((d) => checkedItems.includes(d))) {
+          return CheckedState.Indeterminate;
+        }
+      }
+
+      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]);
+      }
+    },
+
+    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),
+        );
+      }
+    },
+  },
+};

package/src/features/checkboxes/types.ts

@@ -0,0 +1,29 @@
+import { SetStateFn } from "../../types/core";
+
+export enum CheckedState {
+  Checked = "checked",
+  Unchecked = "unchecked",
+  Indeterminate = "indeterminate",
+}
+
+export type CheckboxesFeatureDef<T> = {
+  state: {
+    checkedItems: string[];
+  };
+  config: {
+    setCheckedItems?: SetStateFn<string[]>;
+    canCheckFolders?: boolean;
+    propagateCheckedState?: boolean;
+  };
+  treeInstance: {
+    setCheckedItems: (checkedItems: string[]) => void;
+  };
+  itemInstance: {
+    setChecked: () => void;
+    setUnchecked: () => void;
+    toggleCheckedState: () => void;
+    getCheckedState: () => CheckedState;
+    getCheckboxProps: () => Record<string, any>;
+  };
+  hotkeys: never;
+};

package/src/features/drag-and-drop/drag-and-drop.spec.ts

@@ -182,7 +182,7 @@ describe("core-feature/drag-and-drop", () => {
         });
       });
 
-      it("updates dnd state", () => {
+      it("updates dnd state", async () => {
         const setDndState = tree.mockedHandler("setDndState");
         tree.do.startDrag("x111");
         expect(setDndState).toBeCalledWith({
@@ -198,7 +198,7 @@ describe("core-feature/drag-and-drop", () => {
           },
         });
         tree.do.drop("x22");
-        expect(setDndState).toBeCalledWith(null);
+        await vi.waitFor(() => expect(setDndState).toBeCalledWith(null));
       });
     });
 
@@ -300,6 +300,9 @@ describe("core-feature/drag-and-drop", () => {
 
       it("drags foreign object inside tree, on folder", () => {
         tree.mockedHandler("canDropForeignDragObject").mockReturnValue(true);
+        tree
+          .mockedHandler("canDragForeignDragObjectOver")
+          .mockReturnValue(true);
         const onDropForeignDragObject = tree.mockedHandler(
           "onDropForeignDragObject",
         );
@@ -318,6 +321,9 @@ describe("core-feature/drag-and-drop", () => {
         tree
           .mockedHandler("canDropForeignDragObject")
           .mockImplementation((_, target) => target.item.isFolder());
+        tree
+          .mockedHandler("canDragForeignDragObjectOver")
+          .mockImplementation((_, target) => target.item.isFolder());
         const onDropForeignDragObject = tree.mockedHandler(
           "onDropForeignDragObject",
         );
@@ -340,6 +346,9 @@ describe("core-feature/drag-and-drop", () => {
 
       it("doesnt drag foreign object inside tree if not allowed", () => {
         tree.mockedHandler("canDropForeignDragObject").mockReturnValue(false);
+        tree
+          .mockedHandler("canDragForeignDragObjectOver")
+          .mockReturnValue(false);
         const onDropForeignDragObject = tree.mockedHandler(
           "onDropForeignDragObject",
         );