git diff b95ad29..facebook/master -- docs/docs

react-docs-update-to-v0.13.diff

diff --git a/docs/docs/02.1-jsx-in-depth.md b/docs/docs/02.1-jsx-in-depth.md
index 224b8cb..7669ada 100644
--- a/docs/docs/02.1-jsx-in-depth.md
+++ b/docs/docs/02.1-jsx-in-depth.md
@@ -73,6 +73,15 @@ var app = React.createElement(
 );
 ```
 
+JSX will infer the class's [displayName](/react/docs/component-specs.html#displayName) from the variable assignment when the displayName is undefined:
+
+```javascript
+// Input (JSX):
+var Nav = React.createClass({ });
+// Output (JS):
+var Nav = React.createClass({displayName: "Nav", });
+```
+
 Use the [JSX Compiler](/react/jsx-compiler.html) to try out JSX and see how it
 desugars into native JavaScript, and the
 [HTML to JSX converter](/react/html-jsx.html) to convert your existing HTML to
diff --git a/docs/docs/04-multiple-components.md b/docs/docs/04-multiple-components.md
index bafc8b0..c3271da 100644
--- a/docs/docs/04-multiple-components.md
+++ b/docs/docs/04-multiple-components.md
@@ -171,26 +171,7 @@ var MyComponent = React.createClass({
 });
 ```
 
-You can also key children by passing an object. The object keys will be used as `key` for each value. However it is important to remember that JavaScript does not guarantee the ordering of properties will be preserved. In practice browsers will preserve property order **except** for properties that can be parsed as 32-bit unsigned integers. Numeric properties will be ordered sequentially and before other properties. If this happens React will render components out of order. This can be avoided by adding a string prefix to the key:
-
-```javascript
-  render: function() {
-    var items = {};
-
-    this.props.results.forEach(function(result) {
-      // If result.id can look like a number (consider short hashes), then
-      // object iteration order is not guaranteed. In this case, we add a prefix
-      // to ensure the keys are strings.
-      items['result-' + result.id] = <li>{result.text}</li>;
-    });
-
-    return (
-      <ol>
-        {items}
-      </ol>
-    );
-  }
-```
+You can also key children by passing a ReactFragment object. See [Keyed Fragments](create-fragment.html) for more details.
 
 ## Data Flow
 
