Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

8.6 KB
Raw Blame
/**
 * Drag-and-drop file upload logic (#311), kept DOM-free so it can be unit-tested.
 *
 * Dropping files onto the chat area is a third entry point into the composer's existing
 * attachment intake (after the "+" menu pickers and image paste); everything here is about
 * deciding, not doing:
 *   - which drags count as file drags at all (`isFileDrag`) — text selections, in-app drags
 *     such as the sidebar's session and group reorders (each a custom MIME for exactly this
 *     reason) and dragged page images must never light the overlay;
 *   - what the chat area's drop zone should do with one drag event (`dropRegionAction`) —
 *     show the overlay, claim the drag, take the files, or stand aside;
 *   - which staged intake a dropped file belongs to (`splitMediaFiles`) — images join the
 *     pasted-image pipeline, videos the video one, everything else joins the file-attachment
 *     pipeline;
 *   - the app-shell fallback (`guardWindowDragOver` / `guardWindowDrop`) — anywhere no drop
 *     zone claimed the drag, the browser's default is to navigate to the dropped file,
 *     silently replacing the app; the guard cancels that default for file drags only, so
 *     native text drag-and-drop (e.g. dropping selected text into the composer) keeps
 *     working.
 *
 * The two halves are deliberately different in scope. The drop zone is confined to the chat
 * area: overlay, copy cursor and attachment happen only there. The guard is app-wide and
 * entirely silent — no overlay, no attachment, no toast — because the alternative to
 * cancelling the default is the browser navigating the tab to the dropped file and discarding
 * the running app along with any unsent draft. Outside the chat area the gesture is inert,
 * not destructive.
 */

/**
 * True when a drag carries OS files: `DataTransfer.types` contains `"Files"`. Every other
 * drag — text selections (`text/plain`), links, dragged `<img>` elements (`text/uri-list`),
 * the sidebar's session-reorder and group-reorder MIMEs — lacks it and must be left to its
 * native behavior.
 * Accepts null/undefined because `dataTransfer` is nullable on the DOM event type.
 */
export function isFileDrag(types: readonly string[] | null | undefined): boolean {
  return types !== null && types !== undefined && types.includes("Files");
}

/**
 * The drag lifecycle moments the chat area's drop zone listens for, on `window` so it sees
 * the drag wherever it goes:
 *   - `over`   — `dragover`, the authoritative signal. It fires continuously while a drag is
 *                anywhere over the page (per spec at least every 350ms) and names the element
 *                currently under the pointer, so it answers "is the drag over the chat area
 *                right now" outright, with no state to accumulate.
 *   - `leave`  — `dragleave`, needed for one case `over` cannot cover: once the drag leaves
 *                the window entirely, `dragover` simply stops firing, and without this the
 *                last "inside" answer would stand forever.
 *   - `drop`   — the release.
 *   - `end`    — `dragend`, which only fires for drags that STARTED in this page (an OS file
 *                drag ends with drop or dragleave instead); cheap insurance for in-page sources.
 */
export type DragSignal = "over" | "leave" | "drop" | "end";

/** What the chat area's drop zone should do about one drag event. */
export interface DropRegionAction {
  /** Whether the region overlay should be showing once this event has been handled. */
  readonly active: boolean;
  /** Claim the drag: `preventDefault` plus the copy cursor. Cancelling `dragover` is also what makes a later `drop` fire at all. */
  readonly claim: boolean;
  /** Hand this event's files to the composer's attachment intake. */
  readonly accept: boolean;
}

/**
 * The drop zone's whole decision, as a pure function of the current event — never of an
 * accumulated count.
 *
 * `inside` is "the drag is over the chat area once this event has been applied": the event
 * target for `over` and `drop`, the *related* target for `leave` (where the drag is heading —
 * `null`, i.e. outside, when it left the window). That asymmetry is the point: a `dragleave`
 * whose related target is still inside the region is nothing but an internal element
 * boundary being crossed, and must not disturb the overlay.
 *
 * Being stateless is what makes the overlay impossible to strand. The obvious alternative —
 * a dragenter/dragleave depth counter — is an accumulator whose only unconditional resets
 * are `drop` and `dragend`, and neither fires for a file drag that ends outside the browser;
 * one missed `dragleave` would leave the counter permanently off by one, with the overlay
 * stuck on screen. Here, every `dragover` re-derives the answer from scratch, so any missed
 * event is corrected by the next one within a frame.
 */
