dnd-block-tree 0.5.0 → 1.0.0

package/README.md

@@ -13,8 +13,9 @@ A headless React library for building hierarchical drag-and-drop interfaces. Bri
 ## Features
 
 - **Stable Drop Zones** - Zones render based on original block positions, not preview state, ensuring consistent drop targets during drag
-- **Ghost Preview** - Semi-transparent preview shows where blocks will land without affecting zone positions
-- **Depth-Aware Collision** - Smart algorithm prefers nested zones when cursor is at indented levels, with hysteresis to prevent flickering
+- **Ghost Preview** - In-flow semi-transparent preview shows where blocks will land with accurate layout
+- **Snapshotted Collision** - Zone rects are frozen on drag start and re-measured after each ghost commit, preventing layout-shift feedback loops
+- **Depth-Aware Collision** - Smart algorithm prefers nested zones when cursor is at indented levels, with cross-depth-aware hysteresis
 - **Mobile & Touch Support** - Separate touch/pointer activation constraints with configurable `longPressDelay` and optional `hapticFeedback`
 - **Snapshot-Based Computation** - State captured at drag start. All preview computations use snapshot, ensuring consistent behavior
 - **Debounced Preview** - 150ms debounced virtual state for smooth drag previews without jitter
@@ -627,6 +628,31 @@ const collision = createStickyCollision(20)
 
 You can also pass any `CollisionDetection` function from `@dnd-kit/core`.
 
+### Snapshotted Zone Rects
+
+`createStickyCollision` accepts an optional `SnapshotRectsRef` — a ref to a `Map<string, DOMRect>` of frozen zone positions. When provided, collision detection uses these snapshots instead of live DOM measurements, preventing feedback loops caused by the in-flow ghost preview shifting zone positions.
+
+```typescript
+import { createStickyCollision, type SnapshotRectsRef } from 'dnd-block-tree'
+
+const snapshotRef: SnapshotRectsRef = { current: null }
+const collision = createStickyCollision(20, snapshotRef)
+
+// Snapshot all zone rects after drag starts:
+snapshotRef.current = new Map(
+  [...document.querySelectorAll('[data-zone-id]')].map(el => [
+    el.getAttribute('data-zone-id')!,
+    el.getBoundingClientRect(),
+  ])
+)
+```
+
+`BlockTree` handles this lifecycle automatically — zones are snapshotted on drag start and re-measured via `requestAnimationFrame` after each ghost position commit.
+
+### Cross-Depth Hysteresis
+
+The sticky collision uses a reduced threshold (25% of normal) when switching between zones at different indentation levels. This makes it easy to drag blocks in and out of containers while still preventing flickering between same-depth adjacent zones.
+
 ## Type Safety
 
 The library provides automatic type inference for container vs non-container renderers:
@@ -687,7 +713,8 @@ import {
   // Collision detection
   weightedVerticalCollision,  // Edge-distance collision, depth-aware
   closestCenterCollision,     // Simple closest-center collision
-  createStickyCollision,      // Hysteresis wrapper to prevent flickering
+  createStickyCollision,      // Hysteresis wrapper with snapshot support
+  type SnapshotRectsRef,      // Ref type for frozen zone rects
 
   // Hooks
   useBlockHistory,            // Undo/redo state management

package/dist/index.d.mts

@@ -389,6 +389,9 @@ interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
     blockMap: Map<string, T>;
 }
 
+type SnapshotRectsRef = {
+    current: Map<UniqueIdentifier, DOMRect> | null;
+};
 /**
  * Custom collision detection that scores drop zones by distance to nearest edge.
  * Uses edge-distance scoring with a bottom bias for more natural drag behavior.
@@ -404,8 +407,11 @@ declare const weightedVerticalCollision: CollisionDetection;
  * between adjacent drop zones.
  *
  * @param threshold - Minimum score improvement required to switch zones (default: 15px)
+ * @param snapshotRef - Optional ref to snapshotted zone rects. When populated,
+ *   collision detection uses these frozen rects instead of live DOM measurements,
+ *   preventing layout-shift feedback loops from in-flow ghost previews.
  */
