@hienlh/ppm 0.17.57 → 0.18.0

package/src/web/components/os-explorer/dnd/entry-drag-payload.ts

@@ -0,0 +1,115 @@
+/**
+ * The payload every PPM entry drag carries, and the pure path guards that decide whether a
+ * drop is allowed at all.
+ *
+ * One MIME type for the whole app: a tab drag (`application/ppm-tab`) and an entry drag are
+ * told apart by `dataTransfer.types` alone, so a tab dropped on a folder and a folder
+ * dropped on the tab bar both do nothing instead of doing the wrong thing.
+ *
+ * Paths are always absolute host paths, including the ones a project tree contributes —
+ * that is the only address space the explorer and the tree share.
+ */
+
+export const ENTRY_DRAG_MIME = "application/x-ppm-paths";
+
+/** Legacy single-path type the project tree already used for its own internal moves. */
+export const TREE_LEGACY_DRAG_MIME = "application/x-ppm-path";
+
+export type EntryDragOrigin = "explorer" | "tree";
+
+export type DropOperation = "copy" | "move";
+
+export interface EntryDragPayload {
+  /** Absolute host paths. */
+  paths: string[];
+  origin: EntryDragOrigin;
+  /** Present when the drag started in a project tree — a tree-internal drop keeps its own routes. */
+  projectName?: string;
+}
+
+/** Windows paths are case-insensitive; a drive letter or a UNC prefix is the cheap tell. */
+function isWindowsPath(path: string): boolean {
+  return /^[a-zA-Z]:[\\/]/.test(path) || path.startsWith("\\\\");
+}
+
+/**
+ * Comparable form of a path: one separator style, no trailing separator, case-folded on
+ * Windows. Only ever used for comparisons — never for building a path to send to the server.
+ */
+export function normalisePath(path: string): string {
+  const unified = path.replace(/\\/g, "/").replace(/\/+$/, "");
+  return isWindowsPath(path) ? unified.toLowerCase() : unified;
+}
+
+/** Host separator implied by a path, for the helpers that have no `HostInfo` at hand. */
+export function sepOf(path: string): string {
+  return isWindowsPath(path) || path.includes("\\") ? "\\" : "/";
+}
+
+export function encodeEntryDrag(payload: EntryDragPayload): string {
+  return JSON.stringify(payload);
+}
+
+/** Tolerant decode — a foreign or truncated payload is "not our drag", never a throw. */
+export function decodeEntryDrag(raw: string | null | undefined): EntryDragPayload | null {
+  if (!raw) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const candidate = parsed as Partial<EntryDragPayload>;
+  if (!Array.isArray(candidate.paths)) return null;
+  const paths = candidate.paths.filter((p): p is string => typeof p === "string" && p.length > 0);
+  if (paths.length === 0) return null;
+  const payload: EntryDragPayload = {
+    paths,
+    origin: candidate.origin === "tree" ? "tree" : "explorer",
+  };
+  if (typeof candidate.projectName === "string") payload.projectName = candidate.projectName;
+  return payload;
+}
+
+/**
+ * True when `targetDir` is one of the dragged entries or lives inside one — moving a folder
+ * into itself would either delete it or produce infinite nesting, so it is refused outright.
+ */
+export function isSelfOrDescendant(paths: string[], targetDir: string): boolean {
+  const target = normalisePath(targetDir);
+  return paths.some((path) => {
+    const source = normalisePath(path);
+    return target === source || target.startsWith(`${source}/`);
+  });
+}
+
+/** True when every dragged entry already sits directly in `targetDir` — a move would be a no-op. */
+export function allAlreadyIn(paths: string[], targetDir: string): boolean {
+  const target = normalisePath(targetDir);
+  return paths.every((path) => {
+    const source = normalisePath(path);
+    const cut = source.lastIndexOf("/");
+    const parent = cut <= 0 ? source.slice(0, cut + 1) : source.slice(0, cut);
+    return parent === target;
+  });
+}
+
+/**
+ * Move is the default; `Ctrl` (and `Alt`, which is macOS's own copy modifier) switches to
+ * copy. Read again at drop time, because the user is allowed to change their mind mid-drag.
+ */
+export function resolveDropOperation(modifiers: { ctrlKey: boolean; altKey: boolean }): DropOperation {
+  return modifiers.ctrlKey || modifiers.altKey ? "copy" : "move";
+}
+
+/** `text/uri-list` mirror of the payload, so non-PPM drop targets see something meaningful. */
+export function toFileUriList(paths: string[]): string {
+  return paths
+    .map((path) => {
+      const unified = path.replace(/\\/g, "/");
+      const absolute = unified.startsWith("/") ? unified : `/${unified}`;
+      return `file://${absolute.split("/").map(encodeURIComponent).join("/")}`;
+    })
+    .join("\r\n");
+}