export function dropRegionAction(
  signal: DragSignal,
  fileDrag: boolean,
  inside: boolean,
): DropRegionAction {
  const over = fileDrag && inside;
  switch (signal) {
    // The drag is over the region: show the overlay and claim the drag, so the browser
    // delivers the drop here instead of applying its navigate-to-file default.
    case "over":
      return { active: over, claim: over, accept: false };
    // Only a departure matters. Still inside (crossed into a child) → nothing changes;
    // gone from the region or from the window → hide. Claiming a dragleave would be
    // meaningless, so it never does.
    case "leave":
      return { active: over, claim: false, accept: false };
    // The release. Files are taken only when they were released inside the region — a drop
    // on the sidebar or a docked panel reaches the app-shell guard instead and does nothing.
    case "drop":
      return { active: false, claim: over, accept: over };
    // The drag is over, wherever it ended.
    case "end":
      return { active: false, claim: false, accept: false };
  }
}

/**
 * Splits one batch by MIME kind, preserving order within each side: images ride the message as
 * `image_url` parts exactly like pasted images, videos as `video_url` parts (the third intake — a
 * dropped or pasted clip is staged like an image, sized like neither), everything else becomes a
 * file attachment (scratchpad + `[attached file: <path>]` line). The drop zone's partition is the
 * composer's own for every entry point — paste and the two "+" pickers call it too — so a file of
 * one kind cannot be routed two ways depending on how it arrived. Generic over "has a MIME type" so
 * tests don't need a DOM `File`.
 */
export function splitMediaFiles<T extends { readonly type: string }>(
  dropped: Iterable<T>,
): { images: T[]; videos: T[]; files: T[] } {
  const images: T[] = [];
  const videos: T[] = [];
  const files: T[] = [];
  for (const item of dropped) {
    if (item.type.startsWith("image/")) images.push(item);
    else if (item.type.startsWith("video/")) videos.push(item);
    else files.push(item);
  }
  return { images, videos, files };
}

/**
 * The slice of a DragEvent the guards read/write — structural, so DOM `DragEvent` satisfies
 * it and tests can pass plain objects (the vitest environment has no DOM).
 */
export interface DragGuardEvent {
  readonly defaultPrevented: boolean;
  preventDefault(): void;
  readonly dataTransfer: {
    readonly types: readonly string[];
    dropEffect: string;
  } | null;
}

/**
 * Window-level dragover fallback for the whole app shell. Runs after the chat area's drop
 * zone on the bubble path, so `defaultPrevented` is exactly "the chat area claimed this
 * drag": when it did not — the pointer is over the sidebar, the top bar, a docked panel, or
 * a page with no composer at all — cancel the default and show the no-drop cursor, an honest
 * "dropping here does nothing" instead of the browser's copy cursor over a page that would
 * navigate away. Non-file drags pass through untouched (see isFileDrag).
 */
export function guardWindowDragOver(e: DragGuardEvent): void {
  if (e.defaultPrevented || !isFileDrag(e.dataTransfer?.types)) return;
  e.preventDefault();
  if (e.dataTransfer) e.dataTransfer.dropEffect = "none";
}

/**
 * Window-level drop fallback, paired with guardWindowDragOver: cancels the browser's default
 * open-file navigation for any file drop the chat area did not claim. It attaches nothing and
 * says nothing — outside the chat area a file drop is simply inert. Text/link drops keep
 * their native behavior (dropping text into the composer textarea must still insert it).
 */
export function guardWindowDrop(e: DragGuardEvent): void {
  if (e.defaultPrevented || !isFileDrag(e.dataTransfer?.types)) return;
  e.preventDefault();
}