-declare function createStickyCollision(threshold?: number): CollisionDetection & {
+declare function createStickyCollision(threshold?: number, snapshotRef?: SnapshotRectsRef): CollisionDetection & {
     reset: () => void;
 };
 /**
@@ -811,4 +817,4 @@ declare function initFractionalOrder<T extends {
     order: number | string;
 }>(blocks: T[]): T[];
 
-export { type AnimationConfig, type AutoExpandConfig, type BaseBlock, type BlockAction, type BlockAddEvent, type BlockDeleteEvent, type BlockIndex, type BlockMoveEvent, type BlockPosition, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeCallbacks, type BlockTreeConfig, type BlockTreeCustomization, type BlockTreeProps, BlockTreeSSR, type BlockTreeSSRProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DragEndEvent, type DragMoveEvent, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, type DragStartEvent, DropZone, type DropZoneConfig, type DropZoneProps, type DropZoneType, type ExpandChangeEvent, type HoverChangeEvent, type IdGeneratorFn, type InternalRenderers, type MoveOperation, type NestedBlock, type OrderingStrategy, type RendererPropsFor, type SensorConfig, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, type UseBlockHistoryOptions, type UseBlockHistoryResult, type UseLayoutAnimationOptions, type UseVirtualTreeOptions, type UseVirtualTreeResult, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, flatToNested, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSensorConfig, getSubtreeDepth, initFractionalOrder, nestedToFlat, reparentBlockIndex, reparentMultipleBlocks, triggerHaptic, useBlockHistory, useConfiguredSensors, useLayoutAnimation, useVirtualTree, weightedVerticalCollision };
+export { type AnimationConfig, type AutoExpandConfig, type BaseBlock, type BlockAction, type BlockAddEvent, type BlockDeleteEvent, type BlockIndex, type BlockMoveEvent, type BlockPosition, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeCallbacks, type BlockTreeConfig, type BlockTreeCustomization, type BlockTreeProps, BlockTreeSSR, type BlockTreeSSRProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DragEndEvent, type DragMoveEvent, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, type DragStartEvent, DropZone, type DropZoneConfig, type DropZoneProps, type DropZoneType, type ExpandChangeEvent, type HoverChangeEvent, type IdGeneratorFn, type InternalRenderers, type MoveOperation, type NestedBlock, type OrderingStrategy, type RendererPropsFor, type SensorConfig, type SnapshotRectsRef, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, type UseBlockHistoryOptions, type UseBlockHistoryResult, type UseLayoutAnimationOptions, type UseVirtualTreeOptions, type UseVirtualTreeResult, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, flatToNested, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSensorConfig, getSubtreeDepth, initFractionalOrder, nestedToFlat, reparentBlockIndex, reparentMultipleBlocks, triggerHaptic, useBlockHistory, useConfiguredSensors, useLayoutAnimation, useVirtualTree, weightedVerticalCollision };

package/dist/index.d.ts

@@ -389,6 +389,9 @@ interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
     blockMap: Map<string, T>;
 }
 
+type SnapshotRectsRef = {
+    current: Map<UniqueIdentifier, DOMRect> | null;
+};
 /**
  * Custom collision detection that scores drop zones by distance to nearest edge.
  * Uses edge-distance scoring with a bottom bias for more natural drag behavior.
@@ -404,8 +407,11 @@ declare const weightedVerticalCollision: CollisionDetection;
  * between adjacent drop zones.
  *
  * @param threshold - Minimum score improvement required to switch zones (default: 15px)
+ * @param snapshotRef - Optional ref to snapshotted zone rects. When populated,
+ *   collision detection uses these frozen rects instead of live DOM measurements,
+ *   preventing layout-shift feedback loops from in-flow ghost previews.
  */
-declare function createStickyCollision(threshold?: number): CollisionDetection & {
+declare function createStickyCollision(threshold?: number, snapshotRef?: SnapshotRectsRef): CollisionDetection & {
     reset: () => void;
 };
 /**
@@ -811,4 +817,4 @@ declare function initFractionalOrder<T extends {
     order: number | string;
 }>(blocks: T[]): T[];
 
-export { type AnimationConfig, type AutoExpandConfig, type BaseBlock, type BlockAction, type BlockAddEvent, type BlockDeleteEvent, type BlockIndex, type BlockMoveEvent, type BlockPosition, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeCallbacks, type BlockTreeConfig, type BlockTreeCustomization, type BlockTreeProps, BlockTreeSSR, type BlockTreeSSRProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DragEndEvent, type DragMoveEvent, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, type DragStartEvent, DropZone, type DropZoneConfig, type DropZoneProps, type DropZoneType, type ExpandChangeEvent, type HoverChangeEvent, type IdGeneratorFn, type InternalRenderers, type MoveOperation, type NestedBlock, type OrderingStrategy, type RendererPropsFor, type SensorConfig, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, type UseBlockHistoryOptions, type UseBlockHistoryResult, type UseLayoutAnimationOptions, type UseVirtualTreeOptions, type UseVirtualTreeResult, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, flatToNested, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSensorConfig, getSubtreeDepth, initFractionalOrder, nestedToFlat, reparentBlockIndex, reparentMultipleBlocks, triggerHaptic, useBlockHistory, useConfiguredSensors, useLayoutAnimation, useVirtualTree, weightedVerticalCollision };
+export { type AnimationConfig, type AutoExpandConfig, type BaseBlock, type BlockAction, type BlockAddEvent, type BlockDeleteEvent, type BlockIndex, type BlockMoveEvent, type BlockPosition, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeCallbacks, type BlockTreeConfig, type BlockTreeCustomization, type BlockTreeProps, BlockTreeSSR, type BlockTreeSSRProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DragEndEvent, type DragMoveEvent, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, type DragStartEvent, DropZone, type DropZoneConfig, type DropZoneProps, type DropZoneType, type ExpandChangeEvent, type HoverChangeEvent, type IdGeneratorFn, type InternalRenderers, type MoveOperation, type NestedBlock, type OrderingStrategy, type RendererPropsFor, type SensorConfig, type SnapshotRectsRef, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, type UseBlockHistoryOptions, type UseBlockHistoryResult, type UseLayoutAnimationOptions, type UseVirtualTreeOptions, type UseVirtualTreeResult, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, flatToNested, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSensorConfig, getSubtreeDepth, initFractionalOrder, nestedToFlat, reparentBlockIndex, reparentMultipleBlocks, triggerHaptic, useBlockHistory, useConfiguredSensors, useLayoutAnimation, useVirtualTree, weightedVerticalCollision };

package/dist/index.js

@@ -15,11 +15,11 @@ function extractBlockId(zoneId) {
 }
 
 // src/core/collision.ts
-function computeCollisionScores(droppableContainers, collisionRect) {
+function computeCollisionScores(droppableContainers, collisionRect, snapshotRects) {
   const pointerX = collisionRect.left + collisionRect.width / 2;
   const pointerY = collisionRect.top + collisionRect.height / 2;
   const candidates = droppableContainers.map((container) => {
-    const rect = container.rect.current;
+    const rect = snapshotRects?.get(container.id) ?? container.rect.current;
     if (!rect) return null;
     const distanceToTop = Math.abs(pointerY - rect.top);
     const distanceToBottom = Math.abs(pointerY - rect.bottom);
@@ -29,16 +29,17 @@ function computeCollisionScores(droppableContainers, collisionRect) {
     const isWithinX = pointerX >= rect.left && pointerX <= rect.right;
     let horizontalScore = 0;
     if (isWithinX) {
-      horizontalScore = -rect.left * 0.1;
+      horizontalScore = Math.abs(pointerX - rect.left) * 0.3;
     } else {
       const distanceToZone = pointerX < rect.left ? rect.left - pointerX : pointerX - rect.right;
-      horizontalScore = Math.min(distanceToZone, 50);
+      horizontalScore = distanceToZone * 2;
     }
     return {
       id: container.id,
       data: {
         droppableContainer: container,
-        value: edgeDistance + bias + horizontalScore
+        value: edgeDistance + bias + horizontalScore,
+        left: rect.left
       }
     };
   }).filter((c) => c !== null);
@@ -57,14 +58,14 @@ var weightedVerticalCollision = ({
   const candidates = computeCollisionScores(droppableContainers, collisionRect);
   return candidates.slice(0, 1);
 };
-function createStickyCollision(threshold = 15) {
+function createStickyCollision(threshold = 15, snapshotRef) {
   let currentZoneId = null;
   const detector = ({
     droppableContainers,
     collisionRect
   }) => {
     if (!collisionRect) return [];
-    const candidates = computeCollisionScores(droppableContainers, collisionRect);
+    const candidates = computeCollisionScores(droppableContainers, collisionRect, snapshotRef?.current);
     if (candidates.length === 0) return [];
     const bestCandidate = candidates[0];
     const bestScore = bestCandidate.data.value;
@@ -72,7 +73,11 @@ function createStickyCollision(threshold = 15) {
       const currentCandidate = candidates.find((c) => c.id === currentZoneId);
       if (currentCandidate) {
         const currentScore = currentCandidate.data.value;
-        if (currentScore - bestScore < threshold) {
+        const currentLeft = currentCandidate.data.left;
+        const bestLeft = bestCandidate.data.left;
+        const crossDepth = Math.abs(currentLeft - bestLeft) > 20;
+        const effectiveThreshold = crossDepth ? threshold * 0.25 : threshold;
+        if (currentScore - bestScore < effectiveThreshold) {
           return [currentCandidate];
         }
       }
@@ -234,6 +239,9 @@ function DropZoneComponent({
   );
 }
 var DropZone = react.memo(DropZoneComponent);
+function GhostPreview({ children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-dnd-ghost": true, className: "opacity-50", style: { pointerEvents: "none" }, children });
+}
 function DraggableBlock({
   block,
   children,
@@ -320,7 +328,7 @@ function TreeRenderer({
       }
       const GhostRenderer = draggedBlock ? renderers[draggedBlock.type] : null;
       return /* @__PURE__ */ jsxRuntime.jsxs(react.Fragment, { children: [
-        ghostBeforeThis && GhostRenderer && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "opacity-50 pointer-events-none", style: { minWidth: 0 }, children: GhostRenderer({
+        ghostBeforeThis && GhostRenderer && /* @__PURE__ */ jsxRuntime.jsx(GhostPreview, { children: GhostRenderer({
           block: draggedBlock,
           isDragging: true,
           depth
@@ -398,7 +406,7 @@ function TreeRenderer({
     }),
     showGhostHere && previewPosition.index >= filteredBlocks.length && draggedBlock && (() => {
       const GhostRenderer = renderers[draggedBlock.type];
-      return GhostRenderer ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "opacity-50 pointer-events-none", style: { minWidth: 0 }, children: GhostRenderer({
+      return GhostRenderer ? /* @__PURE__ */ jsxRuntime.jsx(GhostPreview, { children: GhostRenderer({
         block: draggedBlock,
         isDragging: true,
         depth
@@ -650,6 +658,23 @@ function reparentBlockIndex(state, activeId, targetZone, containerTypes = [], or
   }
   if (dragged.id === zoneTargetId) return state;
   const oldList = byParent.get(oldParentId) ?? [];
+  const currentIndexInOldParent = oldList.indexOf(dragged.id);
+  const preNewList = byParent.get(newParentId) ?? [];
+  let targetIndex;
+  if (isInto) {
+    targetIndex = 0;
+  } else if (isEnd) {
+    targetIndex = preNewList.length;
+  } else {
+    const idx = preNewList.indexOf(zoneTargetId);
+    targetIndex = idx === -1 ? preNewList.length : isAfter ? idx + 1 : idx;
+  }
+  if (oldParentId === newParentId && currentIndexInOldParent !== -1) {
+    const adjustedTarget = targetIndex > currentIndexInOldParent ? targetIndex - 1 : targetIndex;
+    if (adjustedTarget === currentIndexInOldParent) {
+      return state;
+    }
+  }
   const filtered = oldList.filter((id) => id !== dragged.id);
   byParent.set(oldParentId, filtered);
   const newList = [...byParent.get(newParentId) ?? []];
@@ -662,10 +687,6 @@ function reparentBlockIndex(state, activeId, targetZone, containerTypes = [], or
     const idx = newList.indexOf(zoneTargetId);
     insertIndex = idx === -1 ? newList.length : isAfter ? idx + 1 : idx;
   }
-  const currentIndex = newList.indexOf(dragged.id);
-  if (dragged.parentId === newParentId && currentIndex === insertIndex) {
-    return state;
-  }
   newList.splice(insertIndex, 0, dragged.id);
   byParent.set(newParentId, newList);
   let newOrder = dragged.order;
@@ -835,7 +856,20 @@ function BlockTree({
   const cachedReorderRef = react.useRef(null);
   const fromPositionRef = react.useRef(null);
   const draggedIdsRef = react.useRef([]);
-  const stickyCollisionRef = react.useRef(createStickyCollision(20));
+  const snapshotRectsRef = react.useRef(null);
+  const needsResnapshot = react.useRef(false);
+  const stickyCollisionRef = react.useRef(createStickyCollision(20, snapshotRectsRef));
+  const snapshotZoneRects = react.useCallback(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    const zones = root.querySelectorAll("[data-zone-id]");
+    const map = /* @__PURE__ */ new Map();
+    zones.forEach((el) => {
+      const id = el.getAttribute("data-zone-id");
+      if (id) map.set(id, el.getBoundingClientRect());
+    });
+    snapshotRectsRef.current = map;
+  }, []);
   const [, forceRender] = react.useReducer((x) => x + 1, 0);
   const debouncedSetVirtual = react.useRef(
     debounce((newBlocks) => {
@@ -844,6 +878,7 @@ function BlockTree({
       } else {
         stateRef.current.virtualState = null;
       }
+      needsResnapshot.current = true;
       forceRender();
     }, previewDebounce)
   ).current;
@@ -982,6 +1017,13 @@ function BlockTree({
     }
     lastClickedIdRef.current = blockId;
   }, [multiSelect, selectedIds, setSelectedIds, visibleBlockIds]);
+  react.useEffect(() => {
+    if (!needsResnapshot.current || !stateRef.current.isDragging) return;
+    needsResnapshot.current = false;
+    requestAnimationFrame(() => {
+      snapshotZoneRects();
+    });
+  });
   react.useEffect(() => {
     if (!keyboardNavigation || !focusedIdRef.current || !rootRef.current) return;
     const el = rootRef.current.querySelector(`[data-block-id="${focusedIdRef.current}"]`);
@@ -1034,6 +1076,7 @@ function BlockTree({
     stateRef.current.isDragging = true;
     initialBlocksRef.current = [...blocks];
     cachedReorderRef.current = null;
+    needsResnapshot.current = true;
     forceRender();
   }, [blocks, canDrag, onDragStart, multiSelect, selectedIds, setSelectedIds, visibleBlockIds, sensorConfig?.hapticFeedback]);
   const handleDragMove = react.useCallback((event) => {
@@ -1109,6 +1152,7 @@ function BlockTree({
         cachedReorderRef.current = null;
         initialBlocksRef.current = [];
         fromPositionRef.current = null;
+        snapshotRectsRef.current = null;
         forceRender();
         return;
       }
@@ -1148,6 +1192,7 @@ function BlockTree({
     initialBlocksRef.current = [];
     fromPositionRef.current = null;
     draggedIdsRef.current = [];
+    snapshotRectsRef.current = null;
     if (cached && onChange) {
       onChange(cached.reorderedBlocks);
     }
@@ -1176,6 +1221,7 @@ function BlockTree({
     initialBlocksRef.current = [];
     fromPositionRef.current = null;
     draggedIdsRef.current = [];
+    snapshotRectsRef.current = null;
     forceRender();
   }, [blocks, debouncedSetVirtual, debouncedDragMove, onDragCancel, onDragEnd]);
   const handleHover = react.useCallback((zoneId, _parentId) => {