@pyreon/dnd 0.11.0

package/lib/types/index.d.ts

@@ -0,0 +1,236 @@
+//#region src/types.d.ts
+/** Data attached to a draggable item. */
+type DragData = Record<string, unknown>;
+/** Position of a drop relative to the target element. */
+type DropEdge = "top" | "bottom" | "left" | "right";
+/** Drop location information. */
+interface DropLocation {
+  /** The edge closest to the drop point. */
+  edge: DropEdge | null;
+  /** Custom data attached to the drop target. */
+  data: DragData;
+}
+interface UseDraggableOptions<T extends DragData = DragData> {
+  /** Ref callback or element getter for the draggable element. */
+  element: () => HTMLElement | null;
+  /** Data to transfer on drag. Can be a function for dynamic data. */
+  data: T | (() => T);
+  /** Optional drag handle element (subset of the draggable). */
+  handle?: () => HTMLElement | null;
+  /** Whether dragging is disabled. Reactive. */
+  disabled?: boolean | (() => boolean);
+  /** Called when drag starts. */
+  onDragStart?: () => void;
+  /** Called when drag ends (drop or cancel). */
+  onDragEnd?: () => void;
+}
+interface UseDraggableResult {
+  /** Whether this element is currently being dragged. */
+  isDragging: () => boolean;
+}
+interface UseDroppableOptions<T extends DragData = DragData> {
+  /** Ref callback or element getter for the drop target. */
+  element: () => HTMLElement | null;
+  /** Data to attach to the drop target. */
+  data?: T | (() => T);
+  /** Filter what can be dropped. Return false to reject. */
+  canDrop?: (sourceData: DragData) => boolean;
+  /** Called when a draggable enters this target. */
+  onDragEnter?: (sourceData: DragData) => void;
+  /** Called when a draggable leaves this target. */
+  onDragLeave?: () => void;
+  /** Called when an item is dropped on this target. */
+  onDrop?: (sourceData: DragData) => void;
+}
+interface UseDroppableResult {
+  /** Whether something is currently being dragged over this target. */
+  isOver: () => boolean;
+}
+interface UseSortableOptions<T> {
+  /** Reactive list of items to sort. */
+  items: () => T[];
+  /** Key extractor — matches Pyreon's <For by={...}> pattern. */
+  by: (item: T) => string | number;
+  /** Called with the reordered items after a drop. */
+  onReorder: (items: T[]) => void;
+  /** Sort axis. Default: "vertical". */
+  axis?: "vertical" | "horizontal";
+}
+interface UseSortableResult {
+  /** Attach to the scroll container. */
+  containerRef: (el: HTMLElement) => void;
+  /** Attach to each sortable item. Call with the item's key. */
+  itemRef: (key: string | number) => (el: HTMLElement) => void;
+  /** The key of the currently dragging item. */
+  activeId: () => string | number | null;
+  /** The key of the item being hovered over. */
+  overId: () => string | number | null;
+  /** The closest edge of the hovered item ("top"/"bottom" or "left"/"right"). */
+  overEdge: () => DropEdge | null;
+}
+//#endregion
+//#region src/use-drag-monitor.d.ts
+interface UseDragMonitorOptions {
+  /** Called on any drag start in the page. */
+  onDragStart?: (data: DragData) => void;
+  /** Called on any drop in the page. */
+  onDrop?: (sourceData: DragData, targetData: DragData) => void;
+  /** Filter which drags to monitor. */
+  canMonitor?: (data: DragData) => boolean;
+}
+interface UseDragMonitorResult {
+  /** Whether any element is currently being dragged. */
+  isDragging: () => boolean;
+  /** Data of the currently dragging element (null if not dragging). */
+  dragData: () => DragData | null;
+}
+/**
+ * Monitor all drag operations on the page.
+ * Useful for global drag indicators, analytics, or coordination between
+ * multiple drag-and-drop areas.
+ *
+ * @example
+ * ```tsx
+ * const { isDragging, dragData } = useDragMonitor({
+ *   canMonitor: (data) => data.type === "card",
+ *   onDrop: (source, target) => logDrop(source, target),
+ * })
+ *
+ * <Show when={isDragging()}>
+ *   <div class="global-drag-overlay">
+ *     Dragging: {() => dragData()?.name}
+ *   </div>
+ * </Show>
+ * ```
+ */
+declare function useDragMonitor(options?: UseDragMonitorOptions): UseDragMonitorResult;
+//#endregion
+//#region src/use-draggable.d.ts
+/**
+ * Make an element draggable with signal-driven state.
+ *
+ * @example
+ * ```tsx
+ * let cardEl: HTMLElement | null = null
+ *
+ * const { isDragging } = useDraggable({
+ *   element: () => cardEl,
+ *   data: { id: card.id, type: "card" },
+ * })
+ *
+ * <div ref={(el) => cardEl = el} class={isDragging() ? "opacity-50" : ""}>
+ *   {card.title}
+ * </div>
+ * ```
+ */
+declare function useDraggable<T extends DragData = DragData>(options: UseDraggableOptions<T>): UseDraggableResult;
+//#endregion
+//#region src/use-droppable.d.ts
+/**
+ * Make an element a drop target with signal-driven state.
+ *
+ * @example
+ * ```tsx
+ * let zoneEl: HTMLElement | null = null
+ *
+ * const { isOver } = useDroppable({
+ *   element: () => zoneEl,
+ *   onDrop: (data) => handleDrop(data),
+ *   canDrop: (data) => data.type === "card",
+ * })
+ *
+ * <div ref={(el) => zoneEl = el} class={isOver() ? "bg-blue-50" : ""}>
+ *   Drop here
+ * </div>
+ * ```
+ */
+declare function useDroppable<T extends DragData = DragData>(options: UseDroppableOptions<T>): UseDroppableResult;
+//#endregion
+//#region src/use-file-drop.d.ts
+interface UseFileDropOptions {
+  /** Element getter for the drop zone. */
+  element: () => HTMLElement | null;
+  /** Called when files are dropped. */
+  onDrop: (files: File[]) => void;
+  /** Filter accepted file types (e.g. ["image/*", ".pdf"]). */
+  accept?: string[];
+  /** Maximum number of files. */
+  maxFiles?: number;
+  /** Whether drop is disabled. */
+  disabled?: boolean | (() => boolean);
+}
+interface UseFileDropResult {
+  /** Whether files are being dragged over the drop zone. */
+  isOver: () => boolean;
+  /** Whether files are being dragged anywhere on the page. */
+  isDraggingFiles: () => boolean;
+}
+/**
+ * File drop zone with signal-driven state.
+ * Uses the native file drag events via pragmatic-drag-and-drop.
+ *
+ * @example
+ * ```tsx
+ * let dropZone: HTMLElement | null = null
+ *
+ * const { isOver, isDraggingFiles } = useFileDrop({
+ *   element: () => dropZone,
+ *   accept: ["image/*", ".pdf"],
+ *   maxFiles: 5,
+ *   onDrop: (files) => upload(files),
+ * })
+ *
+ * <div
+ *   ref={(el) => dropZone = el}
+ *   class={isOver() ? "drop-active" : isDraggingFiles() ? "drop-ready" : ""}
+ * >
+ *   Drop files here
+ * </div>
+ * ```
+ */
+declare function useFileDrop(options: UseFileDropOptions): UseFileDropResult;
+//#endregion
+//#region src/use-sortable.d.ts
+/**
+ * Sortable list with signal-driven state, auto-scroll, and edge detection.
+ *
+ * Features:
+ * - Keyed drag items matching `<For by={...}>` pattern
+ * - Auto-scroll when dragging near container edges
+ * - Closest-edge detection (drop above/below or left/right)
+ * - Axis constraint (vertical/horizontal)
+ * - Keyboard reordering (Alt+Arrow keys)
+ *
+ * @example
+ * ```tsx
+ * const items = signal([
+ *   { id: "1", name: "Alice" },
+ *   { id: "2", name: "Bob" },
+ *   { id: "3", name: "Charlie" },
+ * ])
+ *
+ * const { containerRef, itemRef, activeId, overId, overEdge } = useSortable({
+ *   items,
+ *   by: (item) => item.id,
+ *   onReorder: (newItems) => items.set(newItems),
+ * })
+ *
+ * <ul ref={containerRef}>
+ *   <For each={items()} by={item => item.id}>
+ *     {(item) => (
+ *       <li
+ *         ref={itemRef(item.id)}
+ *         class={activeId() === item.id ? "dragging" : ""}
+ *         style={overId() === item.id ? `border-${overEdge()}: 2px solid blue` : ""}
+ *       >
+ *         {item.name}
+ *       </li>
+ *     )}
+ *   </For>
+ * </ul>
+ * ```
+ */
+declare function useSortable<T>(options: UseSortableOptions<T>): UseSortableResult;
+//#endregion
+export { type DragData, type DropEdge, type DropLocation, type UseDragMonitorOptions, type UseDragMonitorResult, type UseDraggableOptions, type UseDraggableResult, type UseDroppableOptions, type UseDroppableResult, type UseFileDropOptions, type UseFileDropResult, type UseSortableOptions, type UseSortableResult, useDragMonitor, useDraggable, useDroppable, useFileDrop, useSortable };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/use-drag-monitor.ts","../../../src/use-draggable.ts","../../../src/use-droppable.ts","../../../src/use-file-drop.ts","../../../src/use-sortable.ts"],"mappings":";;KACY,QAAA,GAAW,MAAA;;KAGX,QAAA;;UAGK,YAAA;EAHL;EAKV,IAAA,EAAM,QAAA;;EAEN,IAAA,EAAM,QAAA;AAAA;AAAA,UAKS,mBAAA,WAA8B,QAAA,GAAW,QAAA;EAT7B;EAW3B,OAAA,QAAe,WAAA;EAPD;EASd,IAAA,EAAM,CAAA,UAAW,CAAA;EAXX;EAaN,MAAA,SAAe,WAAA;EAXT;EAaN,QAAA;EAbc;EAed,WAAA;EAVkC;EAYlC,SAAA;AAAA;AAAA,UAGe,kBAAA;EAbA;EAef,UAAA;AAAA;AAAA,UAKe,mBAAA,WAA8B,QAAA,GAAW,QAAA;EAhB9B;EAkB1B,OAAA,QAAe,WAAA;EAxBoB;EA0BnC,IAAA,GAAO,CAAA,UAAW,CAAA;EA1BsC;EA4BxD,OAAA,IAAW,UAAA,EAAY,QAAA;EA1BR;EA4Bf,WAAA,IAAe,UAAA,EAAY,QAAA;EA1BrB;EA4BN,WAAA;EA1BA;EA4BA,MAAA,IAAU,UAAA,EAAY,QAAA;AAAA;AAAA,UAGP,kBAAA;EAzBf;EA2BA,MAAA;AAAA;AAAA,UAKe,kBAAA;EA7BkB;EA+BjC,KAAA,QAAa,CAAA;EA7Bb;EA+BA,EAAA,GAAK,IAAA,EAAM,CAAA;EA1BI;EA4Bf,SAAA,GAAY,KAAA,EAAO,CAAA;EA5Be;EA8BlC,IAAA;AAAA;AAAA,UAGe,iBAAA;EA7BR;EA+BP,YAAA,GAAe,EAAA,EAAI,WAAA;EA7BI;EA+BvB,OAAA,GAAU,GAAA,uBAA0B,EAAA,EAAI,WAAA;EAzBlB;EA2BtB,QAAA;EA3B8B;EA6B9B,MAAA;EAzC6C;EA2C7C,QAAA,QAAgB,QAAA;AAAA;;;UC7ED,qBAAA;EDHG;ECKlB,WAAA,IAAe,IAAA,EAAM,QAAA;EDLA;ECOrB,MAAA,IAAU,UAAA,EAAY,QAAA,EAAU,UAAA,EAAY,QAAA;EDJlC;ECMV,UAAA,IAAc,IAAA,EAAM,QAAA;AAAA;AAAA,UAGL,oBAAA;EDTG;ECWlB,UAAA;EDR2B;ECU3B,QAAA,QAAgB,QAAA;AAAA;;;;;;;ADDlB;;;;;;;;;;;;;iBCuBgB,cAAA,CAAe,OAAA,GAAU,qBAAA,GAAwB,oBAAA;;;ADtCjE;;;;;AAGA;;;;;AAGA;;;;;;;AANA,iBEoBgB,YAAA,WAAuB,QAAA,GAAW,QAAA,CAAA,CAChD,OAAA,EAAS,mBAAA,CAAoB,CAAA,IAC5B,kBAAA;;;AFtBH;;;;;AAGA;;;;;AAGA;;;;;;;;AANA,iBGqBgB,YAAA,WAAuB,QAAA,GAAW,QAAA,CAAA,CAChD,OAAA,EAAS,mBAAA,CAAoB,CAAA,IAC5B,kBAAA;;;UCjBc,kBAAA;EJNL;EIQV,OAAA,QAAe,WAAA;;EAEf,MAAA,GAAS,KAAA,EAAO,IAAA;EJVW;EIY3B,MAAA;EJTkB;EIWlB,QAAA;EJXkB;EIalB,QAAA;AAAA;AAAA,UAGe,iBAAA;;EAEf,MAAA;EJbA;EIeA,eAAA;AAAA;;;;AJRF;;;;;;;;;;;;;;;;;;;;iBIkCgB,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,iBAAA;;;AJjD1D;;;;;AAGA;;;;;AAGA;;;;;;;;;;AASA;;;;;;;;;;;;;;;;;;;AAfA,iBKsDgB,WAAA,GAAA,CAAe,OAAA,EAAS,kBAAA,CAAmB,CAAA,IAAK,iBAAA"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@pyreon/dnd",
+  "version": "0.11.0",
+  "description": "Signal-driven drag and drop for Pyreon — wraps @atlaskit/pragmatic-drag-and-drop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/pyreon.git",
+    "directory": "packages/fundamentals/dnd"
+  },
+  "bugs": {
+    "url": "https://github.com/pyreon/pyreon/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check ."
+  },
+  "dependencies": {
+    "@atlaskit/pragmatic-drag-and-drop": "^1.7.0",
+    "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "^2.0.0",
+    "@atlaskit/pragmatic-drag-and-drop-hitbox": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@pyreon/core": "^0.11.0",
+    "@pyreon/reactivity": "^0.11.0"
+  },
+  "devDependencies": {
+    "@pyreon/typescript": "^0.11.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export type {
+  DragData,
+  DropEdge,
+  DropLocation,
+  UseDraggableOptions,
+  UseDraggableResult,
+  UseDroppableOptions,
+  UseDroppableResult,
+  UseSortableOptions,
+  UseSortableResult,
+} from "./types"
+
+export type { UseDragMonitorOptions, UseDragMonitorResult } from "./use-drag-monitor"
+export { useDragMonitor } from "./use-drag-monitor"
+
+export { useDraggable } from "./use-draggable"
+export { useDroppable } from "./use-droppable"
+export type { UseFileDropOptions, UseFileDropResult } from "./use-file-drop"
+export { useFileDrop } from "./use-file-drop"
+export { useSortable } from "./use-sortable"

