feat: drag-and-drop multi-image import onto canvas (#21)

trmquang93 · web-flow · commit ba41004ada3d · 2026-04-02T14:53:13.000+07:00
Allow users to drag multiple PNG/JPG files from Finder onto the canvas
to bulk-create screens in a single gesture. Images are auto-arranged in
a grid from the drop point with dynamic row heights based on the tallest
image per row, anti-overlap detection against existing screens, and
filename-derived screen names. The entire batch is a single undo step.

Co-authored-by: Quang Tran &lt;16215255+trmquang93@users.noreply.github.com&gt;
diff --git a/eslint.config.js b/eslint.config.js
@@ -29,6 +29,7 @@ const browserGlobals = {
   KeyboardEvent: "readonly",
   MouseEvent: "readonly",
   CustomEvent: "readonly",
+  Image: "readonly",
 };
 
 export default [
diff --git a/src/Drawd.jsx b/src/Drawd.jsx
@@ -26,6 +26,7 @@ import { StickyNoteSidebar } from "./components/StickyNoteSidebar";
 import { ScreensPanel } from "./components/ScreensPanel";
 import { CanvasArea } from "./components/CanvasArea";
 import { ModalsLayer } from "./components/ModalsLayer";
+import { Toast } from "./components/Toast";
 import { CollabPresence } from "./components/CollabPresence";
 import { CollabBadge } from "./components/CollabBadge";
 import { importFlow } from "./utils/importFlow";
@@ -275,12 +276,45 @@ export default function Drawd({ initialRoomCode }) {
   const { importConfirm, setImportConfirm, importFileRef, onExport, onImport, onImportFileChange, onImportReplace, onImportMerge } =
     useImportExport({ screens, connections, documents, dataModels, stickyNotes, screenGroups, pan, zoom, featureBrief, taskLink, techStack, replaceAll, mergeAll, setPan, setZoom, setStickyNotes, setScreenGroups });
 
+  // ── Toast notification ─────────────────────────────────────────────────────────────
+  const [toast, setToast] = useState(null);
+  const toastTimerRef = useRef(null);
+  const showToast = useCallback((message, duration = 3000) => {
+    if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
+    setToast(message);
+    toastTimerRef.current = setTimeout(() => setToast(null), duration);
+  }, []);
+
+  // ── Drag-over state (drop zone overlay) ───────────────────────────────────────────
+  const [isDraggingOver, setIsDraggingOver] = useState(false);
+  const dragCounterRef = useRef(0);
+  const onCanvasDragEnter = useCallback((e) => {
+    e.preventDefault();
+    dragCounterRef.current++;
+    if (dragCounterRef.current === 1) setIsDraggingOver(true);
+  }, []);
+  const onCanvasDragLeave = useCallback(() => {
+    dragCounterRef.current--;
+    if (dragCounterRef.current === 0) setIsDraggingOver(false);
+  }, []);
+
   // ── Canvas drop (intercepts .drawd files, delegates images) ────────────────────────
   const onCanvasDrop = useCallback(async (e) => {
     e.preventDefault();
+    dragCounterRef.current = 0;
+    setIsDraggingOver(false);
+
     const drawdFile = detectDrawdFile(e.dataTransfer.files);
     if (!drawdFile) {
-      handleCanvasDrop(e);
+      const imageFiles = Array.from(e.dataTransfer.files).filter(
+        (f) => f.type === "image/png" || f.type === "image/jpeg"
+      );
+      if (imageFiles.length === 0) return;
+      const rect = canvasRef.current.getBoundingClientRect();
+      const worldX = (e.clientX - rect.left - pan.x) / zoom;
+      const worldY = (e.clientY - rect.top - pan.y) / zoom;
+      handleCanvasDrop(e, worldX, worldY);
+      showToast(`Created ${imageFiles.length} screen${imageFiles.length > 1 ? "s" : ""} from dropped images`);
       return;
     }
 
@@ -309,7 +343,7 @@ export default function Drawd({ initialRoomCode }) {
     } catch (err) {
       alert(err.message);
     }
-  }, [screens.length, handleCanvasDrop, applyPayload, setImportConfirm, connectHandle, isFileSystemSupported]);
+  }, [screens.length, handleCanvasDrop, applyPayload, setImportConfirm, connectHandle, isFileSystemSupported, pan, zoom, showToast]);
 
   // ── Keyboard shortcuts ──────────────────────────────────────────────────────────────
   useKeyboardShortcuts({
@@ -503,6 +537,9 @@ export default function Drawd({ initialRoomCode }) {
           setGroupContextMenu={setGroupContextMenu}
           handleImageUpload={handleImageUpload}
           addScreenAtCenter={addScreenAtCenter}
+          isDraggingOver={isDraggingOver}
+          onCanvasDragEnter={onCanvasDragEnter}
+          onCanvasDragLeave={onCanvasDragLeave}
           onTemplates={onTemplates}
         />
 
@@ -593,6 +630,7 @@ export default function Drawd({ initialRoomCode }) {
         setShowTemplateBrowser={setShowTemplateBrowser}
         onInsertTemplate={onInsertTemplate}
       />
+      <Toast message={toast} />
     </div>
   );
 }
diff --git a/src/components/CanvasArea.jsx b/src/components/CanvasArea.jsx
@@ -52,6 +52,8 @@ export function CanvasArea({
   groupContextMenu, setGroupContextMenu,
   // ToolBar
   setActiveTool, handleImageUpload, addScreenAtCenter,
+  // Drop zone overlay
+  isDraggingOver, onCanvasDragEnter, onCanvasDragLeave,
   // Templates
   onTemplates,
 }) {
@@ -66,6 +68,8 @@ export function CanvasArea({
       onMouseUp={onCanvasMouseUp}
       onMouseLeave={onCanvasMouseLeave}
       onDragOver={(e) => e.preventDefault()}
+      onDragEnter={onCanvasDragEnter}
+      onDragLeave={onCanvasDragLeave}
       onDrop={onCanvasDrop}
       onClick={() => {
         if (groupContextMenu) setGroupContextMenu(null);
@@ -88,6 +92,32 @@ export function CanvasArea({
         backgroundPosition: `${pan.x}px ${pan.y}px`,
       }}
     >
+      {isDraggingOver && (
+        <div
+          data-testid="drop-zone-overlay"
+          style={{
+            position: "absolute",
+            inset: 0,
+            background: "rgba(97,175,239,0.08)",
+            border: `2px dashed ${COLORS.accent}`,
+            borderRadius: 12,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            zIndex: Z_INDEX.contextMenu,
+            pointerEvents: "none",
+          }}
+        >
+          <span style={{
+            color: COLORS.accent,
+            fontFamily: FONTS.mono,
+            fontSize: 16,
+            fontWeight: 600,
+          }}>
+            Drop images to create screens
+          </span>
+        </div>
+      )}
       <div
         className="canvas-inner"
         style={{
diff --git a/src/components/CanvasArea.test.jsx b/src/components/CanvasArea.test.jsx
@@ -1,5 +1,5 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
 
 const { screenNodeSpy } = vi.hoisted(() => ({
   screenNodeSpy: vi.fn(),
@@ -140,6 +140,9 @@ function makeProps(overrides = {}) {
     setActiveTool: vi.fn(),
     handleImageUpload: vi.fn(),
     addScreenAtCenter: vi.fn(),
+    isDraggingOver: false,
+    onCanvasDragEnter: vi.fn(),
+    onCanvasDragLeave: vi.fn(),
     ...overrides,
   };
 }
@@ -149,6 +152,10 @@ describe("CanvasArea", () => {
     screenNodeSpy.mockClear();
   });
 
+  afterEach(() => {
+    cleanup();
+  });
+
   it("renders screens without throwing when form summary handler is provided", () => {
     const onFormSummary = vi.fn();
     render(
@@ -164,4 +171,15 @@ describe("CanvasArea", () => {
     expect(screenNodeSpy).toHaveBeenCalledTimes(1);
     expect(screenNodeSpy.mock.calls[0][0].onFormSummary).toBe(onFormSummary);
   });
+
+  it("renders drop zone overlay when isDraggingOver is true", () => {
+    render(<CanvasArea {...makeProps({ isDraggingOver: true })} />);
+    expect(screen.getByTestId("drop-zone-overlay")).toBeTruthy();
+    expect(screen.getByText("Drop images to create screens")).toBeTruthy();
+  });
+
+  it("does not render drop zone overlay when isDraggingOver is false", () => {
+    render(<CanvasArea {...makeProps({ isDraggingOver: false })} />);
+    expect(screen.queryByTestId("drop-zone-overlay")).toBeNull();
+  });
 });
diff --git a/src/components/Toast.jsx b/src/components/Toast.jsx
@@ -0,0 +1,25 @@
+import { COLORS, FONTS, Z_INDEX } from "../styles/theme";
+
+export function Toast({ message }) {
+  if (!message) return null;
+  return (
+    <div style={{
+      position: "fixed",
+      bottom: 40,
+      left: "50%",
+      transform: "translateX(-50%)",
+      background: COLORS.surface,
+      border: `1px solid ${COLORS.accent}`,
+      borderRadius: 8,
+      padding: "10px 20px",
+      color: COLORS.text,
+      fontFamily: FONTS.mono,
+      fontSize: 13,
+      zIndex: Z_INDEX.contextMenu + 1,
+      boxShadow: "0 8px 32px rgba(0,0,0,0.5)",
+      pointerEvents: "none",
+    }}>
+      {message}
+    </div>
+  );
+}
diff --git a/src/constants.js b/src/constants.js
@@ -43,6 +43,7 @@ export const GRID_MARGIN = 60;
 export const PASTE_STAGGER = 30;
 export const STATE_VARIANT_OFFSET = 250;
 export const MERGE_GAP = 300;
+export const DROP_OVERLAP_MARGIN = 40;
 export const CENTER_HEIGHT_ESTIMATE = 160;
 export const VIEWPORT_FALLBACK_WIDTH = 800;
 export const VIEWPORT_FALLBACK_HEIGHT = 600;
diff --git a/src/hooks/useScreenManager.js b/src/hooks/useScreenManager.js
@@ -1,5 +1,7 @@
 import { useState, useRef, useCallback } from "react";
 import { generateId } from "../utils/generateId";
+import { screenBounds } from "../utils/canvasMath";
+import { filenameToScreenName, gridPositions, resolveOverlaps } from "../utils/dropImport";
 import {
   DEFAULT_SCREEN_WIDTH,
   CENTER_HEIGHT_ESTIMATE,
@@ -14,6 +16,7 @@ import {
   VIEWPORT_FALLBACK_HEIGHT,
   DEFAULT_STATE_NAME,
   SCREEN_NAME_TEMPLATE,
+  HEADER_HEIGHT,
 } from "../constants";
 
 export function useScreenManager(pan, zoom, canvasRef) {
@@ -163,6 +166,35 @@ export function useScreenManager(pan, zoom, canvasRef) {
     setSelectedScreen(newScreen.id);
   }, [screens, connections, documents, pushHistory, pan, zoom, canvasRef]);
 
+  const addScreensBatch = useCallback((screenDefs) => {
+    if (screenDefs.length === 0) return 0;
+    pushHistory(screens, connections, documents);
+    const newScreens = screenDefs.map((def) => ({
+      id: generateId(),
+      name: def.name,
+      x: def.x,
+      y: def.y,
+      width: DEFAULT_SCREEN_WIDTH,
+      imageData: def.imageData,
+      description: "",
+      notes: "",
+      codeRef: "",
+      status: "new",
+      acceptanceCriteria: [],
+      hotspots: [],
+      stateGroup: null,
+      stateName: "",
+      tbd: false,
+      tbdNote: "",
+      roles: [],
+      figmaSource: null,
+    }));
+    setScreens((prev) => [...prev, ...newScreens]);
+    setSelectedScreen(newScreens[0].id);
+    screenCounter.current += newScreens.length;
+    return newScreens.length;
+  }, [screens, connections, documents, pushHistory]);
+
   const removeScreen = useCallback((id) => {
     pushHistory(screens, connections, documents);
     const removedScreen = screens.find((s) => s.id === id);
@@ -325,17 +357,59 @@ export function useScreenManager(pan, zoom, canvasRef) {
     });
   }, [addScreenAtCenter, selectedScreen, screens, assignScreenImage]);
 
-  const handleCanvasDrop = useCallback((e) => {
+  const handleCanvasDrop = useCallback((e, worldX, worldY) => {
     e.preventDefault();
-    const files = Array.from(e.dataTransfer.files).filter((f) => f.type.startsWith("image/"));
-    files.forEach((file) => {
-      const reader = new FileReader();
-      reader.onload = (ev) => {
-        addScreen(ev.target.result, file.name.replace(/\.[^.]+$/, ""));
-      };
-      reader.readAsDataURL(file);
+    const files = Array.from(e.dataTransfer.files).filter(
+      (f) => f.type === "image/png" || f.type === "image/jpeg"
+    );
+    if (files.length === 0) return;
+
+    Promise.all(
+      files.map(
+        (file) =>
+          new Promise((resolve) => {
+            const reader = new FileReader();
+            reader.onload = (ev) => {
+              const dataUrl = ev.target.result;
+              const img = new Image();
+              img.onload = () => {
+                const renderedHeight = (img.naturalHeight / img.naturalWidth) * DEFAULT_SCREEN_WIDTH;
+                resolve({
+                  imageData: dataUrl,
+                  filename: file.name,
+                  imageHeight: renderedHeight,
+                });
+              };
+              img.onerror = () => {
+                resolve({ imageData: dataUrl, filename: file.name, imageHeight: 120 });
+              };
+              img.src = dataUrl;
+            };
+            reader.readAsDataURL(file);
+          })
+      )
+    ).then((results) => {
+      const itemHeights = results.map((r) => r.imageHeight + HEADER_HEIGHT);
+      const positions = gridPositions(itemHeights, worldX, worldY);
+      const candidateRects = positions.map((pos, i) => ({
+        x: pos.x,
+        y: pos.y,
+        width: DEFAULT_SCREEN_WIDTH,
+        height: itemHeights[i],
+      }));
+      const existingRects = screens.map((s) => screenBounds(s, HEADER_HEIGHT));
+      const adjusted = resolveOverlaps(candidateRects, existingRects);
+
+      const screenDefs = results.map((r, i) => ({
+        imageData: r.imageData,
+        name: filenameToScreenName(r.filename),
+        x: adjusted[i].x,
+        y: adjusted[i].y,
+      }));
+
+      addScreensBatch(screenDefs);
     });
-  }, [addScreen]);
+  }, [screens, addScreensBatch]);
 
   const saveHotspot = useCallback((screenId, hotspot) => {
     pushHistory(screens, connections, documents);
@@ -872,6 +946,7 @@ export function useScreenManager(pan, zoom, canvasRef) {
     fileInputRef,
     addScreen,
     addScreenAtCenter,
+    addScreensBatch,
     removeScreen,
     removeScreens,
     renameScreen,
diff --git a/src/hooks/useScreenManager.test.js b/src/hooks/useScreenManager.test.js
diff --git a/src/utils/dropImport.js b/src/utils/dropImport.js
diff --git a/src/utils/dropImport.test.js b/src/utils/dropImport.test.js
