Reconciliation

The key for a drop target is the element. At any one time, only a single drop target for a particular entity type (eg files) can be attached to the same element.

// ✅ Using the same element as a drop target for elements and for files
const cleanup = combine(
    dropTargetForElements({
        element: myElement,
    }),
    dropTargetForExternal({
        element: myElement,
    }),
);

// ❌ Using the same element for two drop targets of the same entity type is not allowed
const cleanup = combine(
    dropTargetForElements({
        element: myElement,
    }),
    // ⚠️ A warning will be logged if this is detected
    dropTargetForElements({
        element: myElement,
    }),
);

During a drag operation, if a drop target is removed and readded on the same element, then @atlaskit/pragmatic-drag-and-drop will treat the added drop target as if it was the same drop target.

const monitor = monitorForElements({
    onDragStart: () => console.log('monitor:start'),
    onDropTargetChange: () => console.log('monitor:change'),
    onDrop: () => console.log('monitor:drop'),
});
const cleanup1 = dropTargetForElements({
    element: A,
    onDragStart: () => console.log('A1:start'),
    onDropTargetChange: () => console.log('A1:change'),
    onDrop: () => console.log('A1:drop'),
});

// a drag starts
// console.log → 'A1:start', 'monitor:start'

// drop target is removed during a drag
cleanup1();
// console.log not called (no change event is fired)

const cleanup2 = dropTargetForElements({
    element: A,
    onDragStart: () => console.log('A2:start'),
    onDropTargetChange: () => console.log('A2:change'),
    onDrop: () => console.log('A2:drop'),
});

// a dragover occurs
// console.log → 'A2:drag', 'monitor:drag'
// 👆 note: no 'change' event occured, A2 is treated as A1

The key for a draggable is the element. An element can only be used for a single draggable.

// ❌ Using the same element for two draggables
  draggable({
    element: myElement,
  }),
  // ⚠️ A warning will be logged if this is detected
  draggable({
    element: myElement,
  }),
);

During a drag operation, if the dragging draggable is removed and readded on the same element, then @atlaskit/pragmatic-drag-and-drop will treat the added draggable as if it was the original draggable.

const monitor = monitorForElements({
    onDragStart: () => console.log('monitor:start'),
    onDrop: () => console.log('monitor:drop'),
});
const cleanup1 = draggable({
    element: A,
    onDragStart: () => console.log('A1:start'),
    onDrop: () => console.log('A1:drop'),
});

// a drag starts
// console.log → 'A1:start', 'monitor:start'

// drop target is removed during a drag
cleanup1();
// console.log not called (no change event is fired)

const cleanup2 = dropTargetForElements({
    element: A,
    onDragStart: () => console.log('A2:start'),
    onDrop: () => console.log('A2:drop'),
});

// a drop occurs
// console.log → 'A2:drop', 'monitor:drop'
// 👆 note: the drop event occured on 'A2' even though it was not the same `draggable()` as the original drag

Remounting a draggable common in react where you might do something like this:

function Card() {
    const ref = useRef();
    const [dragCount, setCount] = useState(0);

    useEffect(() => {
        return draggable({
            element,
            onDragStart: () => setCount(dragCount + 1),
        });
        // when dragCount changes our `draggable` will be remounted
    }, [dragCount]);

    return <div ref={ref}>I have been dragged {dragCount} times</div>;
}

This is a contrived example, because you could avoid the remounting in this case by doing this:

function Card() {
    const ref = useRef();
    const [dragCount, setCount] = useState(0);

    useEffect(() => {
        return draggable({
            element,
            onDragStart: () => setCount((current) => current + 1),
        });
        // no longer need to remount when `dragCount` changes
    }, []);

    return <div ref={ref}>I have been dragged {dragCount} times</div>;
}

Each call to create a monitor will create a new monitor, even if the monitor definition is shared. There is no key for monitors.

import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';

const args = {
    onGenerateDragPreview: () => console.log('monitor:preview'),
};

// these two monitors are sharing the same `args` reference
// but they will both create an independent monitor
const cleanup1 = monitorForElements(args);
const cleanup2 = monitorForElements(args);

// → A drag starts

// console.log:
// - 'monitor:preview'
// - 'monitor:preview'

// → A drag finishes

// removing one monitor
cleanup1();

// → Another drag starts
// console.log:
// - 'monitor:preview'
// 👆 one monitor is still active