From 20874faa69b1d13236e2edc12ce716afbbc94302 Mon Sep 17 00:00:00 2001
From: Ian Storm Taylor <ian@ianstormtaylor.com>
Date: Fri, 22 Jul 2016 17:15:46 -0700
Subject: [PATCH] add onDrop to docs

---
 docs/reference/components/editor.md | 25 ++++++++++++++--------
 docs/reference/plugins/core.md      | 12 +++++++----
 docs/reference/plugins/plugins.md   | 32 +++++++++++++++++++++++++++++
 3 files changed, 57 insertions(+), 12 deletions(-)

diff --git a/docs/reference/components/editor.md b/docs/reference/components/editor.md
index d6c14661c..12b1fd89d 100644
--- a/docs/reference/components/editor.md
+++ b/docs/reference/components/editor.md
@@ -21,15 +21,16 @@ The top-level React component that renders the Slate editor itself.
   - [`placeholderClassName`](#placeholderclassname)
   - [`placeholderStyle`](#placeholderstyle)
 - [Plugin-like Properties](#plugin-like-properties)
-  - [`onBeforeInput`](#onbeforeinput-function)
-  - [`onKeyDown`](#onkeydown-function)
-  - [`onPaste`](#onpaste-function)
-  - [`renderDecorations`](#renderdecorations-function)
-  - [`renderMark`](#rendermark-function)
-  - [`renderNode`](#rendernode-function)
+  - [`onBeforeInput`](#onbeforeinput)
+  - [`onDrop`](#ondrop)
+  - [`onKeyDown`](#onkeydown)
+  - [`onPaste`](#onpaste)
+  - [`renderDecorations`](#renderdecorations)
+  - [`renderMark`](#rendermark)
+  - [`renderNode`](#rendernode)
 - [Methods](#methods)
-  - [`getState()`](#getstate-state)
-  - [`onChange(state)`](#onchange-state-void)
+  - [`getState()`](#getstate)
+  - [`onChange(state)`](#onchange)
 
 
 ## Properties
@@ -148,6 +149,14 @@ const plugins = [
 />
 ```
 
+### `onBeforeInput`
+### `onDrop`
+### `onKeyDown`
+### `onPaste`
+### `renderDecorations`
+### `renderMark`
+### `renderNode`
+
 To see how these properties behave, check out the [Plugins reference](../plugins/plugins.md).
 
 
diff --git a/docs/reference/plugins/core.md b/docs/reference/plugins/core.md
index cc426e63f..352abb0be 100644
--- a/docs/reference/plugins/core.md
+++ b/docs/reference/plugins/core.md
@@ -11,19 +11,23 @@ Slate's editor is very unopinionated. The only logic it handles by default is lo
 
 The default behavior of the core plugin performs the following logic:
 
-#### `onBeforeInput`
+### `onBeforeInput`
 
 When text is entered, the core plugin inserts the text from `event.data` into the editor.
 
-#### `onKeyDown`
+### `onDrop`
+
+When the user drops content into the editor, the core plugin handles drops of type `text` and `html` as plain text, and does nothing for drops of type `files`.
+
+### `onKeyDown`
 
 When a key is pressed, the core plugin handles performing some of the "native" behavior that `contenteditable` elements must do. For example it splits blocks on `enter`, removes characters `backspace`, triggers an undo state from the history on `cmd-z`, etc.
 
-#### `onPaste`
+### `onPaste`
 
 When the user pastes content into the editor, the core plugin handles all pastes of type `text` and `html` as plain text, and does nothing for pastes of type `files`. 
 
-#### `renderNode`
+### `renderNode`
 
 The core plugin renders a default block and inline node, wrapping in a `<div>` and `<span>`, respectively. Each of these nodes contains `shouldComponentUpdate` logic prevents unnecessary re-renders.
 
diff --git a/docs/reference/plugins/plugins.md b/docs/reference/plugins/plugins.md
index d77ed9864..925626639 100644
--- a/docs/reference/plugins/plugins.md
+++ b/docs/reference/plugins/plugins.md
@@ -10,6 +10,7 @@ When the editor needs to resolve a plugin-related handler, it will loop through
 - [Conventions](#conventions)
 - [Event Handler Properties](#event-handle-properties)
   - [`onBeforeInput`](#onbeforeinput)
+  - [`onDrop`](#ondrop)
   - [`onKeyDown`](#onkeydown)
   - [`onPaste`](#onpaste)
 - [Renderer Properties](#renderer-properties)
@@ -38,6 +39,7 @@ export default MySlatePlugin(options) {
 ```js
 {
   onBeforeInput: Function,
+  onDrop: Function,
   onKeyDown: Function,
   onPaste: Function
 }
@@ -54,6 +56,36 @@ This handler is called right before a string of text is inserted into the `conte
 
 Make sure to `event.preventDefault()` if you do not want the default insertion behavior to occur! If no other plugin handles this event, it will be handled by the [Core plugin](./core.md).
 
+### `onDrop`
+`Function onDrop(event: Event, drop: Object, state: State, editor: Editor) => State || Void`
+
+This handler is called when the user drops content into the `contenteditable` element. The event is already prevented by default, so you must define a state change to have any affect occur.
+
+The `drop` object is a convenience object created to standardize the drop metadata across browsers. Every drop object has a `type` property, can be one of `text`, `html` or `files`, and a `target` property which is a [`Selection`](../models/selection.md) indicating where the drop occured. Depending on the type, it's structure will be:
+
+```js
+{
+  type: 'text',
+  target: Selection,
+  text: String
+}
+
+{
+  type: 'html',
+  target: Selection,
+  text: String,
+  html: String
+}
+
+{
+  type: 'files',
+  target: Selection,
+  files: FileList
+}
+```
+
+If no other plugin handles this event, it will be handled by the [Core plugin](./core.md).
+
 ### `onKeyDown` 
 `Function onKeyDown(event: Event, state: State, editor: Editor) => State || Void`