feat(webapp): drag floating chat to edges to dock right or fullscreen

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/DashboardAgent.tsx

@@ -382,7 +382,7 @@ export function DashboardAgent({
               // Tailwind v4's important modifier is a trailing `!`, not a leading one.
               className={mode === "rightPanel" ? undefined : "overflow-visible!"}
             >
-              <FloatingAgentWindow mode={mode}>
+              <FloatingAgentWindow mode={mode} onRequestModeChange={changeMode}>
                 {({ dragHandleProps, dragHandleClassName }) => (
                   <DashboardAgentPanel
                     onClose={() => setPanelOpen(false)}

apps/webapp/app/components/dashboard-agent/panel-layout.dom.test.ts

@@ -86,6 +86,10 @@ function fakePanInfo(dx: number, dy: number): PanInfo {
   };
 }
 
+function fakePanInfoAt(point: { x: number; y: number }): PanInfo {
+  return { delta: { x: 0, y: 0 }, offset: { x: 0, y: 0 }, point, velocity: { x: 0, y: 0 } };
+}
+
 describe("the floating window's rect, wired with panel-layout's own constants", () => {
   it("renders at initialFloatingRect's position and size", () => {
     stubViewport(1200, 900);
@@ -107,19 +111,23 @@ describe("the floating window's rect, wired with panel-layout's own constants",
 
 // Mirrors the real header: a title-like element (draggable) beside a
 // `data-agent-no-drag` action (opted out), same as DashboardAgentHeader's button group.
-function renderFloatingAgentWindow() {
+function renderFloatingAgentWindow(onRequestModeChange?: (mode: DashboardAgentMode) => void) {
   let latest!: FloatingDragProps;
   function Harness() {
-    return createElement(FloatingAgentWindow, { mode: "floating" }, (drag: FloatingDragProps) => {
-      // oxlint-disable-next-line react/globals -- test harness capturing the render-prop's value.
-      latest = drag;
-      return createElement(
-        "div",
-        null,
-        createElement("span", { "data-testid": "title" }, "Chat title"),
-        createElement("button", { "data-agent-no-drag": "", "data-testid": "action" }, "Close")
-      );
-    });
+    return createElement(
+      FloatingAgentWindow,
+      { mode: "floating", onRequestModeChange },
+      (drag: FloatingDragProps) => {
+        // oxlint-disable-next-line react/globals -- test harness capturing the render-prop's value.
+        latest = drag;
+        return createElement(
+          "div",
+          null,
+          createElement("span", { "data-testid": "title" }, "Chat title"),
+          createElement("button", { "data-agent-no-drag": "", "data-testid": "action" }, "Close")
+        );
+      }
+    );
   }
   container = document.createElement("div");
   document.body.appendChild(container);
@@ -183,6 +191,82 @@ describe("FloatingAgentWindow's drag-vs-click filter", () => {
   });
 });
 
+describe("FloatingAgentWindow's drag-to-dock zones", () => {
+  it("shows the rightPanel hint while dragging near the right edge", () => {
+    stubViewport(1200, 900);
+    const view = renderFloatingAgentWindow();
+    const target = view.titleEl() as unknown as PointerEvent["target"];
+
+    act(() => {
+      view.dragHandleProps.onPanStart!({ target } as PointerEvent, fakePanInfoAt({ x: 0, y: 0 }));
+      view.dragHandleProps.onPan!({ target } as PointerEvent, fakePanInfoAt({ x: 1190, y: 400 }));
+    });
+
+    expect(document.body.textContent).toContain("Dock right");
+  });
+
+  it("calls onRequestModeChange with rightPanel on release in the right zone, without a rect jump", () => {
+    stubViewport(1200, 900);
+    const onRequestModeChange = vi.fn();
+    const view = renderFloatingAgentWindow(onRequestModeChange);
+    const target = view.titleEl() as unknown as PointerEvent["target"];
+
+    act(() => {
+      view.dragHandleProps.onPanStart!({ target } as PointerEvent, fakePanInfoAt({ x: 0, y: 0 }));
+      view.dragHandleProps.onPan!({ target } as PointerEvent, fakePanInfoAt({ x: 1190, y: 400 }));
+    });
+    const leftBeforeRelease = view.outerLeft();
+
+    act(() => {
+      view.dragHandleProps.onPanEnd!({ target } as PointerEvent, fakePanInfoAt({ x: 1190, y: 400 }));
+    });
+
+    expect(onRequestModeChange).toHaveBeenCalledTimes(1);
+    expect(onRequestModeChange).toHaveBeenCalledWith("rightPanel");
+    expect(view.outerLeft()).toBe(leftBeforeRelease);
+    expect(document.body.textContent).not.toContain("Dock right");
+  });
+
+  it("shows the fullscreen hint and requests fullscreen on release near the top edge", () => {
+    stubViewport(1200, 900);
+    const onRequestModeChange = vi.fn();
+    const view = renderFloatingAgentWindow(onRequestModeChange);
+    const target = view.titleEl() as unknown as PointerEvent["target"];
+
+    act(() => {
+      view.dragHandleProps.onPanStart!({ target } as PointerEvent, fakePanInfoAt({ x: 0, y: 0 }));
+      view.dragHandleProps.onPan!({ target } as PointerEvent, fakePanInfoAt({ x: 500, y: 5 }));
+    });
+    expect(document.body.textContent).toContain("Fullscreen");
+
+    act(() => {
+      view.dragHandleProps.onPanEnd!({ target } as PointerEvent, fakePanInfoAt({ x: 500, y: 5 }));
+    });
+
+    expect(onRequestModeChange).toHaveBeenCalledTimes(1);
+    expect(onRequestModeChange).toHaveBeenCalledWith("fullscreen");
+  });
+
+  it("does not change mode and updates the rect normally on release outside any zone", () => {
+    stubViewport(1200, 900);
+    const onRequestModeChange = vi.fn();
+    const view = renderFloatingAgentWindow(onRequestModeChange);
+    const target = view.titleEl() as unknown as PointerEvent["target"];
+    const startLeft = view.outerLeft();
+
+    act(() => {
+      view.dragHandleProps.onPanStart!({ target } as PointerEvent, fakePanInfo(0, 0));
+      view.dragHandleProps.onPan!({ target } as PointerEvent, fakePanInfo(-20, 0));
+    });
+    act(() => {
+      view.dragHandleProps.onPanEnd!({ target } as PointerEvent, fakePanInfoAt({ x: 500, y: 400 }));
+    });
+
+    expect(onRequestModeChange).not.toHaveBeenCalled();
+    expect(view.outerLeft()).not.toBe(startLeft);
+  });
+});
+
 describe("FloatingAgentWindow keeps its child mounted across every mode transition", () => {
   it("never remounts the child across any of the three modes (same tree shape always)", () => {
     let mounts = 0;

apps/webapp/app/components/dashboard-agent/panel-layout.tsx

@@ -1,13 +1,19 @@
 // Both class helpers apply to always-rendered wrappers, so switching display mode is a
 // class change only and the open chat's transport, session and transcript survive it.
 import { useMemo, useRef, useState, type CSSProperties } from "react";
+import { createPortal } from "react-dom";
 import { motion, type PanInfo } from "framer-motion";
 import {
   draggableResizeHandleClassName,
   useDraggableResizable,
   type PanHandlerProps,
   type ResizeEdge,
 } from "~/components/primitives/DraggableResizable";
+import {
+  dockZoneForPoint,
+  type DockZone,
+  type Point,
+} from "~/components/primitives/draggableResizableMath";
 import { cn } from "~/utils/cn";
 
 // Mark an element (e.g. a header button, or just its icon) with `data-agent-no-drag` so a
@@ -89,6 +95,27 @@ export function agentHiddenContentClassName(fullscreen: boolean): string {
   return cn("h-full overflow-hidden", fullscreen && "invisible");
 }
 
+const DOCK_ZONE_LABEL: Record<DockZone, string> = {
+  rightPanel: "Dock right",
+  fullscreen: "Fullscreen",
+};
+
+/** Transparent hint over the drop target, portaled so panel overflow can't clip it. */
+function DockZoneOverlay({ zone }: { zone: DockZone }) {
+  if (typeof document === "undefined") return null;
+  return createPortal(
+    <div
+      className={cn(
+        "pointer-events-none fixed z-50 flex items-center justify-center border-2 border-dashed border-text-link bg-background-dimmed/70 text-sm text-text-bright backdrop-blur-xs",
+        zone === "rightPanel" ? "inset-y-0 right-0 w-[380px]" : "inset-0"
+      )}
+    >
+      {DOCK_ZONE_LABEL[zone]}
+    </div>,
+    document.body
+  );
+}
+
 /**
  * Owns the drag-vs-click filter, so the panel and the standalone story behave identically.
  * Fullscreen needs a `relative` ancestor for `agentTakeoverClassName`, supplied by the caller.
@@ -97,9 +124,11 @@ export function agentHiddenContentClassName(fullscreen: boolean): string {
  */
 export function FloatingAgentWindow({
   mode,
+  onRequestModeChange,
   children,
 }: {
   mode: DashboardAgentMode;
+  onRequestModeChange?: (mode: DashboardAgentMode) => void;
   children: (drag: FloatingDragProps) => React.ReactNode;
 }) {
   const fullscreen = mode === "fullscreen";
@@ -111,6 +140,7 @@ export function FloatingAgentWindow({
     viewportPadding: FLOATING_MARGIN,
   });
   const [dragging, setDragging] = useState(false);
+  const [dockZone, setDockZone] = useState<DockZone | null>(null);
   // onPan can arrive before onPanStart, so the no-drag check runs once, on whichever fires first.
   const gestureClassified = useRef(false);
   const ignoringGesture = useRef(false);
@@ -121,6 +151,9 @@ export function FloatingAgentWindow({
     ignoringGesture.current = !!(event.target as HTMLElement | null)?.closest(NO_DRAG_SELECTOR);
   };
 
+  const zoneForPoint = (point: Point) =>
+    dockZoneForPoint(point, { width: window.innerWidth, height: window.innerHeight });
+
   // Same shape as `dragHandleProps` below empty, so a mode with no drag doesn't change types.
   const filteredDragHandleProps: Partial<PanHandlerProps> =
     fullscreen || docked
@@ -135,56 +168,67 @@ export function FloatingAgentWindow({
           onPan: (event: PointerEvent, info: PanInfo) => {
             classifyGesture(event);
             if (ignoringGesture.current) return;
+            setDockZone(zoneForPoint(info.point));
             dragHandleProps.onPan?.(event, info);
           },
           onPanEnd: (event: PointerEvent, info: PanInfo) => {
+            const wasIgnoring = ignoringGesture.current;
             gestureClassified.current = false;
             ignoringGesture.current = false;
             setDragging(false);
+            setDockZone(null);
+            const droppedZone = wasIgnoring ? null : zoneForPoint(info.point);
+            if (droppedZone) {
+              onRequestModeChange?.(droppedZone);
+              return;
+            }
             dragHandleProps.onPanEnd?.(event, info);
           },
         };
 
   // Same two-`div` shape in all three modes — only classes/style change — so switching `mode`
   // never unmounts `children`; only className/style differ.
   return (
-    <div
-      style={fullscreen || docked ? CLEARED_FLOATING_STYLE : style}
-      className={
-        fullscreen
-          ? agentTakeoverClassName(true)
-          : docked
-            ? "flex h-full flex-col"
-            : "z-30 flex flex-col rounded-lg border border-border-bright bg-background-bright shadow-2xl"
-      }
-    >
-      {/* Clips content to the rounded corners without clipping the resize handles below,
-          which sit half outside this box's edges. */}
+    <>
+      {dragging && dockZone && <DockZoneOverlay zone={dockZone} />}
       <div
-        className={cn(
-          "flex min-h-0 flex-1 flex-col",
-          !fullscreen && !docked && "overflow-hidden rounded-lg"
-        )}
+        style={fullscreen || docked ? CLEARED_FLOATING_STYLE : style}
+        className={
+          fullscreen
+            ? agentTakeoverClassName(true)
+            : docked
+              ? "flex h-full flex-col"
+              : "z-30 flex flex-col rounded-lg border border-border-bright bg-background-bright shadow-2xl"
+        }
       >
-        {/* oxlint-disable-next-line react/refs -- the ref is only read inside event handlers, not during render. */}
-        {children({
-          dragHandleProps: filteredDragHandleProps,
-          dragHandleClassName:
-            fullscreen || docked
-              ? ""
-              : cn("select-none touch-none", dragging ? "cursor-grabbing" : "cursor-grab"),
-        })}
+        {/* Clips content to the rounded corners without clipping the resize handles below,
+          which sit half outside this box's edges. */}
+        <div
+          className={cn(
+            "flex min-h-0 flex-1 flex-col",
+            !fullscreen && !docked && "overflow-hidden rounded-lg"
+          )}
+        >
+          {/* oxlint-disable-next-line react/refs -- the ref is only read inside event handlers, not during render. */}
+          {children({
+            dragHandleProps: filteredDragHandleProps,
+            dragHandleClassName:
+              fullscreen || docked
+                ? ""
+                : cn("select-none touch-none", dragging ? "cursor-grabbing" : "cursor-grab"),
+          })}
+        </div>
+        {!fullscreen &&
+          !docked &&
+          RESIZE_EDGES.map((edge) => (
+            <motion.div
+              key={edge}
+              {...resizeHandleProps(edge)}
+              className={draggableResizeHandleClassName(edge)}
+            />
+          ))}
       </div>
-      {!fullscreen &&
-        !docked &&
-        RESIZE_EDGES.map((edge) => (
-          <motion.div
-            key={edge}
-            {...resizeHandleProps(edge)}
-            className={draggableResizeHandleClassName(edge)}
-          />
-        ))}
-    </div>
+    </>
   );
 }
 

apps/webapp/app/components/primitives/draggableResizableMath.test.ts

@@ -6,10 +6,31 @@ import {
   clampPosition,
   clampRectToViewport,
   clampSize,
+  dockZoneForPoint,
   resizeRect,
   type Rect,
 } from "./draggableResizableMath";
 
+describe("dockZoneForPoint", () => {
+  const viewport = { width: 1200, height: 900 };
+
+  it("targets rightPanel near the right edge", () => {
+    expect(dockZoneForPoint({ x: 1180, y: 400 }, viewport)).toBe("rightPanel");
+  });
+
+  it("targets fullscreen near the top edge", () => {
+    expect(dockZoneForPoint({ x: 600, y: 10 }, viewport)).toBe("fullscreen");
+  });
+
+  it("prefers rightPanel in the top-right corner", () => {
+    expect(dockZoneForPoint({ x: 1180, y: 10 }, viewport)).toBe("rightPanel");
+  });
+
+  it("returns null away from every edge", () => {
+    expect(dockZoneForPoint({ x: 600, y: 400 }, viewport)).toBeNull();
+  });
+});
+
 describe("clamp", () => {
   it("clamps to the bounds", () => {
     expect(clamp(5, 0, 10)).toBe(5);

apps/webapp/app/components/primitives/draggableResizableMath.ts

@@ -103,6 +103,21 @@ export function applyDragDelta(
   return { ...current, ...nextPosition };
 }
 
+export type DockZone = "rightPanel" | "fullscreen";
+
+export const DOCK_ZONE_SIZE = 48;
+
+/** Right edge wins the top-right corner, matching which hint the overlay shows there. */
+export function dockZoneForPoint(
+  point: Point,
+  viewport: Viewport,
+  zoneSize = DOCK_ZONE_SIZE
+): DockZone | null {
+  if (point.x >= viewport.width - zoneSize) return "rightPanel";
+  if (point.y <= zoneSize) return "fullscreen";
+  return null;
+}
+
 /** Resize counterpart of {@link applyDragDelta} — same incremental-step rationale. */
 export function applyResizeDelta(
   edge: ResizeEdge,