formatPastedText prop

Summary:
A missing use case for draft i've ran into a couple times is that when text is pasted, there are ways to override the default paste handler and do your own thing. Overriding the default paste handler means you have to manage your own fragment, have logic to handle html potentially, and then insert the blocks you generate in the proper place relative to the cursor and selection. More often than not, this seems overkill?

An example: (and the reason I'm posting this RFC) is that i'm trying to turn leading tabs into spaces when pasting markdown lists, since they can't be parsed. Users can't actually _type_ a tab so this is only a problem on pastes. Reimplementing the paste handler for this is doable but using the proposed method, it's implementation becomes a oneliner.

## Precedent

There's some precedent to this type of handler. `blockRendererFn` and `blockStyleFn` both plug into a similar way, overriding the default implementation.

Then  `handlePastedText` of course works similarly and I decided to copy its signature, when it comes to naming all `handle*` functions return a handle, which is not what we want in this case.

## Q's

Handling html might be a bit smelly? it is doable but you really don't wanna transform raw html to raw html, at that point you do wanna replace the paste handler.
What I've done is that it's the responsibility of `formatPastedText` to pass the html result through or eat it up and return undefined, formatting only the static text.
I'd be cool with just assuming that if `formatPastedText` exists, we ignore `html` automatically, and that simplifies the signature

Reviewed By: claudiopro

Differential Revision: D22574367

fbshipit-source-id: afe1fac1bb11328e354805161cf9489a77245eff

src/component/base/DraftEditorProps.js

@@ -81,6 +81,10 @@ export type DraftEditorProps = {
   // use case should not have any block or inline styles, it is recommended
   // that you set this to `true`.
   stripPastedStyles: boolean,
+  formatPastedText?: (
+    text: string,
+    html: ?string,
+  ) => {text: string, html: ?string},
   tabIndex?: number,
   // exposed especially to help improve mobile web behaviors
   autoCapitalize?: string,

src/component/handlers/edit/editOnPaste.js

@@ -94,10 +94,18 @@ function editOnPaste(editor: DraftEditor, e: SyntheticClipboardEvent<>): void {
   }
 
   let textBlocks: Array<string> = [];
-  const text: string = (data.getText(): any);
-  const html: string = (data.getHTML(): any);
+  let text: string = (data.getText(): any);
+  let html: string = (data.getHTML(): any);
   const editorState = editor._latestEditorState;
 
+  if (editor.props.formatPastedText) {
+    const {
+      text: formattedText,
+      html: formattedHtml,
+    } = editor.props.formatPastedText(text, html);
+    text = formattedText;
+    html = ((formattedHtml: any): string);
+  }
   if (
     editor.props.handlePastedText &&
     isEventHandled(editor.props.handlePastedText(text, html, editorState))
@@ -118,11 +126,15 @@ function editOnPaste(editor: DraftEditor, e: SyntheticClipboardEvent<>): void {
     // editor in Firefox and IE will not include empty lines. The resulting
     // paste will preserve the newlines correctly.
     const internalClipboard = editor.getClipboard();
-    if (data.isRichText() && internalClipboard) {
+    if (
+      !editor.props.formatPastedText &&
+      data.isRichText() &&
+      internalClipboard
+    ) {
       if (
         // If the editorKey is present in the pasted HTML, it should be safe to
         // assume this is an internal paste.
-        html.indexOf(editor.getEditorKey()) !== -1 ||
+        html?.indexOf(editor.getEditorKey()) !== -1 ||
         // The copy may have been made within a single block, in which case the
         // editor key won't be part of the paste. In this case, just check
         // whether the pasted text matches the internal clipboard.