Refactor CollisionDetection to return an array of Collisions (#558)

Author: clauderic

.changeset/array-of-collisions.md

@@ -0,0 +1,41 @@
+---
+'@dnd-kit/core': major
+'@dnd-kit/sortable': minor
+---
+
+Refactor of the `CollisionDetection` interface to return an array of `Collision`s:
+
+```diff
++export interface Collision {
++  id: UniqueIdentifier;
++  data?: Record<string, any>;
++}
+
+export type CollisionDetection = (args: {
+  active: Active;
+  collisionRect: ClientRect;
+  droppableContainers: DroppableContainer[];
+  pointerCoordinates: Coordinates | null;
+-}) => UniqueIdentifier;
++}) => Collision[];
+```
+
+This is a breaking change that requires all collision detection strategies to be updated to return an array of `Collision` rather than a single `UniqueIdentifier`
+
+The `over` property remains a single `UniqueIdentifier`, and is set to the first item in returned in the collisions array.
+
+Consumers can also access the `collisions` property which can be used to implement use-cases such as combining droppables in user-land.
+
+The `onDragMove`, `onDragOver` and `onDragEnd` callbacks are also updated to receive the collisions array property.
+
+Built-in collision detections such as rectIntersection, closestCenter, closestCorners and pointerWithin adhere to the CollisionDescriptor interface, which extends the Collision interface:
+
+```ts
+export interface CollisionDescriptor extends Collision {
+  data: {
+    droppableContainer: DroppableContainer;
+    value: number;
+    [key: string]: any;
+  };
+}
+```

packages/core/src/components/DndContext/DndContext.tsx

@@ -59,6 +59,7 @@ import {
   defaultCoordinates,
   getAdjustedRect,
   getRectDelta,
+  getFirstCollision,
   rectIntersection,
 } from '../../utilities';
 import {getTransformAgnosticClientRect} from '../../utilities/rect';
@@ -209,6 +210,7 @@ export const DndContext = memo(function DndContext({
     active: null,
     activeNode,
     collisionRect: null,
+    collisions: null,
     droppableRects,
     draggableNodes,
     draggingNode: null,
@@ -282,7 +284,7 @@ export const DndContext = memo(function DndContext({
     ? getAdjustedRect(draggingNodeRect, modifiedTranslate)
     : null;
 
-  const overId =
+  const collisions =
     active && collisionRect
       ? collisionDetection({
           active,
@@ -291,6 +293,7 @@ export const DndContext = memo(function DndContext({
           pointerCoordinates,
         })
       : null;
+  const overId = getFirstCollision(collisions, 'id');
   const [over, setOver] = useState<Over | null>(null);
 
   const transform = adjustScale(
@@ -368,14 +371,20 @@ export const DndContext = memo(function DndContext({
 
       function createHandler(type: Action.DragEnd | Action.DragCancel) {
         return async function handler() {
-          const {active, over, scrollAdjustedTranslate} = sensorContext.current;
+          const {
+            active,
+            collisions,
+            over,
+            scrollAdjustedTranslate,
+          } = sensorContext.current;
           let event: DragEndEvent | null = null;
 
           if (active && scrollAdjustedTranslate) {
             const {cancelDrop} = latestProps.current;
 
             event = {
               active: active,
+              collisions,
               delta: scrollAdjustedTranslate,
               over,
             };
@@ -480,14 +489,15 @@ export const DndContext = memo(function DndContext({
 
   useEffect(() => {
     const {onDragMove} = latestProps.current;
-    const {active, over} = sensorContext.current;
+    const {active, collisions, over} = sensorContext.current;
 
     if (!active) {
       return;
     }
 
     const event: DragMoveEvent = {
       active,
+      collisions,
       delta: {
         x: scrollAdjustedTranslate.x,
         y: scrollAdjustedTranslate.y,
@@ -503,6 +513,7 @@ export const DndContext = memo(function DndContext({
     () => {
       const {
         active,
+        collisions,
         droppableContainers,
         scrollAdjustedTranslate,
       } = sensorContext.current;
@@ -524,6 +535,7 @@ export const DndContext = memo(function DndContext({
           : null;
       const event: DragOverEvent = {
         active,
+        collisions,
         delta: {
           x: scrollAdjustedTranslate.x,
           y: scrollAdjustedTranslate.y,
@@ -546,6 +558,7 @@ export const DndContext = memo(function DndContext({
       active,
       activeNode,
       collisionRect,
+      collisions,
       droppableRects,
       draggableNodes,
       draggingNode,
@@ -563,6 +576,7 @@ export const DndContext = memo(function DndContext({
   }, [
     active,
     activeNode,
+    collisions,
     collisionRect,
     draggableNodes,
     draggingNode,
@@ -592,6 +606,7 @@ export const DndContext = memo(function DndContext({
       ariaDescribedById: {
         draggable: draggableDescribedById,
       },
+      collisions,
       containerNodeRect,
       dispatch,
       dragOverlay,
@@ -613,6 +628,7 @@ export const DndContext = memo(function DndContext({
     activeNodeRect,
     activatorEvent,
     activators,
+    collisions,
     containerNodeRect,
     dragOverlay,
     dispatch,

packages/core/src/hooks/useDroppable.ts

@@ -23,7 +23,7 @@ export function useDroppable({
   id,
 }: UseDroppableArguments) {
   const key = useUniqueId(ID_PREFIX);
-  const {active, dispatch, over} = useContext(Context);
+  const {active, collisions, dispatch, over} = useContext(Context);
   const rect = useRef<ClientRect | null>(null);
   const [nodeRef, setNodeRef] = useNodeRef();
   const dataRef = useData(data);
@@ -68,6 +68,7 @@ export function useDroppable({
 
   return {
     active,
+    collisions,
     rect,
     isOver: over?.id === id,
     node: nodeRef,

packages/core/src/index.ts

@@ -94,10 +94,15 @@ export type {
 export {
   defaultCoordinates,
   getClientRect,
+  getFirstCollision,
   getScrollableAncestors,
   closestCenter,
   closestCorners,
   rectIntersection,
   pointerWithin,
 } from './utilities';
-export type {CollisionDetection} from './utilities';
+export type {
+  Collision,
+  CollisionDescriptor,
+  CollisionDetection,
+} from './utilities';

packages/core/src/sensors/pointer/AbstractPointerSensor.ts

@@ -5,6 +5,7 @@ import {
   getWindow,
 } from '@dnd-kit/utilities';
 
+import {defaultCoordinates} from '../../utilities';
 import {
   getEventListenerTarget,
   hasExceededDistance,
@@ -80,7 +81,7 @@ export class AbstractPointerSensor implements SensorInstance {
     this.documentListeners = new Listeners(this.document);
     this.listeners = new Listeners(listenerTarget);
     this.windowListeners = new Listeners(getWindow(target));
-    this.initialCoordinates = getEventCoordinates(event);
+    this.initialCoordinates = getEventCoordinates(event) ?? defaultCoordinates;
     this.handleStart = this.handleStart.bind(this);
     this.handleMove = this.handleMove.bind(this);
     this.handleEnd = this.handleEnd.bind(this);
@@ -174,7 +175,7 @@ export class AbstractPointerSensor implements SensorInstance {
       return;
     }
 
-    const coordinates = getEventCoordinates(event);
+    const coordinates = getEventCoordinates(event) ?? defaultCoordinates;
     const delta = getCoordinatesDelta(initialCoordinates, coordinates);
 
     if (!activated && activationConstraint) {

packages/core/src/sensors/types.ts

@@ -14,6 +14,7 @@ import type {
   UniqueIdentifier,
   ClientRect,
 } from '../types';
+import type {Collision} from '../utilities/algorithms';
 
 export enum Response {
   Start = 'start',
@@ -25,6 +26,7 @@ export type SensorContext = {
   active: Active | null;
   activeNode: HTMLElement | null;
   collisionRect: ClientRect | null;
+  collisions: Collision[] | null;
   draggableNodes: DraggableNodes;
   draggingNode: HTMLElement | null;
   draggingNodeRect: ClientRect | null;

packages/core/src/store/context.ts

@@ -13,6 +13,7 @@ export const Context = createContext<DndContextDescriptor>({
   ariaDescribedById: {
     draggable: '',
   },
+  collisions: null,
   containerNodeRect: null,
   dispatch: noop,
   draggableNodes: {},

packages/core/src/store/types.ts

@@ -1,6 +1,7 @@
 import type {MutableRefObject} from 'react';
 
 import type {Coordinates, ClientRect, UniqueIdentifier} from '../types';
+import type {Collision} from '../utilities/algorithms';
 import type {SyntheticListeners} from '../hooks/utilities';
 import type {Actions} from './actions';
 import type {DroppableContainersMap} from './constructors';
@@ -80,6 +81,7 @@ export interface DndContextDescriptor {
   ariaDescribedById: {
     draggable: UniqueIdentifier;
   };
+  collisions: Collision[] | null;
   containerNodeRect: ClientRect | null;
   draggableNodes: DraggableNodes;
   droppableContainers: DroppableContainers;

packages/core/src/types/events.ts

@@ -1,8 +1,11 @@
 import type {Active, Over} from '../store';
+import type {Collision} from '../utilities/algorithms';
+
 import type {Translate} from './coordinates';
 
 interface DragEvent {
   active: Active;
+  collisions: Collision[] | null;
   delta: Translate;
   over: Over | null;
 }

packages/core/src/utilities/algorithms/closestCenter.ts

@@ -1,7 +1,8 @@
 import {distanceBetween} from '../coordinates';
-import type {Coordinates, ClientRect, UniqueIdentifier} from '../../types';
+import type {Coordinates, ClientRect} from '../../types';
 
-import type {CollisionDetection} from './types';
+import type {CollisionDescriptor, CollisionDetection} from './types';
+import {sortCollisionsAsc} from './helpers';
 
 /**
  * Returns the coordinates of the center of a given ClientRect
@@ -18,7 +19,7 @@ function centerOfRectangle(
 }
 
 /**
- * Returns the closest rectangle from an array of rectangles to the center of a given
+ * Returns the closest rectangles from an array of rectangles to the center of a given
  * rectangle.
  */
 export const closestCenter: CollisionDetection = ({
@@ -30,23 +31,20 @@ export const closestCenter: CollisionDetection = ({
     collisionRect.left,
     collisionRect.top
   );
-  let minDistanceToCenter = Infinity;
-  let minDroppableContainer: UniqueIdentifier | null = null;
+  const collisions: CollisionDescriptor[] = [];
 
   for (const droppableContainer of droppableContainers) {
     const {
+      id,
       rect: {current: rect},
     } = droppableContainer;
 
     if (rect) {
       const distBetween = distanceBetween(centerOfRectangle(rect), centerRect);
 
-      if (distBetween < minDistanceToCenter) {
-        minDistanceToCenter = distBetween;
-        minDroppableContainer = droppableContainer.id;
-      }
+      collisions.push({id, data: {droppableContainer, value: distBetween}});
     }
   }
 
-  return minDroppableContainer;
+  return collisions.sort(sortCollisionsAsc);
 };