package/src/web/components/os-explorer/dnd/entry-drag-state.ts

@@ -0,0 +1,35 @@
+/**
+ * The payload of the drag currently in flight, kept in a module-level ref.
+ *
+ * Chromium refuses to read `dataTransfer` during `dragover` (only `types` is exposed, for
+ * privacy), so a drop target that has to decide "is this folder one of the dragged ones?"
+ * before the drop cannot get the paths from the event. Every drag in this app starts in
+ * this app, so stashing the payload here at `dragstart` and clearing it at `dragend` gives
+ * hover-time validation without weakening the drop-time check, which still reads the real
+ * `dataTransfer`.
+ */
+
+import type { EntryDragPayload } from "./entry-drag-payload";
+
+let inFlight: EntryDragPayload | null = null;
+
+export function setInFlightDrag(payload: EntryDragPayload): void {
+  inFlight = payload;
+}
+
+export function getInFlightDrag(): EntryDragPayload | null {
+  return inFlight;
+}
+
+export function clearInFlightDrag(): void {
+  inFlight = null;
+}
+
+// Last-resort net: a source row that unmounts mid-drag (e.g. a spring-load navigation) can
+// skip its own `dragend`, and the row would otherwise never clear this ref itself. A
+// window-level bubble listener still clears it for any drop/dragend that reaches this far —
+// every drop target that actually claims one already clears it itself first.
+if (typeof window !== "undefined") {
+  window.addEventListener("dragend", clearInFlightDrag);
+  window.addEventListener("drop", clearInFlightDrag);
+}

package/src/web/components/os-explorer/dnd/entry-drop-executor.ts

@@ -0,0 +1,43 @@
+/**
+ * The last gate a dropped payload passes before it touches the filesystem.
+ *
+ * Everything funnels through the clipboard module's `transfer()`, the same call Paste
+ * makes, so drag-and-drop inherits the collision prompt, the trash-first Replace, the
+ * cross-device (`EXDEV`) fallback handled server-side and the `fsChanged` refresh of both
+ * the source and the destination directory. There are deliberately no optimistic updates:
+ * the panes only move once the server has confirmed.
+ */
+
+import { toast } from "sonner";
+import { transfer, type TransferContext } from "../actions/explorer-actions-clipboard";
+import { isSelfOrDescendant, type DropOperation, type EntryDragPayload } from "./entry-drag-payload";
+
+/** How a surface performs the transfer — an explorer window passes its bound action. */
+export type DropRunner = (paths: string[], dstDir: string, op: DropOperation) => Promise<void>;
+
+/**
+ * Re-checks the self/descendant guard the hover-time decision already applied. The modifier
+ * and the pointer can both change between the last `dragover` and the `drop`, and a payload
+ * that arrives without ever having been hovered (a target reached by keyboard-driven drop in
+ * some browsers) never went through that check at all.
+ */
+export async function executeEntryDrop(
+  payload: EntryDragPayload,
+  dstDir: string,
+  op: DropOperation,
+  run: DropRunner,
+): Promise<void> {
+  if (payload.paths.length === 0) return;
+  if (isSelfOrDescendant(payload.paths, dstDir)) {
+    toast.error("Cannot place an item inside itself");
+    return;
+  }
+  await run(payload.paths, dstDir, op);
+}
+
+/** A `DropRunner` for surfaces that own a `TransferContext` instead of an explorer action set. */
+export function transferRunner(context: TransferContext): DropRunner {
+  return async (paths, dstDir, op) => {
+    await transfer(paths, dstDir, op, context);
+  };
+}

