@mk-drag-and-drop/dom 0.2.0 → 0.4.0

package/README.md

@@ -36,6 +36,8 @@ The root export includes:
 - `createDropContainer`
 - `createSortable`
 - `createDragHandle`
+- controller types: `DragController`, `DragControllerOptions`,
+  `DragControllerOverlayInput`, `DragControllerAnnouncements`
 - lifecycle types: `DragStartEvent`, `DragUpdateEvent`, `DragEndEvent`,
   `DropEvent`, `DragSource`, `DragEndResult`, `DragLifecycleCallbacks`,
   `DragLifecycleHelpers`
@@ -94,6 +96,11 @@ The returned controller has:
 
 - `remeasureDropTargets(input?)`: remeasures all targets, one target id, an
   array of target ids, or `{ group }`
+- `remeasureOverlay()`: remeasures the currently mounted drag overlay element;
+  it is a safe no-op when no overlay is mounted or no drag is active
+- `recomputeActiveDrag()`: reruns active targeting and drag update from the
+  last pointer position; it is a safe no-op when no drag is active and does not
+  remeasure drop targets
 
 The controller does not expose runtime teardown, disposal, update, or broad
 overlay removal methods. Runtime objects are ordinary JavaScript objects; DOM
@@ -108,6 +115,14 @@ controller calls `dragOverlay` once more for the `"released"` phase and passes
 `removeOverlay`; call that function when app-owned release animation is done.
 Pointer movement does not call `dragOverlay`.
 
+The overlay input includes:
+
+- `dragState`: item id, group, source rect, start pointer, and current pointer.
+- `phase`: `"dragging"` or `"released"`.
+- `remeasureOverlay`: manually refreshes the cached overlay measurement.
+- `removeOverlay`: present only for `"released"` overlays in manual release
+  mode; call it when app-owned release animation should remove the overlay.
+
 `removeOverlay` is only present for released overlays in manual release mode.
 Calling it more than once is safe. It removes the overlay host state only; it is
 not a controller or runtime teardown API.
@@ -121,7 +136,31 @@ from the current pointer delta.
 The controller measures the returned overlay element on mount/replacement. When
 `ResizeObserver` is available, it also remeasures when that element changes
 size. The runtime derives the current overlay rect from that cached measurement
-plus pointer movement.
+plus modified pointer movement, and it does not measure overlay DOM on every
+pointer move.
+
+Manual `remeasureOverlay()` is for cases automatic observation cannot cover or
+where the app knows visual geometry changed. CSS transforms can change visual
+bounds without necessarily triggering `ResizeObserver`.
+
+```ts
+controller.remeasureOverlay();
+```
+
+```ts
+const controller = createDragController({
+  dragOverlay({ dragState, remeasureOverlay }) {
+    const element = document.createElement("div");
+    element.textContent = dragState.draggableId;
+
+    element.addEventListener("transitionend", () => {
+      remeasureOverlay();
+    });
+
+    return element;
+  },
+});
+```
 
 For dynamic overlay content, keep a reference to the element and update it from
 lifecycle callbacks or subscriptions:
@@ -164,6 +203,7 @@ type DragUpdateEvent = {
   draggableId: string;
   source: DragSource;
   pointerPosition: DragPoint;
+  overlayRect: DragRect | null;
   activeDropTargetId: string | null;
   previousDropTargetId: string | null;
 };
