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

package/README.md

@@ -22,7 +22,7 @@ callbacks, and optional announcements.
 The React package wraps `@mk-drag-and-drop/dom`.
 
 `DragProvider` creates and configures the DOM runtime through the package
-integration handle.
+integration scope.
 Hooks such as `useDraggable`, `useDroppable`, `useSortable`, and
 `useDropContainer` register DOM nodes with that runtime through React refs.
 React hooks are adapters over DOM behavior, not a separate implementation.
@@ -57,6 +57,7 @@ The React root export includes:
 - DOM targeting helpers, modifier helpers, lifecycle/source/result types,
   sortable placement types, keyboard/pointer configuration types, and geometry
   types re-exported from the DOM package
+- `OverlayReleaseMode`
 - `DragState` and `DragOverlayPhase` from the DOM integration layer
 
 ## Core Mental Model
@@ -72,11 +73,28 @@ The package reports drag/drop operations. Your app owns the data and the final
 UI commit. React state is one common way to commit the result, but it is not
 required by the package.
 
+## Lifetime Model
+
+`DragProvider` is a drag-and-drop scope for a React subtree. It does not expose
+runtime lifecycle controls, and application code does not dispose of the
+runtime. The internal runtime is normal JavaScript memory and is released by
+garbage collection when unreachable.
+
+Hooks are adapters over the DOM behavior layer. They register committed DOM
+nodes through refs/effects, update those registrations when ids, groups, or
+container ids change, and unregister current nodes on ref/effect unmount.
+Stale disconnected DOM registrations are still pruned by the shared DOM runtime
+while the scope remains alive.
+
+Pending pointer activation resources and active drag resources belong to the
+input/drag lifecycle. Provider unmount releases active resources through the
+same active-drag resource path used by DOM drag cancellation; it is not a
+terminal runtime destructor. React StrictMode replay is supported for
+draggable, droppable, sortable, overlay, callback, and announcement behavior.
+
 ## Installation
 
-This workspace currently marks `@mk-drag-and-drop/react` as private. Install the
-React and DOM packages from your workspace or package registry when they are
-available:
+Install the React and DOM packages from your workspace or package registry:
 
 - `@mk-drag-and-drop/react`
 - `@mk-drag-and-drop/dom`
@@ -153,9 +171,11 @@ Real apps own the markup, layout, styling, state updates, and persistence.
 
 ## DragProvider
 
-`DragProvider` owns the runtime lifetime for the React subtree. It creates the
-DOM runtime, configures it from props, exposes it through React context, renders
-an optional drag overlay, and disposes the runtime when the provider unmounts.
+`DragProvider` creates a DOM runtime scope for the React subtree, configures it
+from props, exposes it through React context, and renders an optional drag
+overlay. Provider effect cleanup is not a runtime destructor; runtime objects
+are ordinary JavaScript objects and active drag resources are released by drag
+drop/cancel paths.
 
 Key props:
 
@@ -171,8 +191,8 @@ Key props:
 - `pointerConfiguration`: configures pointer activation delay and distance.
 - `keyboardConfiguration`: enables and configures keyboard drag commands.
 - `announcements`: optional callbacks that return live-region messages.
-- `keepOverlayOnDrop`: keeps the overlay in the released phase until the overlay
-  calls `finish`.
+- `overlayRelease`: `"auto"` removes overlays on drag end; `"manual"` keeps a
+  released overlay until its `removeOverlay` callback is called.
 
 Callbacks receive operation information and helper methods from the runtime.
 Use those callbacks to commit app data. Do not mutate package internals.