package/src/web/components/os-explorer/dnd/use-drag-auto-scroll.ts

@@ -0,0 +1,70 @@
+/**
+ * Scrolls a container while an entry drag hovers near its edge, so a destination that is
+ * off-screen is still reachable without letting go.
+ *
+ * Listens natively on the element rather than through React props: `dragover` bubbles from
+ * whatever row the pointer is really over, and the row's own React handler stops the
+ * synthetic event — which would hide every edge hover from a JSX-level handler here.
+ */
+
+import { useEffect, type RefObject } from "react";
+import { ENTRY_DRAG_MIME } from "./entry-drag-payload";
+
+/** Distance from an edge at which scrolling starts. */
+const EDGE_ZONE_PX = 48;
+/** Fastest scroll step per frame, reached at the very edge. */
+const MAX_STEP_PX = 16;
+
+function stepFor(distance: number): number {
+  if (distance >= EDGE_ZONE_PX) return 0;
+  const intensity = Math.min(1, Math.max(0, (EDGE_ZONE_PX - distance) / EDGE_ZONE_PX));
+  return Math.ceil(intensity * MAX_STEP_PX);
+}
+
+export function useDragAutoScroll(ref: RefObject<HTMLElement | null>): void {
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    let frame: number | null = null;
+    let velocity = { x: 0, y: 0 };
+
+    const stop = () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      frame = null;
+      velocity = { x: 0, y: 0 };
+    };
+
+    const tick = () => {
+      if (velocity.x === 0 && velocity.y === 0) {
+        frame = null;
+        return;
+      }
+      element.scrollBy(velocity.x, velocity.y);
+      frame = requestAnimationFrame(tick);
+    };
+
+    const onDragOver = (event: DragEvent) => {
+      if (!event.dataTransfer?.types.includes(ENTRY_DRAG_MIME)) return;
+      const box = element.getBoundingClientRect();
+      const up = stepFor(event.clientY - box.top);
+      const down = stepFor(box.bottom - event.clientY);
+      const left = stepFor(event.clientX - box.left);
+      const right = stepFor(box.right - event.clientX);
+      velocity = { x: right - left, y: down - up };
+      if (frame === null && (velocity.x !== 0 || velocity.y !== 0)) frame = requestAnimationFrame(tick);
+    };
+
+    element.addEventListener("dragover", onDragOver);
+    element.addEventListener("dragleave", stop);
+    element.addEventListener("drop", stop);
+    window.addEventListener("dragend", stop);
+    return () => {
+      stop();
+      element.removeEventListener("dragover", onDragOver);
+      element.removeEventListener("dragleave", stop);
+      element.removeEventListener("drop", stop);
+      window.removeEventListener("dragend", stop);
+    };
+  }, [ref]);
+}

package/src/web/components/os-explorer/dnd/use-drop-transfer.tsx