diff --git a/docs/docs/05-reusable-components.md b/docs/docs/05-reusable-components.md
index 22d188e..0178c5e 100644
--- a/docs/docs/05-reusable-components.md
+++ b/docs/docs/05-reusable-components.md
@@ -187,3 +187,48 @@ React.render(
 
 A nice feature of mixins is that if a component is using multiple mixins and several mixins define the same lifecycle method (i.e. several mixins want to do some cleanup when the component is destroyed), all of the lifecycle methods are guaranteed to be called. Methods defined on mixins run in the order mixins were listed, followed by a method call on the component.
 
+## ES6 Classes
+
+You may also define your React classes as a plain JavaScript class. For example using ES6 class syntax:
+
+```javascript
+class HelloMessage extends React.Component {
+  render() {
+    return <div>Hello {this.props.name}</div>;
+  }
+}
+React.render(<HelloMessage name="Sebastian" />, mountNode);
+```
+
+The API is similar to `React.createClass` with the exception or `getInitialState`. Instead of providing a separate `getInitialState` method, you set up your own `state` property in the constructor.
+
+Another difference is that `propTypes` and `defaultProps` are defined as properties on the constructor instead of in the class body.
+
+```javascript
+export class Counter extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {count: props.initialCount};
+  }
+  tick() {
+    this.setState({count: this.state.count + 1});
+  }
+  render() {
+    return (
+      <div onClick={this.tick.bind(this)}>
+        Clicks: {this.state.count}
+      </div>
+    );
+  }
+}
+Counter.propTypes = { initialCount: React.PropTypes.number };
+Counter.defaultProps = { initialCount: 0 };
+```
+
+### No Autobinding
+
+Methods follow the same semantics as regular ES6 classes, meaning that they don't automatically bind `this` to the instance. You'll have to explicitly use `.bind(this)` or arrow functions.
+
+### No Mixins
+
+Unfortunately ES6 launched without any mixin support. Therefore, there is no support for mixins when you use React with ES6 classes. Instead, we're working on making it easier to support such use cases without resorting to mixins.
diff --git a/docs/docs/08.1-more-about-refs.md b/docs/docs/08.1-more-about-refs.md
index e3bbde6..d028c6a 100644
--- a/docs/docs/08.1-more-about-refs.md
+++ b/docs/docs/08.1-more-about-refs.md
@@ -65,7 +65,7 @@ In this counterexample, the `<input />` is merely a *description* of an `<input
 
 So how do we talk to the *real* backing instance of the input?
 
-## The ref Attribute
+## The ref String Attribute
 
 React supports a very special property that you can attach to any component that is output from `render()`. This special property allows you to refer to the corresponding **backing instance** of anything returned from `render()`. It is always guaranteed to be the proper instance, at any point in time.
 
@@ -85,6 +85,18 @@ It's as simple as:
 
   You can access the component's DOM node directly by calling `React.findDOMNode(this.refs.myInput)`.
 
+
+## The ref Callback Attribute
+
+The `ref` attribute can be a callback function instead of a name.  This callback will be executed immediately after the component is mounted.  The referenced component will be passed in as a parameter, and the callback function may use the component immediately, or save the reference for future use (or both).
+
+It's as simple as assigning a `ref` attribute to anything returned from `render` such as:
+
+  ```html
+  <input ref={ function(component){ React.findDOMNode(component).focus();} } />
+  ```
+
+
 ## Completing the Example
 
 ```javascript
diff --git a/docs/docs/10-addons.md b/docs/docs/10-addons.md
index 11b11f0..6b3458c 100644
--- a/docs/docs/10-addons.md
+++ b/docs/docs/10-addons.md
@@ -10,10 +10,11 @@ next: animation.html
 
 - [`TransitionGroup` and `CSSTransitionGroup`](animation.html), for dealing with animations and transitions that are usually not simple to implement, such as before a component's removal.
 - [`LinkedStateMixin`](two-way-binding-helpers.html), to simplify the coordination between user's form input data and the component's state.
-- [`classSet`](class-name-manipulation.html), for manipulating the DOM `class` string a bit more cleanly.
 - [`cloneWithProps`](clone-with-props.html), to make shallow copies of React components and change their props.
+- [`createFragment`](create-fragment.html), to create a set of externally-keyed children.
 - [`update`](update.html), a helper function that makes dealing with immutable data in JavaScript easier.
 - [`PureRenderMixin`](pure-render-mixin.html), a performance booster under certain situations.
+- (DEPRECATED) [`classSet`](class-name-manipulation.html), for manipulating the DOM `class` string a bit more cleanly.
 
 The add-ons below are in the development (unminified) version of React only:
 
diff --git a/docs/docs/10.4-test-utils.md b/docs/docs/10.4-test-utils.md
index 78d56d7..eead79f 100644
--- a/docs/docs/10.4-test-utils.md
+++ b/docs/docs/10.4-test-utils.md
@@ -138,3 +138,46 @@ ReactComponent findRenderedComponentWithType(ReactComponent tree, function compo
 ```
 
 Same as `scryRenderedComponentsWithType()` but expects there to be one result and returns that one result, or throws exception if there is any other number of matches besides one.
+
+
+## Shallow rendering
+
+Shallow rendering is an experimental feature that lets you render a component "one level deep" and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM.
+
+```javascript
+ReactShallowRenderer createRenderer()
+```
+
+Call this in your tests to create a shallow renderer. You can think of this as a "place" to render the component you're testing, where it can respond to events and update itself.
+
+```javascript
+shallowRenderer.render(ReactElement element)
+```
+
+Similar to `React.render`.
+
+```javascript
+ReactComponent shallowRenderer.getRenderOutput()
+```
+
+After render has been called, returns shallowly rendered output. You can then begin to assert facts about the output. For example, if your component's render method returns:
+
+```javascript
+<div>
+  <span className="heading">Title</span>
+  <Subcomponent foo="bar" />
+</div>
+```
+
+Then you can assert:
+
+```javascript
+result = renderer.getRenderOutput();
+expect(result.type).toBe('div');
+expect(result.props.children).toEqual([
+  <span className="heading">Title</span>
+  <Subcomponent foo="bar" />
+]);
+```
+
+Shallow testing currently has some limitations, namely not supporting refs. We're releasing this feature early and would appreciate the React community's feedback on how it should evolve.
diff --git a/docs/docs/10.5-clone-with-props.md b/docs/docs/10.5-clone-with-props.md
index 73652a0..9236859 100644
--- a/docs/docs/10.5-clone-with-props.md
+++ b/docs/docs/10.5-clone-with-props.md
@@ -3,7 +3,7 @@ id: clone-with-props
 title: Cloning ReactElement
 permalink: clone-with-props.html
 prev: test-utils.html
-next: update.html
+next: create-fragment.html
 ---
 
 In rare situations a element may want to change the props of a element that it doesn't own (like changing the `className` of a element passed as `this.props.children`). Other times it may want to make multiple copies of a element passed to it. `cloneWithProps()` makes this possible.
diff --git a/docs/docs/10.6-create-fragment.md b/docs/docs/10.6-create-fragment.md
new file mode 100644
index 0000000..28f932c
--- /dev/null
+++ b/docs/docs/10.6-create-fragment.md
@@ -0,0 +1,73 @@
+---
+id: create-fragment
+title: Keyed Fragments
+permalink: create-fragment.html
+prev: clone-with-props.html
+next: update.html
+---
+
+In most cases, you can use the `key` prop to specify keys on the elements you're returning from `render`. However, this breaks down in one situation: if you have two sets of children that you need to reorder, there's no way to put a key on each set without adding a wrapper element.
+
+That is, if you have a component such as:
+
+```js
+var Swapper = React.createClass({
+  propTypes: {
+    // `leftChildren` and `rightChildren` can be a string, element, array, etc.
+    leftChildren: React.PropTypes.node,
+    rightChildren: React.PropTypes.node,
+
+    swapped: React.PropTypes.bool
+  }
+  render: function() {
+    var children;
+    if (this.props.swapped) {
+      children = [this.props.rightChildren, this.props.leftChildren];
+    } else {
+      children = [this.props.leftChildren, this.props.rightChildren];
+    }
+    return <div>{children}</div>;
+  }
+});
+```
+
+The children will unmount and remount as you change the `swapped` prop because there aren't any keys marked on the two sets of children.
+
+To solve this problem, you can use `React.addons.createFragment` to give keys to the sets of children.
+
+#### `ReactFragment React.addons.createFragment(object children)`
+
+Instead of creating arrays, we write:
+
+```js
+if (this.props.swapped) {
+  children = React.addons.createFragment({
+    right: this.props.rightChildren,
+    left: this.props.leftChildren
+  });
+} else {
+  children = React.addons.createFragment({
+    left: this.props.leftChildren,
+    right: this.props.rightChildren
+  });
+}
+```
+
+The keys of the passed object (that is, `left` and `right`) are used as keys for the entire set of children, and the order of the object's keys is used to determine the order of the rendered children. With this change, the two sets of children will be properly reordered in the DOM without unmounting.
+
+The return value of `createFragment` should be treated as an opaque object; you can use the `React.Children` helpers to loop through a fragment but should not access it directly. Note also that we're relying on the JavaScript engine preserving object enumeration order here, which is not guaranteed by the spec but is implemented by all major browsers and VMs for objects with non-numeric keys.
+
+> **Note:**
+>
+> In the future, `createFragment` may be replaced by an API such as
+>
+> ```js
+> return (
+>   <div>
+>     <x:frag key="right">{this.props.rightChildren}</x:frag>,
+>     <x:frag key="left">{this.props.leftChildren}</x:frag>
+>   </div>
+> );
+> ```
+>
+> allowing you to assign keys directly in JSX without adding wrapper elements.
diff --git a/docs/docs/10.6-update.md b/docs/docs/10.6-update.md
deleted file mode 100644
index 4c90d0e..0000000
--- a/docs/docs/10.6-update.md
+++ /dev/null
@@ -1,100 +0,0 @@
----
-id: update
-title: Immutability Helpers
-permalink: update.html
-prev: clone-with-props.html
-next: pure-render-mixin.html
----
-
-React lets you use whatever style of data management you want, including mutation. However, if you can use immutable data in performance-critical parts of your application it's easy to implement a fast `shouldComponentUpdate()` method to significantly speed up your app.
-
-Dealing with immutable data in JavaScript is more difficult than in languages designed for it, like [Clojure](http://clojure.org/). However, we've provided a simple immutability helper, `update()`, that makes dealing with this type of data much easier, *without* fundamentally changing how your data is represented.
-
-## The main idea
-
-If you mutate data like this:
-
-```js
-myData.x.y.z = 7;
-// or...
-myData.a.b.push(9);
-```
-
-you have no way of determining which data has changed since the previous copy is overridden. Instead, you need to create a new copy of `myData` and change only the parts of it that need to be changed. Then you can compare the old copy of `myData` with the new one in `shouldComponentUpdate()` using triple-equals:
-
-```js
-var newData = deepCopy(myData);
-newData.x.y.z = 7;
-newData.a.b.push(9);
-```
-
-Unfortunately, deep copies are expensive, and sometimes impossible. You can alleviate this by only copying objects that need to be changed and by reusing the objects that haven't changed. Unfortunately, in today's JavaScript this can be cumbersome:
-
-```js
-var newData = extend(myData, {
-  x: extend(myData.x, {
-    y: extend(myData.x.y, {z: 7}),
-  }),
-  a: extend(myData.a, {b: myData.a.b.concat(9)})
-});
-```
-
-While this is fairly performant (since it only shallow copies `log n` objects and reuses the rest), it's a big pain to write. Look at all the repetition! This is not only annoying, but also provides a large surface area for bugs.
-
-`update()` provides simple syntactic sugar around this pattern to make writing this code easier. This code becomes:
-
-```js
-var newData = React.addons.update(myData, {
-  x: {y: {z: {$set: 7}}},
-  a: {b: {$push: [9]}}
-});
-```
-
-While the syntax takes a little getting used to (though it's inspired by [MongoDB's query language](http://docs.mongodb.org/manual/core/crud-introduction/#query)) there's no redundancy, it's statically analyzable and it's not much more typing than the mutative version.
-
-The `$`-prefixed keys are called *commands*. The data structure they are "mutating" is called the *target*.
-
-## Available commands
-
-  * `{$push: array}` `push()` all the items in `array` on the target.
-  * `{$unshift: array}` `unshift()` all the items in `array` on the target.
-  * `{$splice: array of arrays}` for each item in `arrays` call `splice()` on the target with the parameters provided by the item.
-  * `{$set: any}` replace the target entirely.
-  * `{$merge: object}` merge the keys of `object` with the target.
-  * `{$apply: function}` passes in the current value to the function and updates it with the new returned value.
-
-## Examples
-
-### Simple push
-
-```js
-var initialArray = [1, 2, 3];
-var newArray = update(initialArray, {$push: [4]}); // => [1, 2, 3, 4]
-```
-`initialArray` is still `[1, 2, 3]`.
-
-### Nested collections
-
-```js
-var collection = [1, 2, {a: [12, 17, 15]}];
-var newCollection = update(collection, {2: {a: {$splice: [[1, 1, 13, 14]]}}});
-// => [1, 2, {a: [12, 13, 14, 15]}]
-```
-This accesses `collection`'s index `2`, key `a`, and does a splice of one item starting from index `1` (to remove `17`) while inserting `13` and `14`.
-
-### Updating a value based on its current one
-
-```js
-var obj = {a: 5, b: 3};
-var newObj = update(obj, {b: {$apply: function(x) {return x * 2;}}});
-// => {a: 5, b: 6}
-// This is equivalent, but gets verbose for deeply nested collections:
-var newObj2 = update(obj, {b: {$set: obj.b * 2}});
-```
-
-### (Shallow) merge
-
-```js
-var obj = {a: 5, b: 3};
-var newObj = update(obj, {$merge: {b: 6, c: 7}}); // => {a: 5, b: 6, c: 7}
-```
diff --git a/docs/docs/10.7-pure-render-mixin.md b/docs/docs/10.7-pure-render-mixin.md
deleted file mode 100644
index ab48a40..0000000
--- a/docs/docs/10.7-pure-render-mixin.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-id: pure-render-mixin
-title: PureRenderMixin
-permalink: pure-render-mixin.html
-prev: update.html
-next: perf.html
----
-
-If your React component's render function is "pure" (in other words, it renders the same result given the same props and state), you can use this mixin for a performance boost in some cases.
-
-Example:
-
-```js
-var PureRenderMixin = require('react/addons').addons.PureRenderMixin;
-React.createClass({
-  mixins: [PureRenderMixin],
-
-  render: function() {
-    return <div className={this.props.className}>foo</div>;
-  }
-});
-```
-
-Under the hood, the mixin implements [shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate), in which it compares the current props and state with the next ones and returns `false` if the equalities pass.
-
-> Note:
->
-> This only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only mix into components which have simple props and state, or use `forceUpdate()` when you know deep data structures have changed. Or, consider using [immutable objects](http://facebook.github.io/immutable-js/) to facilitate fast comparisons of nested data.
->
-> Furthermore, `shouldComponentUpdate` skips updates for the whole component subtree. Make sure all the children components are also "pure".
diff --git a/docs/docs/10.7-update.md b/docs/docs/10.7-update.md
new file mode 100644
index 0000000..d506583
--- /dev/null
+++ b/docs/docs/10.7-update.md
@@ -0,0 +1,100 @@
+---
+id: update
+title: Immutability Helpers
+permalink: update.html
+prev: create-fragment.html
+next: pure-render-mixin.html
+---
+
+React lets you use whatever style of data management you want, including mutation. However, if you can use immutable data in performance-critical parts of your application it's easy to implement a fast `shouldComponentUpdate()` method to significantly speed up your app.
+
+Dealing with immutable data in JavaScript is more difficult than in languages designed for it, like [Clojure](http://clojure.org/). However, we've provided a simple immutability helper, `update()`, that makes dealing with this type of data much easier, *without* fundamentally changing how your data is represented.
+
+## The main idea
+
+If you mutate data like this:
+
+```js
+myData.x.y.z = 7;
+// or...
+myData.a.b.push(9);
+```
+
+you have no way of determining which data has changed since the previous copy is overridden. Instead, you need to create a new copy of `myData` and change only the parts of it that need to be changed. Then you can compare the old copy of `myData` with the new one in `shouldComponentUpdate()` using triple-equals:
+
+```js
+var newData = deepCopy(myData);
+newData.x.y.z = 7;
+newData.a.b.push(9);
+```
+
+Unfortunately, deep copies are expensive, and sometimes impossible. You can alleviate this by only copying objects that need to be changed and by reusing the objects that haven't changed. Unfortunately, in today's JavaScript this can be cumbersome:
+
+```js
+var newData = extend(myData, {
+  x: extend(myData.x, {
+    y: extend(myData.x.y, {z: 7}),
+  }),
+  a: extend(myData.a, {b: myData.a.b.concat(9)})
+});
+```
+
+While this is fairly performant (since it only shallow copies `log n` objects and reuses the rest), it's a big pain to write. Look at all the repetition! This is not only annoying, but also provides a large surface area for bugs.
+
+`update()` provides simple syntactic sugar around this pattern to make writing this code easier. This code becomes:
+
+```js
+var newData = React.addons.update(myData, {
+  x: {y: {z: {$set: 7}}},
+  a: {b: {$push: [9]}}
+});
+```
+
+While the syntax takes a little getting used to (though it's inspired by [MongoDB's query language](http://docs.mongodb.org/manual/core/crud-introduction/#query)) there's no redundancy, it's statically analyzable and it's not much more typing than the mutative version.
+
+The `$`-prefixed keys are called *commands*. The data structure they are "mutating" is called the *target*.
+
+## Available commands
+
+  * `{$push: array}` `push()` all the items in `array` on the target.
+  * `{$unshift: array}` `unshift()` all the items in `array` on the target.
+  * `{$splice: array of arrays}` for each item in `arrays` call `splice()` on the target with the parameters provided by the item.
+  * `{$set: any}` replace the target entirely.
+  * `{$merge: object}` merge the keys of `object` with the target.
+  * `{$apply: function}` passes in the current value to the function and updates it with the new returned value.
+
+## Examples
+
+### Simple push
+
+```js
+var initialArray = [1, 2, 3];
+var newArray = update(initialArray, {$push: [4]}); // => [1, 2, 3, 4]
+```
+`initialArray` is still `[1, 2, 3]`.
+
+### Nested collections
+
+```js
+var collection = [1, 2, {a: [12, 17, 15]}];
+var newCollection = update(collection, {2: {a: {$splice: [[1, 1, 13, 14]]}}});
+// => [1, 2, {a: [12, 13, 14, 15]}]
+```
+This accesses `collection`'s index `2`, key `a`, and does a splice of one item starting from index `1` (to remove `17`) while inserting `13` and `14`.
+
+### Updating a value based on its current one
+
+```js
+var obj = {a: 5, b: 3};
+var newObj = update(obj, {b: {$apply: function(x) {return x * 2;}}});
+// => {a: 5, b: 6}
+// This is equivalent, but gets verbose for deeply nested collections:
+var newObj2 = update(obj, {b: {$set: obj.b * 2}});
+```
+
+### (Shallow) merge
+
+```js
+var obj = {a: 5, b: 3};
+var newObj = update(obj, {$merge: {b: 6, c: 7}}); // => {a: 5, b: 6, c: 7}
+```
diff --git a/docs/docs/10.8-perf.md b/docs/docs/10.8-perf.md
deleted file mode 100644
index 33f257c..0000000
--- a/docs/docs/10.8-perf.md
+++ /dev/null
@@ -1,72 +0,0 @@
----
-id: perf
-title: Performance Tools
-permalink: perf.html
-prev: pure-render-mixin.html
-next: advanced-performance.html
----
-
-React is usually quite fast out of the box. However, in situations where you need to squeeze every ounce of performance out of your app, it provides a [shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate) hook where you can add optimization hints to React's diff algorithm.
-
-In addition to giving you an overview of your app's overall performance, ReactPerf is a profiling tool that tells you exactly where you need to put these hooks.
-
-> Note:
->
-> The dev build of React is slower than the prod build, due to all the extra logic for providing, for example, React's friendly console warnings (stripped away in the prod build). Therefore, the profiler only serves to indicate the _relatively_ expensive parts of your app.
-
-## General API
-
-The `Perf` object documented here is exposed as `React.addons.Perf` when using the `react-with-addons.js` build in development mode.
-
-### `Perf.start()` and `Perf.stop()`
-Start/stop the measurement. The React operations in-between are recorded for analyses below. Operations that took an insignificant amount of time are ignored.
-
-### `Perf.printInclusive(measurements)`
-Prints the overall time taken. If no argument's passed, defaults to all the measurements from the last recording. This prints a nicely formatted table in the console, like so:
-
-![](/react/img/docs/perf-inclusive.png)
-
-### `Perf.printExclusive(measurements)`
-"Exclusive" times don't include the times taken to mount the components: processing props, `getInitialState`, call `componentWillMount` and `componentDidMount`, etc.
-
-![](/react/img/docs/perf-exclusive.png)
-
-### `Perf.printWasted(measurements)`
-
-**The most useful part of the profiler**.
-
-"Wasted" time is spent on components that didn't actually render anything, e.g. the render stayed the same, so the DOM wasn't touched.
-
-![](/react/img/docs/perf-wasted.png)
-
-### `Perf.printDOM(measurements)`
-Prints the underlying DOM manipulations, e.g. "set innerHTML" and "remove".
-
-![](/react/img/docs/perf-dom.png)
-
-## Advanced API
-
-The above print methods use `Perf.getLastMeasurements()` to pretty-print the result.
-
-### `Perf.getLastMeasurements()`
-Get the measurements array from the last start-stop session. The array contains objects, each of which looks like this:
-
-```js
-{
-  // The term "inclusive" and "exclusive" are explained below
-  "exclusive": {},
-  // '.0.0' is the React ID of the node
-  "inclusive": {".0.0": 0.0670000008540228, ".0": 0.3259999939473346},
-  "render": {".0": 0.036999990697950125, ".0.0": 0.010000003385357559},
-  // Number of instances
-  "counts": {".0": 1, ".0.0": 1},
-  // DOM touches
-  "writes": {},
-  // Extra debugging info
-  "displayNames": {
-    ".0": {"current": "App", "owner": "<root>"},
-    ".0.0": {"current": "Box", "owner": "App"}
-  },
-  "totalTime": 0.48499999684281647
-}
-```
diff --git a/docs/docs/10.8-pure-render-mixin.md b/docs/docs/10.8-pure-render-mixin.md
new file mode 100644
index 0000000..ab48a40
--- /dev/null
+++ b/docs/docs/10.8-pure-render-mixin.md
@@ -0,0 +1,30 @@
+---
+id: pure-render-mixin
+title: PureRenderMixin
+permalink: pure-render-mixin.html
+prev: update.html
+next: perf.html
+---
+
+If your React component's render function is "pure" (in other words, it renders the same result given the same props and state), you can use this mixin for a performance boost in some cases.
+
+Example:
+
+```js
+var PureRenderMixin = require('react/addons').addons.PureRenderMixin;
+React.createClass({
+  mixins: [PureRenderMixin],
+
+  render: function() {
+    return <div className={this.props.className}>foo</div>;
+  }
+});
+```
+
+Under the hood, the mixin implements [shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate), in which it compares the current props and state with the next ones and returns `false` if the equalities pass.
+
+> Note:
+>
+> This only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only mix into components which have simple props and state, or use `forceUpdate()` when you know deep data structures have changed. Or, consider using [immutable objects](http://facebook.github.io/immutable-js/) to facilitate fast comparisons of nested data.
+>
+> Furthermore, `shouldComponentUpdate` skips updates for the whole component subtree. Make sure all the children components are also "pure".
diff --git a/docs/docs/10.9-perf.md b/docs/docs/10.9-perf.md
new file mode 100644
index 0000000..33f257c
--- /dev/null
+++ b/docs/docs/10.9-perf.md
@@ -0,0 +1,72 @@
+---
+id: perf
+title: Performance Tools
+permalink: perf.html
+prev: pure-render-mixin.html
+next: advanced-performance.html
+---
+
+React is usually quite fast out of the box. However, in situations where you need to squeeze every ounce of performance out of your app, it provides a [shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate) hook where you can add optimization hints to React's diff algorithm.
+
+In addition to giving you an overview of your app's overall performance, ReactPerf is a profiling tool that tells you exactly where you need to put these hooks.
+
+> Note:
+>
+> The dev build of React is slower than the prod build, due to all the extra logic for providing, for example, React's friendly console warnings (stripped away in the prod build). Therefore, the profiler only serves to indicate the _relatively_ expensive parts of your app.
+
+## General API
+
+The `Perf` object documented here is exposed as `React.addons.Perf` when using the `react-with-addons.js` build in development mode.
+
+### `Perf.start()` and `Perf.stop()`
+Start/stop the measurement. The React operations in-between are recorded for analyses below. Operations that took an insignificant amount of time are ignored.
+
+### `Perf.printInclusive(measurements)`
+Prints the overall time taken. If no argument's passed, defaults to all the measurements from the last recording. This prints a nicely formatted table in the console, like so:
+
+![](/react/img/docs/perf-inclusive.png)
+
+### `Perf.printExclusive(measurements)`
+"Exclusive" times don't include the times taken to mount the components: processing props, `getInitialState`, call `componentWillMount` and `componentDidMount`, etc.
+
+![](/react/img/docs/perf-exclusive.png)
+
+### `Perf.printWasted(measurements)`
+
+**The most useful part of the profiler**.
+
+"Wasted" time is spent on components that didn't actually render anything, e.g. the render stayed the same, so the DOM wasn't touched.
+
+![](/react/img/docs/perf-wasted.png)
+
+### `Perf.printDOM(measurements)`
+Prints the underlying DOM manipulations, e.g. "set innerHTML" and "remove".
+
+![](/react/img/docs/perf-dom.png)
+
+## Advanced API
+
+The above print methods use `Perf.getLastMeasurements()` to pretty-print the result.
+
+### `Perf.getLastMeasurements()`
+Get the measurements array from the last start-stop session. The array contains objects, each of which looks like this:
+
+```js
+{
+  // The term "inclusive" and "exclusive" are explained below
+  "exclusive": {},
+  // '.0.0' is the React ID of the node
+  "inclusive": {".0.0": 0.0670000008540228, ".0": 0.3259999939473346},
+  "render": {".0": 0.036999990697950125, ".0.0": 0.010000003385357559},
+  // Number of instances
+  "counts": {".0": 1, ".0.0": 1},
+  // DOM touches
+  "writes": {},
+  // Extra debugging info
+  "displayNames": {
+    ".0": {"current": "App", "owner": "<root>"},
+    ".0.0": {"current": "Box", "owner": "App"}
+  },
+  "totalTime": 0.48499999684281647
+}
+```
diff --git a/docs/docs/ref-01-top-level-api.md b/docs/docs/ref-01-top-level-api.md
index 6bea767..0f91d50 100644
--- a/docs/docs/ref-01-top-level-api.md
+++ b/docs/docs/ref-01-top-level-api.md
@@ -11,6 +11,15 @@ redirect_from: "/docs/reference.html"
 `React` is the entry point to the React library. If you're using one of the prebuilt packages it's available as a global; if you're using CommonJS modules you can `require()` it.
 
 
+### React.Component
+
+```javascript
+class Component
+```
+
+This is the base class for React Components when they're defined using ES6 classes. See [Reusable Components](/react/docs/reusable-components.html#es6-classes) for how to use ES6 classes with React. For what methods are actually provided by the base class, see the [Component API](/react/docs/component-api.html).
+
+
 ### React.createClass
 
 ```javascript
@@ -36,6 +45,19 @@ Create and return a new `ReactElement` of the given type. The type argument can
 html tag name string (eg. 'div', 'span', etc), or a `ReactClass` (created via `React.createClass`).
 
 
+### React.cloneElement
+
+```
+ReactElement cloneElement(
+  ReactElement element,
+  [object props],
+  [children ...]
+)
+```
+
+Clone and return a new `ReactElement` using `element` as the starting point. The resulting element will have the original element's props with the new props merged in shallowly. New children will replace existing children. Unlike `React.addons.cloneWithProps`, `key` and `ref` from the original element will be preserved. There is no special behavior for merging any props (unlike `cloneWithProps`). See the [v0.13 RC2 blog post](/react/blog/2015/03/03/react-v0.13-rc2.html) for additional details.
+
+
 ### React.createFactory
 
 ```javascript
diff --git a/docs/docs/ref-02-component-api.md b/docs/docs/ref-02-component-api.md
index b2d3bf9..31b08b0 100644
--- a/docs/docs/ref-02-component-api.md
+++ b/docs/docs/ref-02-component-api.md
@@ -6,7 +6,7 @@ prev: top-level-api.html
 next: component-specs.html
 ---
 
-## ReactComponent
+## React.Component
 
 Instances of a React Component are created internally in React when rendering. These instances are reused in subsequent renders, and can be accessed in your component methods as `this`. The only way to get a handle to a React Component instance outside of React is by storing the return value of `React.render`. Inside other Components, you may use [refs](/react/docs/more-about-refs.html) to achieve the same result.
 
@@ -14,10 +14,27 @@ Instances of a React Component are created internally in React when rendering. T
 ### setState
 
 ```javascript
-setState(object nextState[, function callback])
+setState(function|object nextState[, function callback])
 ```
+Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks.
 
-Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks.  In addition, you can supply an optional callback function that is executed once `setState` is completed and the component is re-rendered.
+The first argument can be an object (containing zero or more keys to update) or a function (of state and props) that returns an object containing keys to update.
+
+Here is the simple object usage...
+
+```javascript
+setState({mykey: 'my new value'});
+```
+
+It's also possible to pass a function with the signature `function(state, props)`. This can be useful in some cases when you want to enqueue an atomic update that consults the previous value of state+props before setting any values.  For instance, suppose we wanted to increment a value in state: 
+
+```javascript
+setState(function(previousState, currentProps) {
+  return {myInteger: previousState.myInteger + 1};
+});`
+```
+
+The second (optional) parameter is a callback function that will be executed once `setState` is completed and the component is re-rendered.
 
 > Notes:
 >
@@ -38,6 +55,10 @@ replaceState(object nextState[, function callback])
 
 Like `setState()` but deletes any pre-existing state keys that are not in nextState.
 
+> Note:
+>
+> This method is not available on ES6 `class` components that extend `React.Component`. It may be removed entirely in a future version of React.
+
 
 ### forceUpdate
 
@@ -63,6 +84,8 @@ If this component has been mounted into the DOM, this returns the corresponding
 > Note:
 >
 > getDOMNode is deprecated and has been replaced with [React.findDOMNode()](/react/docs/top-level-api.html#react.finddomnode).
+>
+> This method is not available on ES6 `class` components that extend `React.Component`. It may be removed entirely in a future version of React.
 
 
 ### isMounted
@@ -73,6 +96,10 @@ bool isMounted()
 
 `isMounted()` returns true if the component is rendered into the DOM, false otherwise. You can use this method to guard asynchronous calls to `setState()` or `forceUpdate()`.
 
+> Note:
+>
+> This method is not available on ES6 `class` components that extend `React.Component`. It may be removed entirely in a future version of React.
+
 
 ### setProps
 
@@ -89,7 +116,8 @@ Though calling `React.render()` again on the same node is the preferred way to u
 > When possible, the declarative approach of calling `React.render()` again is preferred; it tends to make updates easier to reason about. (There's no significant performance difference between the two approaches.)
 >
 > This method can only be called on a root-level component. That is, it's only available on the component passed directly to `React.render()` and none of its children. If you're inclined to use `setProps()` on a child component, instead take advantage of reactive updates and pass the new prop to the child component when it's created in `render()`.
-
+>
+> This method is not available on ES6 `class` components that extend `React.Component`. It may be removed entirely in a future version of React.
 
 ### replaceProps
 
@@ -98,3 +126,7 @@ replaceProps(object nextProps[, function callback])
 ```
 
 Like `setProps()` but deletes any pre-existing props instead of merging the two objects.
+
+> Note:
+>
+> This method is not available on ES6 `class` components that extend `React.Component`. It may be removed entirely in a future version of React.
diff --git a/docs/docs/ref-03-component-specs.md b/docs/docs/ref-03-component-specs.md
index 85924f9..493bfb8 100644
--- a/docs/docs/ref-03-component-specs.md
+++ b/docs/docs/ref-03-component-specs.md
@@ -95,7 +95,7 @@ Methods defined within this block are _static_, meaning that you can run them be
 string displayName
 ```
 
-The `displayName` string is used in debugging messages. JSX sets this value automatically; see [JSX in Depth](/react/docs/jsx-in-depth.html#react-composite-components).
+The `displayName` string is used in debugging messages. JSX sets this value automatically; see [JSX in Depth](/react/docs/jsx-in-depth.html#the-transform).
 
 
 ## Lifecycle Methods
diff --git a/docs/docs/ref-05-events.md b/docs/docs/ref-05-events.md
index c49ff06..c9888a5 100644
--- a/docs/docs/ref-05-events.md
+++ b/docs/docs/ref-05-events.md
@@ -112,8 +112,8 @@ For more information about the onChange event, see [Forms](/react/docs/forms.htm
 Event names:
 
 ```
-onClick onDoubleClick onDrag onDragEnd onDragEnter onDragExit onDragLeave
-onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
+onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit
+onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
 onMouseMove onMouseOut onMouseOver onMouseUp
 ```
 
diff --git a/docs/docs/ref-05-events.zh-CN.md b/docs/docs/ref-05-events.zh-CN.md
index 2da62a1..e83a281 100644
--- a/docs/docs/ref-05-events.zh-CN.md
+++ b/docs/docs/ref-05-events.zh-CN.md
@@ -111,8 +111,8 @@ onChange onInput onSubmit
 事件名称：
 
 ```
-onClick onDoubleClick onDrag onDragEnd onDragEnter onDragExit onDragLeave
-onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
+onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit
+onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
 onMouseMove onMouseOut onMouseOver onMouseUp
 ```