@vue-dnd-kit/core 2.0.0-alpha8 → 2.0.0

package/dist/external/composables/makeDraggable.d.ts

@@ -1,4 +1,4 @@
-import { IBaseOptions, IDragActivationOptions, IDraggableEvents, IModifierOptions, IPlacementMargins, TDnDNodeRef, TDraggablePayload } from '../types';
+import { IBaseOptions, IDragActivationOptions, IDraggableEvents, IModifierOptions, IPlacement, IPlacementMargins, TDnDNodeRef, TDraggablePayload } from '../types';
 import { Component, ComputedRef, Ref, WritableComputedRef } from 'vue';
 interface IMakeDraggableOptions extends IBaseOptions {
     events?: IDraggableEvents;
@@ -12,6 +12,7 @@ interface IMakeDraggableReturnType {
     selected: WritableComputedRef<boolean>;
     isDragging: ComputedRef<boolean>;
     isAllowed: ComputedRef<boolean>;
+    isDragOver: ComputedRef<IPlacement | undefined>;
 }
 export declare function makeDraggable(ref: TDnDNodeRef, payload?: TDraggablePayload): IMakeDraggableReturnType;
 export declare function makeDraggable(ref: TDnDNodeRef, options: IMakeDraggableOptions, payload?: TDraggablePayload): IMakeDraggableReturnType;

package/dist/external/composables/makeDroppable.d.ts

@@ -1,10 +1,11 @@
-import { IBaseOptions, IDroppableEvents, TDnDNodeRef, TDroppablePayload } from '../types';
+import { IBaseOptions, IDroppableEvents, IPlacement, TDnDNodeRef, TDroppablePayload } from '../types';
 import { ComputedRef } from 'vue';
 interface IMakeDroppableOptions extends IBaseOptions {
     events?: IDroppableEvents;
 }
 interface IMakeDroppableReturnType {
     isAllowed: ComputedRef<boolean>;
+    isDragOver: ComputedRef<IPlacement | undefined>;
 }
 export declare function makeDroppable(ref: TDnDNodeRef): IMakeDroppableReturnType;
 export declare function makeDroppable(ref: TDnDNodeRef, options: IMakeDroppableOptions, payload?: TDroppablePayload): IMakeDroppableReturnType;

package/dist/external/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const component: DefineComponent<object, object, unknown>;
+  export default component;
+}

package/dist/external/index.d.ts

@@ -1,8 +1,5 @@
-/**
- * Public API (external)
- * Re-exports from internal for future package consumers
- */
-export { default as DnDProvider } from './components/DnDProvider.vue';
+import { default as DnDProvider } from './components/DnDProvider.vue';
+export { DnDProvider };
 export { makeDraggable } from './composables/makeDraggable';
 export { makeSelectionArea } from './composables/makeSelectionArea';
 export { makeConstraintArea } from './composables/makeConstraintArea';
@@ -10,4 +7,5 @@ export { makeDroppable } from './composables/makeDroppable';
 export { useDnDProvider } from './composables/useDnDProvider';
 export { makeAutoScroll, type IAutoScrollOptions, } from './composables/makeAutoScroll';
 export { makeSnappedOverlayPosition, type TSnapOverlayOptions, } from './composables/makeSnappedOverlayPosition';
+export { createSensor, defaultCollisionDetection, type CollisionDetectionFn, type TMergeStrategy, } from '../internal/sensors';
 export type * from './types';

package/dist/external/types/entities.d.ts

@@ -1,26 +1,51 @@
-import { ComponentPublicInstance, ComputedRef, Ref } from 'vue';
-import { IPlacementMargins } from './placement';
+import { ComponentPublicInstance, ComputedRef, Ref, ShallowRef } from 'vue';
+import { IPlacement, IPlacementMargins } from './placement';
 import { IDragEvent } from './provider';
 export type TDnDNode = HTMLElement | ComponentPublicInstance | null;
 export type TDnDNodeRef = Readonly<Ref<TDnDNode>>;
 export type TDragAxis = 'x' | 'y' | 'both';
+/** Factory registered on a draggable: returns [index, items, dropData?] */
 export type TDraggablePayload<T = any, D = any> = () => [number, T[], D?];
 