@@ -0,0 +1,82 @@
+/**
+ * A self-contained transfer runner for the drop surfaces that live outside an explorer
+ * window's action set: the places sidebar, the breadcrumb and the project file tree.
+ *
+ * Those three are rendered by components that never receive `ExplorerActions`, so they own
+ * the two interruptions `transfer()` can raise (name collision, and a Replace on a host with
+ * no Trash) themselves. The dialogs are the very same components the window body renders —
+ * only the promise wiring is local — so a collision looks identical wherever the drop landed.
+ */
+
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import type { CollisionChoice, CollisionRequest, TransferContext } from "../actions/explorer-actions-clipboard";
+import type { ExplorerDialogState } from "../actions/use-explorer-actions";
+import { ExplorerDialogs } from "../explorer-dialogs";
+import { transferRunner, type DropRunner } from "./entry-drop-executor";
+
+export interface DropTransfer {
+  run: DropRunner;
+  /** Render this somewhere inside the surface — it is empty until a prompt is raised. */
+  prompts: ReactNode;
+}
+
+export function useDropTransfer(sep: string, platform?: string): DropTransfer {
+  const [collision, setCollision] = useState<ExplorerDialogState["collision"]>(null);
+  const [permanentOverwrite, setPermanentOverwrite] = useState<ExplorerDialogState["permanentOverwrite"]>(null);
+
+  // The separator can change under a long-lived surface (the tree follows the active
+  // project), so the context reads it live rather than closing over the first value.
+  // Assigned in an effect, not during render — React may discard a render before commit.
+  const sepRef = useRef(sep);
+  useEffect(() => { sepRef.current = sep; }, [sep]);
+
+  const context = useMemo<TransferContext>(
+    () => ({
+      get sep() {
+        return sepRef.current;
+      },
+      resolve: (request: CollisionRequest) =>
+        new Promise<CollisionChoice>((resolve) => {
+          setCollision({
+            ...request,
+            resolve: (choice) => {
+              setCollision(null);
+              resolve(choice);
+            },
+          });
+        }),
+      confirmPermanentOverwrite: (name: string) =>
+        new Promise<boolean>((resolve) => {
+          setPermanentOverwrite({
+            name,
+            resolve: (proceed) => {
+              setPermanentOverwrite(null);
+              resolve(proceed);
+            },
+          });
+        }),
+    }),
+    [],
+  );
+
+  const run = useMemo<DropRunner>(() => transferRunner(context), [context]);
+
+  const prompts = (
+    <ExplorerDialogs
+      dialogs={{
+        collision,
+        permanentOverwrite,
+        pendingDelete: null,
+        properties: null,
+        inlineError: null,
+        closeDelete: () => {},
+        runPermanentDelete: () => {},
+        closeProperties: () => {},
+      }}
+      platform={platform}
+      sep={sep}
+    />
+  );
+
+  return { run, prompts };
+}

package/src/web/components/os-explorer/dnd/use-entry-drag-source.ts

@@ -0,0 +1,73 @@
+/**
+ * Makes a row, tile or tree node the source of an entry drag.
+ *
+ * Returns nothing at all on a coarse pointer: HTML5 drag has no touch equivalent, and the
+ * guideline reserves a long press for the context menu, so a phone must not even get the
+ * `draggable` attribute (it would swallow the press). Cut/Copy/Paste stays the touch path.
+ */
+
+import { useCallback, useMemo, type DragEvent } from "react";
+import { setEntryDragGhost } from "./drag-ghost";
+import { clearInFlightDrag, setInFlightDrag } from "./entry-drag-state";
+import {
+  encodeEntryDrag, ENTRY_DRAG_MIME, toFileUriList,
+  type EntryDragOrigin,
+} from "./entry-drag-payload";
+import { usePrefersCoarsePointer } from "../use-coarse-long-press";
+
+export interface EntryDragSourceOptions {
+  /** Absolute host paths this drag carries — the whole selection when the row is selected. */
+  paths: string[];
+  /** Ghost labels; defaults to the basenames of `paths`. */
+  names?: string[];
+  origin: EntryDragOrigin;
+  projectName?: string;
+  /**
+   * Extra `dataTransfer` entries written alongside the shared payload. The project tree
+   * keeps writing its own legacy single-path type here so tree-internal drops, which have
+   * their own project-scoped route, behave exactly as they did before.
+   */
+  extraData?: Record<string, string>;
+  disabled?: boolean;
+  /** Runs before the payload is written — used to make the dragged row the selected one. */
+  onDragStarted?(): void;
+}
+
+export interface EntryDragSourceProps {
+  draggable?: true;
+  onDragStart?(event: DragEvent): void;
+  onDragEnd?(event: DragEvent): void;
+}
+
+function basenameOf(path: string): string {
+  return path.split(/[/\\]/).filter(Boolean).pop() ?? path;
+}
+
+export function useEntryDragSource(options: EntryDragSourceOptions): EntryDragSourceProps {
+  const { paths, names, origin, projectName, extraData, disabled, onDragStarted } = options;
+  const coarse = usePrefersCoarsePointer();
+  const enabled = !coarse && !disabled && paths.length > 0;
+
+  const handleDragStart = useCallback(
+    (event: DragEvent) => {
+      onDragStarted?.();
+      const payload = { paths, origin, ...(projectName ? { projectName } : {}) };
+      const data = event.dataTransfer;
+      data.setData(ENTRY_DRAG_MIME, encodeEntryDrag(payload));
+      // Accessibility / interop mirror: anything that understands dropped files sees paths.
+      data.setData("text/uri-list", toFileUriList(paths));
+      data.setData("text/plain", paths.join("\n"));
+      for (const [type, value] of Object.entries(extraData ?? {})) data.setData(type, value);
+      data.effectAllowed = "copyMove";
+      setEntryDragGhost(data, names ?? paths.map(basenameOf));
+      // Hover-time validation cannot read `dataTransfer`; see `entry-drag-state.ts`.
+      setInFlightDrag(payload);
+    },
+    [paths, names, origin, projectName, extraData, onDragStarted],
+  );
+
+  return useMemo<EntryDragSourceProps>(
+    () => (enabled ? { draggable: true, onDragStart: handleDragStart, onDragEnd: clearInFlightDrag } : {}),
+    [enabled, handleDragStart],
+  );
+}