@@ -365,9 +385,10 @@ requestAnimationFrame(() => {
 
 It accepts no argument, a target id, an array of target ids, or `{ group }`.
 Use it intentionally for expand/collapse, grouped trees, or drag-state layout
-changes. It is not needed for normal cleanup and should not run on every render.
-Sortable preview movement does not automatically remeasure a group; call this
-function when an app-owned layout change needs to affect targeting.
+changes. It is not needed for normal resource release and should not run on
+every render. Sortable preview movement does not automatically remeasure a
+group; call this function when an app-owned layout change needs to affect
+targeting.
 
 ## Sortable Behavior
 
@@ -420,14 +441,20 @@ The overlay input includes:
 
 - `dragState`: item id, group, source rect, start pointer, and current pointer.
 - `phase`: `"dragging"` or `"released"`.
-- `finish`: call this when a kept release overlay should be removed.
+- `removeOverlay`: present only for `"released"` overlays in manual release
+  mode; call it when app-owned release animation should remove the overlay.
 
 Overlay rendering is app-owned. `DragProvider` mounts overlay content for the
-dragging phase and, when `keepOverlayOnDrop` is enabled, replaces it once for
-the released phase. Pointer movement updates the package-owned overlay host
-imperatively and does not call `dragOverlay` by default.
+dragging phase. Default `overlayRelease: "auto"` removes the overlay
+immediately on drag end. Manual release replaces it once for the released phase
+and leaves removal to `removeOverlay`. Pointer movement updates the
+package-owned overlay host imperatively and does not call `dragOverlay` by
+default.
+
+`removeOverlay` is idempotent and belongs to overlay release only. It is not a
+provider, controller, or runtime teardown API.
 
-The package owns overlay hosting, movement, cleanup, and measurement for
+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
@@ -451,7 +478,10 @@ The React package re-exports targeting helpers such as `pointerToCenter`,
 `maxPointerDistanceToRect` / `maxOverlayCenterDistanceToRect`, plus modifier
 helpers. Sortable placement remains separate from targeting: the configured
 targeting algorithm chooses the active target, and sortable only chooses
-before/after placement relative to that target.
+before/after placement relative to that target. For sortable groups, the shared
+DOM registry may narrow measured candidates to relevant sortable item, neighbor,
+or container entries before the targeting algorithm runs; the algorithm still
+chooses from that narrowed measured list.
 
 - `lockToXAxis()`
 - `lockToYAxis()`
@@ -507,19 +537,20 @@ Accessibility still depends on the app's markup and product behavior:
 - Do not assume this package alone provides complete screen-reader drag-and-drop
   support for your domain.
 
-## Cleanup And Effects
+## Lifetime And Effects
 
 Hooks attach input props and register DOM nodes through refs and lifecycle
-effects. Users should not manually clean runtime entries for normal React
+effects. Users should not manually release runtime entries for normal React
 mount/unmount.
 
-`DragProvider` owns runtime lifetime and disposes the runtime when it unmounts.
-`useDropContainer` also cleans its DOM binding on effect cleanup.
+`DragProvider` does not call a terminal runtime destructor when it unmounts.
+`useDropContainer` releases its current DOM registration from effect cleanup.
 `useDraggable`, `useDroppable`, and `useSortable` rely on React prop/ref updates
 for normal mount, unmount, and element replacement behavior.
 
-`useRemeasureDropTargets` is for layout changes, not cleanup. The runtime also
-prunes disconnected targets on drag-critical paths such as remeasurement.
+`useRemeasureDropTargets` is for layout changes, not resource release. The
+runtime also prunes disconnected targets on drag-critical paths such as
+remeasurement.
 
 ## Examples
 
@@ -540,7 +571,7 @@ React examples live in `apps/react-web/src/react`:
 - `DragProvider`: creates/configures the DOM runtime for a React subtree.
   Important props include lifecycle callbacks, overlay rendering, targeting,
   constraints, modifiers, pointer/keyboard configuration, announcements, and
-  `keepOverlayOnDrop`.
+  `overlayRelease`.
 - `useDraggable(options)`: registers a drag source. Important options:
   `draggableId`, `group`. Returns ref and input props.
 - `useDroppable(options)`: registers a drop target. Important options:
@@ -561,8 +592,9 @@ Important event/helper types are re-exported from the React package, including
 `DragStartEvent`, `DragUpdateEvent`, `DragEndEvent`, `DropEvent`,
 `DragSource`, `DragEndResult`, `DragLifecycleHelpers`, `DragState`,
 `DragOverlayPhase`, `SortableDropPlacement`, `RemeasureDropTargetsInput`,
-`PointerConfiguration`, `KeyboardConfiguration`, `KeyboardCommand`, `DropTarget`,
-targeting types, geometry types, and modifier types.
+`OverlayReleaseMode`, `PointerConfiguration`, `KeyboardConfiguration`,
+`KeyboardCommand`, `DropTarget`, targeting types, geometry types, and modifier
+types.
 
 ## When To Use DOM Directly
 
@@ -577,7 +609,7 @@ Use `@mk-drag-and-drop/react` when:
 
 - Your UI is rendered with React.
 - You want ref-based hooks for registration.
-- You want provider-based runtime lifetime and lifecycle integration.
+- You want provider-based runtime scoping and lifecycle integration.
 
 ## Development
 

package/dist/drag-context.d.ts

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

package/dist/drag-overlay.d.ts

@@ -3,9 +3,13 @@ import type { DragRect } from "@mk-drag-and-drop/dom";
 import type { DragOverlayPhase, DragState } from "@mk-drag-and-drop/dom/integration";
 export type DragOverlayInput = {
     dragState: DragState;
-    phase: DragOverlayPhase;
-    finish: () => void;
-};
+} & ({
+    phase: Extract<DragOverlayPhase, "dragging">;
+    removeOverlay?: never;
+} | {
+    phase: Extract<DragOverlayPhase, "released">;
+    removeOverlay: () => void;
+});
 export type DragOverlayHostHandle = {
     move: (dragState: DragState) => void;
 };

package/dist/drag-provider.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import { type DragEndEvent, type DragLifecycleCallbacks, type DragModifierInput, type DragStartEvent, type DragUpdateEvent, type DropEvent, type KeyboardConfiguration, type PointerConfiguration, type TargetingAlgorithm, type TargetingConstraint } from "@mk-drag-and-drop/dom";
+import { type DragEndEvent, type DragLifecycleCallbacks, type DragModifierInput, type DragStartEvent, type DragUpdateEvent, type DropEvent, type KeyboardConfiguration, type OverlayReleaseMode, type PointerConfiguration, type TargetingAlgorithm, type TargetingConstraint } from "@mk-drag-and-drop/dom";
 import { type DragOverlayInput } from "./drag-overlay.js";
 export type DragAnnouncements = {
     onDragStart?: (event: DragStartEvent) => string | null;
@@ -12,10 +12,10 @@ export type DragProviderProps = {
     announcements?: DragAnnouncements;
     dragOverlay?: (overlay: DragOverlayInput) => ReactNode;
     keyboardConfiguration?: KeyboardConfiguration;
-    keepOverlayOnDrop?: boolean;
     modifiers?: readonly DragModifierInput[];
+    overlayRelease?: OverlayReleaseMode;
     pointerConfiguration?: PointerConfiguration;
     targetingAlgorithm?: TargetingAlgorithm;
     targetingConstraint?: TargetingConstraint;
 } & DragLifecycleCallbacks;
-export declare function DragProvider({ children, announcements, dragOverlay, keyboardConfiguration, keepOverlayOnDrop, modifiers, pointerConfiguration, targetingAlgorithm, targetingConstraint, onDragStart, onDragUpdate, onDragEnd, onDrop, }: DragProviderProps): import("react").JSX.Element;
+export declare function DragProvider({ children, announcements, dragOverlay, keyboardConfiguration, modifiers, overlayRelease, pointerConfiguration, targetingAlgorithm, targetingConstraint, onDragStart, onDragUpdate, onDragEnd, onDrop, }: DragProviderProps): import("react").JSX.Element;

package/dist/drag-provider.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
 import { pointerToCenter, } from "@mk-drag-and-drop/dom";
-import { createDragRuntimeHandle, } from "@mk-drag-and-drop/dom/integration";
+import { createDragRuntimeScope, } from "@mk-drag-and-drop/dom/integration";
 import { DragContext } from "./drag-context.js";
 import { DragOverlayHost, } from "./drag-overlay.js";
 const visuallyHiddenStyle = {
@@ -15,7 +15,7 @@ const visuallyHiddenStyle = {
     whiteSpace: "nowrap",
     border: 0,
 };
-export function DragProvider({ children, announcements, dragOverlay, keyboardConfiguration, keepOverlayOnDrop = false, modifiers, pointerConfiguration, targetingAlgorithm = pointerToCenter, targetingConstraint, onDragStart, onDragUpdate, onDragEnd, onDrop, }) {
+export function DragProvider({ children, announcements, dragOverlay, keyboardConfiguration, modifiers, overlayRelease = "auto", pointerConfiguration, targetingAlgorithm = pointerToCenter, targetingConstraint, onDragStart, onDragUpdate, onDragEnd, onDrop, }) {
     const [overlayRequest, setOverlayRequest] = useState(null);
     const [announcementState, setAnnouncementState] = useState({
         id: 0,
@@ -38,7 +38,7 @@ export function DragProvider({ children, announcements, dragOverlay, keyboardCon
     const lifecycleCallbacksRef = useRef(null);
     const runtimeConfigurationSnapshotRef = useRef(null);
     const keyboardDragEnabled = isKeyboardDragEnabledFromConfiguration(keyboardConfiguration);
-    const finishOverlay = useCallback(() => {
+    const clearOverlayHost = useCallback(() => {
         pendingOverlayDragStateRef.current = null;
         overlayHostRef.current = null;
         overlaySnapshotRef.current = null;
@@ -72,7 +72,7 @@ export function DragProvider({ children, announcements, dragOverlay, keyboardCon
         };
     }
     if (runtimeRef.current === null) {
-        runtimeRef.current = createDragRuntimeHandle({
+        runtimeRef.current = createDragRuntimeScope({
             updateOverlayHost: handleOverlayHostUpdate,
         });
     }
@@ -81,11 +81,16 @@ export function DragProvider({ children, announcements, dragOverlay, keyboardCon
         runtime,
         keyboardDragEnabled,
     }), [keyboardDragEnabled, runtime]);
+    useEffect(() => {
+        return () => {
+            runtime.releaseActiveDragResources();
+        };
+    }, [runtime]);
     const nextRuntimeConfiguration = {
         targetingAlgorithm,
         targetingConstraint,
         hasDragOverlay: dragOverlay !== undefined,
-        keepOverlayOnDrop,
+        overlayRelease,
         lifecycleCallbacks: lifecycleCallbacksRef.current,
         keyboardConfiguration,
         modifiers,
@@ -109,16 +114,11 @@ export function DragProvider({ children, announcements, dragOverlay, keyboardCon
         runtimeConfigurationSnapshotRef.current =
             createRuntimeConfigurationSnapshot(nextRuntimeConfiguration);
     });
-    useEffect(() => {
-        return () => {
-            runtime.dispose();
-        };
-    }, [runtime]);
     useEffect(() => {
         if (!dragOverlay) {
-            finishOverlay();
+            clearOverlayHost();
         }
-    }, [dragOverlay, finishOverlay]);
+    }, [dragOverlay, clearOverlayHost]);
     useEffect(() => {
         if (!announcements) {
             lastAnnouncementRef.current = null;
@@ -154,13 +154,13 @@ export function DragProvider({ children, announcements, dragOverlay, keyboardCon
             moveOverlay(update.dragState);
             return;
         }
-        finishOverlay();
+        clearOverlayHost();
     }
     function mountOverlay(state) {
         pendingOverlayDragStateRef.current = state.dragState;
         overlayHostRef.current?.move(state.dragState);
         if (!dragOverlayRef.current) {
-            finishOverlay();
+            clearOverlayHost();
             return;
         }
         overlayContentIdRef.current += 1;
@@ -184,21 +184,30 @@ export function DragProvider({ children, announcements, dragOverlay, keyboardCon
         overlaySnapshotRef.current = {
             id: overlayRequest.id,
             state: overlayRequest.state,
-            content: dragOverlay({
-                dragState: overlayRequest.state.dragState,
-                phase: overlayRequest.state.phase,
-                finish: finishOverlay,
-            }),
+            content: dragOverlay(createOverlayInput(overlayRequest.state)),
         };
         return overlaySnapshotRef.current;
     }
+    function createOverlayInput(overlayState) {
+        if (overlayState.phase === "released") {
+            return {
+                dragState: overlayState.dragState,
+                phase: "released",
+                removeOverlay: clearOverlayHost,
+            };
+        }
+        return {
+            dragState: overlayState.dragState,
+            phase: "dragging",
+        };
+    }
 }
 function createRuntimeConfigurationSnapshot(input) {
     return {
         targetingAlgorithm: input.targetingAlgorithm,
         targetingConstraint: input.targetingConstraint,
         hasDragOverlay: input.hasDragOverlay,
-        keepOverlayOnDrop: input.keepOverlayOnDrop,
+        overlayRelease: input.overlayRelease,
         keyboardConfiguration: cloneKeyboardConfiguration(input.keyboardConfiguration),
         modifiers: input.modifiers ? Array.from(input.modifiers) : undefined,
         pointerConfiguration: input.pointerConfiguration
@@ -211,7 +220,7 @@ function areRuntimeConfigurationSnapshotsEqual(previous, next) {
         previous.targetingAlgorithm === next.targetingAlgorithm &&
         previous.targetingConstraint === next.targetingConstraint &&
         previous.hasDragOverlay === next.hasDragOverlay &&
-        previous.keepOverlayOnDrop === next.keepOverlayOnDrop &&
+        previous.overlayRelease === next.overlayRelease &&
         areKeyboardConfigurationsEqual(previous.keyboardConfiguration, next.keyboardConfiguration) &&
         arePointerConfigurationsEqual(previous.pointerConfiguration, next.pointerConfiguration) &&
         areModifierInputsEqual(previous.modifiers, next.modifiers));

package/dist/hooks/use-drop-container.js

@@ -19,7 +19,7 @@ export function useDropContainer({ containerId, group = defaultDropContainerGrou
             existingBehavior.group === group) {
             return existingBehavior.behavior;
         }
-        existingBehavior?.behavior.cleanup();
+        existingBehavior?.behavior.releaseRegistration();
         const behavior = createDomDropContainer({
             runtime,
             containerId,
@@ -44,7 +44,7 @@ export function useDropContainer({ containerId, group = defaultDropContainerGrou
             behavior.setElement(nodeRef.current);
         }
         return () => {
-            behavior.cleanup();
+            behavior.releaseRegistration();
             if (behaviorRef.current?.behavior === behavior) {
                 behaviorRef.current = null;
             }

package/dist/hooks/use-droppable.js

@@ -1,9 +1,10 @@
-import { useCallback, useContext, useMemo, } from "react";
+import { useCallback, useContext, useEffect, useMemo, useRef, } from "react";
 import { createDomDroppable } from "@mk-drag-and-drop/dom/integration";
 import { DragContext } from "../drag-context.js";
 const defaultDroppableGroup = "default";
 export function useDroppable({ dropTargetId, group = defaultDroppableGroup, containerId = null, }) {
     const context = useContext(DragContext);
+    const nodeRef = useRef(null);
     if (!context) {
         throw new Error("useDroppable must be used inside DragProvider");
     }
@@ -15,8 +16,17 @@ export function useDroppable({ dropTargetId, group = defaultDroppableGroup, cont
         containerId,
     }), [containerId, dropTargetId, group, runtime]);
     const setNodeRef = useCallback((node) => {
+        nodeRef.current = node;
         behavior.setElement(node);
     }, [behavior]);
+    useEffect(() => {
+        if (nodeRef.current) {
+            behavior.setElement(nodeRef.current);
+        }
+        return () => {
+            behavior.releaseRegistration();
+        };
+    }, [behavior]);
     return useMemo(() => ({
         ref: setNodeRef,
     }), [setNodeRef]);

package/dist/hooks/use-sortable.js

@@ -1,4 +1,4 @@
-import { useCallback, useContext, useMemo, useRef, } from "react";
+import { useCallback, useContext, useEffect, useMemo, useRef, } from "react";
 import { createDomSortable, } from "@mk-drag-and-drop/dom/integration";
 import { DragContext } from "../drag-context.js";
 const defaultSortableGroup = "default";
@@ -33,6 +33,14 @@ export function useSortable({ draggableId, group = defaultSortableGroup, contain
         nodeRef.current = node;
         behavior.setElement(node);
     }, [behavior]);
+    useEffect(() => {
+        if (nodeRef.current) {
+            behavior.setElement(nodeRef.current);
+        }
+        return () => {
+            behavior.releaseRegistration();
+        };
+    }, [behavior]);
     return useMemo(() => {
         const sortableProps = {
             ref: setNodeRef,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { DragProvider, type DragAnnouncements, type DragProviderProps, } from "./drag-provider.js";
 export type { DragOverlayInput } from "./drag-overlay.js";
-export { centerToCenter, getDistanceToRect, lockToXAxis, lockToYAxis, maxOverlayCenterDistanceToRect, maxPointerDistanceToRect, pointerToCenter, pointerToRectDistance, type DragEndResult, type DragEndEvent, type DragLifecycleCallbacks, type DragLifecycleHelpers, type DragModifier, type DragModifierInput, type DragModifierSetupInput, type DragModifierTransformInput, type DragPoint, type DragRect, type DragSource, type DragStartEvent, type DragUpdateEvent, type DropEvent, type DropTarget, type KeyboardCommand, type KeyboardConfiguration, type PointerConfiguration, type RemeasureDropTargetsInput, type SortableAxis, type SortableDropPlacement, type SortablePlacementBoundary, type TargetingAlgorithm, type TargetingAlgorithmInput, type TargetingConstraint, type TargetingConstraintInput, } from "@mk-drag-and-drop/dom";
+export { centerToCenter, getDistanceToRect, lockToXAxis, lockToYAxis, maxOverlayCenterDistanceToRect, maxPointerDistanceToRect, pointerToCenter, pointerToRectDistance, type DragEndResult, type DragEndEvent, type DragLifecycleCallbacks, type DragLifecycleHelpers, type DragModifier, type DragModifierInput, type DragModifierSetupInput, type DragModifierTransformInput, type DragPoint, type DragRect, type DragSource, type DragStartEvent, type DragUpdateEvent, type DropEvent, type DropTarget, type KeyboardCommand, type KeyboardConfiguration, type OverlayReleaseMode, type PointerConfiguration, type RemeasureDropTargetsInput, type SortableAxis, type SortableDropPlacement, type SortablePlacementBoundary, type TargetingAlgorithm, type TargetingAlgorithmInput, type TargetingConstraint, type TargetingConstraintInput, } from "@mk-drag-and-drop/dom";
 export { restrictToContainer, type ReactRestrictToContainerInput, } from "./modifiers/restrict-to-container.js";
 export type { DragOverlayPhase, DragState, } from "@mk-drag-and-drop/dom/integration";
 export { useDragHandle, type UseDragHandleResult, } from "./hooks/use-drag-handle.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mk-drag-and-drop/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React hooks and provider for the mk drag-and-drop DOM runtime.",
   "license": "MIT",
   "homepage": "https://mkramer.dev",
@@ -38,7 +38,7 @@
     "dist"
   ],
   "dependencies": {
-    "@mk-drag-and-drop/dom": "0.1.0"
+    "@mk-drag-and-drop/dom": "0.2.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"