@@ -181,6 +221,7 @@ type DragEndEvent = {
   source: DragSource;
   result: DragEndResult;
   dropTargetId: string | null;
+  overlayRect: DragRect | null;
 };
 
 type DropEvent = {
@@ -200,6 +241,14 @@ type SortableDropPlacement = {
 };
 ```
 
+`DragUpdateEvent.overlayRect` is the current viewport-space rectangle for the
+drag overlay. `DragEndEvent.overlayRect` is the final viewport-space rectangle
+at the moment the drag ends. Both are `null` when no drag overlay is configured.
+When an overlay is configured, the runtime uses cached overlay measurement plus
+modified pointer movement. Before overlay content has been measured, it uses the
+same translated source-rect fallback as the visual overlay. The drag update and
+drag end paths do not read overlay DOM just to produce this field.
+
 Helpers:
 
 - `getDropTargetRect(dropTargetId)`
@@ -339,8 +388,14 @@ modifier state.
 ## Measurement
 
 Targets are measured when registered and remeasured at drag start. The explicit
-remeasurement entry point is `controller.remeasureDropTargets(input?)`; call it
-when app-owned layout changes during a drag should affect targeting.
+target remeasurement entry point is `controller.remeasureDropTargets(input?)`;
+call it when app-owned layout changes during a drag should affect targeting.
+
+Overlay measurement is separate from target measurement. Overlay content is
+measured on mount/replacement and by `ResizeObserver` when available. Use
+`controller.remeasureOverlay()` when the current overlay geometry should be
+refreshed manually, such as after an app-owned transition or transform that
+changes visual bounds without a normal size-observer notification.
 
 `RemeasureDropTargetsInput` accepts:
 
@@ -356,6 +411,36 @@ order, so app-owned layout changes such as expanding tree rows or changing
 grouped sections during a drag should call the public remeasure API when those
 changes need to affect targeting.
 
+## Active Drag Recompute
+
+`controller.recomputeActiveDrag()` reruns the active drag update path from the
+last stored raw pointer position. It reapplies modifiers, derives the overlay
+rect from cached overlay measurement, recomputes the active drop target from
+cached target measurements, updates the overlay host, and sends the normal drag
+update notifications. This is the same update path used by pointer movement.
+Calling it with no active drag is safe and does nothing.
+
+Use it when something external changes what is under the pointer during an
+active drag without producing a new pointer event.
+
+```ts
+controller.recomputeActiveDrag();
+```
+
+Recompute does not remeasure drop targets. If target geometry or registrations
+changed and those changes should affect targeting, remeasure first and then
+recompute.
+
+```ts
+controller.remeasureDropTargets({ group: "items" });
+controller.recomputeActiveDrag();
+```
+
+```ts
+// Example: after external scrolling changes what is under the pointer
+controller.recomputeActiveDrag();
+```
+
 ## Data Ownership
 
 The DOM package never owns application data. Item ids, target ids, group ids,

package/dist/controller/create-drag-controller.d.ts

@@ -13,10 +13,12 @@ export type DragControllerAnnouncements = {
 export type DragControllerOverlayInput = {
     dragState: DragState;
     phase: "dragging";
+    remeasureOverlay: () => void;
     removeOverlay?: never;
 } | {
     dragState: DragState;
     phase: "released";
+    remeasureOverlay: () => void;
     removeOverlay: () => void;
 };
 export type DragControllerOptions = {
@@ -32,5 +34,7 @@ export type DragControllerOptions = {
 } & DragLifecycleCallbacks;
 export type DragController = {
     remeasureDropTargets: (input?: RemeasureDropTargetsInput) => void;
+    remeasureOverlay: () => void;
+    recomputeActiveDrag: () => void;
 };
 export declare function createDragController(options?: DragControllerOptions): DragController;

package/dist/controller/create-drag-controller.js

@@ -22,6 +22,10 @@ export function createDragController(options = {}) {
         remeasureDropTargets: (input) => {
             runtime.remeasureDropTargets(input);
         },
+        remeasureOverlay,
+        recomputeActiveDrag: () => {
+            runtime.recomputeActiveDrag();
+        },
     };
     setControllerRuntime(controller, runtime);
     return controller;
@@ -124,6 +128,9 @@ export function createDragController(options = {}) {
         }
         runtime.setOverlayRect(rectToDragRect(overlayElement.getBoundingClientRect()));
     }
+    function remeasureOverlay() {
+        measureOverlayElement();
+    }
     function disconnectOverlayResizeObserver() {
         overlayResizeObserver?.disconnect();
         overlayResizeObserver = null;
@@ -149,12 +156,14 @@ export function createDragController(options = {}) {
             return {
                 dragState: overlayState.dragState,
                 phase: "released",
+                remeasureOverlay,
                 removeOverlay: clearOverlayHost,
             };
         }
         return {
             dragState: overlayState.dragState,
             phase: "dragging",
+            remeasureOverlay,
         };
     }
     function syncLiveRegion() {

package/dist/runtime/drag-runtime-scope.d.ts

@@ -11,6 +11,7 @@ export type DragRuntimeScope = DomDraggableRuntime & DomDroppableRuntime & DomDr
     configure: (input: DragRuntimeScopeConfigureInput) => void;
     cancelDrag: () => void;
     releaseActiveDragResources: () => void;
+    recomputeActiveDrag: () => void;
     setOverlayRect: (overlayRect: DragRect | null) => void;
 };
 export type InternalStaleDomBindingRuntime = {

package/dist/runtime/drag-runtime-scope.js

@@ -5,6 +5,7 @@ export function createDragRuntimeScope(options) {
         configure: (input) => runtime.configure(input),
         cancelDrag: () => runtime.cancelDrag(),
         releaseActiveDragResources: () => runtime.releaseActiveDragResources(),
+        recomputeActiveDrag: () => runtime.recomputeActiveDrag(),
         setOverlayRect: (overlayRect) => runtime.setOverlayRect(overlayRect),
         requestDragStart: (input) => runtime.requestDragStart(input),
         isKeyboardDragEnabled: () => runtime.isKeyboardDragEnabled(),

package/dist/runtime/drag-runtime.d.ts

@@ -43,6 +43,7 @@ export declare class DragRuntime {
     requestKeyboardDragStart(input: RequestKeyboardDragStartInput): void;
     moveKeyboardDrag(direction: KeyboardMoveDirection): void;
     updatePointer(rawPointerPosition: Point): void;
+    recomputeActiveDrag(): void;
     private updatePointerNow;
     private updatePointerNowOrRelease;
     private finishDragAfterQueuedPointerUpdate;

package/dist/runtime/drag-runtime.js

@@ -180,6 +180,13 @@ export class DragRuntime {
             }
         });
     }
+    recomputeActiveDrag() {
+        const session = this.getDraggingSession();
+        if (!session) {
+            return;
+        }
+        this.updatePointerNowOrRelease(session.rawPointerPosition);
+    }
     updatePointerNow(rawPointerPosition) {
         const session = this.getDraggingSession();
         if (!session) {
@@ -221,6 +228,7 @@ export class DragRuntime {
             draggableId: nextSession.draggableId,
             source: nextSession.source,
             pointerPosition,
+            overlayRect,
             activeDropTargetId: nextSession.activeDropTargetId,
             previousDropTargetId,
         };
@@ -499,6 +507,9 @@ export class DragRuntime {
                         ? "dropped"
                         : "invalid-target"
             : null;
+        const overlayRect = session && this.hasDragOverlay
+            ? this.getCurrentDragRectAt(session.pointerPosition)
+            : null;
         const sortablePlacement = session && dropTargetId
             ? this.getDropEventSortablePlacement(session, dropTargetId)
             : undefined;
@@ -525,6 +536,7 @@ export class DragRuntime {
                     draggableId: session.draggableId,
                     source: session.source,
                     result,
+                    overlayRect,
                     dropTargetId,
                 });
                 if (result === "dropped" && dropTargetId) {

package/dist/runtime/lifecycle.d.ts

@@ -12,6 +12,7 @@ export type DragUpdateEvent = {
     draggableId: string;
     source: DragSource;
     pointerPosition: DragPoint;
+    overlayRect: DragRect | null;
     activeDropTargetId: string | null;
     previousDropTargetId: string | null;
 };
@@ -19,6 +20,7 @@ export type DragEndEvent = {
     draggableId: string;
     source: DragSource;
     result: DragEndResult;
+    overlayRect: DragRect | null;
     dropTargetId: string | null;
 };
 export type DropEvent = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mk-drag-and-drop/dom",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Headless DOM drag-and-drop primitives for draggable, droppable, sortable, and grouped interactions.",
   "license": "MIT",
   "homepage": "https://mkramer.dev",
@@ -41,13 +41,14 @@
   "files": [
     "dist"
   ],
+  "sideEffects": false,
   "devDependencies": {
     "eslint": "^8.57.0",
     "jsdom": "^24.1.3",
     "typescript": "5.5.4",
     "vitest": "^2.1.9",
-    "@repo/eslint-config": "0.0.0",
-    "@repo/typescript-config": "0.0.0"
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
   },
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",