package/src/web/components/os-explorer/dnd/use-entry-drop-target.ts

@@ -0,0 +1,150 @@
+/**
+ * Makes any element a drop target for an entry drag: a directory row, a view background, a
+ * sidebar place, a breadcrumb crumb or a project-tree node.
+ *
+ * Two timers, both Finder/Explorer behaviour: the highlight only appears after the pointer
+ * has stayed 120 ms (a drag that sweeps across ten rows must not flash all ten), and an
+ * optional spring-load opens the hovered folder after 800 ms so a deep destination is
+ * reachable without dropping first. Spring-load is opt-in because it only makes sense where
+ * "open" does not destroy the drag — Column view and the project tree.
+ */
+
+import { useCallback, useEffect, useRef, useState, type DragEvent } from "react";
+import { decideDrop, type DropDecision } from "./drop-target-decision";
+import { clearInFlightDrag, getInFlightDrag } from "./entry-drag-state";
+import { decodeEntryDrag, ENTRY_DRAG_MIME, type DropOperation, type EntryDragPayload } from "./entry-drag-payload";
+
+const HIGHLIGHT_DELAY_MS = 120;
+const SPRING_LOAD_MS = 800;
+
+export interface EntryDropTargetOptions {
+  /** Directory a drop writes into; null disables the target (a file row, a missing path). */
+  targetDir: string | null;
+  onDropEntries(payload: EntryDragPayload, op: DropOperation, targetDir: string): void;
+  /** Opens the hovered folder after a rest — Column view and the project tree only. */
+  springLoad?: () => void;
+  disabled?: boolean;
+}
+
+export interface EntryDropTargetResult {
+  /** True once the pointer has rested long enough for the target to claim the drop. */
+  isOver: boolean;
+  handlers: {
+    onDragEnter(event: DragEvent): void;
+    onDragOver(event: DragEvent): void;
+    onDragLeave(event: DragEvent): void;
+    onDrop(event: DragEvent): void;
+  };
+}
+
+function decisionFor(event: DragEvent, targetDir: string | null, payload: EntryDragPayload | null): DropDecision {
+  return decideDrop({
+    types: Array.from(event.dataTransfer.types),
+    payload,
+    targetDir,
+    modifiers: { ctrlKey: event.ctrlKey, altKey: event.altKey },
+  });
+}
+
+export function useEntryDropTarget(options: EntryDropTargetOptions): EntryDropTargetResult {
+  const { targetDir, onDropEntries, springLoad, disabled } = options;
+  const [isOver, setIsOver] = useState(false);
+  // Nested children fire their own enter/leave pairs; only a balanced count means "left".
+  const depth = useRef(0);
+  const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
+
+  const stopTimers = useCallback(() => {
+    for (const timer of timers.current) clearTimeout(timer);
+    timers.current = [];
+  }, []);
+
+  const reset = useCallback(() => {
+    depth.current = 0;
+    stopTimers();
+    setIsOver(false);
+  }, [stopTimers]);
+
+  useEffect(() => stopTimers, [stopTimers]);
+
+  const onDragEnter = useCallback(
+    (event: DragEvent) => {
+      if (disabled) return;
+      // Count this row's own entry drags unconditionally, even when the current decision
+      // rejects (e.g. same-directory move) — a modifier held later (Ctrl → copy) can flip
+      // that same hover to an accept without a matching enter/leave pair, so counting must
+      // not depend on the decision or a later dragleave over the same subtree desyncs the
+      // balance and clears the highlight while the pointer is still over the target.
+      if (!event.dataTransfer.types.includes(ENTRY_DRAG_MIME)) return;
+      const decision = decisionFor(event, targetDir, getInFlightDrag());
+      if (decision.accept) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+      depth.current++;
+      if (depth.current > 1 || !decision.accept) return;
+      timers.current.push(setTimeout(() => setIsOver(true), HIGHLIGHT_DELAY_MS));
+      if (springLoad) timers.current.push(setTimeout(springLoad, SPRING_LOAD_MS));
+    },
+    [disabled, targetDir, springLoad],
+  );
+
+  const onDragOver = useCallback(
+    (event: DragEvent) => {
+      if (disabled) return;
+      const decision = decisionFor(event, targetDir, getInFlightDrag());
+      if (!decision.accept) return;
+      // Claiming the drop here is what keeps a directory row from also handing the drop to
+      // the view background behind it.
+      event.preventDefault();
+      event.stopPropagation();
+      event.dataTransfer.dropEffect = decision.op === "copy" ? "copy" : "move";
+    },
+    [disabled, targetDir],
+  );
+
+  const onDragLeave = useCallback(
+    (event: DragEvent) => {
+      if (depth.current === 0) return;
+      event.stopPropagation();
+      depth.current--;
+      if (depth.current === 0) {
+        stopTimers();
+        setIsOver(false);
+      }
+    },
+    [stopTimers],
+  );
+
+  const onDrop = useCallback(
+    (event: DragEvent) => {
+      if (disabled) return;
+      // The real payload is readable now; the module ref is only the hover-time stand-in.
+      // Clear it here too — `dragend` is not guaranteed to reach a source that unmounted
+      // mid-drag (e.g. a spring-load navigation), and a stale ref must never outlive a drop.
+      const payload = decodeEntryDrag(event.dataTransfer.getData(ENTRY_DRAG_MIME)) ?? getInFlightDrag();
+      clearInFlightDrag();
+      const decision = decisionFor(event, targetDir, payload);
+      if (!decision.accept) {
+        // A rejected PPM drag is still consumed here, so the browser does not fall back to
+        // navigating to the dropped path; a foreign drag is left alone entirely.
+        if (decision.reason !== "not-an-entry-drag") {
+          event.preventDefault();
+          event.stopPropagation();
+        }
+        reset();
+        return;
+      }
+      if (!payload || targetDir == null) {
+        reset();
+        return;
+      }
+      event.preventDefault();
+      event.stopPropagation();
+      reset();
+      onDropEntries(payload, decision.op, targetDir);
+    },
+    [disabled, targetDir, onDropEntries, reset],
+  );
+
+  return { isOver, handlers: { onDragEnter, onDragOver, onDragLeave, onDrop } };
+}

