External adapter

• drags that started from the users operating system (eg files)
• drags that started from other windows (including from child <iframe>s)

• dropTargetForExternal: marking an element as a valid drop target for external entities
• monitorForExternal: create a monitor to listen for an external drag operation events anywhere
• types: all types for this adapter

• Files
• URLs
• Text
• HTML
• Custom media

• some: combine predicates and return true if any predicate matches (eg some(containsText, containsHTML))

import { dropTargetForExternal } from '@atlaskit/pragmatic-drag-and-drop/external/adapter';

const cleanup = dropTargetForExternal({
  element: myElement,
  onDragEnter: () => console.log('Some external data was dragged over me');
});

import { monitorForExternal } from '@atlaskit/pragmatic-drag-and-drop/external/adapter';

const cleanup = monitorForExternal({
  onDragStart: () => console.log('An external drag has entered the window');
});

import { dropTargetForExternal, monitorForExternal } from '@atlaskit/pragmatic-drag-and-drop/external/adapter';
import { containsFiles } from '@atlaskit/pragmatic-drag-and-drop/external/file';

dropTargetForExternal({
  element: myElement,
  canDrop: containsFiles,
  onDragEnter: () => console.log('A file is being dragged over me');
});

monitorForExternal({
  canMonitor: containsFiles,
  onDragStart: () => console.log('A file is being dragged');
});

import { dropTargetForExternal, monitorForExternal } from '@atlaskit/pragmatic-drag-and-drop/external/adapter';
import { containsFiles } from '@atlaskit/pragmatic-drag-and-drop/external/file';
import { containsText } from '@atlaskit/pragmatic-drag-and-drop/external/text';

dropTargetForExternal({
  canMonitor: some(containsFiles, containsText),
  onDragEnter: () => console.log('A file or text is being dragged over me');
});

monitorForExternal({
  canMonitor: some(containsFiles, containsText),
  onDragStart: () => console.log('A file or text is being dragged');
});

• onGenerateDragPreview is removed from external drop targets and monitors. For external operations the drag preview has already been generated externally.
• onDragStart is removed from external drop targets as an external drag operation can never start from inside a drop target in the window

dropTargetForExternal({
    element: el,
    onDragEnter: () => console.log('user is now over this drop target'),
    onDragLeave: () => console.log('user is no longer over this drop target'),
    onDrop: () => console.log('user dropped on this drop target (or a child drop target)'),
});
monitorForExternal({
    onDragStart: () => console.log('file is entering the window'),
    onDrop: () => console.log('drag is finished'),
});

• dragging from one page to another browser tab on the same domain
• dragging from one page to another browser tab on a different domain
• dragging from one page native applications
• dragging from one page to a child <iframe> on the same domain
• dragging from a child <iframe> to a child <iframe> on the same domain
• dragging from one page to an <iframe> (on any domain) on a different browser tab (on any domain)

• dragging from one page to a child <iframe> on a different domain
• dragging from a child <iframe> to a parent page on a different domain

import {
    dropTargetForExternal,
    monitorForExternal,
} from '@atlaskit/pragmatic-drag-and-drop/external/adapter';
import { containsFiles, getFiles } from '@atlaskit/pragmatic-drag-and-drop/external/file';
import { containsText, getText } from '@atlaskit/pragmatic-drag-and-drop/external/text';

dropTargetForExternal({
    canDrop: some(containsFiles, containsText),
    onDrop({ source }) {
        const files = getFiles({ source });
        const text = getText({ source });
    },
});

monitorForExternal({
    canMonitor: some(containsFiles, containsText),
    onDrop({ source }) {
        const files = getFiles({ source });
        const text = getText({ source });
    },
});

1. in the onDrop() event, and
2. when the user is dropping on a drop target (including when over a drop target due to stickiness)

type ExternalEventBasePayload = {
    location: DragLocationHistory;
    source: ExternalDragPayload;
};

export type ExternalDragPayload = {
    /**
     * The media types that are being dragged during a drag.
     *
     * @example
     *
     * console.log(source.types);
     * // → ["text/plain", "text/html"]
     */
    types: NativeMediaType[];
    /**
     * The entities that are being dragged.
     * Usually you will not be using these directly, but
     * our helper functions can leverage them to extract
     * particular kinds of data (eg files) that are being dragged
     */
    items: DataTransferItem[];
    /**
     * returns the data for a given media type.
     *
     * - `getStringData(mediaType)` will return `null` if there is no data for that media type
     * - `getStringData(mediaType)` will return the empty string (`""`) if the empty string (`""`)
     *      was explicitly set as the data for a media type.
     * - `getStringData(mediaType)` will return null if requesting files (ie `getStringData('Files')`).
     *      To access files, use `source.items`, or better still, `getFiles({source})`
     *
     * Generally we recommend folks use our helpers to read native data rather than `getStringData(mediaType)`
     *
     * @example
     *
     * ```ts
     * // Using getStringData()
     * const text: string | null = source.getStringData("text/plain");
     *
     * // Using our text helper
     * const text: string | null = getText({source});
     * ```
     * */
    getStringData: (mediaType: string) => string | null;
};

type NativeMediaType = 'text/uri-list' | 'text/plain' | 'text/html' | 'Files' | string;

type ExternalEventPayloadMap = {
    onDragStart: ExternalEventBasePayload;
    // .. the rest of the events
};

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

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

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

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

import type {
  // The data that is being dragged
  NativeMediaType,
  ExternalDragPayload
  // Base events
  ExternalEventBasePayload
  ExternalEventPayloadMap,
  // Drop target events
  ElementDropTargetEventBasePayload,
  ExternalDropTargetEventPayloadMap,
  // Feedback types
  ExternalDropTargetGetFeedbackArgs,
  ExternalMonitorGetFeedbackArgs,
} from '@atlaskit/pragmatic-drag-and-drop/external/adapter';