Add docs for createFragment

docs/_data/nav_docs.yml

@@ -59,6 +59,8 @@
       title: Test Utilities
     - id: clone-with-props
       title: Cloning Components
+    - id: create-fragment
+      title: Keyed Fragments
     - id: update
       title: Immutability Helpers
     - id: pure-render-mixin

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
 

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:
 

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.

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.

docs/docs/10.6-update.md → docs/docs/10.7-update.md

@@ -2,7 +2,7 @@
 id: update
 title: Immutability Helpers
 permalink: update.html
-prev: clone-with-props.html
+prev: create-fragment.html
 next: pure-render-mixin.html
 ---