From e59e2d8ec8fdaa40731c8b214b5d53ba194876b7 Mon Sep 17 00:00:00 2001
From: Josh Duck <github@joshduck.com>
Date: Wed, 29 Jan 2014 10:53:21 -0800
Subject: [PATCH 1/2] Add warning about object property order.

It's easy to misuse the properties-as-keys feature and end up with children rendered out of order. Add a note and example of how to avoid this.
---
 docs/04-multiple-components.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/04-multiple-components.md b/docs/04-multiple-components.md
index b69312af..38d1a9c2 100644
--- a/docs/04-multiple-components.md
+++ b/docs/04-multiple-components.md
@@ -134,6 +134,25 @@ The situation gets more complicated when the children are shuffled around (as in
 
 When React reconciles the keyed children, it will ensure that any child with `key` will be reordered (instead of clobbered) or destroyed (instead of reused).
 
+Keys can also be specified as object properties. 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 a 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) {
+      // Using the numeric 'id' value as a key would result non-deterministic ordering
+      // of results.
+      items['result-' + result.id] = <li>{result.text}</li>;
+    });
+    
+    return (
+      <ol>
+        {items}
+      </ol>
+    );
+  }
+```
 
 ## Data Flow
 

From cdf67d6c24432d49c7412a0bd6e76b658897d586 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Paul=20O=E2=80=99Shannessy?= <paul@oshannessy.com>
Date: Wed, 19 Feb 2014 18:07:24 -0800
Subject: [PATCH 2/2] tweak object property warning.

---
 docs/04-multiple-components.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/04-multiple-components.md b/docs/04-multiple-components.md
index 38d1a9c2..29bc1e32 100644
--- a/docs/04-multiple-components.md
+++ b/docs/04-multiple-components.md
@@ -134,15 +134,16 @@ The situation gets more complicated when the children are shuffled around (as in
 
 When React reconciles the keyed children, it will ensure that any child with `key` will be reordered (instead of clobbered) or destroyed (instead of reused).
 
-Keys can also be specified as object properties. 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 a 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:
+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 a 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) {
-      // Using the numeric 'id' value as a key would result non-deterministic ordering
-      // of results.
+      // 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>;
     });