support setting drag preview (#115)

Author: lukasbach

.changeset/poor-coats-relate.md

@@ -0,0 +1,5 @@
+---
+"@headless-tree/core": patch
+---
+
+support setting the drag preview with the `setDragImage` option (#115)

packages/core/src/features/drag-and-drop/feature.ts

@@ -117,6 +117,11 @@ export const dragAndDropFeature: FeatureImplementation = {
           return;
         }
 
+        if (config.setDragImage) {
+          const { imgElement, xOffset, yOffset } = config.setDragImage(items);
+          e.dataTransfer?.setDragImage(imgElement, xOffset ?? 0, yOffset ?? 0);
+        }
+
         if (config.createForeignDragObject) {
           const { format, data } = config.createForeignDragObject(items);
           e.dataTransfer?.setData(format, data);

packages/core/src/features/drag-and-drop/types.ts

@@ -58,6 +58,11 @@ export type DragAndDropFeatureDef<T> = {
       format: string;
       data: any;
     };
+    setDragImage?: (items: ItemInstance<T>[]) => {
+      imgElement: Element;
+      xOffset?: number;
+      yOffset?: number;
+    };
     canDropForeignDragObject?: (
       dataTransfer: DataTransfer,
       target: DragTarget<T>,

packages/docs/docs/3-dnd/3-customizability.mdx

@@ -47,3 +47,20 @@ instead.
 
 <DemoBox tags={["feature/dnd"]} initialStory="react-drag-and-drop-can-drop--can-drop" />
 
+## Custom Drag Preview
+
+You can customize the drag preview by providing a `setDragImage` to your tree options. It will be called
+when the user starts dragging, with the dragged items as parameter. The functions return parameters will
+be used to invoke [`dataTransfer.setDragImage`](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer/setDragImage)
+to set the drag preview.
+
+```ts
+setDragImage: (draggedItems) => ({
+  imgElement: document.getElementById("dragpreview"),
+})
+```
+
+The provided element does not have to be an image element, but if it is not, it will need to be visible in the viewport.
+In this case, you will want to move it with CSS off-screen to hide it whenever the user is not dragging anything.
+
+<DemoBox tags={["feature/dnd"]} initialStory="react-drag-and-drop-drag-preview--drag-preview" />

packages/sb-react/src/dnd/drag-preview.stories.tsx

@@ -0,0 +1,120 @@
+import type { Meta } from "@storybook/react";
+import React, { useState } from "react";
+import {
+  TreeState,
+  dragAndDropFeature,
+  hotkeysCoreFeature,
+  keyboardDragAndDropFeature,
+  selectionFeature,
+  syncDataLoaderFeature,
+} from "@headless-tree/core";
+import { AssistiveTreeDescription, useTree } from "@headless-tree/react";
+import cn from "classnames";
+
+const meta = {
+  title: "React/Drag and Drop/Drag Preview",
+  tags: ["feature/dnd"],
+} satisfies Meta;
+
+export default meta;
+
+// story-start
+export const DragPreview = () => {
+  const [state, setState] = useState<Partial<TreeState<any>>>({
+    expandedItems: ["root-1", "root-1-2"],
+    selectedItems: ["root-1-2-1", "root-1-2-2", "root-1-2-3", "root-1-2-4"],
+  });
+  const tree = useTree<string>({
+    state,
+    setState,
+    rootItemId: "root",
+    getItemName: (item) => item.getItemData(),
+    isItemFolder: () => true,
+    canReorder: true,
+    onDrop: (items, target) => {
+      alert(
+        `Dropped ${items.map((item) =>
+          item.getId(),
+        )} on ${target.item.getId()}, ${JSON.stringify(target)}`,
+      );
+    },
+    setDragImage: () => ({
+      imgElement: document.getElementById("dragpreview")!,
+      xOffset: -20,
+    }),
+    indent: 20,
+    dataLoader: {
+      getItem: (itemId) => itemId,
+      getChildren: (itemId) => [
+        `${itemId}-1`,
+        `${itemId}-2`,
+        `${itemId}-3`,
+        `${itemId}-4`,
+      ],
+    },
+    features: [
+      syncDataLoaderFeature,
+      selectionFeature,
+      hotkeysCoreFeature,
+      dragAndDropFeature,
+      keyboardDragAndDropFeature,
+    ],
+  });
+
+  const draggedItems = tree.getState().dnd?.draggedItems;
+
+  return (
+    <>
+      <p className="description">
+        This sample utilizes custom drag previews that are defined with the
+        option setDragImage. Start dragging items to see the custom preview.
+      </p>
+      <div {...tree.getContainerProps()} className="tree">
+        <AssistiveTreeDescription tree={tree} />
+        {tree.getItems().map((item) => (
+          <button
+            {...item.getProps()}
+            key={item.getId()}
+            style={{ paddingLeft: `${item.getItemMeta().level * 20}px` }}
+          >
+            <div
+              className={cn("treeitem", {
+                focused: item.isFocused(),
+                expanded: item.isExpanded(),
+                selected: item.isSelected(),
+                folder: item.isFolder(),
+                drop: item.isDragTarget(),
+              })}
+            >
+              {item.getItemName()}
+            </div>
+          </button>
+        ))}
+        <div style={tree.getDragLineStyle()} className="dragline" />
+        <div
+          id="dragpreview"
+          style={{
+            // move the drag preview off-screen by default
+            position: "absolute",
+            left: "-9999px",
+
+            // styling to make it look nice
+            width: "200px",
+            background: "white",
+            borderRadius: "4px",
+            border: "1px solid #eee",
+            padding: "4px",
+          }}
+        >
+          Dragging{" "}
+          {draggedItems
+            ?.slice(0, 3)
+            .map((item) => item.getItemName())
+            .join(", ")}
+          {(draggedItems?.length ?? 0) > 3 &&
+            ` and ${(draggedItems?.length ?? 0) - 3} more`}
+        </div>
+      </div>
+    </>
+  );
+};