-/** Resolved payload from TDraggablePayload (index + items + optional dropData) */
+/** Factory registered on a droppable zone: returns [items, userData?] */
+export type TDroppablePayload<T = any, U = any> = () => [T[], U?];
+
+// ─── Internal resolved types (used by entity system) ──────────────────────────
+
+/** @internal */
 export interface IDragPayload<T = unknown, D = unknown> {
   index: number;
   items: T[];
   dropData?: D;
 }
 
-export type TDroppablePayload<T = any, U = any> = () => [T[], U?];
-
-/** Resolved payload from TDroppablePayload (items + optional userData) */
+/** @internal */
 export interface IDropZonePayload<T = unknown, U = unknown> {
   items: T[];
   userData?: U;
 }
 
+// ─── Public event types ────────────────────────────────────────────────────────
+
+/** One dragged item — always carries its source array and position */
+export interface IDragItem<T = unknown, D = unknown> {
+  /** Index of this item in `items` */
+  index: number;
+  /** The actual object: `items[index]` */
+  item: T;
+  /** Source array (same reference as passed to the draggable payload factory) */
+  items: T[];
+  dropData?: D;
+}
+
+/** Drop zone context — present in onEnter / onDrop / onLeave */
+export interface IDropZoneContext<T = unknown, U = unknown> {
+  items: T[];
+  userData?: U;
+  /** Cursor position relative to the zone boundary */
+  placement: IPlacement | undefined;
+}
+
 export interface IBaseOptions {
   disabled?: boolean | Ref<boolean>;
   groups?: string[] | Ref<string[]>;
@@ -104,7 +129,7 @@ export interface IDraggableEvents {
 
 export interface IDroppableEvents {
   onEnter?: (event: IDragEvent) => void;
-  onDrop?: (event: IDragEvent) => void | Promise<void>;
+  onDrop?: (event: IDragEvent) => void | boolean | Promise<void | boolean>;
   onLeave?: (event: IDragEvent) => void;
 }
 
@@ -143,6 +168,7 @@ export interface IDraggableEntity extends IBaseEntity {
   activation?: IDragActivation;
   /** Margins for center zone. When pointer in center and element is also droppable, zone mode is used. */
   placementMargins?: IPlacementMargins;
+  hoveredPlacement?: IPlacement;
 }
 
 export interface IDraggingEntity extends IDraggableEntity {
@@ -154,4 +180,5 @@ export interface IDraggingEntity extends IDraggableEntity {
 export interface IDroppableEntity extends IBaseEntity {
   events?: IDroppableEvents;
   payload?: TDroppablePayload;
+  hoveredPlacement: IPlacement | undefined;
 }

package/dist/external/types/index.d.ts

@@ -1,4 +1,5 @@
-export type * from './pointer';
-export type * from './provider';
-export type * from './placement';
-export type * from './entities';
+export type * from './pointer';
+export type * from './provider';
+export type * from './placement';
+export type * from './entities';
+export type * from './operations';

package/dist/external/types/operations.d.ts

@@ -0,0 +1,184 @@
+import { IPlacement, TInsertSide, TPlacementOrientation } from './placement';
+// ── Result types ───────────────────────────────────────────────────────────────
+
+/**
+ * Result of suggestSort.
+ * Same-list: sourceItems === targetItems (one array, reordered).
+ * Cross-list: two different arrays — apply both.
+ */
+export interface ISuggestSortResult<T = unknown> {
+  /** Source list after removing dragged items. Same ref as targetItems when sameList. */
+  sourceItems: T[];
+  /** Target list after inserting dragged items at targetIndex. */
+  targetItems: T[];
+  /** The items that were moved (in original order). */
+  draggedItems: T[];
+  sourceIndexes: number[];
+  targetIndex: number;
+  mode: 'insert' | 'append' | 'prepend';
+  sameList: boolean;
+}
+
+/**
+ * Result of suggestSwap.
+ * Same-list: one array with positions swapped (sourceItems === targetItems).
+ * Cross-list: two arrays with the items exchanged.
+ * Multi-drag: dragged group exchanges with the single hovered item.
+ */
+export interface ISuggestSwapResult<T = unknown> {
+  /** Source list after swap. */
+  sourceItems: T[];
+  /** Target list after swap. Same ref as sourceItems when sameList. */
+  targetItems: T[];
+  sourceIndexes: number[];
+  targetIndex: number;
+  sameList: boolean;
+}
+
+/**
+ * Result of suggestCopy.
+ * Source list is NEVER modified — only target receives new items.
+ */
+export interface ISuggestCopyResult<T = unknown> {
+  /** Target list after inserting copies. */
+  targetItems: T[];
+  /** Shallow copies of the dragged items that were inserted. */
+  copiedItems: T[];
+  targetIndex: number;
+  mode: 'insert' | 'append' | 'prepend';
+}
+
+/**
+ * Result of suggestRemove.
+ */
+export interface ISuggestRemoveResult<T = unknown> {
+  /** Source list after removing dragged items. */
+  sourceItems: T[];
+  /** The items that were removed. */
+  removedItems: T[];
+  sourceIndexes: number[];
+}
+
+/** Draggable element currently under the cursor (inside the drop zone). */
+export interface IHoveredDraggableContext<T = unknown, D = unknown> {
+  element: HTMLElement;
+  /** Cursor position relative to this element. */
+  placement: IPlacement;
+  index: number;
+  /** The actual object: items[index]. */
+  item: T;
+  items: T[];
+  dropData?: D;
+}
+
+/** Placement helpers: interpret placement flags by list orientation. */
+export interface IPlacementHelpers {
+  /** 'before' = top (vertical) / left (horizontal). 'after' = bottom / right. */
+  getInsertSide(
+    placement: IPlacement | undefined,
+    orientation: TPlacementOrientation
+  ): TInsertSide | null;
+  isAtZoneStart(
+    placement: IPlacement | undefined,
+    orientation: TPlacementOrientation
+  ): boolean;
+  isAtZoneEnd(
+    placement: IPlacement | undefined,
+    orientation: TPlacementOrientation
+  ): boolean;
+}
+
+/**
+ * Helpers object available on every drag event via `event.helpers`.
+ *
+ * ── Low-level (stateless, no event context) ─────────────────────────────────
+ * Array primitives and placement interpreters. Use these to build custom logic.
+ *
+ * ── High-level (event-bound) ────────────────────────────────────────────────
+ * Preset operations that read the current event context.
+ * The user decides which one to call based on `event.hoveredDraggable`:
+ *
+ * ```ts
+ * onDrop(event) {
+ *   if (event.hoveredDraggable) {
+ *     // hovering over an element → sort / swap / copy into position
+ *     const r = event.helpers.suggestSort()
+ *     if (r) list.value = r.targetItems
+ *   } else {
+ *     // hovering over zone only → append / prepend / copy to zone
+ *     const r = event.helpers.suggestSort()
+ *     if (r) list.value = r.targetItems
+ *   }
+ * }
+ * ```
+ */
+export interface IHelpers {
+  // ── Low-level: array ops ──────────────────────────────────────────────────
+  /** Insert toInsert items into items at index. Returns new array. */
+  insertAt<T>(items: T[], index: number, toInsert: T[]): T[];
+  /** Remove count items at index. Returns new array. */
+  removeAt<T>(items: T[], index: number, count?: number): T[];
+  /** Remove multiple indexes (high → low, safe). Returns new array. */
+  removeIndexes<T>(items: T[], indexes: number[]): T[];
+  /** Swap items at positions i and j. Returns new array. */
+  swapAt<T>(items: T[], i: number, j: number): T[];
+
+  // ── Low-level: placement ──────────────────────────────────────────────────
+  /** 'before' or 'after' relative to the orientation axis, or null if ambiguous. */
+  getInsertSide(
+    placement: IPlacement | undefined,
+    orientation: TPlacementOrientation
+  ): TInsertSide | null;
+  /** True when pointer is at the very start edge of the zone (no center). */
+  isAtZoneStart(
+    placement: IPlacement | undefined,
+    orientation: TPlacementOrientation
+  ): boolean;
+  /** True when pointer is at the very end edge of the zone (no center). */
+  isAtZoneEnd(
+    placement: IPlacement | undefined,
+    orientation: TPlacementOrientation
+  ): boolean;
+
+  // ── High-level: event-bound presets ───────────────────────────────────────
+
+  /**
+   * **Sort / Transfer** — universal insert.
+   *
+   * - With `hoveredDraggable`: inserts dragged items before or after the
+   *   hovered element (determined by cursor placement).
+   * - Without `hoveredDraggable`: appends to zone start/end based on zone placement.
+   * - Same-list: reorders in place. Cross-list: transfers (removes from source, inserts into target).
+   *
+   * Returns null when context is insufficient (no draggedItems or no dropZone).
+   * Cast result arrays to your item type: `r.targetItems as MyItem[]`.
+   */
+  suggestSort(orientation?: TPlacementOrientation): ISuggestSortResult | null;
+
+  /**
+   * **Swap** — exchange the single dragged item with the hovered element.
+   *
+   * - Same-list: swaps two positions in one array.
+   * - Cross-list: exchanges items between two arrays.
+   *
+   * Returns null when multi-drag or no `hoveredDraggable`.
+   */
+  suggestSwap(): ISuggestSwapResult | null;
+
+  /**
+   * **Copy** — insert copies of dragged items at target position WITHOUT removing from source.
+   *
+   * Position logic is identical to `suggestSort`.
+   * Useful for copy-on-drag (e.g. held Ctrl key).
+   *
+   * Returns null when context is insufficient.
+   */
+  suggestCopy(orientation?: TPlacementOrientation): ISuggestCopyResult | null;
+
+  /**
+   * **Remove** — remove dragged items from their source list.
+   *
+   * Returns null when there are no draggedItems.
+   */
+  suggestRemove(): ISuggestRemoveResult | null;
+}

package/dist/external/types/placement.d.ts

@@ -1,12 +1,24 @@
+/**
+ * Which side(s) of the element/zone the pointer is in.
+ * Multiple flags can be true (e.g. top + right for corner). Do not normalize.
+ * - vertical list: top = before, bottom = after
+ * - horizontal list: left = before, right = after
+ * - center: pointer in center zone (dual-role draggable+zone)
+ */
 export interface IPlacement {
   top: boolean;
   right: boolean;
   bottom: boolean;
   left: boolean;
   /** True when pointer is in center zone (inside placementMargins). Used for dual-role draggable+zone. */
-  center?: boolean;
+  center: boolean;
 }
 
+export type TPlacementOrientation = 'vertical' | 'horizontal';
+
+/** 'before' | 'after' for insert position along one axis */
+export type TInsertSide = 'before' | 'after';
+
 export interface IPlacementMargins {
   top?: number;
   right?: number;

package/dist/external/types/provider.d.ts

@@ -1,19 +1,24 @@
-import { IConstraintsAreaEntity, IDragPayload, IDropZonePayload, IDraggableEntity, IDroppableEntity, IEntities, ISelectableAreaEntity, TDnDNode } from './entities';
+import { IConstraintsAreaEntity, IDraggableEntity, IDroppableEntity, IEntities, ISelectableAreaEntity, TDnDNode, IDragItem, IDropZoneContext } from './entities';
 import { ICoordinates, TPointerState } from './pointer';
-import { IAutoScrollOptions, IPlacement } from './placement';
+import { IAutoScrollOptions } from './placement';
+import { IHelpers, IHoveredDraggableContext } from './operations';
 import { Component, ComputedRef, CSSProperties, Reactive, Ref, ShallowRef, WritableComputedRef } from 'vue';
-/** Event object passed to drag/drop handlers */
+/** Event object passed to all drag/drop handlers */
 export interface IDragEvent<
-  T = unknown,
-  D = unknown,
-  U = unknown,
-  V = unknown,
+  DragT = unknown,
+  DragD = unknown,
+  ZoneT = unknown,
+  ZoneU = unknown,
 > {
-  /** Payload from the dragged item (draggable payload) */
-  payload: IDragPayload<T, D> | undefined;
-  /** Payload from the drop zone (droppable payload), set for onEnter/onDrop/onLeave */
-  dropZonePayload?: IDropZonePayload<U, V>;
+  /** All dragged items sorted by index. Length > 1 means multi-drag. */
+  draggedItems: IDragItem<DragT, DragD>[];
+  /** Drop zone context — present in onEnter / onDrop / onLeave. */
+  dropZone: IDropZoneContext<ZoneT, ZoneU> | undefined;
+  /** Draggable element under cursor inside the zone — use for insert-before/after. */
+  hoveredDraggable: IHoveredDraggableContext | undefined;
   provider: IDnDProviderExternal;
+  /** Helpers bound to this event. Low-level array ops + high-level suggest* presets. */
+  helpers: IHelpers;
 }
 
 /** Map element → placement for elements under cursor during drag */
@@ -24,6 +29,14 @@ export interface IHovered {
   droppable: THoveredMap;
 }
 
+export interface ICollision {
+  run?: (provider: any) => {
+    elements: HTMLElement[];
+    zones: HTMLElement[];
+  };
+  throttle: Ref<number>;
+}
+
 export interface IDnDProviderExternal {
   state: Ref<TDnDState | undefined>;
   pointer: Ref<TPointerState | undefined>;
@@ -51,13 +64,7 @@ export interface IDnDProviderExternal {
     to: WritableComputedRef<string | false | null | undefined>;
   };
   hovered: IHovered;
-  collision: {
-    run?: (provider: any) => {
-      elements: HTMLElement[];
-      zones: HTMLElement[];
-    };
-    throttle: Ref<number>;
-  };
+  collision: ICollision;
   autoScrollViewport: ComputedRef<
     IAutoScrollOptions | true | false | null | undefined
   >;
@@ -72,9 +79,12 @@ export type TDnDState =
   | 'dragging'
   | 'selecting'
   | 'activating'
+  | 'pending' /** awaiting async onDrop (e.g. confirm); drag still active */
   | null
   | undefined;
 
+export type TDropResult = 'accept' | 'cancel' | 'decline';
+
 /** DnDProvider props */
 export interface IDnDProviderProps {
   /** Enable viewport auto-scroll: true = defaults, object = options. false | null | undefined = disabled. */

package/dist/internal/logic/hover.d.ts

@@ -1,6 +1,5 @@
 import { IDnDProviderInternal } from '../types/provider';
 import { IHovered } from '../../external/types/provider';
-/** Applies collision result to hovered and triggers zone/draggable events */
 export declare const applyCollisionResultToHovered: (provider: IDnDProviderInternal, hovered: IHovered, result: {
     elements: HTMLElement[];
     zones: HTMLElement[];

package/dist/internal/logic/operations.d.ts

@@ -0,0 +1,35 @@
+import { IHelpers, IPlacementHelpers, ISuggestCopyResult, ISuggestRemoveResult, ISuggestSortResult, ISuggestSwapResult } from '../../external/types/operations';
+import { TPlacementOrientation, IPlacement } from '../../external/types/placement';
+/** Minimal event shape used by internal suggest* (avoids circular import). */
+export interface IDropEventContext {
+    draggedItems: Array<{
+        index: number;
+        item: unknown;
+        items: unknown[];
+        dropData?: unknown;
+    }>;
+    dropZone?: {
+        items: unknown[];
+        userData?: unknown;
+        placement: IPlacement | undefined;
+    };
+    hoveredDraggable?: {
+        element: HTMLElement;
+        placement: IPlacement;
+        index: number;
+        item: unknown;
+        items: unknown[];
+        dropData?: unknown;
+    };
+}
+export declare function insertAt<T>(items: T[], index: number, toInsert: T[]): T[];
+export declare function removeAt<T>(items: T[], index: number, count?: number): T[];
+/** Remove multiple indexes (order-safe: removes high → low). Returns new array. */
+export declare function removeIndexes<T>(items: T[], indexes: number[]): T[];
+export declare function swapAt<T>(items: T[], i: number, j: number): T[];
+export declare const placementHelpers: IPlacementHelpers;
+export declare function _suggestSort(event: IDropEventContext, orientation?: TPlacementOrientation): ISuggestSortResult | null;
+export declare function _suggestSwap(event: IDropEventContext): ISuggestSwapResult | null;
+export declare function _suggestCopy(event: IDropEventContext, orientation?: TPlacementOrientation): ISuggestCopyResult | null;
+export declare function _suggestRemove(event: IDropEventContext): ISuggestRemoveResult | null;
+export declare function createHelpers(ctx: IDropEventContext): IHelpers;

package/dist/internal/logic/payload.d.ts

@@ -1,12 +1,5 @@
-import { IDragPayload, IDropZonePayload } from '../../external/types';
-import { IDnDProviderInternal } from '../types/provider';
+export {};
 /**
- * Resolves payload from initiating draggable.
- * Calls entity.payload() and returns { index, items, dropData }.
+ * @internal — legacy helpers kept for compatibility with any code that might import them.
+ * The main drag event is now built directly in events.ts via buildDraggedItems().
  */
-export declare const createDragPayload: (provider: IDnDProviderInternal) => IDragPayload | undefined;
-/**
- * Resolves payload from a droppable zone.
- * Calls zone entity.payload() and returns { items, userData }.
- */
-export declare const createDropZonePayload: (provider: IDnDProviderInternal, zone: HTMLElement) => IDropZonePayload | undefined;

package/dist/internal/logic/pointer.d.ts

@@ -1,5 +1,7 @@
 import { IDnDProviderInternal } from '../types/provider';
-export declare function handleDropAndFinish(provider: IDnDProviderInternal): Promise<boolean>;
+import { TDropResult } from '../../external';
+export declare function runCollisionAndApply(provider: IDnDProviderInternal): void;
+export declare function handleDropAndFinish(provider: IDnDProviderInternal): Promise<TDropResult>;
 export declare function finishDragSession(provider: IDnDProviderInternal): void;
 export declare const createPointerHandlers: (provider: IDnDProviderInternal) => {
     pointerDown: (event: PointerEvent) => void;

package/dist/internal/sensors/collision-worker.d.ts

@@ -0,0 +1,28 @@
+import { IInternalWorker } from '../utils/createInternalWorker';
+export interface ICollisionBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ICollisionWorkerInput {
+    containerBox: ICollisionBox;
+    pointer: {
+        x: number;
+        y: number;
+    };
+    /** Packed as [x, y, width, height, ...] — 4 values per element */
+    elements: number[];
+    elementCount: number;
+    zones: number[];
+    zoneCount: number;
+    config: {
+        minOverlapPercent: number;
+    };
+}
+export interface ICollisionWorkerResult {
+    elementIndices: number[];
+    zoneIndices: number[];
+}
+export declare function getCollisionWorker(): IInternalWorker<ICollisionWorkerInput, ICollisionWorkerResult>;
+export declare function terminateCollisionWorker(): void;

package/dist/internal/sensors/default-collision.d.ts

@@ -1,7 +1,2 @@
-/**
- * Default collision: same logic as vue-dnd-box reference
- * - Filter: AABB overlap with container (overlay)
- * - Sort: pointer outside container → isPointerInElement + depth; else overlap % + centerDistance
- * - Returns full sorted list
- */
-export declare const defaultCollisionDetection: import('./sensor').CollisionDetectionFn;
+import { CollisionDetectionFn } from './sensor';
+export declare const defaultCollisionDetection: CollisionDetectionFn;

package/dist/internal/sensors/index.d.ts

@@ -1,2 +1,3 @@
 export * from './steps';
 export { defaultCollisionDetection } from './default-collision';
+export { createSensor, type CollisionDetectionFn, type TMergeStrategy, } from './sensor';

package/dist/internal/sensors/sensor.d.ts

@@ -6,7 +6,7 @@ import { IDnDProviderInternal } from '../types/provider';
  *
  * IMPORTANT: When implementing custom sensors, use:
  * - `provider.entities.allowedDroppableSet` for zones (visible + filtered by groups)
- * - `provider.entities.allowedDraggableSet` for draggables (visible + filtered by groups)
+ * - `provider.entities.allowedDraggableSet` for draggedItems (visible + filtered by groups)
  * OR use helper functions from `steps.ts`: `allowedVisibleZones()` and `visibleElements()`.
  */
 export type CollisionDetectionFn = (provider: IDnDProviderInternal) => {
@@ -40,6 +40,8 @@ export type TSortCompareFn = (a: {
         y: number;
     };
 }) => number;
+/** Merge strategy: how to combine elements and zones into final result */
+export type TMergeStrategy = 'separate' | 'unified-closest';
 export interface ICollisionMeta {
     isPointerInElement: boolean;
     overlapPercent: number;
@@ -56,6 +58,11 @@ export interface ISensorBuilder {
     collision(fn: TCollisionCheckFn): ISensorBuilder;
     sortElements(fn: TSortCompareFn): ISensorBuilder;
     sortZones(fn: TSortCompareFn): ISensorBuilder;
+    mergeStrategy(strategy: TMergeStrategy): ISensorBuilder;
+    /** Pick closest between first zone and first element by distance to pointer */
+    pickClosestBetweenFirst(enable: boolean): ISensorBuilder;
+    /** Filter by minimum overlap percent (0-100). Applied after collision check. */
+    minOverlapPercent(percent: number): ISensorBuilder;
     build(): CollisionDetectionFn;
 }
 export declare const createSensor: () => ISensorBuilder;

package/dist/internal/sensors/steps.d.ts

@@ -2,9 +2,18 @@ import { IDnDProviderInternal } from '../types/provider';
 import { TSortCompareFn, TFilterFn, TCollisionCheckFn, TContainerBoxFn } from './sensor';
 /** Container from overlay ref */
 export declare const overlayContainer: (p: IDnDProviderInternal) => HTMLElement | null;
-/** Box from overlay style (x,y) + size — overlay uses fixed+transform, getBoundingClientRect is wrong */
+/**
+ * Box from overlay style (x,y) + size.
+ * The overlay is `position:fixed; top:0; left:0; transform:translate(x,y)`, so
+ * getBoundingClientRect() is unreliable for the position (transform offsets it from 0,0).
+ * However the SIZE from getBoundingClientRect IS correct and is used as a fallback
+ * when the ResizeObserver hasn't fired yet (`overlay.size.value` is still null).
+ *
+ * Without the fallback: size=0 → containerBox is a zero-size point → pointer.x <= box.x+0
+ * fails whenever offset.x>0 (grabbed away from left edge) → pointerInContainer=false always.
+ */
 export declare const overlayBoxFromStyle: TContainerBoxFn;
-/** Allowed draggables (visible + filtered by groups) */
+/** Allowed draggedItems (visible + filtered by groups) */
 export declare const visibleElements: (p: IDnDProviderInternal) => Set<HTMLElement>;
 /** Allowed droppables (visible + filtered by groups) */
 export declare const allowedVisibleZones: (p: IDnDProviderInternal) => Set<HTMLElement>;
@@ -12,7 +21,7 @@ export declare const allowedVisibleZones: (p: IDnDProviderInternal) => Set<HTMLE
 export declare const filterNotDragging: TFilterFn;
 /** Exclude nodes that are descendants of any dragged element (nesting into self) */
 export declare const filterNotDescendantOfDragged: TFilterFn;
-/** Exclude disabled draggables and zones (including those inside disabled parents) */
+/** Exclude disabled draggedItems and zones (including those inside disabled parents) */
 export declare const filterNotDisabled: TFilterFn;
 /** Exclude: not dragging, not descendant of dragged, not disabled */
 export declare const filterValidCollisionTarget: TFilterFn;
@@ -20,7 +29,18 @@ export declare const filterValidCollisionTarget: TFilterFn;
 export declare const aabbCollision: TCollisionCheckFn;
 /** Pointer-in-element: cursor must be inside element (AABB of element) */
 export declare const pointerInElementCollision: TCollisionCheckFn;
+/** Always true — no container check (for "closest on screen" regardless of overlay position) */
+export declare const noContainerCollision: TCollisionCheckFn;
 /** Sort: deepest first (topmost visible element under cursor) */
 export declare const sortByDepth: TSortCompareFn;
-/** Sort: pointer-in-element + depth when pointer INSIDE container; overlap % + centerDistance when OUTSIDE */
+/** Sort: by distance from pointer to element center (closest first) */
+export declare const sortByPointerDistance: TSortCompareFn;
+/**
+ * Sort: pointer-in-element + depth when pointer inside container; overlap % + centerDistance when outside.
+ *
+ * The container box MUST be computed via overlayBoxFromStyle (not getBoundingClientRect) so that
+ * position is correct for a fixed+transform overlay. The size fallback in overlayBoxFromStyle ensures
+ * the box is never zero-sized on the first frame, making `pointerInContainer` reliably true whenever
+ * the cursor is above the drag ghost.
+ */
 export declare const sortByOverlapAndPointer: TSortCompareFn;

package/dist/internal/types/auto-scroll.d.ts

@@ -8,12 +8,13 @@ export interface IAutoScrollOptionsInternal {
 export interface IScrollState {
   scrollTop: number;
   scrollLeft: number;
-  rect: DOMRect;
 }
 
 export interface IScrollAdapter {
   getScrollState(el: HTMLElement): IScrollState;
   setScroll(el: HTMLElement, scrollTop: number, scrollLeft: number): void;
+  /** Override rect calculation. Defaults to el.getBoundingClientRect(). */
+  getRect?(el: HTMLElement): DOMRect;
 }
 
 export type TOverlayPoint = { x: number; y: number } | null;

package/dist/internal/types/provider.d.ts

@@ -26,5 +26,7 @@ export interface IDnDProviderInternal extends IDnDProviderExternal {
     droppableObserver: IIntersectionObserverWrapper;
     selectableAreaObserver: IIntersectionObserverWrapper;
     overlaySizeObserver: { disconnect: () => void };
+    /** BoundingClientRect cache — invalidated on scroll and session reset */
+    rectCache: Map<HTMLElement, DOMRect>;
   };
 }