Element adapter

• draggable: enable dragging of an element.
• dropTargetForElements: marking an element as a valid drop target
• monitorForElements: create a monitor to listen for element drag operation events anywhere.
• types: all types for this adapter.

• setCustomNativeDragPreview: use a new element as the native drag preview
• pointerOutsideOfPreview: native drag preview function to place the users pointer outside of the drag preview
• centerUnderPointer: native drag preview function to place the center of the ntaive drag preview under the users pointer
• preserveOffsetOnSource: native drag preview function to match the pointer position on a native drag preview as close as possible to the pointer position on the draggable element
• disableNativeDragPreview: disable the native drag preview (helpful if you want to use your own custom drag preview or have no drag preview)
• scrollJustEnoughIntoView: scroll an element just enough into view so it is visible (helpful when working with default native drag previews)

• Outside of any drop targets
• Inside any amount of levels of nested drop targets
• So, anywhere!

• You can add new draggables
• You can remount a draggable. See Reconciliation
• You can change the dimensions of the dragging draggable during a drag. But keep in mind that won't change the drag preview image, as that is collected only at the start of the drag (in onGenerateDragPreview())
• You can remove the dragging draggable during a drag operation. When a draggable is removed it's event functions (eg onDrag) will no longer be called. Being able to remove the dragging draggable is a common requirement for virtual lists

• element: HTMLElement: a HTMLElement that will be draggable (using HTMLElement as that is the interface that allows the "draggable" attribute)
• dragHandle?: Element: an optional Element that can be used to designate the part of the draggable that can exclusively used to drag the whole draggable
• canDrag?: (args: GetFeedbackArgs) => boolean: used to conditionally allow dragging (see below)
• getInitialData?: (args: GetFeedbackArgs) => Record<string, unknown>: a one time attaching of data to a draggable as a drag is starting. If you want to understand the type of data attached to a drop target elsewhere in your application, see our typing data guide.
• getInitialDataForExternal?: (args: GetFeedbackArgs) => {[Key in NativeMediaType]?: string;}: used to attach native data (eg "text/plain") to other windows or applications.

type GetFeedbackArgs = {
    /**
     * The user input as a drag is trying to start (the `initial` input)
     */
    input: Input;
    /**
     * The `draggable` element
     */
    element: HTMLElement;
    /**
     * The `dragHandle` element for the `draggable`
     */
    dragHandle: Element | null;
};

• onGenerateDragPreview
• onDragStart
• onDrag
• onDropTargetChange
• onDrop

draggable({
    element: myElement,
    dragHandle: myDragHandleElement,
});

draggable({
    element: myElement,
    // disable dragging
    canDrag: () => false,
});

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

function noop(){};

function Item({isDraggingEnabled}: {isDraggingEnabled: boolean}) {
  const ref = useRef();

  useEffect({
    // when disabled, don't make the element draggable
    // this will allow a parent draggable to still be dragged
    if(!isDraggingEnabled) {
      return noop;
    }
    return draggable({
      element: ref.current,
    });
  }, [isDraggingEnabled]);

  return <div ref={ref}>Draggable item</div>
};

draggable({
    element: myElement,
    getInitialData: () => ({ taskId: task.id }),
    getInitialDataForExternal: () => ({
        'text/plain': task.description,
        'text/uri-list': task.url,
    }),
});

import { formatURLsForExternal } from '@atlaskit/pragmatic-drag-and-drop/element/format-urls-for-external';

draggable({
    element: myElement,
    getInitialData: () => ({ taskId: task.id }),
    getInitialDataForExternal: () => ({
        'text/plain': task.description,
        'text/uri-list': formatURLsForExternal([task.url, task.anotherUrl]),
    }),
});

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

const cleanup = dropTargetForElements({
  element: myElement,
  onDragStart: () => console.log('Something started dragging in me!');
});

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

const cleanup = monitorForElements({
  onDragStart: () => console.log('Dragging an element');
});

type ElementEventBasePayload = {
    location: DragLocationHistory;
    source: ElementDragPayload;
};

type ElementDragPayload = {
    element: HTMLElement;
    dragHandle: Element | null;
    data: Record<string, unknown>;
};

type ElementEventPayloadMap = {
    onDragStart: ElementEventBasePayload;
    // .. the rest of the events
};

type ElementGetFeedbackArgs = {
    /**
     * The user input as a drag is trying to start (the `initial` input)
     */
    input: Input;
    /**
     * The `draggable` element
     */
    element: HTMLElement;
    /**
     * The `dragHandle` element for the `draggable`
     */
    dragHandle: Element | null;
};

type ElementDropTargetEventBasePayload = ElementEventBasePayload & {
    /**
     * A convenance pointer to this drop targets values
     */
    self: DropTargetRecord;
};

type ElementDropTargetEventPayloadMap = {
    onDragStart: ElementDropTargetEventBasePayload;
    // .. the rest of the events
};

type ElementDropTargetGetFeedbackArgs = {
    /**
     * The users _current_ input
     */
    input: Input;
    /**
     * The data associated with the entity being dragged
     */
    source: ElementDragPayload;
    /**
     * This drop target's element
     */
    element: Element;
};

type ElementMonitorGetFeedbackArgs = {
    /**
     * The users `initial` drag location
     */
    initial: DragLocation;
    /**
     * The data associated with the entity being dragged
     */
    source: ElementDragPayload;
};

import type {
    // Payload for the draggable being dragged
    ElementDragPayload,
    // Base events
    ElementEventBasePayload,
    ElementEventPayloadMap,
    // Drop target events
    ElementDropTargetEventBasePayload,
    ElementDropTargetEventPayloadMap,
    // Feedback types
    ElementGetFeedbackArgs,
    ElementDropTargetGetFeedbackArgs,
    ElementMonitorGetFeedbackArgs,
} from '@atlaskit/pragmatic-drag-and-drop/element/adapter';

• Drag preview documentation → how to control what the user drags around during a drag
• Typing data → how to improve the types for "data"
• Unregistered elements