@headless-tree/core 0.0.0-20250726131941 → 0.0.0-20250731075124

package/CHANGELOG.md

@@ -1,9 +1,14 @@
 # @headless-tree/core
 
-## 0.0.0-20250726131941
+## 0.0.0-20250731075124
+
+### Minor Changes
+
+- 21d1679: add `canDragForeignDragObjectOver` to allow customizing whether a draggable visualization should be shown when dragging foreign data. This allows differentiating logic between drag-over and drop (via the existing `canDropForeignDataObject`), since for the latter `dataTransfer.getData` is not available by default in browsers.
 
 ### Patch Changes
 
+- e8ddbb0: Added `item.updateCachedData(data)` in async tree feature, that works similar to the existing `item.updateCachedChildrenIds(childrenIds)` feature
 - 662e2a8: Added stories and documentation on how to use nested DOM rendering for tree structures instead of flat lists,
   which can be used for animating expand/collapse behavior
 - b41e1d2: fixed a bug where ending drag without successful drop doesn't properly reset drag line (#132)

package/dist/index.d.mts

@@ -45,13 +45,22 @@ 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>) => void | Promise<void>;
         onDropForeignDragObject?: (dataTransfer: DataTransfer, target: DragTarget<T>) => void | Promise<void>;
         onCompleteForeignDrop?: (items: ItemInstance<T>[]) => void;
@@ -150,8 +159,6 @@ type MainFeatureDef<T = any> = {
     treeInstance: {
         /** @internal */
         applySubStateUpdate: <K extends keyof TreeState<any>>(stateName: K, updater: Updater<TreeState<T>[K]>) => void;
-        /** @internal */
-        buildItemInstance: (itemId: string) => ItemInstance<T>;
         setState: SetStateFn<TreeState<T>>;
         getState: () => TreeState<T>;
         setConfig: SetStateFn<TreeConfig<T>>;
@@ -296,6 +303,7 @@ 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;
         updateCachedChildrenIds: (childrenIds: string[]) => void;
         isLoading: () => boolean;
     };

package/dist/index.d.ts

@@ -45,13 +45,22 @@ 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>) => void | Promise<void>;
         onDropForeignDragObject?: (dataTransfer: DataTransfer, target: DragTarget<T>) => void | Promise<void>;
         onCompleteForeignDrop?: (items: ItemInstance<T>[]) => void;
@@ -150,8 +159,6 @@ type MainFeatureDef<T = any> = {
     treeInstance: {
         /** @internal */
         applySubStateUpdate: <K extends keyof TreeState<any>>(stateName: K, updater: Updater<TreeState<T>[K]>) => void;
-        /** @internal */
-        buildItemInstance: (itemId: string) => ItemInstance<T>;
         setState: SetStateFn<TreeState<T>>;
         getState: () => TreeState<T>;
         setConfig: SetStateFn<TreeConfig<T>>;
@@ -296,6 +303,7 @@ 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;
         updateCachedChildrenIds: (childrenIds: string[]) => void;
         isLoading: () => boolean;
     };

package/dist/index.js

@@ -547,19 +547,6 @@ var createTree = (initialConfig) => {
         const externalStateSetter = config[stateHandlerNames[stateName]];
         externalStateSetter == null ? void 0 : externalStateSetter(state[stateName]);
       },
-      buildItemInstance: ({}, itemId) => {
-        const [instance, finalizeInstance] = buildInstance(
-          features,
-          "itemInstance",
-          (instance2) => ({
-            item: instance2,
-            tree: treeInstance,
-            itemId
-          })
-        );
-        finalizeInstance();
-        return instance;
-      },
       // TODO rebuildSubTree: (itemId: string) => void;
       rebuildTree: () => {
         var _a2;
@@ -580,7 +567,23 @@ var createTree = (initialConfig) => {
           (_c2 = config.setState) == null ? void 0 : _c2.call(config, state);
         }
       },
-      getItemInstance: ({}, itemId) => itemInstancesMap[itemId],
+      getItemInstance: ({}, itemId) => {
+        const existingInstance = itemInstancesMap[itemId];
+        if (!existingInstance) {
+          const [instance, finalizeInstance] = buildInstance(
+            features,
+            "itemInstance",
+            (instance2) => ({
+              item: instance2,
+              tree: treeInstance,
+              itemId
+            })
+          );
+          finalizeInstance();
+          return instance;
+        }
+        return existingInstance;
+      },
       getItems: () => itemInstances,
       registerElement: ({}, element) => {
         if (treeElement === element) {
@@ -636,7 +639,17 @@ var createTree = (initialConfig) => {
         var _a2;
         return (_a2 = itemDataRefs[itemId]) != null ? _a2 : itemDataRefs[itemId] = { current: {} };
       },
-      getItemMeta: ({ itemId }) => itemMetaMap[itemId]
+      getItemMeta: ({ itemId }) => {
+        var _a2;
+        return (_a2 = itemMetaMap[itemId]) != null ? _a2 : {
+          itemId,
+          parentId: null,
+          level: -1,
+          index: -1,
+          posInSet: 0,
+          setSize: 1
+        };
+      }
     }
   };
   features.unshift(mainFeature);
@@ -801,7 +814,7 @@ var selectionFeature = {
 
 // src/features/checkboxes/feature.ts
 var getAllLoadedDescendants = (tree, itemId, includeFolders = false) => {
-  if (!tree.getConfig().isItemFolder(tree.buildItemInstance(itemId))) {
+  if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
     return [itemId];
   }
   const descendants = tree.retrieveChildrenIds(itemId).map((child) => getAllLoadedDescendants(tree, child, includeFolders)).flat();
@@ -1147,6 +1160,11 @@ var asyncDataLoaderFeature = {
       const dataRef = tree.getDataRef();
       dataRef.current.childrenIds[itemId] = childrenIds;
       tree.rebuildTree();
+    },
+    updateCachedData: ({ tree, itemId }, data) => {
+      const dataRef = tree.getDataRef();
+      dataRef.current.itemData[itemId] = data;
+      tree.rebuildTree();
     }
   }
 };
@@ -1354,12 +1372,14 @@ var getDragTarget = (e, item, tree, canReorder = tree.getConfig().canReorder) =>
 };
 
 // src/features/drag-and-drop/feature.ts
