@leavepulse/ui 0.96.2 → 0.97.0

package/dist/chunks/{LpHints-wsawHZCP.js → LpHints-lGLsGxOx.js}

@@ -4,7 +4,7 @@ import { useAppleKeyboard, appleModifierLabel } from "../composables/useHotkeys.
 import { useLabels } from "../composables/useLpConfig.js";
 import { _ as _sfc_main$3 } from "./LpActionBar-DuwBawji.js";
 import { _ as _sfc_main$2 } from "./LpHintLayer-rD3BTMfK.js";
-import { _ as _sfc_main$1 } from "./LpTour-iZNl_vdy.js";
+import { _ as _sfc_main$1 } from "./LpTour-DUzpkD8W.js";
 const _sfc_main = /* @__PURE__ */ defineComponent({
   __name: "LpHints",
   props: {

package/dist/chunks/{LpTour-iZNl_vdy.js → LpTour-DUzpkD8W.js}

@@ -149,6 +149,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       clearTimeout(glide);
       glide = window.setTimeout(() => gliding.value = false, durationToken("duration-medium", void 0, doc()) + 40);
     }
+    let shownRaw = void 0;
     function measure() {
       viewport.value = { width: win().innerWidth, height: win().innerHeight };
       const el = target.value;
@@ -156,7 +157,11 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
         box.value = null;
         return;
       }
-      if (!el.isConnected) return;
+      if (!el.isConnected) {
+        const again = resolve(shownRaw);
+        glideTo(again && again.getClientRects().length ? again : null);
+        return;
+      }
       const r = el.getBoundingClientRect();
       const prev = box.value;
       if (!prev || prev.x !== r.x || prev.y !== r.y || prev.width !== r.width || prev.height !== r.height) {
@@ -193,6 +198,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       }
       const el = current.enter || sampled.value ? await waitFor(raw, mine) : resolve(raw);
       if (mine !== token) return;
+      shownRaw = raw;
       if (!el || !el.getClientRects().length) return skip();
       await settled(el);
       if (mine !== token) return;

package/dist/components/LpHints.vue.js

@@ -1,4 +1,4 @@
-import { _ as _sfc_main } from "../chunks/LpHints-wsawHZCP.js";
+import { _ as _sfc_main } from "../chunks/LpHints-lGLsGxOx.js";
 export {
   _sfc_main as default
 };

package/dist/components/LpTour.vue.js

@@ -1,4 +1,4 @@
-import { _ as _sfc_main } from "../chunks/LpTour-iZNl_vdy.js";
+import { _ as _sfc_main } from "../chunks/LpTour-DUzpkD8W.js";
 export {
   _sfc_main as default
 };

package/dist/composables/scroll.d.ts

@@ -12,7 +12,12 @@ export declare function scrollParent(el: Element | null | undefined, { axis, sel
  */
 export declare function atScrollEnd(el: Element | null | undefined, slack?: number): boolean;
 export interface ScrollToElementOptions {
-    /** `nearest` scrolls only when the element is out of view. */
+    /**
+     * `nearest` scrolls only when the element is out of view. An element taller
+     * than the scroller is brought in by its start whatever the block: centring
+     * or meeting its far edge would show its middle or end, and a list that
+     * loads more at its end would start loading.
+     */
     block?: "nearest" | "center" | "start";
     behavior?: ScrollBehavior;
     /** Room kept between the element and the scroller's edge. */

package/dist/composables/scroll.js

@@ -35,8 +35,10 @@ function scrollToElement(el, { block = "nearest", behavior = "auto", margin = 0,
   const lo = x ? inner.left - outer.left : inner.top - outer.top;
   const hi = x ? inner.right - outer.right : inner.bottom - outer.bottom;
   const at = lo + from;
+  const fits = size + 2 * margin <= view;
   let target = from;
   if (block === "start") target = at - margin;
+  else if (!fits) target = lo < margin || lo > view - margin || block === "center" ? at - margin : from;
   else if (block === "center") target = at - (view - size) / 2;
   else if (lo < margin) target = at - margin;
   else if (hi > -margin) target = at - view + size + margin;

package/dist/composables/useDragDrop.d.ts

@@ -0,0 +1,19 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+export interface UseDragDropOptions<I, Z> {
+    /** The element that holds the items and the zones. */
+    root: Ref<HTMLElement | null>;
+    /** Turn dragging off without unmounting (e.g. read-only). */
+    enabled?: MaybeRefOrGetter<boolean>;
+    /** Map an item's `data-drag-key` to the item. Defaults to the string itself. */
+    item?: (raw: string) => I | undefined;
+    /** Map a zone's `data-drop-zone` to the zone. Defaults to the string itself. */
+    zone?: (raw: string) => Z | undefined;
+    /** Whether this item may land in this zone; a refused zone is not highlighted. */
+    canDrop?: (item: I, zone: Z) => boolean;
+    /** The item landed in a zone other than the one it came from. */
+    onDrop: (item: I, zone: Z, from: Z | undefined) => void;
+}
+export declare function useDragDrop<I = string, Z = string>(options: UseDragDropOptions<I, Z>): {
+    dragging: Readonly<Ref<import("vue").DeepReadonly<I> | null, import("vue").DeepReadonly<I> | null>>;
+    over: Readonly<Ref<import("vue").DeepReadonly<Z> | null, import("vue").DeepReadonly<Z> | null>>;
+};

package/dist/composables/useDragDrop.js

@@ -0,0 +1,241 @@
+import { HOLD_TO_DRAG_MS, TOUCH_SLOP, MOUSE_SLOP } from "./gesture.js";
+import { ref, onMounted, onBeforeUnmount, readonly, toValue } from "vue";
+import { prefersReducedMotion, durationToken } from "./easing.js";
+import { scrollParent } from "./scroll.js";
+import { nodeWindow } from "./realm.js";
+const EDGE_PX = 48;
+const SCROLL_STEP = 14;
+const NO_DRAG = "button, a, input, textarea, select, [contenteditable=''], [contenteditable='true'], [data-no-drag]";
+function useDragDrop(options) {
+  const toItem = options.item ?? ((raw) => raw);
+  const toZone = options.zone ?? ((raw) => raw);
+  const enabled = () => toValue(options.enabled) ?? true;
+  const hostWindow = () => options.root.value ? nodeWindow(options.root.value) : window;
+  let drag = null;
+  let pending = null;
+  let swallowClick = false;
+  let frame = 0;
+  const dragging = ref(null);
+  const over = ref(null);
+  function zoneOf(el) {
+    const zone = el?.closest("[data-drop-zone]") ?? null;
+    return zone && options.root.value?.contains(zone) ? zone : null;
+  }
+  function accepts(zoneEl) {
+    if (!zoneEl || !drag) return void 0;
+    const zone = toZone(zoneEl.dataset.dropZone ?? "");
+    if (zone === void 0 || zone === drag.from) return void 0;
+    return !options.canDrop || options.canDrop(drag.item, zone) ? zone : void 0;
+  }
+  function cancelPending() {
+    if (pending?.timer) clearTimeout(pending.timer);
+    pending = null;
+  }
+  function begin(el, x, y) {
+    const item = toItem(el.dataset.dragKey ?? "");
+    if (item === void 0) return;
+    const box = el.getBoundingClientRect();
+    const ghost = el.cloneNode(true);
+    ghost.removeAttribute("data-drag-key");
+    ghost.removeAttribute("id");
+    ghost.setAttribute("aria-hidden", "true");
+    Object.assign(ghost.style, {
+      position: "fixed",
+      left: `${box.left}px`,
+      top: `${box.top}px`,
+      width: `${box.width}px`,
+      height: `${box.height}px`,
+      margin: "0",
+      pointerEvents: "none",
+      zIndex: "var(--z-tooltip)",
+      boxShadow: "var(--shadow-panel)",
+      opacity: "0.95",
+      transform: "translate3d(0, 0, 0) scale(1.02)",
+      transition: "none"
+    });
+    el.ownerDocument.body.append(ghost);
+    const fromZone = zoneOf(el);
+    drag = {
+      item,
+      from: fromZone ? toZone(fromZone.dataset.dropZone ?? "") : void 0,
+      source: el,
+      ghost,
+      dx: x - box.left,
+      dy: y - box.top,
+      x,
+      y,
+      over: null,
+      scroller: scrollParent(options.root.value)
+    };
+    el.setAttribute("data-drag-source", "");
+    dragging.value = item;
+    hostWindow().getSelection()?.removeAllRanges();
+    if (options.root.value) options.root.value.style.userSelect = "none";
+    follow();
+    if (!frame) frame = requestAnimationFrame(tick);
+  }
+  function follow() {
+    if (!drag) return;
+    const box = drag.source.getBoundingClientRect();
+    drag.ghost.style.left = `${drag.x - drag.dx}px`;
+    drag.ghost.style.top = `${drag.y - drag.dy}px`;
+    drag.ghost.style.width = `${box.width}px`;
+    const zoneEl = zoneOf(drag.source.ownerDocument.elementFromPoint(drag.x, drag.y));
+    const zone = accepts(zoneEl);
+    const target = zone === void 0 ? null : zoneEl;
+    if (target !== drag.over) {
+      drag.over?.removeAttribute("data-drop-over");
+      target?.setAttribute("data-drop-over", "");
+      drag.over = target;
+      over.value = zone ?? null;
+    }
+  }
+  function tick() {
+    frame = 0;
+    if (!drag) return;
+    const box = drag.scroller?.getBoundingClientRect() ?? { top: 0, bottom: hostWindow().innerHeight };
+    const delta = drag.y > box.bottom - EDGE_PX ? SCROLL_STEP : drag.y < box.top + EDGE_PX ? -SCROLL_STEP : 0;
+    if (delta) {
+      if (drag.scroller) drag.scroller.scrollTop += delta;
+      else hostWindow().scrollBy(0, delta);
+      follow();
+    }
+    frame = requestAnimationFrame(tick);
+  }
+  function finish(drop) {
+    cancelPending();
+    const done = drag;
+    if (!done) return;
+    drag = null;
+    if (frame) cancelAnimationFrame(frame);
+    frame = 0;
+    if (options.root.value) options.root.value.style.userSelect = "";
+    done.over?.removeAttribute("data-drop-over");
+    done.source.removeAttribute("data-drag-source");
+    dragging.value = null;
+    over.value = null;
+    swallowClick = true;
+    setTimeout(() => swallowClick = false, 0);
+    const zone = drop && done.over ? toZone(done.over.dataset.dropZone ?? "") : void 0;
+    if (zone !== void 0) {
+      done.ghost.remove();
+      options.onDrop(done.item, zone, done.from);
+      return;
+    }
+    settle(done);
+  }
+  function settle(done) {
+    if (prefersReducedMotion(hostWindow()) || !done.source.isConnected) {
+      done.ghost.remove();
+      return;
+    }
+    const home = done.source.getBoundingClientRect();
+    const ghost = done.ghost;
+    const ms = durationToken("duration-medium", void 0, done.source.ownerDocument);
+    ghost.style.transition = `left ${ms}ms var(--ease-emphasized), top ${ms}ms var(--ease-emphasized), opacity ${ms}ms ease-out`;
+    ghost.style.left = `${home.left}px`;
+    ghost.style.top = `${home.top}px`;
+    ghost.style.opacity = "0";
+    setTimeout(() => ghost.remove(), ms);
+  }
+  function onPointerDown(event) {
+    if (!enabled() || event.button !== 0 || drag) return;
+    const target = event.target;
+    const el = target?.closest("[data-drag-key]");
+    if (!el || !options.root.value?.contains(el)) return;
+    const control = target?.closest(NO_DRAG);
+    if (control && el.contains(control)) return;
+    cancelPending();
+    const touch = event.pointerType === "touch";
+    pending = { el, pointerId: event.pointerId, x: event.clientX, y: event.clientY, touch, timer: null };
+    if (!touch) return;
+    const { clientX: x, clientY: y } = event;
+    pending.timer = setTimeout(() => {
+      if (!pending) return;
+      const held = pending.el;
+      pending = null;
+      begin(held, x, y);
+      navigator.vibrate?.(8);
+    }, HOLD_TO_DRAG_MS);
+  }
+  function onMove(event) {
+    if (pending && event.pointerId === pending.pointerId) {
+      const moved = Math.hypot(event.clientX - pending.x, event.clientY - pending.y);
+      if (pending.touch) {
+        if (moved > TOUCH_SLOP) cancelPending();
+        return;
+      }
+      if (moved <= MOUSE_SLOP) return;
+      const { el, x, y } = pending;
+      pending = null;
+      begin(el, x, y);
+    }
+    if (!drag) return;
+    drag.x = event.clientX;
+    drag.y = event.clientY;
+    follow();
+  }
+  function onUp() {
+    cancelPending();
+    finish(true);
+  }
+  function onCancel() {
+    cancelPending();
+    finish(false);
+  }
+  function onKey(event) {
+    if (event.key !== "Escape" || !drag) return;
+    event.preventDefault();
+    event.stopPropagation();
+    finish(false);
+  }
+  function onClickCapture(event) {
+    if (!swallowClick) return;
+    swallowClick = false;
+    event.stopPropagation();
+    event.preventDefault();
+  }
+  function onContextMenu(event) {
+    if (!drag && !swallowClick) return;
+    event.preventDefault();
+    event.stopPropagation();
+  }
+  function onTouchMove(event) {
+    if (drag) event.preventDefault();
+  }
+  function onNativeDrag(event) {
+    if (pending || drag) event.preventDefault();
+  }
+  let listening = null;
+  let rootEl = null;
+  onMounted(() => {
+    listening = hostWindow();
+    rootEl = options.root.value;
+    rootEl?.addEventListener("pointerdown", onPointerDown);
+    rootEl?.addEventListener("touchmove", onTouchMove, { passive: false });
+    rootEl?.addEventListener("dragstart", onNativeDrag);
+    listening.addEventListener("pointermove", onMove);
+    listening.addEventListener("pointerup", onUp);
+    listening.addEventListener("pointercancel", onCancel);
+    listening.addEventListener("keydown", onKey, true);
+    listening.addEventListener("click", onClickCapture, true);
+    listening.addEventListener("contextmenu", onContextMenu, true);
+  });
+  onBeforeUnmount(() => {
+    finish(false);
+    swallowClick = false;
+    rootEl?.removeEventListener("pointerdown", onPointerDown);
+    rootEl?.removeEventListener("touchmove", onTouchMove);
+    rootEl?.removeEventListener("dragstart", onNativeDrag);
+    listening?.removeEventListener("pointermove", onMove);
+    listening?.removeEventListener("pointerup", onUp);
+    listening?.removeEventListener("pointercancel", onCancel);
+    listening?.removeEventListener("keydown", onKey, true);
+    listening?.removeEventListener("click", onClickCapture, true);
+    listening?.removeEventListener("contextmenu", onContextMenu, true);
+  });
+  return { dragging: readonly(dragging), over: readonly(over) };
+}
+export {
+  useDragDrop
+};

package/dist/index.d.ts

@@ -297,6 +297,8 @@ export type { PersistedOptions } from "./composables/usePersisted";
 export { useMergedClass, useMergedAttrs, mergeClass } from "./composables/useMergedClass";
 export { anchorPattern, stripDisallowed, useInputFilter } from "./composables/useInputFilter";
 export { usePaintSelect } from "./composables/usePaintSelect";
+export { useDragDrop } from "./composables/useDragDrop";
+export type { UseDragDropOptions } from "./composables/useDragDrop";
 export type { UsePaintSelectOptions } from "./composables/usePaintSelect";
 export { LP_FIELD, fieldMessageId, provideField, useField, useFieldControl } from "./composables/useField";
 export { FIELD_NOTICE_MS, useFieldNotice } from "./composables/useFieldNotice";

package/dist/index.js

@@ -127,10 +127,10 @@ import { _ as _83 } from "./chunks/LpThemeSwitcher-CnkIH76z.js";
 import { _ as _84 } from "./chunks/LpTilt-B7KHX1zH.js";
 import { _ as _85 } from "./chunks/LpToaster-CGHXxCie.js";
 import { _ as _86 } from "./chunks/LpTooltip-CzIfznts.js";
-import { _ as _87 } from "./chunks/LpTour-iZNl_vdy.js";
+import { _ as _87 } from "./chunks/LpTour-DUzpkD8W.js";
 import { holeOf, openContextMenu, panelsAround } from "./components/tour.js";
 import { _ as _88 } from "./chunks/LpHintLayer-rD3BTMfK.js";
-import { _ as _89 } from "./chunks/LpHints-wsawHZCP.js";
+import { _ as _89 } from "./chunks/LpHints-lGLsGxOx.js";
 import { HINT_SIGNALS, contextMenuTip, createHintSystem, dropzoneTip, hintKey, hintSummary, hotkeyTip, localHintStorage, noteDropzone, noteHotkeyTarget, paletteTip, provideHintSystem, runningHintSystem, useHintSystem } from "./composables/useHintSystem.js";
 import { _ as _90 } from "./chunks/LpTooltipProvider-CftjV7Xc.js";
 import { _ as _91 } from "./chunks/LpTopologyCanvas-DKn0Xcz4.js";
@@ -166,6 +166,7 @@ import { useOptimisticToggle } from "./composables/useOptimisticToggle.js";
 import { mergeClass, useMergedAttrs, useMergedClass } from "./composables/useMergedClass.js";
 import { anchorPattern, stripDisallowed, useInputFilter } from "./composables/useInputFilter.js";
 import { usePaintSelect } from "./composables/usePaintSelect.js";
+import { useDragDrop } from "./composables/useDragDrop.js";
 import { LP_FIELD, fieldMessageId, provideField, useField, useFieldControl } from "./composables/useField.js";
 import { FIELD_NOTICE_MS, useFieldNotice } from "./composables/useFieldNotice.js";
 import { easeOut, easeTravel, easingToken, prefersReducedMotion } from "./composables/easing.js";
@@ -1316,6 +1317,7 @@ export {
   useCloseGuard,
   useCommands,
   useConfirm,
+  useDragDrop,
   useField,
   useFieldControl,
   useFieldNotice,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leavepulse/ui",
-  "version": "0.96.2",
+  "version": "0.97.0",
   "type": "module",
   "description": "LeavePulse token-driven Vue component kit.",
   "repository": {

package/src/components/LpTour.vue

@@ -256,6 +256,11 @@ function glideTo(el: Element | null) {
   glide = window.setTimeout(() => (gliding.value = false), durationToken("duration-medium", undefined, doc()) + 40)
 }
 
+// What the shown step points at, kept to find it again: a list that re-renders
+// replaces the element, and a card anchored to the old one would hang over
+// nothing (or nowhere) with the page dimmed under it.
+let shownRaw: TourStep["target"] = undefined
+
 function measure() {
   viewport.value = { width: win().innerWidth, height: win().innerHeight }
   const el = target.value
@@ -263,7 +268,11 @@ function measure() {
     box.value = null
     return
   }
-  if (!el.isConnected) return
+  if (!el.isConnected) {
+    const again = resolve(shownRaw)
+    glideTo(again && again.getClientRects().length ? again : null)
+    return
+  }
   const r = el.getBoundingClientRect()
   const prev = box.value
   if (!prev || prev.x !== r.x || prev.y !== r.y || prev.width !== r.width || prev.height !== r.height) {
@@ -302,6 +311,7 @@ async function show(): Promise<void> {
   }
   const el = current.enter || sampled.value ? await waitFor(raw, mine) : resolve(raw)
   if (mine !== token) return
+  shownRaw = raw
   if (!el || !el.getClientRects().length) return skip()
   await settled(el)
   if (mine !== token) return

package/src/composables/scroll.ts

@@ -40,7 +40,12 @@ export function atScrollEnd(el: Element | null | undefined, slack = 2): boolean
 }
 
 export interface ScrollToElementOptions {
-  /** `nearest` scrolls only when the element is out of view. */
+  /**
+   * `nearest` scrolls only when the element is out of view. An element taller
+   * than the scroller is brought in by its start whatever the block: centring
+   * or meeting its far edge would show its middle or end, and a list that
+   * loads more at its end would start loading.
+   */
   block?: "nearest" | "center" | "start"
   behavior?: ScrollBehavior
   /** Room kept between the element and the scroller's edge. */
@@ -76,8 +81,10 @@ export function scrollToElement(
   const lo = x ? inner.left - outer.left : inner.top - outer.top
   const hi = x ? inner.right - outer.right : inner.bottom - outer.bottom
   const at = lo + from
+  const fits = size + 2 * margin <= view
   let target = from
   if (block === "start") target = at - margin
+  else if (!fits) target = lo < margin || lo > view - margin || block === "center" ? at - margin : from
   else if (block === "center") target = at - (view - size) / 2
   else if (lo < margin) target = at - margin
   else if (hi > -margin) target = at - view + size + margin

package/src/composables/useDragDrop.ts

@@ -0,0 +1,331 @@
+import { HOLD_TO_DRAG_MS, MOUSE_SLOP, TOUCH_SLOP } from "./gesture"
+import { onBeforeUnmount, onMounted, readonly, ref, toValue, type MaybeRefOrGetter, type Ref } from "vue"
+import { durationToken, prefersReducedMotion } from "./easing"
+import { scrollParent } from "./scroll"
+import { nodeWindow } from "./useView"
+
+/*
+ * Moving things between places by dragging them: a person from one team to
+ * another, a card to another column, a row back to the pool. The page marks
+ * what can be picked up with `data-drag-key` and where it can land with
+ * `data-drop-zone`; this composable does the rest and reports a drop as
+ * (item, zone, from).
+ *
+ *   const dnd = useDragDrop({ root, onDrop: (item, zone) => move(item, zone) })
+ *   <div ref="root">
+ *     <section data-drop-zone="team-a"><div data-drag-key="u1">Ada</div></section>
+ *     <section data-drop-zone="pool" />
+ *   </div>
+ *
+ * A mouse or pen starts dragging once it moves a few pixels, so a click on the
+ * item stays a click. A finger holds still for HOLD_TO_DRAG_MS first, so a
+ * swipe through the list still scrolls it, and the long press does not open
+ * the context menu once it has turned into a drag. Controls inside an item
+ * (buttons, links, fields, `data-no-drag`) never start one.
+ *
+ * While dragging, a copy of the item follows the pointer, the item itself
+ * carries `data-drag-source` and the zone under the pointer `data-drop-over`,
+ * for styling (`data-[drop-over]:border-brand`). Near the edge of the
+ * scrolling box the page scrolls on its own. A drop on the zone the item came
+ * from, on a zone `canDrop` refuses or outside every zone is no drop: the copy
+ * glides back. Escape cancels.
+ *
+ * Dragging is a shortcut, never the only way: whatever a drop does should also
+ * be reachable from a menu or a button, for the keyboard and screen readers.
+ */
+export interface UseDragDropOptions<I, Z> {
+  /** The element that holds the items and the zones. */
+  root: Ref<HTMLElement | null>
+  /** Turn dragging off without unmounting (e.g. read-only). */
+  enabled?: MaybeRefOrGetter<boolean>
+  /** Map an item's `data-drag-key` to the item. Defaults to the string itself. */
+  item?: (raw: string) => I | undefined
+  /** Map a zone's `data-drop-zone` to the zone. Defaults to the string itself. */
+  zone?: (raw: string) => Z | undefined
+  /** Whether this item may land in this zone; a refused zone is not highlighted. */
+  canDrop?: (item: I, zone: Z) => boolean
+  /** The item landed in a zone other than the one it came from. */
+  onDrop: (item: I, zone: Z, from: Z | undefined) => void
+}
+
+const EDGE_PX = 48
+const SCROLL_STEP = 14
+const NO_DRAG = "button, a, input, textarea, select, [contenteditable=''], [contenteditable='true'], [data-no-drag]"
+
+interface Drag<I, Z> {
+  item: I
+  from: Z | undefined
+  source: HTMLElement
+  ghost: HTMLElement
+  dx: number
+  dy: number
+  x: number
+  y: number
+  over: HTMLElement | null
+  scroller: HTMLElement | null
+}
+
+interface Pending {
+  el: HTMLElement
+  pointerId: number
+  x: number
+  y: number
+  touch: boolean
+  timer: ReturnType<typeof setTimeout> | null
+}
+
+export function useDragDrop<I = string, Z = string>(options: UseDragDropOptions<I, Z>) {
+  const toItem = options.item ?? ((raw: string) => raw as unknown as I)
+  const toZone = options.zone ?? ((raw: string) => raw as unknown as Z)
+  const enabled = () => toValue(options.enabled) ?? true
+  const hostWindow = (): Window => (options.root.value ? nodeWindow(options.root.value) : window)
+
+  let drag: Drag<I, Z> | null = null
+  let pending: Pending | null = null
+  let swallowClick = false
+  let frame = 0
+  const dragging = ref<I | null>(null) as Ref<I | null>
+  const over = ref<Z | null>(null) as Ref<Z | null>
+
+  function zoneOf(el: Element | null): HTMLElement | null {
+    const zone = el?.closest<HTMLElement>("[data-drop-zone]") ?? null
+    return zone && options.root.value?.contains(zone) ? zone : null
+  }
+
+  function accepts(zoneEl: HTMLElement | null): Z | undefined {
+    if (!zoneEl || !drag) return undefined
+    const zone = toZone(zoneEl.dataset.dropZone ?? "")
+    if (zone === undefined || zone === drag.from) return undefined
+    return !options.canDrop || options.canDrop(drag.item, zone) ? zone : undefined
+  }
+
+  function cancelPending() {
+    if (pending?.timer) clearTimeout(pending.timer)
+    pending = null
+  }
+
+  function begin(el: HTMLElement, x: number, y: number) {
+    const item = toItem(el.dataset.dragKey ?? "")
+    if (item === undefined) return
+    const box = el.getBoundingClientRect()
+    const ghost = el.cloneNode(true) as HTMLElement
+    ghost.removeAttribute("data-drag-key")
+    ghost.removeAttribute("id")
+    ghost.setAttribute("aria-hidden", "true")
+    Object.assign(ghost.style, {
+      position: "fixed",
+      left: `${box.left}px`,
+      top: `${box.top}px`,
+      width: `${box.width}px`,
+      height: `${box.height}px`,
+      margin: "0",
+      pointerEvents: "none",
+      zIndex: "var(--z-tooltip)",
+      boxShadow: "var(--shadow-panel)",
+      opacity: "0.95",
+      transform: "translate3d(0, 0, 0) scale(1.02)",
+      transition: "none",
+    })
+    el.ownerDocument.body.append(ghost)
+    const fromZone = zoneOf(el)
+    drag = {
+      item,
+      from: fromZone ? toZone(fromZone.dataset.dropZone ?? "") : undefined,
+      source: el,
+      ghost,
+      dx: x - box.left,
+      dy: y - box.top,
+      x,
+      y,
+      over: null,
+      scroller: scrollParent(options.root.value),
+    }
+    el.setAttribute("data-drag-source", "")
+    dragging.value = item
+    hostWindow().getSelection()?.removeAllRanges()
+    if (options.root.value) options.root.value.style.userSelect = "none"
+    follow()
+    if (!frame) frame = requestAnimationFrame(tick)
+  }
+
+  function follow() {
+    if (!drag) return
+    const box = drag.source.getBoundingClientRect()
+    drag.ghost.style.left = `${drag.x - drag.dx}px`
+    drag.ghost.style.top = `${drag.y - drag.dy}px`
+    drag.ghost.style.width = `${box.width}px`
+    const zoneEl = zoneOf(drag.source.ownerDocument.elementFromPoint(drag.x, drag.y))
+    const zone = accepts(zoneEl)
+    const target = zone === undefined ? null : zoneEl
+    if (target !== drag.over) {
+      drag.over?.removeAttribute("data-drop-over")
+      target?.setAttribute("data-drop-over", "")
+      drag.over = target
+      over.value = zone ?? null
+    }
+  }
+
+  function tick() {
+    frame = 0
+    if (!drag) return
+    const box = drag.scroller?.getBoundingClientRect() ?? { top: 0, bottom: hostWindow().innerHeight }
+    const delta = drag.y > box.bottom - EDGE_PX ? SCROLL_STEP : drag.y < box.top + EDGE_PX ? -SCROLL_STEP : 0
+    if (delta) {
+      if (drag.scroller) drag.scroller.scrollTop += delta
+      else hostWindow().scrollBy(0, delta)
+      follow()
+    }
+    frame = requestAnimationFrame(tick)
+  }
+
+  function finish(drop: boolean) {
+    cancelPending()
+    const done = drag
+    if (!done) return
+    drag = null
+    if (frame) cancelAnimationFrame(frame)
+    frame = 0
+    if (options.root.value) options.root.value.style.userSelect = ""
+    done.over?.removeAttribute("data-drop-over")
+    done.source.removeAttribute("data-drag-source")
+    dragging.value = null
+    over.value = null
+    swallowClick = true
+    setTimeout(() => (swallowClick = false), 0)
+    const zone = drop && done.over ? toZone(done.over.dataset.dropZone ?? "") : undefined
+    if (zone !== undefined) {
+      done.ghost.remove()
+      options.onDrop(done.item, zone, done.from)
+      return
+    }
+    settle(done)
+  }
+
+  // A drag that landed nowhere glides back to where the item still is.
+  function settle(done: Drag<I, Z>) {
+    if (prefersReducedMotion(hostWindow()) || !done.source.isConnected) {
+      done.ghost.remove()
+      return
+    }
+    const home = done.source.getBoundingClientRect()
+    const ghost = done.ghost
+    const ms = durationToken("duration-medium", undefined, done.source.ownerDocument)
+    ghost.style.transition = `left ${ms}ms var(--ease-emphasized), top ${ms}ms var(--ease-emphasized), opacity ${ms}ms ease-out`
+    ghost.style.left = `${home.left}px`
+    ghost.style.top = `${home.top}px`
+    ghost.style.opacity = "0"
+    setTimeout(() => ghost.remove(), ms)
+  }
+
+  function onPointerDown(event: PointerEvent) {
+    if (!enabled() || event.button !== 0 || drag) return
+    const target = event.target as Element | null
+    const el = target?.closest<HTMLElement>("[data-drag-key]")
+    if (!el || !options.root.value?.contains(el)) return
+    const control = target?.closest(NO_DRAG)
+    if (control && el.contains(control)) return
+    cancelPending()
+    const touch = event.pointerType === "touch"
+    pending = { el, pointerId: event.pointerId, x: event.clientX, y: event.clientY, touch, timer: null }
+    if (!touch) return
+    const { clientX: x, clientY: y } = event
+    pending.timer = setTimeout(() => {
+      if (!pending) return
+      const held = pending.el
+      pending = null
+      begin(held, x, y)
+      navigator.vibrate?.(8)
+    }, HOLD_TO_DRAG_MS)
+  }
+
+  function onMove(event: PointerEvent) {
+    if (pending && event.pointerId === pending.pointerId) {
+      const moved = Math.hypot(event.clientX - pending.x, event.clientY - pending.y)
+      if (pending.touch) {
+        if (moved > TOUCH_SLOP) cancelPending()
+        return
+      }
+      if (moved <= MOUSE_SLOP) return
+      const { el, x, y } = pending
+      pending = null
+      begin(el, x, y)
+    }
+    if (!drag) return
+    drag.x = event.clientX
+    drag.y = event.clientY
+    follow()
+  }
+
+  function onUp() {
+    cancelPending()
+    finish(true)
+  }
+
+  function onCancel() {
+    cancelPending()
+    finish(false)
+  }
+
+  function onKey(event: KeyboardEvent) {
+    if (event.key !== "Escape" || !drag) return
+    event.preventDefault()
+    event.stopPropagation()
+    finish(false)
+  }
+
+  function onClickCapture(event: MouseEvent) {
+    if (!swallowClick) return
+    swallowClick = false
+    event.stopPropagation()
+    event.preventDefault()
+  }
+
+  // A long press is also how a finger asks for the context menu; once it has
+  // turned into a drag, that menu would open over it.
+  function onContextMenu(event: Event) {
+    if (!drag && !swallowClick) return
+    event.preventDefault()
+    event.stopPropagation()
+  }
+
+  // A finger that has started dragging must not scroll the page under it.
+  function onTouchMove(event: TouchEvent) {
+    if (drag) event.preventDefault()
+  }
+
+  // The browser's own drag of a link or an image would take over the pointer.
+  function onNativeDrag(event: DragEvent) {
+    if (pending || drag) event.preventDefault()
+  }
+
+  let listening: Window | null = null
+  let rootEl: HTMLElement | null = null
+  onMounted(() => {
+    listening = hostWindow()
+    rootEl = options.root.value
+    rootEl?.addEventListener("pointerdown", onPointerDown)
+    rootEl?.addEventListener("touchmove", onTouchMove, { passive: false })
+    rootEl?.addEventListener("dragstart", onNativeDrag)
+    listening.addEventListener("pointermove", onMove)
+    listening.addEventListener("pointerup", onUp)
+    listening.addEventListener("pointercancel", onCancel)
+    listening.addEventListener("keydown", onKey, true)
+    listening.addEventListener("click", onClickCapture, true)
+    listening.addEventListener("contextmenu", onContextMenu, true)
+  })
+  onBeforeUnmount(() => {
+    finish(false)
+    swallowClick = false
+    rootEl?.removeEventListener("pointerdown", onPointerDown)
+    rootEl?.removeEventListener("touchmove", onTouchMove)
+    rootEl?.removeEventListener("dragstart", onNativeDrag)
+    listening?.removeEventListener("pointermove", onMove)
+    listening?.removeEventListener("pointerup", onUp)
+    listening?.removeEventListener("pointercancel", onCancel)
+    listening?.removeEventListener("keydown", onKey, true)
+    listening?.removeEventListener("click", onClickCapture, true)
+    listening?.removeEventListener("contextmenu", onContextMenu, true)
+  })
+
+  return { dragging: readonly(dragging), over: readonly(over) }
+}

package/src/index.ts

@@ -459,6 +459,8 @@ export type { PersistedOptions } from "./composables/usePersisted"
 export { useMergedClass, useMergedAttrs, mergeClass } from "./composables/useMergedClass"
 export { anchorPattern, stripDisallowed, useInputFilter } from "./composables/useInputFilter"
 export { usePaintSelect } from "./composables/usePaintSelect"
+export { useDragDrop } from "./composables/useDragDrop"
+export type { UseDragDropOptions } from "./composables/useDragDrop"
 export type { UsePaintSelectOptions } from "./composables/usePaintSelect"
 export { LP_FIELD, fieldMessageId, provideField, useField, useFieldControl } from "./composables/useField"
 export { FIELD_NOTICE_MS, useFieldNotice } from "./composables/useFieldNotice"