@headless-tree/core 0.0.0-20250730213235 → 0.0.0-20250807163338

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # @headless-tree/core
 
-## 0.0.0-20250730213235
+## 0.0.0-20250807163338
+
+### 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
 
@@ -10,6 +14,7 @@
 - b41e1d2: fixed a bug where ending drag without successful drop doesn't properly reset drag line (#132)
 - b413f74: Fix `aria-posinset` and `aria-level` to be 1-based indexing
 - a250b3b: Fix a bug where expand from the initial keyboard focus fails when rootItemId is an empty string
+- 62867e8: Introduced a short delay before hiding the drag line when leaving a drag target, which helps to reduce flickering of the dragline when moving between items
 - 662e2a8: Improved customizability of checkboxes feature (still alpha state), allowing you to customize `propagateCheckedState` and `canCheckFolders` independently
 - 662e2a8: Changed to new buildtool in core packages (now using tsup) to hopefully fix some ESM/CJS integrations
 

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 interface DndDataRef {
     lastDragCode?: string;
     lastAllowDrop?: boolean;
+    lastDragEnter?: number;
     windowDragEndListener?: () => void;
 }
 interface DndState<T> {
@@ -45,13 +46,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;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 interface DndDataRef {
     lastDragCode?: string;
     lastAllowDrop?: boolean;
+    lastDragEnter?: number;
     windowDragEndListener?: () => void;
 }
 interface DndState<T> {
@@ -45,13 +46,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;

package/dist/index.js

@@ -1372,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),
@@ -1476,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();
@@ -1491,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,
@@ -1502,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) {
@@ -1511,8 +1516,9 @@ var dragAndDropFeature = {
           return;
         }
         dataRef.current.lastDragCode = nextDragCode;
+        dataRef.current.lastDragEnter = Date.now();
         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;
         }
@@ -1528,20 +1534,29 @@ var dragAndDropFeature = {
         e.preventDefault();
       },
       onDragLeave: () => {
-        const dataRef = tree.getDataRef();
-        dataRef.current.lastDragCode = "no-drag";
-        tree.applySubStateUpdate("dnd", (state) => __spreadProps(__spreadValues({}, state), {
-          draggingOverItem: void 0,
-          dragTarget: void 0
-        }));
+        setTimeout(() => {
+          var _a;
+          const dataRef = tree.getDataRef();
+          if (((_a = dataRef.current.lastDragEnter) != null ? _a : 0) + 100 >= Date.now()) return;
+          dataRef.current.lastDragCode = "no-drag";
+          tree.applySubStateUpdate("dnd", (state) => __spreadProps(__spreadValues({}, state), {
+            draggingOverItem: void 0,
+            dragTarget: void 0
+          }));
+        }, 100);
       },
       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

@@ -1328,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),
@@ -1432,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();
@@ -1447,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,
@@ -1458,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) {
@@ -1467,8 +1472,9 @@ var dragAndDropFeature = {
           return;
         }
         dataRef.current.lastDragCode = nextDragCode;
+        dataRef.current.lastDragEnter = Date.now();
         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;
         }
@@ -1484,20 +1490,29 @@ var dragAndDropFeature = {
         e.preventDefault();
       },
       onDragLeave: () => {
-        const dataRef = tree.getDataRef();
-        dataRef.current.lastDragCode = "no-drag";
-        tree.applySubStateUpdate("dnd", (state) => __spreadProps(__spreadValues({}, state), {
-          draggingOverItem: void 0,
-          dragTarget: void 0
-        }));
+        setTimeout(() => {
+          var _a;
+          const dataRef = tree.getDataRef();
+          if (((_a = dataRef.current.lastDragEnter) != null ? _a : 0) + 100 >= Date.now()) return;
+          dataRef.current.lastDragCode = "no-drag";
+          tree.applySubStateUpdate("dnd", (state) => __spreadProps(__spreadValues({}, state), {
+            draggingOverItem: void 0,
+            dragTarget: void 0
+          }));
+        }, 100);
       },
       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-20250730213235",
+  "version": "0.0.0-20250807163338",
   "main": "dist/index.d.ts",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",

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) {
@@ -183,6 +193,7 @@ export const dragAndDropFeature: FeatureImplementation = {
           return;
         }
         dataRef.current.lastDragCode = nextDragCode;
+        dataRef.current.lastDragEnter = Date.now();
 
         const target = getDragTarget(e, item, tree);
 
@@ -191,7 +202,7 @@ export const dragAndDropFeature: FeatureImplementation = {
           (!e.dataTransfer ||
             !tree
               .getConfig()
-              .canDropForeignDragObject?.(e.dataTransfer, target))
+              .canDragForeignDragObjectOver?.(e.dataTransfer, target))
         ) {
           dataRef.current.lastAllowDrop = false;
           return;
@@ -212,23 +223,37 @@ 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;
 
         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

@@ -3,6 +3,7 @@ import { ItemInstance, SetStateFn } from "../../types/core";
 export interface DndDataRef {
   lastDragCode?: string;
   lastAllowDrop?: boolean;
+  lastDragEnter?: number;
   windowDragEndListener?: () => void;
 }
 
@@ -58,16 +59,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>,