package/src/tests/dnd.test.ts

@@ -0,0 +1,281 @@
+import { signal } from "@pyreon/reactivity"
+import { describe, expect, it } from "vitest"
+
+// ─── useDraggable ───────────────────────────────────────────────────────────
+
+describe("useDraggable", () => {
+  it("exports useDraggable", async () => {
+    const { useDraggable } = await import("../index")
+    expect(typeof useDraggable).toBe("function")
+  })
+
+  it("returns isDragging signal initialized to false", async () => {
+    const { useDraggable } = await import("../use-draggable")
+    const el = document.createElement("div")
+    const { isDragging } = useDraggable({ element: () => el, data: { id: "1" } })
+    expect(isDragging()).toBe(false)
+  })
+
+  it("accepts function data for dynamic values", async () => {
+    const { useDraggable } = await import("../use-draggable")
+    const el = document.createElement("div")
+    const counter = signal(0)
+    const { isDragging } = useDraggable({
+      element: () => el,
+      data: () => ({ count: counter() }),
+    })
+    expect(isDragging()).toBe(false)
+  })
+
+  it("accepts disabled as boolean", async () => {
+    const { useDraggable } = await import("../use-draggable")
+    const el = document.createElement("div")
+    const { isDragging } = useDraggable({
+      element: () => el,
+      data: { id: "1" },
+      disabled: true,
+    })
+    expect(isDragging()).toBe(false)
+  })
+
+  it("accepts disabled as reactive getter", async () => {
+    const { useDraggable } = await import("../use-draggable")
+    const el = document.createElement("div")
+    const disabled = signal(false)
+    const { isDragging } = useDraggable({
+      element: () => el,
+      data: { id: "1" },
+      disabled,
+    })
+    expect(isDragging()).toBe(false)
+  })
+
+  it("handles null element gracefully", async () => {
+    const { useDraggable } = await import("../use-draggable")
+    const { isDragging } = useDraggable({
+      element: () => null,
+      data: { id: "1" },
+    })
+    expect(isDragging()).toBe(false)
+  })
+})
+
+// ─── useDroppable ───────────────────────────────────────────────────────────
+
+describe("useDroppable", () => {
+  it("exports useDroppable", async () => {
+    const { useDroppable } = await import("../index")
+    expect(typeof useDroppable).toBe("function")
+  })
+
+  it("returns isOver signal initialized to false", async () => {
+    const { useDroppable } = await import("../use-droppable")
+    const el = document.createElement("div")
+    const { isOver } = useDroppable({ element: () => el, onDrop: () => {} })
+    expect(isOver()).toBe(false)
+  })
+
+  it("accepts canDrop filter", async () => {
+    const { useDroppable } = await import("../use-droppable")
+    const el = document.createElement("div")
+    const { isOver } = useDroppable({
+      element: () => el,
+      canDrop: (data) => data.type === "card",
+      onDrop: () => {},
+    })
+    expect(isOver()).toBe(false)
+  })
+
+  it("handles null element gracefully", async () => {
+    const { useDroppable } = await import("../use-droppable")
+    const { isOver } = useDroppable({ element: () => null, onDrop: () => {} })
+    expect(isOver()).toBe(false)
+  })
+})
+
+// ─── useSortable ────────────────────────────────────────────────────────────
+
+describe("useSortable", () => {
+  it("exports useSortable", async () => {
+    const { useSortable } = await import("../index")
+    expect(typeof useSortable).toBe("function")
+  })
+
+  it("returns full sortable API with overEdge", async () => {
+    const { useSortable } = await import("../use-sortable")
+    const items = signal([
+      { id: "1", name: "A" },
+      { id: "2", name: "B" },
+      { id: "3", name: "C" },
+    ])
+
+    const result = useSortable({
+      items,
+      by: (item) => item.id,
+      onReorder: (newItems) => items.set(newItems),
+    })
+
+    expect(typeof result.containerRef).toBe("function")
+    expect(typeof result.itemRef).toBe("function")
+    expect(result.activeId()).toBeNull()
+    expect(result.overId()).toBeNull()
+    expect(result.overEdge()).toBeNull()
+  })
+
+  it("itemRef returns a ref callback per key", async () => {
+    const { useSortable } = await import("../use-sortable")
+    const items = signal([{ id: "1" }, { id: "2" }])
+
+    const { itemRef } = useSortable({
+      items,
+      by: (item) => item.id,
+      onReorder: () => {},
+    })
+
+    const ref1 = itemRef("1")
+    const ref2 = itemRef("2")
+    expect(typeof ref1).toBe("function")
+    expect(typeof ref2).toBe("function")
+    expect(ref1).not.toBe(ref2)
+  })
+
+  it("itemRef sets accessibility attributes on elements", async () => {
+    const { useSortable } = await import("../use-sortable")
+    const items = signal([{ id: "1" }])
+
+    const { itemRef } = useSortable({
+      items,
+      by: (item) => item.id,
+      onReorder: () => {},
+    })
+
+    const el = document.createElement("div")
+    itemRef("1")(el)
+
+    expect(el.getAttribute("role")).toBe("listitem")
+    expect(el.getAttribute("aria-roledescription")).toBe("sortable item")
+    expect(el.getAttribute("tabindex")).toBe("0")
+    expect(el.dataset.pyreonSortKey).toBe("1")
+  })
+
+  it("does not override existing tabindex", async () => {
+    const { useSortable } = await import("../use-sortable")
+    const items = signal([{ id: "1" }])
+
+    const { itemRef } = useSortable({
+      items,
+      by: (item) => item.id,
+      onReorder: () => {},
+    })
+
+    const el = document.createElement("div")
+    el.setAttribute("tabindex", "-1")
+    itemRef("1")(el)
+
+    expect(el.getAttribute("tabindex")).toBe("-1")
+  })
+
+  it("supports horizontal axis", async () => {
+    const { useSortable } = await import("../use-sortable")
+    const items = signal([{ id: "1" }, { id: "2" }])
+
+    const result = useSortable({
+      items,
+      by: (item) => item.id,
+      onReorder: () => {},
+      axis: "horizontal",
+    })
+
+    expect(result.activeId()).toBeNull()
+  })
+})
+
+// ─── useFileDrop ────────────────────────────────────────────────────────────
+
+describe("useFileDrop", () => {
+  it("exports useFileDrop", async () => {
+    const { useFileDrop } = await import("../index")
+    expect(typeof useFileDrop).toBe("function")
+  })
+
+  it("returns isOver and isDraggingFiles signals", async () => {
+    const { useFileDrop } = await import("../use-file-drop")
+    const el = document.createElement("div")
+    const { isOver, isDraggingFiles } = useFileDrop({
+      element: () => el,
+      onDrop: () => {},
+    })
+    expect(isOver()).toBe(false)
+    expect(isDraggingFiles()).toBe(false)
+  })
+
+  it("accepts accept filter and maxFiles", async () => {
+    const { useFileDrop } = await import("../use-file-drop")
+    const el = document.createElement("div")
+    const { isOver } = useFileDrop({
+      element: () => el,
+      accept: ["image/*", ".pdf"],
+      maxFiles: 5,
+      onDrop: () => {},
+    })
+    expect(isOver()).toBe(false)
+  })
+
+  it("accepts disabled option", async () => {
+    const { useFileDrop } = await import("../use-file-drop")
+    const el = document.createElement("div")
+    const disabled = signal(true)
+    const { isOver } = useFileDrop({
+      element: () => el,
+      disabled,
+      onDrop: () => {},
+    })
+    expect(isOver()).toBe(false)
+  })
+})
+
+// ─── useDragMonitor ─────────────────────────────────────────────────────────
+
+describe("useDragMonitor", () => {
+  it("exports useDragMonitor", async () => {
+    const { useDragMonitor } = await import("../index")
+    expect(typeof useDragMonitor).toBe("function")
+  })
+
+  it("returns isDragging and dragData signals", async () => {
+    const { useDragMonitor } = await import("../use-drag-monitor")
+    const { isDragging, dragData } = useDragMonitor()
+    expect(isDragging()).toBe(false)
+    expect(dragData()).toBeNull()
+  })
+
+  it("accepts canMonitor filter", async () => {
+    const { useDragMonitor } = await import("../use-drag-monitor")
+    const { isDragging } = useDragMonitor({
+      canMonitor: (data) => data.type === "card",
+    })
+    expect(isDragging()).toBe(false)
+  })
+
+  it("accepts onDragStart and onDrop callbacks", async () => {
+    const { useDragMonitor } = await import("../use-drag-monitor")
+    const { isDragging } = useDragMonitor({
+      onDragStart: () => {},
+      onDrop: () => {},
+    })
+    expect(isDragging()).toBe(false)
+  })
+})
+
+// ─── Module exports ─────────────────────────────────────────────────────────
+
+describe("module exports", () => {
+  it("exports all 5 hooks", async () => {
+    const mod = await import("../index")
+    expect(mod.useDraggable).toBeDefined()
+    expect(mod.useDroppable).toBeDefined()
+    expect(mod.useSortable).toBeDefined()
+    expect(mod.useFileDrop).toBeDefined()
+    expect(mod.useDragMonitor).toBeDefined()
+  })
+})

