Merge remote-tracking branch 'ianstormtaylor/master' into cut-copy-void

* ianstormtaylor/master: (81 commits)
  Address doc suggestion in ianstormtaylor#644 (ianstormtaylor#760)
  Clarifying insertTextByKey description (ianstormtaylor#778)
  Documenting node's 'getFirstText' & 'getLastText' (ianstormtaylor#779)
  0.19.22
  fix selection handling for changing tabs, and inside embedded inputs, closes ianstormtaylor#749
  fix to restrict window blur/focus handling, closes ianstormtaylor#773
  remove warn throwing since console.warn includes callsites now
  Update defining-custom-block-nodes.md (ianstormtaylor#776)
  0.19.21
  update table example to make scope clearer
  Fixed the link to comparisons, which was broken (ianstormtaylor#769)
  fix error when dragging void nodes without selection, closes ianstormtaylor#757
  fix to depend on prop-types for react 15.5
  fix to maintain focus on switching tabs, closes ianstormtaylor#756
  update issue template
  Add "data-key" to root div for the whole document (ianstormtaylor#759)
  add an issue template
  add note to document documentation (ianstormtaylor#755)
  Fix typo in plugin.md (ianstormtaylor#753)
  update readme
  ...

.github/Issue-template.md

@@ -0,0 +1,31 @@
+
+#### Do you want to request a *feature* or report a *bug*?
+
+<!-- 
+If you have a question, you might ask it in our Slack channel instead.
+
+https://slate-slack.herokuapp.com/
+-->
+
+#### What's the current behavior?
+
+<!-- 
+For bugs, please create a JSFiddle that reproduces the issue using 
+our template, and include a GIF showing how to easily reproduce it.
+
+And for bugs please include your OS, browser, Slate version and any
+other bit of info that may track down why it's happening.
+
+https://jsfiddle.net/2zokvrvt/7/
+http://recordit.co/
+-->
+
+#### What's the expected behavior?
+
+<!-- 
+Researching how other editors handle this issue is super helpful!
+
+https://draftjs.org/
+http://prosemirror.net/
+https://quilljs.com/
+-->

.gitignore

@@ -3,10 +3,9 @@ dist
 examples/build.dev.js
 examples/build.prod.js
 lib
-perf/reference.json
-test/support/build.js
 
 # Temporary files.
+bench/output
 tmp
 
 # Gitbook files.

.npmignore

@@ -1,6 +1,6 @@
+benchmark
 docs
 examples
 src
 test
 tmp
-perf

.travis.yml

@@ -3,13 +3,10 @@ env:
   matrix:
   - TEST_TYPE=test
   - TEST_TYPE=lint
-  - TEST_TYPE=benchmarks
 script:
   - |
     if [ "$TEST_TYPE" = test ]; then
-      npm test
-    elif [ "$TEST_TYPE" = benchmarks ]; then
-      npm run perf
+      npm run test
     elif [ "$TEST_TYPE" = lint ]; then
       npm run lint
     fi

History.md

@@ -8,7 +8,7 @@ This document maintains a list of changes to Slate with each new version. Until
 
 ###### BREAKING CHANGES
 
-- **The `filterDescendants` and `findDescendants` methods are now depth-first. This shouldn't affect almost anyone, since they are usually not the best things to be using for performance reasons. If you happen to have a very specific use case that needs breadth-first, (or even likely something better), you'll need to implement it yourself.
+- **The `filterDescendants` and `findDescendants` methods are now depth-first.** This shouldn't affect almost anyone, since they are usually not the best things to be using for performance reasons. If you happen to have a very specific use case that needs breadth-first, (or even likely something better), you'll need to implement it yourself.
 
 ###### DEPRECATION CHANGES
 

Readme.md

@@ -1,16 +1,37 @@
 
-
-<p align="center"><a href="#"><img src="./docs/images/banner.png" /></a></p>
-
-<p align="center">A <em>completely</em> customizable framework <br/>for building rich text editors.</p>
+<p align="center">
+  <a href="#"><img src="./docs/images/banner.png" /></a>
+</p>
+
+<p align="center">
+  A <em>completely</em> customizable framework <br/>
+  for building rich text editors.
+</p>
 <br/>
 
-<p align="center"><a href="#why"><strong>Why?</strong></a> · <a href="#principles"><strong>Principles</strong></a> · <a href="http://slatejs.org"><strong>Demo</strong></a> · <a href="#examples"><strong>Examples</strong></a> · <a href="#plugins"><strong>Plugins</strong></a> · <a href="http://docs.slatejs.org"><strong>Documentation</strong></a> · <a href="./Contributing.md"><strong>Contributing!</strong></a></p>
+<p align="center">
+  <a href="#why"><strong>Why?</strong></a> · 
+  <a href="#principles"><strong>Principles</strong></a> · 
+  <a href="http://slatejs.org"><strong>Demo</strong></a> · 
+  <a href="#examples"><strong>Examples</strong></a> · 
+  <a href="#plugins"><strong>Plugins</strong></a> · 
+  <a href="http://docs.slatejs.org"><strong>Documentation</strong></a> · 
+  <a href="./Contributing.md"><strong>Contributing!</strong></a>
+</p>
 <br/>
 
-<p align="center"><a href="http://slatejs.org"><img src="./docs/images/preview.png"></a></p>
-
-<p align="center"><a href="https://www.npmjs.com/package/slate"><img src="https://img.shields.io/npm/dt/localeval.svg?maxAge=2592000"></a> <a href="https://travis-ci.org/ianstormtaylor/slate"><img src="https://travis-ci.org/ianstormtaylor/slate.svg?branch=master"></a> <a href="https://slate-slack.herokuapp.com"><img src="https://slate-slack.herokuapp.com/badge.svg"><a/> <a href="https://github.com/ianstormtaylor/slate/releases"><img src="https://img.shields.io/github/release/ianstormtaylor/slate.svg?maxAge=2592000"></a> <a href="./License.md"><img src="https://img.shields.io/npm/l/slate.svg?maxAge=2592000"></a></p>
+<p align="center">
+  <a href="http://slatejs.org"><img src="./docs/images/preview.png"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/slate"><img src="https://img.shields.io/npm/dt/localeval.svg?maxAge=2592000"></a> 
+  <a href="https://unpkg.com/[email protected]/dist/slate.min.js"><img src="https://camo.githubusercontent.com/1fc98058815d91270a61227a28add53d0dbf7438/687474703a2f2f696d672e626164676573697a652e696f2f68747470733a2f2f756e706b672e636f6d2f736c61746540302e31392e32302f646973742f736c6174652e6d696e2e6a733f636f6d7072657373696f6e3d677a6970266c6162656c3d677a697025323073697a65" alt="gzip size" data-canonical-src="http://img.badgesize.io/https://unpkg.com/[email protected]/dist/slate.min.js?compression=gzip&amp;label=gzip%20size"></a>
+  <a href="https://travis-ci.org/ianstormtaylor/slate"><img src="https://travis-ci.org/ianstormtaylor/slate.svg?branch=master"></a> 
+  <a href="https://slate-slack.herokuapp.com"><img src="https://slate-slack.herokuapp.com/badge.svg"><a/> 
+  <a href="https://github.com/ianstormtaylor/slate/releases"><img src="https://img.shields.io/github/release/ianstormtaylor/slate.svg?maxAge=2592000"></a> 
+  <a href="./License.md"><img src="https://img.shields.io/npm/l/slate.svg?maxAge=2592000"></a> 
+</p>
 <br/>
 
 Slate lets you build rich, intuitive editors like those in [Medium](https://medium.com/), [Dropbox Paper](https://www.dropbox.com/paper) or [Canvas](https://usecanvas.com/)—which are becoming table stakes for applications on the web—without your codebase getting mired in complexity.
@@ -34,15 +55,9 @@ Here's how Slate compares to some of the existing editors out there:
 
 - [**Prosemirror**](http://prosemirror.net/) — Slate borrowed a few concepts from Prosemirror, namely its nested document tree, and its transform model. But the issues I ran into while using it were: that the API is hard to understand, that the codebase wasn't structured around common node module practices, that lots of magic was built into the core library that was hard to customize, that toolbars and buttons are too tied to the editor itself, and that the documentation isn't great. (It's still in beta though!)
 
-- [**Quill**](http://quilljs.com/) — I never used Quill directly, so my hesitations about it are solely from considering it in early stages. The issues I see with it are: that the concept of "toolbars" is too coupled with the editor itself, that the configuration is too coupled to HTML classes and DOM nodes, that the idea of "formats" and "toolbars" being linked is limiting, and generally that too much "core" logic is given special privileges and is hard to customize.
-
-- [**Trix**](https://trix-editor.org/) — I never used Trix directly either, so my issues with it are solely from considering it in early stages. The issues I found with it are: that it aims to be simple by limiting functionality instead of by limiting its own scope, that many behaviors are just impossible to implement with it, that it's too coupled to the DOM, and that the flat document model is limiting.
+- [**Quill**](http://quilljs.com/) — I never used Quill directly, so my hesitations about it are solely from considering it in early stages—and it has changed since then. The issues I see with it are: that the concept of "toolbars" is too coupled with the editor itself, that the configuration is too coupled to HTML classes and DOM nodes, that the idea of "formats" and "toolbars" being linked is limiting, and generally that too much "core" logic is given special privileges and is hard to customize.
 
-- [**Medium Editor**](https://yabwe.github.io/medium-editor/) — I never used the Medium Editor directly either, so my issues with it are solely from considering it in early stages. The issues I found with it are: that it doesn't actually pave over `contenteditable`, so you continue wrestling with the DOM, that the concept of a "toolbar" is tightly coupled with core in many respects making it harder to customize, that the extension system requires learning an entirely new view abstraction, and that the editor relying on the DOM's HTML as its data model makes collaborative editing much more difficult.
-
-- [**Scribe**](https://github.com/guardian/scribe) — I added Scribe to this list after creating Slate, so the issues with it are solely from reading their documentation. In terms of plugin architectures, Slate and Scribe are very similar in striving to move as much possible logic from "core" into plugins as possible. The issues I found with Scribe are: that it works directly on the DOM and its goal is to simply "fix" contenteditable such that all userland and plugin logic still has to account for x-browser differences, that its data model is tied to the DOM so serialization to formats besides HTML is more complex, that without a backing data model collaborative editing is much more difficult to layer in, and that it lacks broader mobile and browser support.
-
-- [**Mobiledoc Kit**](https://github.com/bustlelabs/mobiledoc-kit) — I added Mobiledoc Kit to this list after creating Slate as well, so the issues with it are solely from reading their documentation. In terms of the goal of customizability, Slate and Mobiledoc Kit are similar in striving to give the developer control over the rendering and serialization methods. The issues I found with Mobiledoc Kit are: that the JSON representation of content is complex to wrap your head around, that the naming terminology chosen doesn't build on prior art to make it easier to pick up, that the event handler architecture makes assumptions about use cases which leads to complexity, that the flat document model makes certain complex experiences difficult to build, and that core library makes assumptions about the behavior of specific types of nodes in the content.
+For more opinionated, and potentially useless, comparisons check out the [Comparisons](./docs/general/comparisons.md) document._
 
 Of course those are my own opinions, and if those libraries solve your needs, use them! But if you've tried using any of those libraries you might have run into similar problems. If so, you might like Slate. Which brings me to how Slate solves all of that...
 
@@ -111,6 +126,7 @@ Slate encourages you to write small, reusable modules. Check out the public ones
 - [`slate-drop-or-paste-images`](https://github.com/ianstormtaylor/slate-drop-or-paste-images) lets users drop or paste images to insert them!
 - [**View all plugins on `npm`...**](https://www.npmjs.com/browse/keyword/slate)
 
+
 <br/>
 
 ### Documentation

benchmark/compare.js

@@ -0,0 +1,43 @@
+/* eslint-disable no-console */
+
+import chalk from 'chalk'
+import baseline from '../tmp/benchmark-baseline'
+import comparison from '../tmp/benchmark-comparison'
+
+/**
+ * Constants.
+ */
+
+const THRESHOLD = 0.2
+
+/**
+ * Print.
+ */
+
+console.log()
+console.log(`  benchmarks`)
+
+baseline.forEach((suite, i) => {
+  console.log(`    ${suite.name}`)
+
+  suite.benchmarks.forEach((base, j) => {
+    const comp = comparison[i].benchmarks[j]
+    if (!comp) return
+
+    const b = base.iterations / base.elapsed * 100
+    const c = comp.iterations / comp.elapsed * 100
+    const threshold = b * THRESHOLD
+    const slower = (b - c) > threshold
+    const faster = (b - c) < (0 - threshold)
+    const percent = Math.round(Math.abs(b - c) / b * 100)
+
+    let output = `${b.toFixed(2)} --> ${c.toFixed(2)} iterations/sec`
+    if (slower) output = chalk.red(`${output} (${percent}% slower)`)
+    if (faster) output = chalk.green(`${output} (${percent}% faster)`)
+
+    console.log(`      ${base.title}`)
+    console.log(`        ${output}`)
+  })
+})
+
+console.log()

benchmark/fixtures/models/get-blocks/index.js

@@ -0,0 +1,10 @@
+
+import { __clear } from '../../../../lib/utils/memoize'
+
+export default function (state) {
+  state.document.getBlocks()
+}
+
+export function after() {
+  __clear()
+}