+var defaultCanDropForeignDragObject = () => false;
 var dragAndDropFeature = {
   key: "drag-and-drop",
   deps: ["selection"],
   getDefaultConfig: (defaultConfig, tree) => __spreadValues({
     canDrop: (_, target) => target.item.isFolder(),
-    canDropForeignDragObject: () => false,
+    canDropForeignDragObject: defaultCanDropForeignDragObject,
+    canDragForeignDragObjectOver: defaultConfig.canDropForeignDragObject !== defaultCanDropForeignDragObject ? (dataTransfer) => dataTransfer.effectAllowed !== "none" : () => false,
     setDndState: makeStateUpdater("dnd", tree),
     canReorder: true
   }, defaultConfig),
@@ -1458,7 +1478,7 @@ var dragAndDropFeature = {
       draggable: true,
       onDragEnter: (e) => e.preventDefault(),
       onDragStart: (e) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         const selectedItems = tree.getSelectedItems();
         const items = selectedItems.includes(item) ? selectedItems : [item];
         const config = tree.getConfig();
@@ -1473,9 +1493,11 @@ var dragAndDropFeature = {
           const { imgElement, xOffset, yOffset } = config.setDragImage(items);
           (_c = e.dataTransfer) == null ? void 0 : _c.setDragImage(imgElement, xOffset != null ? xOffset : 0, yOffset != null ? yOffset : 0);
         }
-        if (config.createForeignDragObject) {
-          const { format, data } = config.createForeignDragObject(items);
-          (_d = e.dataTransfer) == null ? void 0 : _d.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", {
           draggedItems: items,
@@ -1484,6 +1506,7 @@ var dragAndDropFeature = {
       },
       onDragOver: (e) => {
         var _a, _b, _c;
+        e.stopPropagation();
         const dataRef = tree.getDataRef();
         const nextDragCode = getDragCode(e, item, tree);
         if (nextDragCode === dataRef.current.lastDragCode) {
@@ -1494,7 +1517,7 @@ var dragAndDropFeature = {
         }
         dataRef.current.lastDragCode = nextDragCode;
         const target = getDragTarget(e, item, tree);
-        if (!((_a = tree.getState().dnd) == null ? void 0 : _a.draggedItems) && (!e.dataTransfer || !((_c = (_b = tree.getConfig()).canDropForeignDragObject) == null ? void 0 : _c.call(_b, e.dataTransfer, target)))) {
+        if (!((_a = tree.getState().dnd) == null ? void 0 : _a.draggedItems) && (!e.dataTransfer || !((_c = (_b = tree.getConfig()).canDragForeignDragObjectOver) == null ? void 0 : _c.call(_b, e.dataTransfer, target)))) {
           dataRef.current.lastAllowDrop = false;
           return;
         }
@@ -1518,12 +1541,17 @@ var dragAndDropFeature = {
         }));
       },
       onDragEnd: (e) => {
-        var _a, _b, _c, _d;
+        var _a, _b;
+        const { onCompleteForeignDrop, canDragForeignDragObjectOver } = tree.getConfig();
         const draggedItems = (_a = tree.getState().dnd) == null ? void 0 : _a.draggedItems;
         if (((_b = e.dataTransfer) == null ? void 0 : _b.dropEffect) === "none" || !draggedItems) {
           return;
         }
-        (_d = (_c = tree.getConfig()).onCompleteForeignDrop) == null ? void 0 : _d.call(_c, draggedItems);
+        const target = getDragTarget(e, item, tree);
+        if (canDragForeignDragObjectOver && e.dataTransfer && !canDragForeignDragObjectOver(e.dataTransfer, target)) {
+          return;
+        }
+        onCompleteForeignDrop == null ? void 0 : onCompleteForeignDrop(draggedItems);
       },
       onDrop: (e) => __async(null, null, function* () {
         var _a, _b, _c;

package/dist/index.mjs

@@ -503,19 +503,6 @@ var createTree = (initialConfig) => {
         const externalStateSetter = config[stateHandlerNames[stateName]];
         externalStateSetter == null ? void 0 : externalStateSetter(state[stateName]);
       },
-      buildItemInstance: ({}, itemId) => {
-        const [instance, finalizeInstance] = buildInstance(
-          features,
-          "itemInstance",
-          (instance2) => ({
-            item: instance2,
-            tree: treeInstance,
-            itemId
-          })
-        );
-        finalizeInstance();
-        return instance;
-      },
       // TODO rebuildSubTree: (itemId: string) => void;
       rebuildTree: () => {
         var _a2;
@@ -536,7 +523,23 @@ var createTree = (initialConfig) => {
           (_c2 = config.setState) == null ? void 0 : _c2.call(config, state);
         }
       },
-      getItemInstance: ({}, itemId) => itemInstancesMap[itemId],
+      getItemInstance: ({}, itemId) => {
+        const existingInstance = itemInstancesMap[itemId];
+        if (!existingInstance) {
+          const [instance, finalizeInstance] = buildInstance(
+            features,
+            "itemInstance",
+            (instance2) => ({
+              item: instance2,
+              tree: treeInstance,
+              itemId
+            })
+          );
+          finalizeInstance();
+          return instance;
+        }
+        return existingInstance;
+      },
       getItems: () => itemInstances,
       registerElement: ({}, element) => {
         if (treeElement === element) {
@@ -592,7 +595,17 @@ var createTree = (initialConfig) => {
         var _a2;
         return (_a2 = itemDataRefs[itemId]) != null ? _a2 : itemDataRefs[itemId] = { current: {} };
       },
-      getItemMeta: ({ itemId }) => itemMetaMap[itemId]
+      getItemMeta: ({ itemId }) => {
+        var _a2;
+        return (_a2 = itemMetaMap[itemId]) != null ? _a2 : {
+          itemId,
+          parentId: null,
+          level: -1,
+          index: -1,
+          posInSet: 0,
+          setSize: 1
+        };
+      }
     }
   };
   features.unshift(mainFeature);
@@ -757,7 +770,7 @@ var selectionFeature = {
 
 // src/features/checkboxes/feature.ts
 var getAllLoadedDescendants = (tree, itemId, includeFolders = false) => {
-  if (!tree.getConfig().isItemFolder(tree.buildItemInstance(itemId))) {
+  if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
     return [itemId];
   }
   const descendants = tree.retrieveChildrenIds(itemId).map((child) => getAllLoadedDescendants(tree, child, includeFolders)).flat();
@@ -1103,6 +1116,11 @@ var asyncDataLoaderFeature = {
       const dataRef = tree.getDataRef();
       dataRef.current.childrenIds[itemId] = childrenIds;
       tree.rebuildTree();
+    },
+    updateCachedData: ({ tree, itemId }, data) => {
+      const dataRef = tree.getDataRef();
+      dataRef.current.itemData[itemId] = data;
+      tree.rebuildTree();
     }
   }
 };
@@ -1310,12 +1328,14 @@ var getDragTarget = (e, item, tree, canReorder = tree.getConfig().canReorder) =>
 };
 
 // src/features/drag-and-drop/feature.ts
+var defaultCanDropForeignDragObject = () => false;
 var dragAndDropFeature = {
   key: "drag-and-drop",
   deps: ["selection"],
   getDefaultConfig: (defaultConfig, tree) => __spreadValues({
     canDrop: (_, target) => target.item.isFolder(),
-    canDropForeignDragObject: () => false,
+    canDropForeignDragObject: defaultCanDropForeignDragObject,
+    canDragForeignDragObjectOver: defaultConfig.canDropForeignDragObject !== defaultCanDropForeignDragObject ? (dataTransfer) => dataTransfer.effectAllowed !== "none" : () => false,
     setDndState: makeStateUpdater("dnd", tree),
     canReorder: true
   }, defaultConfig),
@@ -1414,7 +1434,7 @@ var dragAndDropFeature = {
       draggable: true,
       onDragEnter: (e) => e.preventDefault(),
       onDragStart: (e) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         const selectedItems = tree.getSelectedItems();
         const items = selectedItems.includes(item) ? selectedItems : [item];
         const config = tree.getConfig();
@@ -1429,9 +1449,11 @@ var dragAndDropFeature = {
           const { imgElement, xOffset, yOffset } = config.setDragImage(items);
           (_c = e.dataTransfer) == null ? void 0 : _c.setDragImage(imgElement, xOffset != null ? xOffset : 0, yOffset != null ? yOffset : 0);
         }
-        if (config.createForeignDragObject) {
-          const { format, data } = config.createForeignDragObject(items);
-          (_d = e.dataTransfer) == null ? void 0 : _d.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", {
           draggedItems: items,
@@ -1440,6 +1462,7 @@ var dragAndDropFeature = {
       },
       onDragOver: (e) => {
         var _a, _b, _c;
+        e.stopPropagation();
         const dataRef = tree.getDataRef();
         const nextDragCode = getDragCode(e, item, tree);
         if (nextDragCode === dataRef.current.lastDragCode) {
@@ -1450,7 +1473,7 @@ var dragAndDropFeature = {
         }
         dataRef.current.lastDragCode = nextDragCode;
         const target = getDragTarget(e, item, tree);
-        if (!((_a = tree.getState().dnd) == null ? void 0 : _a.draggedItems) && (!e.dataTransfer || !((_c = (_b = tree.getConfig()).canDropForeignDragObject) == null ? void 0 : _c.call(_b, e.dataTransfer, target)))) {
+        if (!((_a = tree.getState().dnd) == null ? void 0 : _a.draggedItems) && (!e.dataTransfer || !((_c = (_b = tree.getConfig()).canDragForeignDragObjectOver) == null ? void 0 : _c.call(_b, e.dataTransfer, target)))) {
           dataRef.current.lastAllowDrop = false;
           return;
         }
@@ -1474,12 +1497,17 @@ var dragAndDropFeature = {
         }));
       },
       onDragEnd: (e) => {
-        var _a, _b, _c, _d;
+        var _a, _b;
+        const { onCompleteForeignDrop, canDragForeignDragObjectOver } = tree.getConfig();
         const draggedItems = (_a = tree.getState().dnd) == null ? void 0 : _a.draggedItems;
         if (((_b = e.dataTransfer) == null ? void 0 : _b.dropEffect) === "none" || !draggedItems) {
           return;
         }
-        (_d = (_c = tree.getConfig()).onCompleteForeignDrop) == null ? void 0 : _d.call(_c, draggedItems);
+        const target = getDragTarget(e, item, tree);
+        if (canDragForeignDragObjectOver && e.dataTransfer && !canDragForeignDragObjectOver(e.dataTransfer, target)) {
+          return;
+        }
+        onCompleteForeignDrop == null ? void 0 : onCompleteForeignDrop(draggedItems);
       },
       onDrop: (e) => __async(null, null, function* () {
         var _a, _b, _c;

package/package.json

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

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/feature.ts

@@ -8,7 +8,7 @@ const getAllLoadedDescendants = <T>(
   itemId: string,
   includeFolders = false,
 ): string[] => {
-  if (!tree.getConfig().isItemFolder(tree.buildItemInstance(itemId))) {
+  if (!tree.getConfig().isItemFolder(tree.getItemInstance(itemId))) {
     return [itemId];
   }
   const descendants = tree

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

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

@@ -8,13 +8,18 @@ import {
 } from "./utils";
 import { makeStateUpdater } from "../../utils";
 
+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,
     ...defaultConfig,
@@ -162,9 +167,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", {
@@ -174,6 +183,7 @@ 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);
         if (nextDragCode === dataRef.current.lastDragCode) {
@@ -191,7 +201,7 @@ export const dragAndDropFeature: FeatureImplementation = {
           (!e.dataTransfer ||
             !tree
               .getConfig()
-              .canDropForeignDragObject?.(e.dataTransfer, target))
+              .canDragForeignDragObjectOver?.(e.dataTransfer, target))
         ) {
           dataRef.current.lastAllowDrop = false;
           return;
@@ -222,13 +232,24 @@ export const dragAndDropFeature: FeatureImplementation = {
       },
 
       onDragEnd: (e: DragEvent) => {
+        const { onCompleteForeignDrop, canDragForeignDragObjectOver } =
+          tree.getConfig();
         const draggedItems = tree.getState().dnd?.draggedItems;
 
         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) => {

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

@@ -58,16 +58,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>,

package/src/features/main/types.ts

@@ -36,8 +36,6 @@ export type MainFeatureDef<T = any> = {
       stateName: K,
       updater: Updater<TreeState<T>[K]>,
     ) => void;
-    /** @internal */
-    buildItemInstance: (itemId: string) => ItemInstance<T>;
     setState: SetStateFn<TreeState<T>>;
     getState: () => TreeState<T>;
     setConfig: SetStateFn<TreeConfig<T>>;