({
+ dragging: undefined,
+ setDragging: () => {},
+});
+
+/**
+ * The argument to DragDropProvider.
+ */
+export interface ProviderProps {
+ /**
+ * The item being dragged. If unspecified, the provider will
+ * behave as if it is the root provider.
+ */
+ dragging: unknown;
+
+ /**
+ * Sets the item being dragged. If unspecified, the provider
+ * will behave as if it is the root provider.
+ */
+ setDragging: (dragging: unknown) => void;
+
+ /**
+ * The React children.
+ */
+ children: React.ReactNode;
+}
+
+/**
+ * A React provider that tracks the dragging state. This should
+ * be placed at the root of any React application that supports
+ * drag / drop.
+ *
+ * @param props
+ */
+export function RootDragDropProvider({ children }: { children: React.ReactNode }) {
+ const [state, setState] = useState<{ dragging: unknown }>({
+ dragging: undefined,
+ });
+ const setDragging = (dragging: unknown) => setState({ dragging });
+
+ return (
+
+ {children}
+
+ );
+}
+
+/**
+ * A React drag / drop provider that derives its state from a RootDragDropProvider. If
+ * part of a React application is rendered separately from the root, this provider can
+ * be used to enable drag / drop functionality within the disconnected part.
+ *
+ * @param props
+ */
+export function ChildDragDropProvider({ dragging, setDragging, children }: ProviderProps) {
+ return {children};
+}
diff --git a/x-pack/plugins/lens/public/drag_drop/readme.md b/x-pack/plugins/lens/public/drag_drop/readme.md
new file mode 100644
index 0000000000000..8d11cb6226927
--- /dev/null
+++ b/x-pack/plugins/lens/public/drag_drop/readme.md
@@ -0,0 +1,69 @@
+# Drag / Drop
+
+This is a simple drag / drop mechanism that plays nice with React.
+
+We aren't using EUI or another library, due to the fact that Lens visualizations and datasources may or may not be written in React. Even visualizations which are written in React will end up having their own ReactDOM.render call, and in that sense will be a standalone React application. We want to enable drag / drop across React and native DOM boundaries.
+
+## Getting started
+
+First, place a RootDragDropProvider at the root of your application.
+
+```js
+
+ ... your app here ...
+
+```
+
+If you have a child React application (e.g. a visualization), you will need to pass the drag / drop context down into it. This can be obtained like so:
+
+```js
+const context = useContext(DragContext);
+```
+
+In your child application, place a `ChildDragDropProvider` at the root of that, and spread the context into it:
+
+```js
+
+ ... your child app here ...
+
+```
+
+This enables your child application to share the same drag / drop context as the root application.
+
+## Dragging
+
+An item can be both draggable and droppable at the same time, but for simplicity's sake, we'll treat these two cases separately.
+
+To enable dragging an item, use `DragDrop` with both a `draggable` and a `value` attribute.
+
+```js
+
+ {fields.map(f => (
+
+ {f.name}
+
+ ))}
+
+```
+
+## Dropping
+
+To enable dropping, use `DragDrop` with both a `droppable` attribute and an `onDrop` handler attribute. Droppable should only be set to true if there is an item being dragged, and if a drop of the dragged item is supported.
+
+```js
+const { dragging } = useContext(DragContext);
+
+return (
+ onChange([...items, item])}
+ >
+ {items.map(x => {x.name}
)}
+
+);
+```
+
+## Limitations
+
+Currently this is a very simple drag / drop mechanism. We don't support reordering out of the box, though it could probably be built on top of this solution without modification of the core.