package/src/web/components/os-explorer/dnd/use-entry-row-dnd.ts

@@ -0,0 +1,66 @@
+/**
+ * Drag source + drop target for one entry row/tile, collapsed into a single spreadable prop
+ * bag.
+ *
+ * The row components sit under a Radix `ContextMenuTrigger asChild`, which clones them and
+ * merges its own `ref` and `onContextMenu`. Adding seven more handlers to those signatures
+ * would make an easy place to drop one of the two by accident, so the wiring stays one
+ * object the row spreads verbatim.
+ */
+
+import { useMemo, type DragEvent } from "react";
+import type { FsEntry } from "@/lib/fs-api";
+import type { DropRunner } from "./entry-drop-executor";
+import type { EntryDragOrigin } from "./entry-drag-payload";
+import { useEntryDragSource } from "./use-entry-drag-source";
+import { usePathDropTarget } from "./use-path-drop-target";
+
+export interface EntryRowDndProps {
+  draggable?: true;
+  onDragStart?(event: DragEvent): void;
+  onDragEnd?(event: DragEvent): void;
+  onDragEnter(event: DragEvent): void;
+  onDragOver(event: DragEvent): void;
+  onDragLeave(event: DragEvent): void;
+  onDrop(event: DragEvent): void;
+}
+
+export interface EntryRowDndOptions {
+  entry: FsEntry;
+  /** Absolute paths the drag carries — the whole selection when this row is part of it. */
+  dragPaths: string[];
+  run: DropRunner;
+  /** Column view and the tree open the hovered folder after a rest; List/Icons do not. */
+  springLoad?: () => void;
+  origin?: EntryDragOrigin;
+  projectName?: string;
+  extraData?: Record<string, string>;
+  onDragStarted?(): void;
+}
+
+export interface EntryRowDnd {
+  props: EntryRowDndProps;
+  /** True while this row is the claimed drop destination — draw the ring from it. */
+  isDropTarget: boolean;
+}
+
+export function useEntryRowDnd(options: EntryRowDndOptions): EntryRowDnd {
+  const { entry, dragPaths, run, springLoad, origin = "explorer", projectName, extraData, onDragStarted } = options;
+
+  const source = useEntryDragSource({ paths: dragPaths, origin, projectName, extraData, onDragStarted });
+
+  // Only a directory can receive a drop; a file row lets the event fall through to the view
+  // background, which is the same folder the file lives in — exactly what the OS does.
+  const target = usePathDropTarget({
+    targetDir: entry.type === "directory" ? entry.path : null,
+    run,
+    springLoad: entry.type === "directory" ? springLoad : undefined,
+  });
+
+  const props = useMemo<EntryRowDndProps>(
+    () => ({ ...source, ...target.handlers }),
+    [source, target.handlers],
+  );
+
+  return { props, isDropTarget: target.isOver };
+}

