@mk-drag-and-drop/react 0.2.0 → 0.3.0

package/README.md

@@ -52,6 +52,7 @@ The React root export includes:
 - `useSortable`, `UseSortableOptions`, `UseSortableResult`
 - `useDragHandle`, `UseDragHandleResult`
 - `useRemeasureDropTargets`
+- `useRemeasureOverlay`
 - `composeRefs`
 - React-friendly `restrictToContainer`, `ReactRestrictToContainerInput`
 - DOM targeting helpers, modifier helpers, lifecycle/source/result types,
@@ -222,6 +223,7 @@ type DragUpdateEvent = {
   draggableId: string;
   source: DragSource;
   pointerPosition: DragPoint;
+  overlayRect: DragRect | null;
   activeDropTargetId: string | null;
   previousDropTargetId: string | null;
 };
@@ -231,6 +233,7 @@ type DragEndEvent = {
   source: DragSource;
   result: DragEndResult;
   dropTargetId: string | null;
+  overlayRect: DragRect | null;
 };
 
 type DropEvent = {
@@ -241,6 +244,15 @@ type DropEvent = {
 };
 ```
 
+`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. React receives these DOM lifecycle event types
+unchanged. The field is `null` when no drag overlay is configured. When an
+overlay exists, it is based on cached overlay measurement plus modified pointer
+movement, with the translated source rect as the fallback before overlay content
+has been measured. React does not add overlay DOM measurement on every pointer
+move.
+
 `onDrop` only runs for a valid successful drop. `onDragEnd.result` distinguishes
 successful drops, normal releases with no target, stale/invalid targets, and
 cancellations such as Escape or pointercancel. Plain drops are id-only.
@@ -390,6 +402,22 @@ every render. Sortable preview movement does not automatically remeasure a
 group; call this function when an app-owned layout change needs to affect
 targeting.
 
+### useRemeasureOverlay
+
+`useRemeasureOverlay` returns a function for manually refreshing the current
+overlay measurement. It must be used inside `DragProvider`. Calling the returned
+function with no mounted overlay is safe and does nothing.
+
+```tsx
+const remeasureOverlay = useRemeasureOverlay();
+
+remeasureOverlay();
+```
+
+Normal overlay size changes are observed automatically with `ResizeObserver`
+when available. Use this hook when the app knows visual geometry changed outside
+that automatic path, such as after a CSS transform or transition.
+
 ## Sortable Behavior
 
 Sortable preview is transient. The runtime may move DOM temporarily to show
@@ -429,8 +457,10 @@ shape.
 
 ```tsx
 <DragProvider
-  dragOverlay={({ dragState }) => (
-    <div className="dragOverlay">{dragState.draggableId}</div>
+  dragOverlay={({ dragState, remeasureOverlay }) => (
+    <div className="dragOverlay" onTransitionEnd={remeasureOverlay}>
+      {dragState.draggableId}
+    </div>
   )}
 >
   {children}
@@ -441,6 +471,7 @@ 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.
 
@@ -456,10 +487,21 @@ provider, controller, or runtime teardown API.
 
 The package owns overlay hosting, movement, release, and measurement for
 targeting and modifiers. It measures overlay content on mount/replacement and
-uses `ResizeObserver` when available to remeasure content size changes. Dynamic
-overlay content should use overlay-local state, component effects, lifecycle
-callbacks feeding a subscription/external store, or another app-owned update
-path rather than relying on `dragOverlay` being called for every pointer move.
+uses `ResizeObserver` when available to remeasure content size changes. The
+React package mirrors DOM behavior: overlay movement remains package-managed and
+imperative, so pointer movement should not require React state updates on every
+move.
+
+Use the overlay input `remeasureOverlay` helper when overlay-local UI knows its
+visual bounds changed. It uses the same provider/runtime path as
+`useRemeasureOverlay` and avoids reaching into internal runtime or provider
+state. CSS transforms can change visual bounds without necessarily triggering
+`ResizeObserver`.
+
+Dynamic overlay content should use overlay-local state, component effects,
+lifecycle callbacks feeding a subscription/external store, or another app-owned
+update path rather than relying on `dragOverlay` being called for every pointer
+move.
 
 ## Targeting And Modifiers
 
@@ -548,9 +590,9 @@ mount/unmount.
 `useDraggable`, `useDroppable`, and `useSortable` rely on React prop/ref updates
 for normal mount, unmount, and element replacement behavior.
 
-`useRemeasureDropTargets` is for layout changes, not resource release. The
-runtime also prunes disconnected targets on drag-critical paths such as
-remeasurement.
+`useRemeasureDropTargets` and `useRemeasureOverlay` are for geometry changes,
+not resource release. The runtime also prunes disconnected targets on
+drag-critical paths such as remeasurement.
 
 ## Examples
 
@@ -584,6 +626,8 @@ React examples live in `apps/react-web/src/react`:
 - `useDragHandle()`: returns the handle attribute props for a handle element.
 - `useRemeasureDropTargets()`: returns a function for remeasuring all targets,
   one target, multiple targets, or a group.
+- `useRemeasureOverlay()`: returns a function for manually refreshing the
+  currently mounted overlay measurement.
 - `composeRefs`: helper for combining the refs returned by hooks with app refs.
 - `lockToXAxis`, `lockToYAxis`: DOM movement modifiers re-exported by React.
 - `restrictToContainer`: React-friendly container-bound modifier.

package/dist/drag-context.d.ts

@@ -2,5 +2,6 @@ import type { DragRuntimeScope } from "@mk-drag-and-drop/dom/integration";
 export type DragContextValue = {
     runtime: DragRuntimeScope;
     keyboardDragEnabled: boolean;
+    remeasureOverlay: () => void;
 };
 export declare const DragContext: import("react").Context<DragContextValue | null>;

package/dist/drag-overlay.d.ts

@@ -5,13 +5,16 @@ export type DragOverlayInput = {
     dragState: DragState;
 } & ({
     phase: Extract<DragOverlayPhase, "dragging">;
+    remeasureOverlay: () => void;
     removeOverlay?: never;
 } | {
     phase: Extract<DragOverlayPhase, "released">;
+    remeasureOverlay: () => void;
     removeOverlay: () => void;
 });
 export type DragOverlayHostHandle = {
     move: (dragState: DragState) => void;
+    remeasure: () => void;
 };
 export declare const DragOverlayHost: import("react").NamedExoticComponent<{
     dragState: DragState;

package/dist/drag-overlay.js

@@ -1,7 +1,19 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { memo, useLayoutEffect, useRef, } from "react";
+import { memo, useCallback, useLayoutEffect, useRef, } from "react";
 export const DragOverlayHost = memo(function DragOverlayHost({ dragState, children, contentId, onHostReady, onOverlayRectChange, }) {
     const overlayWrapperRef = useRef(null);
+    const measureOverlayElement = useCallback(() => {
+        const wrapper = overlayWrapperRef.current;
+        if (!wrapper) {
+            onOverlayRectChange?.(null);
+            return;
+        }
+        const measuredElement = getMeasuredOverlayElement(wrapper);
+        if (!measuredElement.isConnected) {
+            return;
+        }
+        onOverlayRectChange?.(domRectToDragRect(measuredElement.getBoundingClientRect()));
+    }, [onOverlayRectChange]);
     useLayoutEffect(() => {
         const wrapper = overlayWrapperRef.current;
         if (!wrapper) {
@@ -12,26 +24,21 @@ export const DragOverlayHost = memo(function DragOverlayHost({ dragState, childr
             move: (nextDragState) => {
                 moveOverlayWrapper(wrapper, nextDragState);
             },
+            remeasure: measureOverlayElement,
         };
         onHostReady?.(host);
         host.move(dragState);
         return () => {
             onHostReady?.(null);
         };
-    }, [dragState, onHostReady]);
+    }, [dragState, measureOverlayElement, onHostReady]);
     useLayoutEffect(() => {
         const wrapper = overlayWrapperRef.current;
         if (!wrapper) {
             onOverlayRectChange?.(null);
             return;
         }
-        const measuredElement = wrapper.firstElementChild ?? wrapper;
-        const measureOverlayElement = () => {
-            if (!measuredElement.isConnected) {
-                return;
-            }
-            onOverlayRectChange?.(domRectToDragRect(measuredElement.getBoundingClientRect()));
-        };
+        const measuredElement = getMeasuredOverlayElement(wrapper);
         measureOverlayElement();
         if (typeof ResizeObserver === "undefined") {
             return () => {
@@ -46,7 +53,7 @@ export const DragOverlayHost = memo(function DragOverlayHost({ dragState, childr
             resizeObserver.disconnect();
             onOverlayRectChange?.(null);
         };
-    }, [contentId, onOverlayRectChange]);
+    }, [contentId, measureOverlayElement, onOverlayRectChange]);
     return (_jsx("div", { ref: overlayWrapperRef, style: {
             position: "fixed",
             left: dragState.sourceRect.left,
@@ -58,6 +65,9 @@ export const DragOverlayHost = memo(function DragOverlayHost({ dragState, childr
             transform: getOverlayTransform(dragState),
         }, children: children }));
 });
+function getMeasuredOverlayElement(wrapper) {
+    return wrapper.firstElementChild ?? wrapper;
+}
 function moveOverlayWrapper(wrapper, dragState) {
     wrapper.style.transform = getOverlayTransform(dragState);
 }

package/dist/drag-provider.js

@@ -77,10 +77,14 @@ export function DragProvider({ children, announcements, dragOverlay, keyboardCon
         });
     }
     const runtime = runtimeRef.current;
+    const remeasureOverlay = useCallback(() => {
+        overlayHostRef.current?.remeasure();
+    }, []);
     const contextValue = useMemo(() => ({
         runtime,
         keyboardDragEnabled,
-    }), [keyboardDragEnabled, runtime]);
+        remeasureOverlay,
+    }), [keyboardDragEnabled, remeasureOverlay, runtime]);
     useEffect(() => {
         return () => {
             runtime.releaseActiveDragResources();
@@ -193,12 +197,14 @@ export function DragProvider({ children, announcements, dragOverlay, keyboardCon
             return {
                 dragState: overlayState.dragState,
                 phase: "released",
+                remeasureOverlay,
                 removeOverlay: clearOverlayHost,
             };
         }
         return {
             dragState: overlayState.dragState,
             phase: "dragging",
+            remeasureOverlay,
         };
     }
 }

package/dist/hooks/use-remeasure-overlay.d.ts

@@ -0,0 +1 @@
+export declare function useRemeasureOverlay(): () => void;

package/dist/hooks/use-remeasure-overlay.js

@@ -0,0 +1,12 @@
+import { useCallback, useContext } from "react";
+import { DragContext } from "../drag-context.js";
+export function useRemeasureOverlay() {
+    const context = useContext(DragContext);
+    if (!context) {
+        throw new Error("useRemeasureOverlay must be used inside DragProvider");
+    }
+    const { remeasureOverlay } = context;
+    return useCallback(() => {
+        remeasureOverlay();
+    }, [remeasureOverlay]);
+}

package/dist/index.d.ts

@@ -8,5 +8,6 @@ export { useDraggable, type UseDraggableOptions, type UseDraggableResult, } from
 export { useDropContainer, type UseDropContainerOptions, type UseDropContainerResult, } from "./hooks/use-drop-container.js";
 export { useDroppable, type UseDroppableOptions, type UseDroppableResult, } from "./hooks/use-droppable.js";
 export { useRemeasureDropTargets } from "./hooks/use-remeasure-drop-targets.js";
+export { useRemeasureOverlay } from "./hooks/use-remeasure-overlay.js";
 export { useSortable, type UseSortableOptions, type UseSortableResult, } from "./hooks/use-sortable.js";
 export { composeRefs } from "./utils/compose-refs.js";

package/dist/index.js

@@ -6,5 +6,6 @@ export { useDraggable, } from "./hooks/use-draggable.js";
 export { useDropContainer, } from "./hooks/use-drop-container.js";
 export { useDroppable, } from "./hooks/use-droppable.js";
 export { useRemeasureDropTargets } from "./hooks/use-remeasure-drop-targets.js";
+export { useRemeasureOverlay } from "./hooks/use-remeasure-overlay.js";
 export { useSortable, } from "./hooks/use-sortable.js";
 export { composeRefs } from "./utils/compose-refs.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mk-drag-and-drop/react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React hooks and provider for the mk drag-and-drop DOM runtime.",
   "license": "MIT",
   "homepage": "https://mkramer.dev",
@@ -37,8 +37,9 @@
   "files": [
     "dist"
   ],
+  "sideEffects": false,
   "dependencies": {
-    "@mk-drag-and-drop/dom": "0.2.0"
+    "@mk-drag-and-drop/dom": "^0.3.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"