package/src/types.ts

@@ -0,0 +1,83 @@
+/** Data attached to a draggable item. */
+export type DragData = Record<string, unknown>
+
+/** Position of a drop relative to the target element. */
+export type DropEdge = "top" | "bottom" | "left" | "right"
+
+/** Drop location information. */
+export interface DropLocation {
+  /** The edge closest to the drop point. */
+  edge: DropEdge | null
+  /** Custom data attached to the drop target. */
+  data: DragData
+}
+
+// ─── useDraggable ───────────────────────────────────────────────────────────
+
+export interface UseDraggableOptions<T extends DragData = DragData> {
+  /** Ref callback or element getter for the draggable element. */
+  element: () => HTMLElement | null
+  /** Data to transfer on drag. Can be a function for dynamic data. */
+  data: T | (() => T)
+  /** Optional drag handle element (subset of the draggable). */
+  handle?: () => HTMLElement | null
+  /** Whether dragging is disabled. Reactive. */
+  disabled?: boolean | (() => boolean)
+  /** Called when drag starts. */
+  onDragStart?: () => void
+  /** Called when drag ends (drop or cancel). */
+  onDragEnd?: () => void
+}
+
+export interface UseDraggableResult {
+  /** Whether this element is currently being dragged. */
+  isDragging: () => boolean
+}
+
+// ─── useDroppable ───────────────────────────────────────────────────────────
+
+export interface UseDroppableOptions<T extends DragData = DragData> {
+  /** Ref callback or element getter for the drop target. */
+  element: () => HTMLElement | null
+  /** Data to attach to the drop target. */
+  data?: T | (() => T)
+  /** Filter what can be dropped. Return false to reject. */
+  canDrop?: (sourceData: DragData) => boolean
+  /** Called when a draggable enters this target. */
+  onDragEnter?: (sourceData: DragData) => void
+  /** Called when a draggable leaves this target. */
+  onDragLeave?: () => void
+  /** Called when an item is dropped on this target. */
+  onDrop?: (sourceData: DragData) => void
+}
+
+export interface UseDroppableResult {
+  /** Whether something is currently being dragged over this target. */
+  isOver: () => boolean
+}
+
+// ─── useSortable ────────────────────────────────────────────────────────────
+
+export interface UseSortableOptions<T> {
+  /** Reactive list of items to sort. */
+  items: () => T[]
+  /** Key extractor — matches Pyreon's <For by={...}> pattern. */
+  by: (item: T) => string | number
+  /** Called with the reordered items after a drop. */
+  onReorder: (items: T[]) => void
+  /** Sort axis. Default: "vertical". */
+  axis?: "vertical" | "horizontal"
+}
+
+export interface UseSortableResult {
+  /** Attach to the scroll container. */
+  containerRef: (el: HTMLElement) => void
+  /** Attach to each sortable item. Call with the item's key. */
+  itemRef: (key: string | number) => (el: HTMLElement) => void
+  /** The key of the currently dragging item. */
+  activeId: () => string | number | null
+  /** The key of the item being hovered over. */
+  overId: () => string | number | null
+  /** The closest edge of the hovered item ("top"/"bottom" or "left"/"right"). */
+  overEdge: () => DropEdge | null
+}