package/src/web/components/os-explorer/dnd/use-path-drop-target.ts

@@ -0,0 +1,30 @@
+/**
+ * Drop target for a surface that already knows its destination directory and has no drag
+ * source of its own: a view background, a sidebar place, a breadcrumb crumb, the tree root.
+ */
+
+import { useCallback } from "react";
+import { executeEntryDrop, type DropRunner } from "./entry-drop-executor";
+import type { DropOperation, EntryDragPayload } from "./entry-drag-payload";
+import { useEntryDropTarget, type EntryDropTargetResult } from "./use-entry-drop-target";
+
+export interface PathDropTargetOptions {
+  targetDir: string | null;
+  run: DropRunner;
+  /** Opens this destination after a rest — the project tree and Column view use it. */
+  springLoad?: () => void;
+  disabled?: boolean;
+}
+
+export function usePathDropTarget(options: PathDropTargetOptions): EntryDropTargetResult {
+  const { targetDir, run, springLoad, disabled } = options;
+
+  const onDropEntries = useCallback(
+    (payload: EntryDragPayload, op: DropOperation, dstDir: string) => {
+      void executeEntryDrop(payload, dstDir, op, run);
+    },
+    [run],
+  );
+
+  return useEntryDropTarget({ targetDir, onDropEntries, springLoad, disabled });
+}