@headless-tree/core 1.2.1 → 1.4.0

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "@headless-tree/core",
-  "version": "1.2.1",
-  "main": "lib/cjs/index.js",
-  "module": "lib/esm/index.js",
-  "types": "lib/esm/index.d.ts",
+  "version": "1.4.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

@@ -170,19 +170,6 @@ export const createTree = <T>(
         ] as Function;
         externalStateSetter?.(state[stateName]);
       },
-      buildItemInstance: ({}, itemId) => {
-        const [instance, finalizeInstance] = buildInstance(
-          features,
-          "itemInstance",
-          (instance) => ({
-            item: instance,
-            tree: treeInstance,
-            itemId,
-          }),
-        );
-        finalizeInstance();
-        return instance;
-      },
       // TODO rebuildSubTree: (itemId: string) => void;
       rebuildTree: () => {
         rebuildItemMeta();
@@ -206,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) {
@@ -249,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

@@ -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

@@ -74,17 +74,28 @@ describe("core-feature/checkboxes", () => {
     });
   });
 
-  it("should handle folder checking when canCheckFolders is true", async () => {
+  it("should handle folder checking", async () => {
     const tree = await factory
-      .with({ canCheckFolders: true })
+      .with({ canCheckFolders: true, propagateCheckedState: false })
       .createTestCaseTree();
 
     tree.item("x11").setChecked();
     expect(tree.instance.getState().checkedItems).toContain("x11");
   });
 
-  it("should handle folder checking when canCheckFolders is false", async () => {
-    const tree = await factory.createTestCaseTree();
+  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(
@@ -93,7 +104,9 @@ describe("core-feature/checkboxes", () => {
   });
 
   it("should turn folder indeterminate", async () => {
-    const tree = await factory.createTestCaseTree();
+    const tree = await factory
+      .with({ propagateCheckedState: true })
+      .createTestCaseTree();
 
     tree.item("x111").setChecked();
     expect(tree.item("x11").getCheckedState()).toBe(CheckedState.Indeterminate);
@@ -103,6 +116,8 @@ describe("core-feature/checkboxes", () => {
     const tree = await factory
       .with({
         isItemFolder: (item) => item.getItemData().length < 4,
+        propagateCheckedState: true,
+        canCheckFolders: false,
       })
       .createTestCaseTree();
 

package/src/features/checkboxes/feature.ts

@@ -6,14 +6,16 @@ import { throwError } from "../../utilities/errors";
 const getAllLoadedDescendants = <T>(
   tree: TreeInstance<T>,
   itemId: string,
+  includeFolders = false,
 ): string[] => {
-  if (!tree.getConfig().isItemFolder(tree.buildItemInstance(itemId))) {
+  if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
     return [itemId];
   }
-  return tree
+  const descendants = tree
     .retrieveChildrenIds(itemId)
-    .map((child) => getAllLoadedDescendants(tree, child))
+    .map((child) => getAllLoadedDescendants(tree, child, includeFolders))
     .flat();
+  return includeFolders ? [itemId, ...descendants] : descendants;
 };
 
 export const checkboxesFeature: FeatureImplementation = {
@@ -30,12 +32,17 @@ export const checkboxesFeature: FeatureImplementation = {
     const hasAsyncLoader = defaultConfig.features?.some(
       (f) => f.key === "async-data-loader",
     );
-    if (hasAsyncLoader && !defaultConfig.canCheckFolders) {
-      throwError(`!canCheckFolders not supported with async trees`);
+    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),
-      canCheckFolders: hasAsyncLoader ?? false,
+      propagateCheckedState,
+      canCheckFolders,
       ...defaultConfig,
     };
   },
@@ -72,14 +79,16 @@ export const checkboxesFeature: FeatureImplementation = {
       }
     },
 
-    getCheckedState: ({ item, tree, itemId }) => {
+    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() && !tree.getConfig().canCheckFolders) {
+      if (item.isFolder() && propagateCheckedState) {
         const descendants = getAllLoadedDescendants(tree, itemId);
         if (descendants.every((d) => checkedItems.includes(d))) {
           return CheckedState.Checked;
@@ -93,25 +102,31 @@ export const checkboxesFeature: FeatureImplementation = {
     },
 
     setChecked: ({ item, tree, itemId }) => {
-      if (!item.isFolder() || tree.getConfig().canCheckFolders) {
-        tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
-      } else {
+      const { propagateCheckedState, canCheckFolders } = tree.getConfig();
+      if (item.isFolder() && propagateCheckedState) {
         tree.applySubStateUpdate("checkedItems", (items) => [
           ...items,
-          ...getAllLoadedDescendants(tree, itemId),
+          ...getAllLoadedDescendants(tree, itemId, canCheckFolders),
         ]);
+      } else if (!item.isFolder() || canCheckFolders) {
+        tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
       }
     },
 
     setUnchecked: ({ item, tree, itemId }) => {
-      if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+      const { propagateCheckedState, canCheckFolders } = tree.getConfig();
+      if (item.isFolder() && propagateCheckedState) {
+        const descendants = getAllLoadedDescendants(
+          tree,
+          itemId,
+          canCheckFolders,
+        );
         tree.applySubStateUpdate("checkedItems", (items) =>
-          items.filter((id) => id !== itemId),
+          items.filter((id) => !descendants.includes(id) && id !== itemId),
         );
       } else {
-        const descendants = getAllLoadedDescendants(tree, itemId);
         tree.applySubStateUpdate("checkedItems", (items) =>
-          items.filter((id) => !descendants.includes(id)),
+          items.filter((id) => id !== itemId),
         );
       }
     },

package/src/features/checkboxes/types.ts

@@ -13,6 +13,7 @@ export type CheckboxesFeatureDef<T> = {
   config: {
     setCheckedItems?: SetStateFn<string[]>;
     canCheckFolders?: boolean;
+    propagateCheckedState?: boolean;
   };
   treeInstance: {
     setCheckedItems: (checkedItems: string[]) => void;

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",
         );

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

@@ -1,22 +1,62 @@
-import { FeatureImplementation } from "../../types/core";
+import {
+  FeatureImplementation,
+  type ItemInstance,
+  type TreeInstance,
+} from "../../types/core";
 import { DndDataRef, DragLineData, DragTarget } from "./types";
 import {
+  PlacementType,
+  type TargetPlacement,
   canDrop,
   getDragCode,
   getDragTarget,
+  getTargetPlacement,
   isOrderedDragTarget,
 } from "./utils";
 import { makeStateUpdater } from "../../utils";
 
+const handleAutoOpenFolder = (
+  dataRef: { current: DndDataRef },
+  tree: TreeInstance<any>,
+  item: ItemInstance<any>,
+  placement: TargetPlacement,
+) => {
+  const { openOnDropDelay } = tree.getConfig();
+  const dragCode = dataRef.current.lastDragCode;
+
+  if (
+    !openOnDropDelay ||
+    !item.isFolder() ||
+    item.isExpanded() ||
+    placement.type !== PlacementType.MakeChild
+  ) {
+    return;
+  }
+  clearTimeout(dataRef.current.autoExpandTimeout);
+  dataRef.current.autoExpandTimeout = setTimeout(() => {
+    if (
+      dragCode !== dataRef.current.lastDragCode ||
+      !dataRef.current.lastAllowDrop
+    )
+      return;
+    item.expand();
+  }, openOnDropDelay);
+};
+
+const defaultCanDropForeignDragObject = () => false;
 export const dragAndDropFeature: FeatureImplementation = {
   key: "drag-and-drop",
-  deps: ["selection"],
 
   getDefaultConfig: (defaultConfig, tree) => ({
     canDrop: (_, target) => target.item.isFolder(),
-    canDropForeignDragObject: () => false,
+    canDropForeignDragObject: defaultCanDropForeignDragObject,
+    canDragForeignDragObjectOver:
+      defaultConfig.canDropForeignDragObject !== defaultCanDropForeignDragObject
+        ? (dataTransfer) => dataTransfer.effectAllowed !== "none"
+        : () => false,
     setDndState: makeStateUpdater("dnd", tree),
     canReorder: true,
+    openOnDropDelay: 800,
     ...defaultConfig,
   }),
 
@@ -24,6 +64,19 @@ export const dragAndDropFeature: FeatureImplementation = {
     dnd: "setDndState",
   },
 
+  onTreeMount: (tree) => {
+    const listener = () => {
+      tree.applySubStateUpdate("dnd", null);
+    };
+    tree.getDataRef<DndDataRef>().current.windowDragEndListener = listener;
+    window.addEventListener("dragend", listener);
+  },
+  onTreeUnmount: (tree) => {
+    const { windowDragEndListener } = tree.getDataRef<DndDataRef>().current;
+    if (!windowDragEndListener) return;
+    window.removeEventListener("dragend", windowDragEndListener);
+  },
+
   treeInstance: {
     getDragTarget: ({ tree }) => {
       return tree.getState().dnd?.dragTarget ?? null;
@@ -56,7 +109,7 @@ export const dragAndDropFeature: FeatureImplementation = {
         }
       }
 
-      const bb = targetItem.getElement()?.getBoundingClientRect();
+      const bb = targetItem?.getElement()?.getBoundingClientRect();
 
       if (bb) {
         return {
@@ -106,7 +159,6 @@ export const dragAndDropFeature: FeatureImplementation = {
           const draggedItems = tree.getState().dnd?.draggedItems;
 
           dataRef.current.lastDragCode = undefined;
-          tree.applySubStateUpdate("dnd", null);
 
           if (draggedItems) {
             await config.onDrop?.(draggedItems, target);
@@ -132,12 +184,14 @@ export const dragAndDropFeature: FeatureImplementation = {
       onDragEnter: (e: DragEvent) => e.preventDefault(),
 
       onDragStart: (e: DragEvent) => {
-        const selectedItems = tree.getSelectedItems();
+        const selectedItems = tree.getSelectedItems
+          ? tree.getSelectedItems()
+          : [tree.getFocusedItem()];
         const items = selectedItems.includes(item) ? selectedItems : [item];
         const config = tree.getConfig();
 
         if (!selectedItems.includes(item)) {
-          tree.setSelectedItems([item.getItemMeta().itemId]);
+          tree.setSelectedItems?.([item.getItemMeta().itemId]);
         }
 
         if (!(config.canDrag?.(items) ?? true)) {
@@ -150,9 +204,13 @@ export const dragAndDropFeature: FeatureImplementation = {
           e.dataTransfer?.setDragImage(imgElement, xOffset ?? 0, yOffset ?? 0);
         }
 
-        if (config.createForeignDragObject) {
-          const { format, data } = config.createForeignDragObject(items);
-          e.dataTransfer?.setData(format, data);
+        if (config.createForeignDragObject && e.dataTransfer) {
+          const { format, data, dropEffect, effectAllowed } =
+            config.createForeignDragObject(items);
+          e.dataTransfer.setData(format, data);
+
+          if (dropEffect) e.dataTransfer.dropEffect = dropEffect;
+          if (effectAllowed) e.dataTransfer.effectAllowed = effectAllowed;
         }
 
         tree.applySubStateUpdate("dnd", {
@@ -162,8 +220,11 @@ export const dragAndDropFeature: FeatureImplementation = {
       },
 
       onDragOver: (e: DragEvent) => {
+        e.stopPropagation(); // don't bubble up to container dragover
         const dataRef = tree.getDataRef<DndDataRef>();
-        const nextDragCode = getDragCode(e, item, tree);
+        const placement = getTargetPlacement(e, item, tree, true);
+        const nextDragCode = getDragCode(item, placement);
+
         if (nextDragCode === dataRef.current.lastDragCode) {
           if (dataRef.current.lastAllowDrop) {
             e.preventDefault();
@@ -171,6 +232,9 @@ export const dragAndDropFeature: FeatureImplementation = {
           return;
         }
         dataRef.current.lastDragCode = nextDragCode;
+        dataRef.current.lastDragEnter = Date.now();
+
+        handleAutoOpenFolder(dataRef, tree, item, placement);
 
         const target = getDragTarget(e, item, tree);
 
@@ -179,7 +243,7 @@ export const dragAndDropFeature: FeatureImplementation = {
           (!e.dataTransfer ||
             !tree
               .getConfig()
-              .canDropForeignDragObject?.(e.dataTransfer, target))
+              .canDragForeignDragObjectOver?.(e.dataTransfer, target))
         ) {
           dataRef.current.lastAllowDrop = false;
           return;
@@ -200,41 +264,60 @@ export const dragAndDropFeature: FeatureImplementation = {
       },
 
       onDragLeave: () => {
-        const dataRef = tree.getDataRef<DndDataRef>();
-        dataRef.current.lastDragCode = "no-drag";
-        tree.applySubStateUpdate("dnd", (state) => ({
-          ...state,
-          draggingOverItem: undefined,
-          dragTarget: undefined,
-        }));
+        setTimeout(() => {
+          const dataRef = tree.getDataRef<DndDataRef>();
+          if ((dataRef.current.lastDragEnter ?? 0) + 100 >= Date.now()) return;
+          dataRef.current.lastDragCode = "no-drag";
+          tree.applySubStateUpdate("dnd", (state) => ({
+            ...state,
+            draggingOverItem: undefined,
+            dragTarget: undefined,
+          }));
+        }, 100);
       },
 
       onDragEnd: (e: DragEvent) => {
+        const { onCompleteForeignDrop, canDragForeignDragObjectOver } =
+          tree.getConfig();
         const draggedItems = tree.getState().dnd?.draggedItems;
-        tree.applySubStateUpdate("dnd", null);
 
         if (e.dataTransfer?.dropEffect === "none" || !draggedItems) {
           return;
         }
 
-        tree.getConfig().onCompleteForeignDrop?.(draggedItems);
+        const target = getDragTarget(e, item, tree);
+        if (
+          canDragForeignDragObjectOver &&
+          e.dataTransfer &&
+          !canDragForeignDragObjectOver(e.dataTransfer, target)
+        ) {
+          return;
+        }
+
+        onCompleteForeignDrop?.(draggedItems);
       },
 
       onDrop: async (e: DragEvent) => {
         e.stopPropagation();
         const dataRef = tree.getDataRef<DndDataRef>();
         const target = getDragTarget(e, item, tree);
+        const draggedItems = tree.getState().dnd?.draggedItems;
+        const isValidDrop = canDrop(e.dataTransfer, target, tree);
 
-        if (!canDrop(e.dataTransfer, target, tree)) {
+        tree.applySubStateUpdate("dnd", {
+          draggedItems: undefined,
+          draggingOverItem: undefined,
+          dragTarget: undefined,
+        });
+
+        if (!isValidDrop) {
           return;
         }
 
         e.preventDefault();
         const config = tree.getConfig();
-        const draggedItems = tree.getState().dnd?.draggedItems;
 
         dataRef.current.lastDragCode = undefined;
-        tree.applySubStateUpdate("dnd", null);
 
         if (draggedItems) {
           await config.onDrop?.(draggedItems, target);

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

@@ -3,6 +3,9 @@ import { ItemInstance, SetStateFn } from "../../types/core";
 export interface DndDataRef {
   lastDragCode?: string;
   lastAllowDrop?: boolean;
+  lastDragEnter?: number;
+  autoExpandTimeout?: any;
+  windowDragEndListener?: () => void;
 }
 
 export interface DndState<T> {
@@ -57,16 +60,31 @@ export type DragAndDropFeatureDef<T> = {
     createForeignDragObject?: (items: ItemInstance<T>[]) => {
       format: string;
       data: any;
+      dropEffect?: DataTransfer["dropEffect"];
+      effectAllowed?: DataTransfer["effectAllowed"];
     };
     setDragImage?: (items: ItemInstance<T>[]) => {
       imgElement: Element;
       xOffset?: number;
       yOffset?: number;
     };
+
+    /** Checks if a foreign drag object can be dropped on a target, validating that an actual drop can commence based on
+     * the data in the DataTransfer object. */
     canDropForeignDragObject?: (
       dataTransfer: DataTransfer,
       target: DragTarget<T>,
     ) => boolean;
+
+    /** Checks if a droppable visualization should be displayed when dragging a foreign object over a target. Since this
+     * is executed on a dragover event, `dataTransfer.getData()` is not available, so `dataTransfer.effectAllowed` or
+     * `dataTransfer.types` should be used instead. Before actually completing the drag, @{link canDropForeignDragObject}
+     * will be called by HT before applying the drop. */
+    canDragForeignDragObjectOver?: (
+      dataTransfer: DataTransfer,
+      target: DragTarget<T>,
+    ) => boolean;
+
     onDrop?: (
       items: ItemInstance<T>[],
       target: DragTarget<T>,
@@ -76,6 +94,9 @@ export type DragAndDropFeatureDef<T> = {
       target: DragTarget<T>,
     ) => void | Promise<void>;
     onCompleteForeignDrop?: (items: ItemInstance<T>[]) => void;
+
+    /** When dragging for this many ms on a closed folder, the folder will automatically open. Set to zero to disable. */
+    openOnDropDelay?: number;
   };
   treeInstance: {
     getDragTarget: () => DragTarget<T> | null;